fix: register the unit of work with its store context (#41)

* fix: register the unit of work with its store context

* fix: pin read-side lifetimes and name the unit of work's other dependencies

---------

Co-authored-by: Norbert Rosenwinkel <199918463+yesbert@users.noreply.github.com>

Author: yesbert

CHANGELOG.md

@@ -18,6 +18,15 @@ applies to the entire NuGet family.
 
 ### Fixed
 
+- **Registering a store context now registers its unit of work.**
+  `AddNpgsqlWriteDbContextFactory<T>()` registered the context factory, the context and the default
+  connection resolver but not the `IWriteUnitOfWork` that the event source, the outbox dispatcher and
+  the command worker take from the container — and nothing else in the published packages did, so a
+  host composed exactly as documented failed at its first command with a dependency-injection error.
+  The write registration now try-adds a scoped `IWriteUnitOfWork` over its context, and
+  `AddNpgsqlReadDbContextFactory<T>()` try-adds `IProjectionsUnitOfWork` and `IReadUnitOfWork`
+  likewise. A unit of work the host registers itself, before or after, is still the one used; a
+  hand-written registration can simply be deleted.
 - **`AddMediator()` no longer requires the host to register an OpenTelemetry `Tracer`.** The
   mediator traces every dispatch and obtained its tracer from the host, but nothing registered one,
   so a host that called `AddMediator()` and nothing else failed at the first resolve of `IMediator`.

docs/reference/di-extensions-cheatsheet.md

@@ -120,8 +120,8 @@ transport, but registering both in one host is still a smell — pick one.
 
 | Extension | What it does |
 |---|---|
-| `services.AddNpgsqlWriteDbContextFactory<TContext>()` | Npgsql-backed `IDbContextFactory<TContext>` for the write-store context, plus the default `IWriteUnitOfWork` if none is registered |
-| `services.AddNpgsqlReadDbContextFactory<TContext>()` | The same for a read-store context |
+| `services.AddNpgsqlWriteDbContextFactory<TContext>()` | Npgsql-backed `IDbContextFactory<TContext>` for the write-store context, plus a scoped `IWriteUnitOfWork` over it unless the host registered its own. The unit of work also needs `ISessionContextProvider` and `ISecureJsonSerializer` from `AddSessionContext()` / `AddSecurity()`, which every worker composite applies |
+| `services.AddNpgsqlReadDbContextFactory<TContext>()` | The same for a read-store context, plus a scoped `IProjectionsUnitOfWork` / `IReadUnitOfWork` over it unless the host registered its own |
 | `services.AddNpgsqlIdentityDbContextFactory<TContext>()` | The same for an identity-store context, **plus** a scoped resolution of the context itself so ASP.NET Identity can inject it directly |
 | `services.AddWriteStore(configuration)` | Binds `EventSourcingOptions` from the `EventSourcing` section — snapshot cadence, batch sizes and the other write-side knobs |
 | `services.AddCommandAuditing()` | `CommandAuditBehavior` for both command shapes — persists an audit row per dispatched command; queries pass through (`Stratara.EventSourcing.Pipeline.CommandAudit`) |

llms-full.txt

@@ -131,8 +131,8 @@ Public extension methods a host calls to wire Stratara, with what each one does
 | `AddMembershipTenantClaimsTransformation()` | Stratara.Identity.AspNetCore | Register MembershipClaimsTransformation as an IClaimsTransformation, resolving the tenant claim from the membership store on every request |
 | `AddMessaging()` | Stratara.Outbox.RabbitMQ | Registers the messaging infrastructure: IMessageBus backed by RabbitMqBus, the IMessagingIdentifier service, and binds MessagingOptions from the Messaging configuration section |
 | `AddNpgsqlIdentityDbContextFactory<TDbContext>()` | Stratara.EventSourcing.EntityFrameworkCore | Registers an Npgsql-backed IDbContextFactory`1 for an identity-store DbContext together with a scoped resolution of the context itself (so ASP.NET Identity can inject it directly) and the default IDbResolver |
-| `AddNpgsqlReadDbContextFactory<TDbContext>()` | Stratara.EventSourcing.EntityFrameworkCore | Registers an Npgsql-backed IDbContextFactory`1 for a read-store DbContext along with the default IDbResolver if none has been registered yet |
-| `AddNpgsqlWriteDbContextFactory<TDbContext>()` | Stratara.EventSourcing.EntityFrameworkCore | Registers an Npgsql-backed IDbContextFactory`1 for a write-store DbContext along with the default IDbResolver if none has been registered yet |
+| `AddNpgsqlReadDbContextFactory<TDbContext>()` | Stratara.EventSourcing.EntityFrameworkCore | Registers an Npgsql-backed IDbContextFactory`1 for a read-store DbContext together with the read-side unit of work over it, and the default IDbResolver if none has been registered yet |
+| `AddNpgsqlWriteDbContextFactory<TDbContext>()` | Stratara.EventSourcing.EntityFrameworkCore | Registers an Npgsql-backed IDbContextFactory`1 for a write-store DbContext together with the write-side unit of work over it, and the default IDbResolver if none has been registered yet |
 | `AddOutboxDispatcher()` | Stratara.Outbox.RabbitMQ | Registers ICommandOutboxDispatcher and IEventBundleOutboxDispatcher (scoped) and, transitively, IProjectionReplayState (singleton via AddProjectionReplayState) |
 | `AddOutboxHealthCheck(Int32? degradedThreshold, Int32? unhealthyThreshold, String name, HealthStatus? failureStatus, IEnumerable<String> tags)` | Stratara.EventSourcing.EntityFrameworkCore | Registers the OutboxBacklogHealthCheck, reporting the depth and age of the Stratara outbox backlog |
 | `AddOutboxWorker(IConfiguration configuration)` | Stratara.Outbox.RabbitMQ | Registers the OutboxWorker hosted service and binds OutboxOptions from configuration |

openspec/changes/let-a-store-context-bring-its-unit-of-work/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-03

openspec/changes/let-a-store-context-bring-its-unit-of-work/design.md

@@ -0,0 +1,96 @@
+# Design — Let a store context bring its unit of work
+
+## Context
+
+See `proposal.md` → *Why*. What matters here is what the two registrations do today and what the
+one place that does register the unit of work looks like.
+
+`NpgsqlDbContextServiceCollectionExtensions` (`src/Stratara.EventSourcing.EntityFrameworkCore/EntityFrameworkCore/DependencyInjection/`):
+
+- `AddNpgsqlWriteDbContextFactory<TDbContext>()` (line 34) — `AddDbContextFactory<TDbContext>` scoped,
+  `TryAddScoped<IWriteDbContext>` from the factory, `TryAddScoped<IDbResolver, DefaultDbResolver>`.
+- `AddNpgsqlReadDbContextFactory<TDbContext>()` (line 54) — the factory and the resolver only.
+
+`WriteUnitOfWork<TDbContext>` (`WriteStore/WriteUnitOfWork.cs:24`) is constructed from
+`(IDbContextFactory<TDbContext>, ISessionContextProvider, ISecureJsonSerializer)`; the last two come
+from `AddSessionContext()` and `AddSecurity()`, which every composite applies.
+`ProjectionsUnitOfWork<TDbContext>` (`ReadStore/ProjectionsUnitOfWork.cs:16`) takes only the
+factory and implements `IProjectionsUnitOfWork : IReadUnitOfWork`.
+
+The only registration of `IWriteUnitOfWork` for a concrete context in the family is in test support,
+`AddStrataraTestingEventStore` (`src/Stratara.Testing.EntityFrameworkCore/TestEventStoreServiceCollectionExtensions.cs:72`):
+
+```csharp
+services.AddScoped<IWriteUnitOfWork>(sp => new WriteUnitOfWork<TWriteDbContext>(
+    sp.GetRequiredService<IDbContextFactory<TWriteDbContext>>(),
+    sp.GetRequiredService<ISessionContextProvider>(),
+    sp.GetRequiredService<ISecureJsonSerializer>()));
+```
+
+`docs/reference/di-extensions-cheatsheet.md:123` describes the write factory as registering "the
+default `IWriteUnitOfWork` if none is registered". `llms-full.txt` is generated from the XML docs
+and the documentation tests fail when it drifts from them.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Registering a context is sufficient for the store on that side to work.
+- A consumer's own unit of work, registered before or after the context, wins.
+- The unit of work is scoped, as the test host registers it and as the repositories it mints assume.
+
+**Non-Goals:**
+
+- Registering the unit of work from the composites (`AddBackendServices`, `AddCommandWorkerServices`).
+  They do not know the consumer's context type, and the point is that the one call that does know it
+  is the one that registers it.
+- Changing the identity-context registration. ASP.NET Identity resolves the context itself; there
+  is no unit of work on that side.
+- Touching the SQLite test host. It keeps its explicit registration, which is now redundant with
+  the production one but harmless, and its `AddScoped` (not try-add) is deliberate there.
+
+## Decisions
+
+### The factory registration try-adds the unit of work for its own context type
+
+`AddNpgsqlWriteDbContextFactory<TDbContext>()` adds
+`TryAddScoped<IWriteUnitOfWork>(sp => new WriteUnitOfWork<TDbContext>(...))` with the three
+constructor dependencies resolved from the provider, exactly the shape the test host uses.
+`AddNpgsqlReadDbContextFactory<TDbContext>()` adds
+`TryAddScoped<IProjectionsUnitOfWork>(sp => new ProjectionsUnitOfWork<TDbContext>(factory))` and
+`TryAddScoped<IReadUnitOfWork>(sp => sp.GetRequiredService<IProjectionsUnitOfWork>())`, so the two
+contracts resolve to one instance per scope.
+
+Try-add is what makes precedence hold in both orders: a consumer registration before the factory
+call means the framework's try-add is a no-op; a consumer registration after it is a later descriptor
+for the same service type, which the container prefers. Registering the same context twice is a
+second no-op.
+
+Evidence: the constructor shapes above; the test host's registration; the new tests in
+`tests/Stratara.EntityFrameworkCore.Tests/` that resolve each contract against a registered context
+and assert the type and the precedence.
+
+*Rejected: `AddScoped` rather than try-add.* It would silently replace a consumer's own unit of work
+registered before the factory call — the opposite of what an additive patch may do.
+
+*Rejected: a separate `AddNpgsqlWriteUnitOfWork<TDbContext>()` the consumer calls in addition.* A
+second call that is mandatory for the first to be useful is the defect restated with one more name.
+
+### The factory dependencies are resolved lazily, not captured at registration
+
+The write unit of work needs the session provider and the serializer. Both are registered by
+composites the consumer may call after the factory extension. Resolving them inside the factory
+delegate, per scope, means the order of `Add*` calls does not matter, which is the standing rule of
+the composition surface.
+
+## Risks / Trade-offs
+
+- [A consumer registered `IWriteUnitOfWork` as a singleton by hand, and now also gets a scoped
+  try-add] → Try-add sees the existing descriptor and does nothing; the consumer's singleton stands.
+  No change.
+- [A host registers the write context but not `AddSecurity()` / `AddSessionContext()`] → The unit of
+  work fails to resolve its serializer or session provider at first use, with the container's message
+  naming that type. That host could not have run the store before either; the error now names a
+  documented composite dependency rather than the unit of work itself.
+- [`llms-full.txt` drifts] → It is regenerated as part of the change; the documentation tests are the
+  gate.

openspec/changes/let-a-store-context-bring-its-unit-of-work/proposal.md

@@ -0,0 +1,66 @@
+> **Status:** approved
+
+# Let a store context bring its unit of work
+
+## Why
+
+A consumer who registers the write store the way the documentation shows — one context class
+deriving from the framework's write context, one call to the Npgsql factory extension — cannot
+dispatch a command. The registration brings the context factory, the context and the default
+connection resolver, but not the write-side unit of work that every repository, the event source,
+the outbox dispatcher and the command worker take from the container. The first dispatch fails with
+a dependency-injection error naming a type the consumer never saw in a guide. The reference page
+even says the factory registers "the default `IWriteUnitOfWork` if none is registered"; it does not,
+and nothing else in the published packages does — only the test-support host, which is why the
+framework's own tests never notice.
+
+The read side has the same gap: the read-context factory registers the factory and the resolver, and
+the read-side unit of work the projections capability requires is left to the consumer to construct
+by hand from a type they have to discover in the source.
+
+Found on 2026-09-03 while briefing the first example that consumes the published packages rather
+than the source. It is the second step of the entry-point work approved that day: the event-sourcing
+door has to be "register the context, write an aggregate", not "register the context, read the
+framework's test host to learn what else is missing".
+
+## What Changes
+
+- **Registering the write context registers the write-side unit of work.** The Npgsql write-context
+  registration also makes the write-side unit of work resolvable for that context, with try-add
+  semantics: a consumer that registers its own keeps it.
+- **Registering the read context registers the read-side unit of work.** The Npgsql read-context
+  registration likewise makes the read-side unit of work — the one projections use, and the plain
+  read unit of work it derives from — resolvable, with the same try-add semantics.
+- The reference page stops describing behaviour the framework did not have and describes the
+  behaviour it now has, for both sides.
+
+Nothing about what the unit of work does changes. A consumer that already registers it by hand sees
+no difference; the line becomes deletable.
+
+## Capabilities
+
+### New Capabilities
+
+_none_
+
+### Modified Capabilities
+
+- `event-sourcing-store`: gains the requirement that registering the store's database context makes
+  the store usable without further registration — the write-side unit of work is available and a
+  consumer-supplied one takes precedence.
+- `projections`: the requirement *Read models are queried through a scoped unit of work* gains the
+  guarantee that registering the read-side database context makes that unit of work available, and
+  that a consumer-supplied one takes precedence.
+
+## Impact
+
+- `src/Stratara.EventSourcing.EntityFrameworkCore/EntityFrameworkCore/DependencyInjection/NpgsqlDbContextServiceCollectionExtensions.cs`
+  — the write and read factory registrations gain the try-add of their unit of work; XML docs say so.
+- `docs/reference/di-extensions-cheatsheet.md` — the write row becomes true, the read row says the
+  same for its side.
+- `llms-full.txt` — regenerated, because it is derived from the XML docs that change.
+- `tests/Stratara.EntityFrameworkCore.Tests/` — the registration is pinned on both sides, including
+  the precedence of a consumer-supplied unit of work.
+- `CHANGELOG.md` — `[Unreleased]`.
+- Additive on the published surface: a patch release. Source: consumer briefing for
+  `Stratara.Examples`, 2026-09-03 (`.claude/docs/examples-consumer-briefing.md`, item 1).

openspec/changes/let-a-store-context-bring-its-unit-of-work/specs/event-sourcing-store/spec.md

@@ -0,0 +1,30 @@
+## ADDED Requirements
+
+### Requirement: Registering the store's context makes the store usable
+
+Registering the write store's database context through the framework's registration SHALL make the
+write-side unit of work available to everything that depends on it — appending events, publishing
+through the outbox, handling commands in a worker — without a further registration by the consumer.
+A write-side unit of work the consumer registers itself SHALL take precedence over the framework's.
+
+A store whose context is registered but whose unit of work is not is a store that fails at the first
+command with an error naming a type no guide mentions. The registration that declares the context
+is the one place that knows which context the unit of work should be built over.
+
+#### Scenario: A consumer registers only the write context
+
+- **WHEN** a consumer registers its write-store context through the framework's registration and
+  nothing else
+- **THEN** the write-side unit of work resolves and is bound to that context, and a command that
+  appends an event can be handled
+
+#### Scenario: A consumer supplies its own write-side unit of work
+
+- **WHEN** a consumer registers its own write-side unit of work, before or after registering the
+  context
+- **THEN** the consumer's unit of work is the one resolved
+
+#### Scenario: The registration is applied more than once
+
+- **WHEN** the write-store context is registered more than once for the same context type
+- **THEN** one unit of work is resolved, bound to that context

openspec/changes/let-a-store-context-bring-its-unit-of-work/specs/projections/spec.md

@@ -0,0 +1,27 @@
+## MODIFIED Requirements
+
+### Requirement: Read models are queried through a scoped unit of work
+
+Read-side access SHALL be through a unit of work distinct from the write side's, so that a query
+never participates in a write transaction and a read model can live in its own store.
+
+Registering the read store's database context through the framework's registration SHALL make that
+read-side unit of work available without a further registration by the consumer. A read-side unit
+of work the consumer registers itself SHALL take precedence over the framework's.
+
+#### Scenario: A projection writes to a read model
+
+- **WHEN** a projection processes a bundle
+- **THEN** it does so through the read-side unit of work, in its own transaction
+
+#### Scenario: A consumer registers only the read context
+
+- **WHEN** a consumer registers its read-store context through the framework's registration and
+  nothing else
+- **THEN** the read-side unit of work resolves, bound to that context
+
+#### Scenario: A consumer supplies its own read-side unit of work
+
+- **WHEN** a consumer registers its own read-side unit of work, before or after registering the
+  context
+- **THEN** the consumer's unit of work is the one resolved

openspec/changes/let-a-store-context-bring-its-unit-of-work/tasks.md

@@ -0,0 +1,35 @@
+## 1. The registrations
+
+- [x] 1.1 `src/Stratara.EventSourcing.EntityFrameworkCore/EntityFrameworkCore/DependencyInjection/NpgsqlDbContextServiceCollectionExtensions.cs`:
+      `AddNpgsqlWriteDbContextFactory<TDbContext>()` try-adds a scoped `IWriteUnitOfWork` built as
+      `WriteUnitOfWork<TDbContext>` from the context factory, `ISessionContextProvider` and
+      `ISecureJsonSerializer`, all resolved inside the factory delegate. Update the XML summary and
+      remarks: what is registered, that a consumer-supplied unit of work wins, that the session and
+      security composites supply the other two dependencies.
+- [x] 1.2 Same file: `AddNpgsqlReadDbContextFactory<TDbContext>()` try-adds a scoped
+      `IProjectionsUnitOfWork` as `ProjectionsUnitOfWork<TDbContext>` and a scoped `IReadUnitOfWork`
+      that resolves to it. XML docs likewise.
+- [x] 1.3 Tests in `tests/Stratara.EntityFrameworkCore.Tests/DependencyInjection/NpgsqlDbContextServiceCollectionExtensionsTests.cs`
+      (new): with a write context registered and the session/security doubles present,
+      `IWriteUnitOfWork` resolves as `WriteUnitOfWork<TContext>` and is scoped; a consumer
+      `IWriteUnitOfWork` registered before, and one registered after, is the instance resolved;
+      registering the context twice yields one `IWriteUnitOfWork` descriptor; the read side resolves
+      `IProjectionsUnitOfWork` and `IReadUnitOfWork` to the same `ProjectionsUnitOfWork<TContext>`
+      instance within a scope, with the same precedence cases. Resolution only — no database is
+      opened.
+
+## 2. Documentation and generated inventory
+
+- [x] 2.1 `docs/reference/di-extensions-cheatsheet.md` rows 123–124: the write row describes the
+      try-added `IWriteUnitOfWork`; the read row says `IProjectionsUnitOfWork` / `IReadUnitOfWork`.
+- [x] 2.2 `src/Stratara.EventSourcing.EntityFrameworkCore/README.md`, where the consumer contexts are
+      shown: the factory registration is all the store needs. (`di-composition.md` shows no consumer
+      context, so it has nothing to say here.)
+- [x] 2.3 Regenerate `llms-full.txt` with the generator the documentation tests use
+      (`tests/Stratara.Documentation.Tests`), so the registration inventory carries the new summaries.
+- [x] 2.4 `CHANGELOG.md` `[Unreleased]` → *Fixed*: registering the write or read context now
+      registers its unit of work; a consumer-supplied one still wins; the hand-written line can go.
+
+## 3. Gate
+
+- [x] 3.1 `./scripts/local-gauntlet.sh` green; `openspec validate --strict` clean.