Onboarding guide

7. Persistence & EF Core

What this group covers. This is the framework's data-access engine: everything between a domain aggregate and a row in a database. It is the single largest group in the guide because it carries a lot of load. One abstract ApplicationDbContext base with a sealed subclass per engine (SQLServerDbContext, CosmosDbContext, SqliteDbContext); four EF Core save interceptors that turn a plain SaveChangesAsync into audit stamping, tenant enforcement, transactional domain-event capture, and a field-level change trail; a small repository family behind an interface-segregated contract (IReadRepository<TEntity, TIdentifierType>, IWriteRepository<TEntity, TIdentifierType>, IRepository<TEntity, TIdentifierType>) coordinated by a UnitOfWork, with the query-shaping helpers (SpecificationEvaluator, KeysetQueryBuilder) that turn a specification or a cursor into SQL; a data-source routing layer that lets every entity resolve to its own physical database ("database per service") and every tenant optionally to its own copy of it; two model-finalizing conventions that keep that routing honest; an engine-portable entity-configuration hierarchy; and a supporting cast of value converters, value generators, an encryption converter, seeders, and design-time factories. The group also owns the settings objects the whole engine binds from configuration (PersistenceSettings, ConnectionStringSettings, DataSourcesSettings, TenancySettings, AuditTrailSettings) plus the two startup validators that fail a boot on a misconfiguration, and the Application-layer storage and push contracts whose implementations are composed in Group 14. The whole thing is the [Rubric §8, Data Architecture] chapter of the codebase, and it leans hard on [Rubric §7, Microservices Readiness] and [Rubric §3, Clean Architecture].

One base context, one class per engine, one instance per database

ApplicationDbContext (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/ApplicationDbContext.cs:41) is an abstract primary-constructor class over EF's DbContext. It holds the cross-cutting model configuration every engine shares. It applies a global soft-delete query filter to every non-owned IAuditableEntity using a runtime-built expression tree, registered as a named "SoftDelete" filter (ApplicationDbContext.cs:367-380, name at :388); it applies a second named "Tenant" filter to every non-owned ITenantEntity (ApplicationDbContext.cs:428-487); it configures the RowVersion optimistic-concurrency token, mapped as a SQL Server rowversion or as a plain application-managed token on other providers (ApplicationDbContext.cs:501-521); and it maps the framework's own bookkeeping tables so every relational database carries its own (OutboxMessage at :528-563, InboxMessage at :570-584, ScheduledJobEntry at :594-618, AuditTrailEntry at :628-656), each with the filtered indexes its poll path and its retention sweep need (IX_OutboxMessages_Pending at :542-545, IX_OutboxMessages_Processed at :550-552, the keyed-ordering index IX_OutboxMessages_Ordering at :559-562, IX_InboxMessages_MessageId at :576-578, IX_InboxMessages_ProcessedOn at :582-583, IX_ScheduledJobs_NextRunOn at :615-617, IX_AuditTrailEntries_Entity at :648-649, IX_AuditTrailEntries_ChangedOn at :654-655). Three of the five framework tables are gated: the job table is mapped only when Scheduler:Enabled is set AND this context targets the Default source (jobs are host-scoped, :286-288), the trail table only when AuditTrail:Enabled is set, on every relational source (a trail row must commit with the change it describes, and a transaction does not span databases, :291), and the refresh-session table only when RefreshSessions:Enabled is set AND this context targets the source that setting names (:296-299, applied at :673-681). A host that opted into none of them keeps the model it had before those features shipped, so none of those tables ever appears in its migrations. The base also registers four keyless ValReturn<T> shapes (:125, :338-341) so raw SQL scalar queries have somewhere to land.

Its SaveChangesAsync(userId, ...) overload (ApplicationDbContext.cs:153-167) is the one entry point handlers care about: it stashes the current user id in CurrentSaveUserId so the audit interceptor can read it, delegates to base, then clears it in a finally so a later internal save cannot silently reuse the previous caller's identity (:165). The base also overrides both SaveChanges overloads purely to run change detection once per save and suppress it for the rest, through the DetectChangesOnce helper and its DetectChangesScope disposable (:173-177, :206-208, :233-246): each interceptor's ChangeTracker.Entries<T>() call would otherwise trigger a full DetectChanges, so a save paid three snapshot comparisons where one suffices, and the previous auto-detect setting is restored on the way out (:245).

The design decision that shapes this whole group is stated in the base's own doc comment: one context class per engine, one instance per physical data source (ApplicationDbContext.cs:29-35). The same SQLServerDbContext class (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/SQLServerDbContext.cs:15) is instantiated once per SQL Server database, each instance carrying a different PhysicalDataSource (connection string, per-engine migrations assembly, Cosmos database name). To keep EF from silently reusing the first-built model for every database, DataSourceModelCacheKeyFactory (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/DataSourceModelCacheKeyFactory.cs:16) keys EF's model cache by context type plus physical source name plus the design-time flag (:19-22), and is installed by the base in OnConfiguring (ApplicationDbContext.cs:303). This is deliberately not a per-module context split: one sealed context per engine over the abstract base is ADR-006's ruling. SQLServerDbContext adds the provider-specific touches: a per-environment command timeout read from PersistenceSettings (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/PersistenceSettings.cs:10, bound from the Persistence section at :13, range-checked between 1 and 600 seconds and defaulting to the same 30 the framework applied implicitly before the section existed, :21-22) rather than ADO.NET's silent 30-second default (SQLServerDbContext.cs:55, with the settings object resolved once into a field at :36-37 using GetService so the design-time provider, which registers no options at all, cannot be made to throw), transient-fault retry (EnableRetryOnFailure with 5 attempts and a 10-second cap, :64-67), and a suppressed PendingModelChangesWarning (:80) so an extracted service that registers only its own module's entity configurations starts cleanly against a migration snapshot that captures every module's tables. That warning suppression is a direct [Rubric §7, Microservices Readiness] decision, and the source comment states the trade-off plainly: monolith hosts lose the "you forgot a migration" safety net, so CI is expected to run dotnet ef migrations has-pending-model-changes as a separate gate (:69-79). The retry comment also carries a rule the rest of the group depends on: with retry-on-failure enabled a manual BeginTransactionAsync must run inside Database.CreateExecutionStrategy().ExecuteAsync (:61-63). SqliteDbContext (.../DbContexts/SqliteDbContext.cs:12) is the same shape with UseSqlite and its own migrations assembly (:24-35), and CosmosDbContext (.../DbContexts/CosmosDbContext.cs:14) deliberately does not call base.OnModelCreating, because the relational bookkeeping tables have no place in a document store; it re-applies only the filters it needs (:89-95).

SaveChanges as an interceptor pipeline

The base context resolves its interceptors from DI in OnConfiguring (ApplicationDbContext.cs:249-281), and registration order is execution order. The audit interceptor runs first, the tenant interceptor between it and the domain-event interceptor (so the outbox rows describe an entity whose tenant is already final, :258-271), and the change-trail interceptor last, because it diffs the final values (:273-281). Two of the four are resolved with GetService rather than GetRequiredService: a directly-constructed test context or a host that never called AddAuditTrail must still build, and their absence has to read as "the feature is off" rather than fail every context construction.

AuditSaveChangesInterceptor (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Interceptors/AuditSaveChangesInterceptor.cs:22) runs on SavingChanges: it walks every tracked IAuditableEntity, stamps CreatedOn/By plus LastModifiedOn/By on Added (:56-60), and on Modified marks the two Created* properties unmodified before re-stamping LastModified* (:67-71), reading the timestamp from an injected TimeProvider and the user id from CurrentSaveUserId (falling back to default as the system-operation sentinel, :49-50). It also writes the soft-delete stamps, and it drives them off the transition of the IsDeleted flag rather than its value: DeletedOn/By are written when the flag goes false to true and cleared when it goes back (:92-105, with the original value read at :83-84), so a later update to an already-deleted row keeps the stamps of the delete that produced it, exactly as CreatedOn/By survive every update. This is why the domain declares audit fields with private setters and never writes them: the interceptor sets them centrally through entry.Property(...).CurrentValue, bypassing setter visibility. That is the [Rubric §12, Performance & Scalability] payoff, one enforcement point instead of copy-paste in every handler.

DomainEventSaveChangesInterceptor (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Interceptors/DomainEventSaveChangesInterceptor.cs:46) is the producer end of the outbox, and it is the most subtle type in the group. On SavingChanges it snapshots each tracked IAggregateRoot and its pending IDomainEvents into an AggregateCapture record (:221-225, record at :373), then writes an OutboxMessage row for each event into the same context, so the events land in the database in the same transaction as the aggregate changes (:207-272). The routing split happens right there: an IIntegrationEvent gets a row but no in-process dispatch (its row stays unprocessed so the OutboxProcessor publishes it over IMessageBus), while a local event gets both a row and the fast in-process path (:249-258). Before capturing, DiscardAbandonedCapture detaches the Added outbox rows left by a previous SavingChanges that never reached SavedChanges (:279-300), which is what stops an execution-strategy retry from writing a second row per event and publishing every integration event twice. The captured state is parked in a CapturedState record (:382) held in a ConditionalWeakTable keyed by context (:62), so it is cleaned up automatically when the context is disposed. A third weak table (:77) holds a per-context capture exclusion set: BeginCaptureExclusion / EndCaptureExclusion (:179-195) let DbContextFactory name exactly the entries it hides from an IDENTITY_INSERT round, so an event is never serialized and cleared a round before the insert that justifies it. The exclusion is by instance rather than by entity state on purpose: a state-based filter would also drop events raised on an already-saved aggregate, which is how the identity module publishes its registration events (:172-176).

After the save, the post-save path DispatchAndFinalizeAsync (DomainEventSaveChangesInterceptor.cs:302-319, reached from SavedChangesAsync at :103-112) does one of two things. With no ambient transaction it flushes immediately: dispatch local events through IDomainEventDispatcher, remove exactly the captured events from their aggregates, mark the local outbox rows processed through OutboxFinalizer, and signal the outbox for integration events (:325-352). With an active transaction it removes the captured events (so a second save inside the same transaction cannot re-capture them) and parks a DeferredDispatch (:389) in a second weak table (:69); DbContextFactory then calls the static FlushDeferredAsync only after a successful commit (:145-159) and DropDeferred on rollback (:162). That is what keeps handler side effects from acting on state that could still roll back, and what keeps a retrying execution strategy from dispatching the same events once per attempt. Note the precision of the clearing: the interceptor calls RemoveDomainEvents(capture.Events) rather than clearing the aggregate wholesale (:361-366), so an event a handler raises on the same aggregate during in-process dispatch survives to a later capture instead of being wiped. If in-process dispatch throws, the interceptor logs a warning and signals the outbox to retry from the persisted rows rather than losing the event (:339-346). The synchronous SavedChanges path cannot await a dispatcher at all, so it removes the captured events, signals the outbox, and leaves delivery entirely to it (:124-137). Two conditions take the everything-in-process branch instead: Cosmos DB has no relational outbox table, so the base exposes a SupportsOutbox flag (ApplicationDbContext.cs:136) that CosmosDbContext overrides to false (CosmosDbContext.cs:69); and a host can turn the outbox off outright, which the interceptor reads once from the message-bus options into _outboxEnabled (:55) and honors at the same branch (:236, :263-268). This split, atomic persistence plus best-effort immediate dispatch with a durable fallback, is the at-least-once contract of ADR-003; the consumer end lives in Group 04.

The tenant boundary, read filter plus write guard

Multi-tenancy (ADR-073) is two independent halves that meet in this group. The read half is the named Tenant query filter the base context applies to every non-owned ITenantEntity (ApplicationDbContext.cs:428-487). Three details make it work: the filter body embeds the context instance as a constant typed as ApplicationDbContext, so EF rewrites it to the executing context and lifts CurrentTenantId into a SQL parameter, letting one compiled model serve every tenant (:413-419, :434-436); the predicate is CurrentTenantId == null || e.TenantId == CurrentTenantId, so a scope with no tenant (the outbox processor, the seeders, the retention jobs) sees every tenant's rows (:478-484); and the column itself is declared required, 64 characters, non-Unicode, and indexed on relational engines, because every tenant-scoped read carries it as the leading predicate (:445-449, width constant at :397). That index follows the filter composition rather than the column: an entity that is also an IAuditableEntity gets (TenantId, IsDeleted), matching the AND-composed predicate every read of a soft-deletable tenant row actually carries, and a tenant-only entity keeps the single-column index (:458-466). The filter reads the value through EF.Property rather than a CLR member access, so an explicitly implemented interface member or a shadow property translates identically (:471-476). Because the two filters are named, EF composes them with AND, and a caller asking for soft-deleted rows drops exactly the SoftDelete filter while the tenant filter stays in force: the repository contract says so in as many words (MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/IRepository.cs:16-19, :75-79), and the repository passes that one filter name explicitly (.../Repositories/EFReadRepository.cs:33).

The write half is TenantSaveChangesInterceptor (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Interceptors/TenantSaveChangesInterceptor.cs:36). It stamps the scope's tenant onto an insert that declares none (:116-119), refuses an insert that names a different one (:122-123), and on update or delete checks both the original and the current value, so touching another tenant's row and reassigning a row to another tenant are both rejected (:131-159, with the original reported in preference to the current one at :161-166). An untenanted insert from an untenanted scope is refused too, because silently writing a row no tenant can ever read is worse than failing the save (:107-110). Owned types are skipped on both sides: an owned value has no independent existence and its owner's tenant is already the row's tenant (:69-75). Failures surface as CrossTenantWriteException (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Interceptors/CrossTenantWriteException.cs:24), which derives from InvalidOperationException so existing catch sites treat it like any other save-time invariant failure (:19-22). The deliberate asymmetry is documented in the interceptor's own remarks: a caller who bypasses the read filter with EF's parameterless IgnoreQueryFilters() can read across tenants, but still cannot write across them (:29-33). That is [Rubric §11, Security] and [Rubric §30, Compliance and Data Governance] in one type. The scope's tenant itself lives in TenantContext (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Context/TenantContext.cs:11), which is set-once-per-scope and idempotent for the same value, and throws rather than switching tenants mid-scope (:20-44).

What a host declares about tenancy is bound into TenancySettings (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Tenancy/TenancySettings.cs:50) from the Tenancy section (:53), and the settings themselves carry the shape of the feature. Enabled gates resolution, not isolation, so the query filter and the save interceptor are always present and simply inert while no tenant is resolved, which is why a host that never opts in keeps exactly the behavior it had (:37-40, default false at :67). RequireTenant defaults to true, so once resolution is on a request that yields no tenant is rejected with 400 Bad Request rather than reading across every tenant (:91-96). Both collection properties express their defaults as "empty means the default", read through EffectiveResolutionOrder (claim, then header) and EffectiveExcludedPathPrefixes (/health, /alive, /.well-known), because the configuration binder ADDS to a pre-populated collection instead of replacing it, so a non-empty default would leave a host that configured its own order running the framework's entries too (:42-48, :56-61, :76-77, :106-107). TenantResolutionStrategy (:6) names the three sources: Claim is the trustworthy one (the token issuer signed it, so a caller cannot pick its own tenant), Header is for service-to-service calls behind a trusted gateway, and Host is defined but not implemented, present only so the configuration contract stays stable (:8-27). TenancySettingsValidator (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Tenancy/TenancySettingsValidator.cs:23) is what makes that honest: registered with ValidateOnStart, it fails the boot when a resolution order names Host (:54-65) and checks each tenant's overrides against the resolved physical sources when IDataSourceResolver is registered (:14-18, :39-42), on the reasoning that every failure here would otherwise surface as silent cross-tenant behavior, which is the exact bug class tenancy exists to prevent (:8-13). Declaring a tenant is only required for the database-per-tenant case: a TenantEntrySettings (TenancySettings.cs:121) entry holds per-source overrides keyed by physical source name, and each TenantDataSourceOverrideSettings (:138) carries connection information only, because a tenant database has the same schema as the shared one and the migrations assembly is deliberately not overridable (:124-137, :140-153). A source without an entry stays shared and is isolated by the query filter (:126-127).

Database-per-tenant is handled one layer up, in the factory, and background sweeps expand their work list through TenantDataSourceTargets.Expand (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/TenantDataSourceTargets.cs:49-79), which emits the shared target for every source plus one extra TenantDataSourceTarget (:13) per tenant that overrides a source, because a tenant with its own database is invisible to the shared sweep (:33-37).

Recording what changed, the audit trail

AuditTrailSaveChangesInterceptor (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/AuditTrail/AuditTrailSaveChangesInterceptor.cs:62) is the fourth interceptor (ADR-075). It records a field-level history for entities marked IAuditedEntity, writing AuditTrailEntry rows in the same transaction as the change they describe, on the outbox precedent that a trail committable without its data is worse than no trail (:18-22). A Modified save produces one row per property whose value actually changed; Added and Deleted produce a single summary row with a null PropertyName (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/AuditTrail/AuditTrailEntry.cs:15-21, class at :23). Four things are worth knowing about it. It is opt-in twice over, once through AddAuditTrail (the interceptor is resolved with GetService) and once through AuditTrail:Enabled (which maps the table), and both are checked cheaply per save by asking the model whether the entity type exists at all (:179-186). Both switches read the same bound AuditTrailSettings (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/AuditTrail/AuditTrailSettings.cs:16, section name at :19), whose Enabled decides both whether changes are recorded and whether the AuditTrailEntries table is mapped at all, defaulting to false so adopting the framework never adds a table or a write per change to a host that did not ask for one (:10-15, :21-26), whose RetentionDays defaults to 90 and is inert unless the host also runs the scheduler (:28-38), and whose DataSource names the one engine the v1 read surface queries, defaulting to SQL Server because the table is relational (:40-46). Personal data never reaches the table: a property carrying PiiAttribute records PiiRedactor.RedactedToken on both sides, and the redaction happens at capture, not at read, so the trail cannot become a second copy of a data subject's personal data that erasure would have to chase (:37-41, applied at :309-310, ADR-005). The framework's own bookkeeping types are excluded by CLR type rather than by marker absence, which is what stops the trail from recording its own rows in an unbounded feedback loop (:106-118, checked at :225-228). And the correlation value it records is the ambient Activity trace id rather than a scoped correlation service, because a singleton interceptor holding a context built by the singleton physical factory cannot reach a scoped service without a lifetime bug; the doc comment says exactly that and names the accessor pattern tenancy introduced as the way to change it later (:43-53). The values every row of one save shares (user, instant, trace id, tenant) are gathered once into a CaptureContext record struct (:189-193, declared at :541), and a row describing an insert whose key the database has not assigned yet is parked as a PendingEntityKey (:550) until the store-generated key exists (:368-401). Two more types close the feature: AuditTrailReader (.../AuditTrail/AuditTrailReader.cs:35) serves paged history for one entity behind IAuditTrailReader and states its own v1 limitation, that it reads only the Default source's trail table (:17-24), and AuditTrailCleanupJob (.../AuditTrail/AuditTrailCleanupJob.cs:48) is the framework's own recurring IScheduledJob, purging rows past RetentionDays from every relational source nightly at 03:00 UTC in 1000-row batches that read ids first and delete them with ExecuteDelete (:58, :63, :67, :70-85, :150-176), expanding that source list through TenantDataSourceTargets so a tenant with its own database gets swept too (:83, per-tenant scope at :105-111). It only runs if the host also runs the scheduler, and a host that records the trail without one is fully supported: pruning is then the operator's job (:23-27).

Repositories, specifications, and the unit of work

Handlers do not touch a DbContext directly. They ask a UnitOfWork (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/UnitOfWork.cs:13) for a repository. The repository contract is deliberately interface-segregated (MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/IRepository.cs, the contract ADR-055 states): a handler that only needs a lookup can depend on the narrow IEntityReader<TEntity, TIdentifierType> (IRepository.cs:21) or IEntityQuerier<TEntity, TIdentifierType> (:80); IReadRepository<TEntity, TIdentifierType> (:330) combines both plus four IQueryable surfaces (tracking, no-tracking, single-query, split-query, :336-345), IWriteRepository<TEntity, TIdentifierType> (:367) adds mutation, and IRepository<TEntity, TIdentifierType> (:467) is the union. That layering is the group's clearest [Rubric §1, SOLID] (interface-segregation) statement, and ReadRepositoryExtensions (MMCA.Common/Source/Core/MMCA.Common.Application/Extensions/ReadRepositoryExtensions.cs:10) adds the GetByIdOrFailAsync convenience that turns a miss into a Result failure (:27-48). The concrete EFReadRepository<TEntity, TIdentifierType> (.../Repositories/EFReadRepository.cs:19) and EFRepository<TEntity, TIdentifierType> (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Repositories/EFRepository.cs:23) wrap an EF DbSet; the read side keeps its GROUP BY projections in the private GroupedCount<TKey> and GroupedSum<TKey> records (EFReadRepository.cs:180, :185) so the aggregation happens in the database rather than in memory. The write side patches already-tracked entities in place through an O(1) Local.FindEntry lookup instead of re-attaching (EFRepository.cs:52-64) and seeds RowVersion original values for optimistic concurrency on both the aggregate and any child implementing IRowVersioned (:74-93, ADR-035). Two set-based escape hatches sit beside the tracked path: ExecuteDeleteAsync, which the interface itself documents as bypassing domain events, audit stamps, and soft-delete (IRepository.cs:419-429), and ExecuteUpdateAsync (:431-453), the contention-proof conditional update whose guard predicate lets the database arbitrate two racing callers with no rowversion retry loop. The latter is described through the persistence-agnostic IUpdatePropertySetter<TEntity> surface and replayed onto EF's setters builder by UpdatePropertySetterBuilder<TEntity> (.../Repositories/UpdatePropertySetterBuilder.cs:14), which is what keeps EF Core out of the Application layer, and because ExecuteUpdate bypasses the interceptor pipeline the repository stamps LastModifiedOn/By itself unless the caller assigned them (EFRepository.cs:119-130).

The read repository does not compose queries by hand. SpecificationEvaluator (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Repositories/SpecificationEvaluator.cs:20) turns an ISpecification<TEntity, TIdentifierType> into an IQueryable: criteria always, then the includes, the OrderExpression chain, and the paging a QuerySpecification<TEntity, TIdentifierType> carries (:36-61), with the shape deliberately skipped for aggregate reads because joining includes to count rows costs a join per navigation (:22-26). Tracking and soft-delete scope are not its business: those choose the base queryable, which only the repository can do (:14-18). It also owns the one split-query heuristic in the framework, opting into AsSplitQuery as soon as any include targets a collection navigation (:86-93), and EFReadRepository.ApplyIncludes delegates to it so the string-include path and the specification path cannot drift (:65-70, EFReadRepository.cs:426-429). Cursor paging is the sibling helper: KeysetQueryBuilder (.../Repositories/KeysetQueryBuilder.cs:22) resolves the requested sort property or fails validation (:35), orders by (sortKey, Id) with the identifier tie-break that makes the order total (:59), and builds the composite seek predicate against the last row of the previous page (:102), so GetPageByCursorAsync (IRepository.cs:316, implemented at EFReadRepository.cs:496) seeks straight to the boundary instead of counting past every skipped row. Exactly one sort key is supported, by design (KeysetQueryBuilder.cs:17-20). That is [Rubric §12, Performance and Scalability] expressed as a contract rather than as advice.

Two factories keep the wiring honest. RepositoryFactory (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Repositories/Factory/RepositoryFactory.cs:15) builds a repository over a given context and conditionally wraps it in a MiniProfiler decorator (EFRepositoryDecorator<TEntity, TIdentifierType> or EFReadRepositoryDecorator<TEntity, TIdentifierType>) when UseMiniProfiler is on (:34-38, :58-62), adding timing without the base repository knowing, and it activates both through a cached compiled ObjectFactory rather than reflecting on every call (:70-84). DbContextFactory (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Factory/DbContextFactory.cs:39) is the scoped coordinator: it caches one ApplicationDbContext per DataSourceKey so every repository in a scope shares one change tracker (:87-118), gives each new context a live tenant accessor rather than a copied value (:129-140), and enlists a late-created context into an already-open transaction (:107-108). It is also the database-per-tenant routing point: when the scope's tenant overrides a source, the context is created against that tenant's connection string while keeping the original DataSourceKey, which is what lets one compiled model serve every tenant's database (:143-173), and a cached routed context is refused to a second tenant rather than silently serving the first tenant's rows (:176-198). Its save loop runs up to MaxSavePasses (3, :53) passes over the cached contexts, because dispatching events in-process can materialize a context for a source nobody had touched yet (:237-251), and it closes with a hard assertion: any context still reporting ChangeTracker.HasChanges() when the unit of work returns throws rather than silently discarding those changes (:259-269).

Because there can be more than one physical source in play, ExecuteInTransactionAsync (:499-544) runs the operation under the first transactional context's execution strategy, opens a transaction per source, and commits them sequentially with no two-phase commit (TryCommit at :621-660); cross-source consistency is the outbox's job, and the doc comment is explicit that a commit failure on the second source leaves the first one committed (:488-498). The method is re-entrant: a nested call joins the ambient transaction instead of opening a second one, so only the outermost call may begin, commit, roll back, or flush (:503-511). A returned failed Result rolls back exactly like an exception (:563-570), which is what makes ADR-013's Result-over-exceptions rule safe for partial persistence; rollback also drops the deferred event dispatch (:443-447), the deferred flush runs only after every commit has succeeded (:576-584), and a retry resets the change tracker first so the aborted attempt's Added entities are not inserted twice (ResetForRetry at :742-751). DbContextFactory further carries the SET IDENTITY_INSERT machinery (IdentityInsertGroup at :405, the per-table save split at :284-403) for importing entities with explicit database-generated ids one table at a time, and the MigrateAsync / HasPendingMigrationsAsync sweeps (:686-739) over every source whose resolved PhysicalDataSource.UsesMigrations says a migrations pipeline owns its schema (PhysicalDataSource.cs:48-54, target selection at DbContextFactory.cs:706-725).

UnitOfWork sits on top, resolving an entity's physical source through IDataSourceService, handing the matching context to the factory, and caching the resulting repository per closed generic interface type (UnitOfWork.cs:33-66). The physical creation itself runs through PhysicalDbContextFactory (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Factory/PhysicalDbContextFactory.cs:16), a singleton that switches on the key's engine to construct the right context class (:41-48) and whose doc comment warns it must never be pooled, because each instance carries per-source constructor state that pooling would smear across databases (:10-14). The interfaces (IUnitOfWork, IDbContextFactory, IPhysicalDbContextFactory, IRepositoryFactory) keep the application layer talking to abstractions. Every member of that factory family has its own section below, including the two types that exist only because of what the coordinator does: IdentityInsertGroup, the per-table batch the SET IDENTITY_INSERT loop saves one at a time, and TransactionCommitAmbiguousException (.../Factory/TransactionCommitAmbiguousException.cs:22), which the commit path raises when the commit itself fails with an outcome nobody can vouch for, naming each physical source's outcome (committed, ambiguous, or rolled back) so the partial state is observable rather than inferred (:57-70, DbContextFactory.cs:649-654). That exception is thrown outside the execution strategy on purpose (DbContextFactory.cs:536-542), because the strategy walks an exception's whole inner chain to decide retriability and would otherwise re-run the operation on top of a possibly-durable commit.

Routing an entity to its database

The heart of ADR-006 is that every entity resolves to a DataSourceKey (MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/DataSourceKey.cs:15), a (Engine, Name) record struct where the DataSource engine (MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/IDataSourceService.cs:6) is one of Cosmos DB, SQLite, or SQL Server, and Name is a physical database name defaulting to "Default" (DataSourceKey.cs:18-23). Two layers compute this. DataSourceResolver (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/DataSourceResolver.cs:15), the IDataSourceResolver singleton (.../DataSources/IDataSourceResolver.cs:15), builds the logical-to-physical map once per engine from configuration and hands out the resolved PhysicalDataSource (:89-102, :139-144). Named sources with no connection string, or whose connection identity equals the top-level one, collapse onto the Default source, so a host with no DataSources section behaves exactly like a single-database monolith (DataSourceResolver.cs:243-282), and sources sharing a connection identity collapse onto one canonical key named after their alphabetically-first member (:325-346, canonical name at :332). What the Default source is built from is itself resolved rather than assumed: the top-level ConnectionStrings section first, and when it names nothing for this engine while DataSources names exactly one database on it, that database becomes Default, which is what keeps the framework's own tables working in a host that declares its database only under DataSources (:198-233, captured in the private DefaultSeed record at :173). Identity is the connection string compared ordinally, with the Cosmos database name appended because one account hosts many databases (:447-450). The resolver fails fast when two logical names collapsing to one database declare conflicting migrations assemblies (:418-439) and logs a warning when a separate SQL Server source falls back to the Default migrations assembly (:340-346, message at :471). It also substitutes the host's own engine for a request naming an engine the host does not configure, in a fixed relational-first preference order (:26, :106-107), because every table the framework owns is relational and honoring an unconfigured engine literally handed those components an empty connection string.

What the resolver reads is two bound settings objects. ConnectionStringSettings (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/ConnectionStringSettings.cs:12) is the top-level ConnectionStrings section (:15): one connection string per engine plus the SQL Server migrations assembly, and deliberately no required property, because a host may run entirely on SQLite or Cosmos, or declare its databases only under DataSources (:5-10, :17-33). DataSourcesSettings (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/DataSourcesSettings.cs:13) is the named half, a dictionary keyed by logical source name (:16, :23-25) that AddInfrastructure builds directly from configuration rather than through the options pipeline, because a root-level dictionary section does not bind there (:8-11); it rejects an empty entry name and reserves Default, which is configured through the top-level section instead (:27-39). Each entry is a DataSourceEntrySettings (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/DataSourceEntrySettings.cs:19) whose properties are all optional and fall back to the corresponding top-level value, which is exactly the collapse-onto-Default behavior the resolver implements (:3-8). The one property with no top-level fallback is SqliteMigrationsAssembly: ConnectionStrings carries only the SQL Server migrations assembly, so a SQLite Default source declares its own through a collapsing entry, and a mixed-engine host cannot silently apply its SQL Server migrations assembly to a SQLite database (:30-43). Across both sections one rule is enforced at startup by ConnectionStringSettingsValidator (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/ConnectionStringSettingsValidator.cs:30), registered with ValidateOnStart: the host must be able to reach at least one database, top level or named, or it fails to boot with a message naming both configuration shapes (:38-43, :46-59). That rule replaced a [Required] annotation on the SQL Server connection string, which encoded "SQL Server is the only engine a host can boot on" and failed a SQLite-only host whose every entity resolved to a configured database (:10-24).

EntityDataSourceRegistry (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/EntityDataSourceRegistry.cs:21), also a singleton, scans the configuration assemblies and maps each entity to its physical key, deriving the engine from the UseDataSourceAttribute on the configuration class and the logical name from UseDatabaseAttribute, the entity's module namespace via NamespaceConventions.GetModuleName, or Default (EntityDataSourceRegistry.cs:172-185). It caches an immutable Snapshot of frozen collections built on first access (:25-28, :82-92, built at :115-160), rescans once on a lookup miss when the assembly set changed so late-loaded module assemblies are picked up (:95-113), rejects an entity claimed by two different sources (:141-149), and precomputes the distinct physical sources in use so the outbox processor's per-poll call allocates nothing (:75-80, :157-159). Because the registry reads the same attributes the model configuration reads, routing and model contents agree by construction, and configurations that implement a provider interface directly without the attributed base classes are deliberately skipped as legacy (:163-176). DataSourceService (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/DataSourceService.cs:11) is the thin application-facing facade over IEntityDataSourceRegistry, and it answers the one question navigation loading needs: two entities support EF .Include() only when their physical keys are equal and the engine is not Cosmos (DataSourceService.cs:30-31).

Two model-finalizing conventions

The base context adds both of its conventions in ConfigureConventions (ApplicationDbContext.cs:309-324), and each exists because a cross-cutting policy above would otherwise produce an invalid or surprising model. CrossDataSourceDegradeConvention (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Conventions/CrossDataSourceDegradeConvention.cs:33, added at ApplicationDbContext.cs:318) is what lets routing be lazy and attribute-driven and still produce a valid EF model. When a relationship's two ends live in different physical sources it removes the foreign key (a database cannot enforce an FK into another database), keeps the declared scalar FK columns plus a compensating index unless an existing index already covers them as a prefix, ignores the CLR navigation members, and drops the foreign entity types out of this database's model entirely (CrossDataSourceDegradeConvention.cs:38-89, :110-140). It works through EF's mutable model API rather than convention builders, because the soft-delete and concurrency helpers have already promoted every entity type to the Explicit configuration source (:22-24, :44-46), it eagerly drops the convention-created FK index before the coverage check so the column does not end up unindexed (:126-131), and it skips the compensating index on Cosmos, which auto-indexes everything and rejects explicit index definitions (:65, :118-121). Runtime navigation across sources then flows through the INavigationPopulator<in TEntity> batch-loading machinery in Group 11. Crucially, when every entity collapses onto one physical source (the monolith case) nothing is foreign and the convention returns early (:52-55), so the model is identical to the single-database model. That is the property that lets the same codebase run as a monolith today and as split services later without a rewrite, the core [Rubric §7, Microservices Readiness] claim.

SoftDeleteUniqueIndexConvention (.../Conventions/SoftDeleteUniqueIndexConvention.cs:33, added at ApplicationDbContext.cs:323) closes a smaller but sharper hole. Soft-delete hides a row from queries, but a plain unique index still enforces uniqueness against it, so "deleting" a speaker would permanently block re-creating one with the same email. The convention adds an IsDeleted = 0 filter to every unique index on a soft-deletable entity and extends rather than skips a hand-authored filter, appending its clause with AND so an index already narrowed on something else keeps its own predicate and still stops enforcing uniqueness against soft-deleted rows; a filter that already constrains the soft-delete column is left exactly as it is, so the append is idempotent (SoftDeleteUniqueIndexConvention.cs:36-81). It is a no-op for Cosmos (:41-42). The predicate text itself is not built inline: both this convention and the opt-in HasSoftDeleteFilter extension go through SoftDeleteFilterSql.Build (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/SoftDeleteFilterSql.cs:27-36), which reads the column name from the model and quotes it per engine (brackets for SQL Server, double quotes for SQLite, null for Cosmos), with a normalized comparison for the already-present check (:53-56), so the automatic and the hand-authored path can never disagree. IndexBuilderExtensions (.../Configuration/IndexBuilderExtensions.cs:10) is that opt-in half, an extension(IndexBuilder) block for the case the convention deliberately leaves alone: a hand-authored non-unique index that serves a live-row query and wants the same predicate (:12-65, with an optional additional predicate joined by AND at :60-64). Both conventions run at model finalization, after module configurations have declared their indexes and after EF's own relationship discovery, which is why they can see the finished picture.

Entity configuration and engine portability

Concrete entity configurations derive from the engine-aware EntityTypeConfiguration<TEntity, TIdentifierType> (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Configuration/EntityTypeConfiguration/EntityTypeConfiguration.cs:28) or, more commonly, one of the fixed-engine shims like EntityTypeConfigurationSQLServer<TEntity, TIdentifierType> (.../EntityTypeConfigurationSQLServer.cs:17), which is that base annotated [UseDataSource(DataSource.SQLServer)] (:16), with EntityTypeConfigurationSqlite<TEntity, TIdentifierType> (.../EntityTypeConfigurationSqlite.cs:17) and EntityTypeConfigurationCosmos<TEntity, TIdentifierType> (.../EntityTypeConfigurationCosmos.cs:18) as its two siblings. The base reads the attribute off its own runtime type and throws a clear error when it is missing (EntityTypeConfiguration.cs:43-46), then applies the engine's conventions in ApplyEngineConventions (:57-99): SQL Server gets a table in a module schema (:65-72), SQLite a plain table (:74-81), and Cosmos a per-module container with the entity id as partition key (:83-94), each mapping key generation according to the entity's EntityTypeExtensions.IsIdValueGenerated marker (:61): ValueGeneratedOnAdd for database identity, ValueGeneratedNever otherwise, or the CosmosIntIdValueGenerator for Cosmos, which has no server-side identity and increments a process-level counter seeded from the Unix timestamp (.../ValueGenerators/CosmosIntIdValueGenerator.cs:16-25). Because the engine is a single attribute and the base implements all three provider marker interfaces (IEntityTypeConfigurationSQLServer<TEntity, TIdentifierType>, IEntityTypeConfigurationSqlite<TEntity, TIdentifierType>, IEntityTypeConfigurationCosmos<TEntity, TIdentifierType>, all over the common IEntityTypeConfigurationBase<TEntity, TIdentifierType>), moving an entity between engines is a one-line attribute change with no configuration-body edits (EntityTypeConfiguration.cs:11-24). The shared EntityTypeConfigurationBase<TEntity, TIdentifierType> (.../EntityTypeConfigurationBase.cs:19) handles the one universal concern: excluding the in-memory DomainEvents collection from mapping (:25-32). Value objects reach the database through this layer too: EntityTypeBuilderExtensions (.../Configuration/EntityTypeBuilderExtensions.cs:12) flattens a Money into an amount plus a three-character non-Unicode ISO 4217 code column with a read-leg fallback to the zero-Money sentinel Currency (:19, mapping at :62-77, fallback at :71); the four converters in Persistence/Conversions map Email and PhoneNumber to plain strings in required (EmailValueConverter at .../Conversions/EmailValueConverter.cs:33, PhoneNumberValueConverter at .../Conversions/PhoneNumberValueConverter.cs:33) and optional (NullableEmailValueConverter at EmailValueConverter.cs:60, NullablePhoneNumberValueConverter at PhoneNumberValueConverter.cs:61) flavors; and EnumerationValueConverter<TEnumeration> (.../Conversions/EnumerationValueConverter.cs:33) plus its nullable sibling NullableEnumerationValueConverter<TEnumeration> (:62) store a smart enumeration as its plain int value, so replacing a CLR enum property with an enumeration is not a schema change.

Discovery runs through ModelBuilderExtensions.ApplyAllConfigurations (.../DbContexts/ModelBuilderExtensions.cs:10, an extension(ModelBuilder) block at :12), which the base calls with an entity filter so each database's model receives only its own entities (ApplicationDbContext.cs:690-717, filter application at ModelBuilderExtensions.cs:57-60), over the assemblies supplied by IEntityConfigurationAssemblyProvider and its DefaultEntityConfigurationAssemblyProvider implementation (.../Persistence/DefaultEntityConfigurationAssemblyProvider.cs:12), which scans loaded *.Infrastructure assemblies, excludes Common.Infrastructure itself, and appends whatever a host registered through EntityConfigurationOptions (DefaultEntityConfigurationAssemblyProvider.cs:16-21, options at .../Persistence/EntityConfigurationOptions.cs:10). Two configurations ship inside the framework itself, PushNotificationConfiguration and UserNotificationConfiguration (.../Configuration/EntityTypeConfiguration/Notifications/PushNotificationConfiguration.cs:16, .../UserNotificationConfiguration.cs:15), both tagged [UseDatabase("Notification")] and re-declaring the Notification schema because namespace derivation would otherwise resolve them to Common (PushNotificationConfiguration.cs:8-15, :25). This engine-portability design is ADR-018 (polyglot persistence); note the current-reality caveat: the SQLite and Cosmos plumbing is shipped and tested, but every concrete subclass of the SQLite and Cosmos configuration bases lives in Common's own test projects, so SQL Server is the only engine backing production entities today.

Refresh sessions, a table one database owns

Multi-device refresh sessions (ADR-097) are the one framework table that is deliberately not cross-cutting. RefreshSessionModelBuilderExtensions (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Auth/RefreshSessionModelBuilderExtensions.cs:16) maps the RefreshSession table on request rather than everywhere, and the doc comment gives the reason: the outbox is infrastructure every relational source needs, while refresh sessions are Identity-module data that exactly one database owns, so mapping them everywhere would leave an empty RefreshSessions table in every other module's migrations (:6-14). It maps the token hash as a fixed-width non-Unicode column, uniquely indexed because that is the lookup a refresh answers and because a collision across users would let one account's token validate against another's session (:44-49, :60-66), plus a (UserId, RevokedAt) index for the per-user family questions the session cap, reuse detection and sign-out-everywhere all ask (:68-71). The base context calls it from the gated ConfigureRefreshSessions (ApplicationDbContext.cs:673-681) precisely because a downstream app runs on the sealed engine contexts and has no OnModelCreating of its own to override. EFRefreshSessionStore (.../Auth/EFRefreshSessionStore.cs:30) is the IRefreshSessionStore implementation over that table; it resolves which database holds it the same way the rest of the framework routes an entity (the registry first, then RefreshSessions:DataSourceName, :6-15) and reads tracked on purpose, because the caller revokes by mutating the instances it hands back (:16-19). RefreshSessionCleanupService (.../Auth/RefreshSessionCleanupService.cs:48) hard-deletes spent rows past RetentionDays: the row is bookkeeping, not an aggregate, and its content is a credential digest plus the IP and user agent of a device, so keeping it past its usefulness is both a growing table and a growing set of records describing a data subject (ADR-005, :8-16). Its own doc comment names the trade the retention window makes: a rotation chain older than the window is gone, so a replay of a token that old reads as an unknown token instead of signalling reuse (:17-23). That is [Rubric §11, Security] meeting [Rubric §30, Compliance and Data Governance] again, in a table rather than in an interceptor.

Encryption, seeding, design time, and the shared helpers

A handful of supporting pieces round out the EF side. EncryptedStringConverter (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Encryption/EncryptedStringConverter.cs:72) is a value converter that transparently encrypts a string column with authenticated AES-256-GCM. The stored value is a versioned Base64 envelope, a one-byte key version, a random 12-byte nonce, the ciphertext, then a 16-byte tag, with the version byte passed to AES-GCM as associated data so it is covered by the authentication tag and a rewritten version byte fails decryption instead of silently selecting a different key (:38-44, envelope assembled at :204-210). A converter is built over either a single key, registered as version 1 (:94-97), or a whole key ring plus a current version so reads resolve their key from the version byte stored with each value and rotation needs no downtime (:109-112), and it rejects any key that is not exactly 32 bytes on both paths (:127-141, :146-181). Its own doc comment states the constraint that governs where it may be used: the ciphertext is non-deterministic, so the column cannot back equality predicates, unique indexes, or server-side sorting (:19-32). It is the [Rubric §11, Security] control that IAnonymizable points at for fields that must remain retrievable after erasure. Its current reality matches ADR-037: it is shipped and unit-tested but unadopted, no entity configuration wires it (the only non-test references are its own file and the IAnonymizable doc comment). On the read side, IQueryableExecutor and its implementation EFQueryableExecutor (.../Persistence/EFQueryableExecutor.cs:11) abstract async query materialization so higher layers can execute an IQueryable without referencing EF, detecting a real EF query by its IAsyncEnumerable<T> implementation and degrading to LINQ-to-Objects otherwise (EFQueryableExecutor.cs:43). That is what makes the specification evaluation in Group 03 unit-testable without a database, a small but real [Rubric §14, Testability] win. Two more helpers sit at this level: SqlServerUniqueConstraintViolationDetector (.../Persistence/SqlServerUniqueConstraintViolationDetector.cs:31) is the IUniqueConstraintViolationDetector implementation that classifies a duplicate-key failure by SQL Server error number 2601 or 2627, walking the whole inner-exception chain and falling back to the message text so a wrapped or non-SQL-Server provider failure still classifies (:34-40, :47-73); and ProfilingHelper (.../Persistence/ProfilingHelper.cs:9) is the MiniProfiler step wrapper the repository decorators share (:11-31). The framework's shared base for fixed-interval sweeps, PeriodicBackgroundService, is a scheduling type documented in Group 14, and ADR-052 covers in-process background work generally.

Seeding and design time close the loop. IDbSeeder (.../Seeding/IDbSeeder.cs:7) and the DbSeeder base (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Seeding/DbSeeder.cs:7) give module seeders a GetId<TIdentifier> helper that maps integer seed ids to either int or a deterministic Guid so seed data reproduces across key strategies (:20-39), and IdentityModuleDbSeederBase<TUser> (.../Seeding/IdentityModuleDbSeederBase.cs:38) hoists the repeated account-seeding idiom out of the two app identity modules, leaving only app-specific hooks and a ShouldSeed opt-in gate that defaults to true (:44, :48, :57, :60-71), each account described by a SeedAccount record (.../Seeding/SeedAccount.cs:17) whose own remarks warn that seed credentials are plaintext by construction and therefore development-only data (:6-11). For migrations, DesignTimeDbContextHelper (.../DbContexts/Design/DesignTimeDbContextHelper.cs:41) builds a SQLServerDbContext for dotnet ef without the app's DI container: a downstream migrations project writes a few-line IDesignTimeDbContextFactory (:18-32, entry points at :50 and the SQLite twin at :71), and dotnet ef migrations add X -- --datasource Conference selects which physical source to build against (:165-181), so each database gets its own migrations project. It composes minimal stand-ins (ExplicitAssemblyProvider at :185, NullDomainEventDispatcher at :190) and a DesignTimeDbContextOptions (.../Design/DesignTimeDbContextOptions.cs:11) carrying the connection settings, then wires the same DataSourceResolver and EntityDataSourceRegistry the runtime uses so the design-time model matches the runtime one (:105-157). It registers the tenant interceptor, the scheduler options, the audit-trail options and the refresh-session options unconditionally, defaulted to disabled, precisely so dotnet ef scaffolds the same migration for consumers with and without those features (:126-154), and the refresh-session registration carries the extra twist that its gate is source-sensitive, so the source name it registers is the one this context resolved to (:144-154).

The storage, image, and push contracts

The group also carries the Application-layer contracts for the storage-adjacent services that are not EF at all. Each has a null default in the container so a host that has not configured the backend still starts and degrades cleanly, and the Azure, ImageSharp, and null implementations behind them are composition-side types documented in Group 14. IFileStorageService (MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Storage/IFileStorageService.cs:11) stores and deletes blobs behind a Result-returning API and exposes an IsConfigured flag handlers can gate features on (:14). IImageProcessor (MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Storage/IImageProcessor.cs:11) is the normalization contract for untrusted uploads, and the dependency-free ImageContentSniffer (MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Storage/ImageContentSniffer.cs:10) is its upload-side companion, deciding the accepted formats (JPEG, PNG, WebP) from magic bytes rather than the client-declared content type (:14-36). Both are ADR-045, and both are squarely [Rubric §11, Security] (EXIF GPS is PII, and a full re-encode is the defense against polyglot payloads). On the push side, INativePushSender (MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Notifications/INativePushSender.cs:10) and IPushDeviceRegistrar (MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Notifications/IPushDeviceRegistrar.cs:11) describe OS-level delivery and the device-installation registry that backs it (ADR-044). This channel sits beside the persisted notification record and the SignalR path in Group 10.

One more Application interface sits in this group's persistence namespace without being repository-shaped at all. IOutboxAdministration (MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/IOutboxAdministration.cs:16) is the operator surface that gives an undelivered event a way back into delivery, projecting each abandoned row into an OutboxDeadLetter record (:80) that deliberately omits the payload, because it can carry personal data and no replay decision depends on reading it (:69-79). It is [Rubric §13, Observability and Operability] material; the rows it administers are written by this group's domain-event interceptor and delivered by the processor and consumers in Group 04.

Where this group sits

Persistence is the concrete floor the abstract domain stands on. The entity bases and audit contracts from Group 02 are what the interceptors stamp and the query filters hide; the domain events aggregates raise are what DomainEventSaveChangesInterceptor drains into the outbox that Group 04 delivers; the transactional decorator in Group 05 is what opens the transaction whose commit releases the deferred dispatch; the specifications and query service in Group 03 are evaluated by this group's SpecificationEvaluator against its repositories and IQueryable surfaces; the refresh-session table this group maps is read and written by the auth stack in Group 08; the navigation populators in Group 11 fill the cross-source gaps the degrade convention opens; the scheduler this group's gated tables answer to lives in Group 14, which also composes the storage, push, and event-consumer implementations behind the contracts this group declares; and the entity-source registry answers the .Include() questions the populators ask. The design axes here are three orthogonal ones collapsed behind a single DataSourceKey plus a scoped tenant: ADR-006's Name axis (which database), ADR-018's Engine axis (which storage technology), and ADR-073's tenant axis (whose rows, and optionally whose database), so application code never has to know which it is running on. Read this group as the answer to one question the rest of the guide keeps asking: how does a framework that describes persistence in pure domain terms actually put a row in a database, and do it in a way that survives a module being pulled out into its own service.

INativePushSender

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Notifications · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Notifications/INativePushSender.cs:10 · Level 0 · interface

• What it is: the contract for sending OS-level push notifications to registered device installations, the delivery channel that reaches a phone when the app is backgrounded or killed.
• Depends on: the UserIdentifierType global alias (INativePushSender.cs:19, see primer §2); BCL otherwise. Its registry counterpart is IPushDeviceRegistrar.
• Concept introduced, native push as the third delivery channel. [Rubric §6, CQRS & Event-Driven Design] assesses whether a delivery mechanism is a swappable abstraction declared in Application and implemented at the edge rather than a hardcoded SDK call inside a handler. The doc comment (INativePushSender.cs:3-9) places this beside the two other channels under ADR-044: the persisted inbox record and the SignalR real-time push handled by IPushNotificationSender. Where SignalR reaches a connected browser, native push reaches a device that is not running the app. Infrastructure targets Azure Notification Hubs (FCM v1 plus APNs), and the default registration is a no-op, so a host that never configures a hub degrades cleanly instead of failing.
• Walkthrough: two methods, both returning a plain Task rather than a Result, because a push is fire-and-forget from the caller's point of view.
  • SendToUsersAsync(IEnumerable<UserIdentifierType> userIds, string title, string body, Dictionary<string, string>? metadata = null, CancellationToken cancellationToken = default) (INativePushSender.cs:19): targets specific users, resolved to installations via user tags (INativePushSender.cs:13); metadata carries optional key-value data such as a deep-link route in the platform payload (INativePushSender.cs:16).
  • BroadcastAsync(string title, string body, Dictionary<string, string>? metadata = null, CancellationToken cancellationToken = default) (INativePushSender.cs:27): sends to every registered installation.
• Why it's built this way: targeting users rather than raw device tokens keeps the caller out of the tag and token bookkeeping, which IPushDeviceRegistrar owns; the no-op default makes native push an opt-in capability rather than a hard dependency of every host.
• Where it's used: injected into SendPushNotificationHandler (MMCA.Common/Source/Core/MMCA.Common.Application/Notifications/PushNotifications/UseCases/Send/SendPushNotificationHandler.cs:31) alongside the SignalR sender. NullNativePushSender is registered by default with TryAddTransient (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:579) and AzureNotificationHubNativePushSender replaces it when a hub is configured (DependencyInjection.cs:678).

IPushDeviceRegistrar

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Notifications · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Notifications/IPushDeviceRegistrar.cs:11 · Level 3 · interface

• What it is: maintains the device-installation registry behind INativePushSender, tagging each installation with its owning user so sends can target users rather than raw device tokens.
• Depends on: Result (via MMCA.Common.Shared.Abstractions, IPushDeviceRegistrar.cs:1), DeviceInstallationRequest (from MMCA.Common.Shared.Notifications.PushNotifications, IPushDeviceRegistrar.cs:2), and the UserIdentifierType alias (IPushDeviceRegistrar.cs:18).
• Concept introduced, ownership scoping on a client-supplied identifier, and the existence-oracle problem. [Rubric §11, Security] assesses whether a resource identifier supplied by a caller is authorized against that caller before it is acted on, and whether error responses leak the existence of other users' resources. Installation ids are client-generated, so nothing stops a caller from sending someone else's; the delete verifies the user:{id} tag stamped by UpsertAsync before deleting, and reports a mismatch as success rather than not-found, because answering differently for "no such installation" and "not yours" would turn the endpoint into an existence oracle for other users' installation ids, and the caller has nothing to do with either answer (IPushDeviceRegistrar.cs:28-36). The stronger property is structural: every delete is scoped to an owner, there is no unscoped form, so an implementation cannot skip the check by accident (IPushDeviceRegistrar.cs:31-32). [Rubric §6, CQRS & Event-Driven Design] also applies: the type doc (IPushDeviceRegistrar.cs:6-10, ADR-044) explains the split, where this type owns the installation registry, tagged by user, so INativePushSender can send to users, and the default implementation is a no-op until a notification hub is configured.
• Walkthrough: two methods, both returning Result.
  • UpsertAsync(UserIdentifierType userId, DeviceInstallationRequest request, CancellationToken cancellationToken = default) (IPushDeviceRegistrar.cs:18): creates or refreshes an installation, tagging it with the authenticated owner (IPushDeviceRegistrar.cs:13-14).
  • DeleteAsync(UserIdentifierType userId, string installationId, CancellationToken cancellationToken = default) (IPushDeviceRegistrar.cs:37): the ownership-scoped delete, and the only delete. Unknown installation ids and installations owned by another user both succeed without deleting anything (IPushDeviceRegistrar.cs:20-23).
• Why it's built this way: separating the registry (this type) from the send (INativePushSender) means the send API can target users while token bookkeeping stays in one place. Making the owner a required parameter of the only delete member is what removes the class of bug where a caller passes a raw client-supplied id straight through: there is no overload to pass it to.
• Where it's used: DevicesController injects it (MMCA.Common/Source/Presentation/MMCA.Common.API/Controllers/Notifications/DevicesController.cs:27) and passes the authenticated user id on both calls, UpsertAsync at DevicesController.cs:44 and DeleteAsync at DevicesController.cs:68. NullPushDeviceRegistrar is the default registration (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:580); AzureNotificationHubDeviceRegistrar replaces it when a hub is configured (DependencyInjection.cs:679).

DataSource

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/IDataSourceService.cs:6 · Level 0 · enum

• What it is: a three-value enum (CosmosDB, Sqlite, SQLServer) naming which database engine persists a given entity type. It shares a file with IDataSourceService: the enum at IDataSourceService.cs:6, the interface at IDataSourceService.cs:24.
• Depends on: nothing first-party. The file has no using directives at all (IDataSourceService.cs:1 is the namespace declaration), which is the point: this is the Application layer's vocabulary for a persistence decision, with no persistence library behind it.
• Concept introduced, database-per-service routing at the entity level. [Rubric §8, Data Architecture] assesses whether storage is deliberately partitioned, whether the routing strategy is explicit, and whether cross-database JOINs happen by accident; this enum is where that decision becomes a first-class value the query pipeline can branch on. [Rubric §7, Microservices Readiness] assesses whether a module could be lifted out without a rewrite; because each module owns its own store (ADR-006), the engine is a per-entity fact rather than a global one. The values encode a capability, not just a name: the CosmosDB doc comment says "document store, no cross-container JOINs" (IDataSourceService.cs:8), while Sqlite supports "JOINs within a single database file" (IDataSourceService.cs:11) and SQLServer has "full relational JOIN support" (IDataSourceService.cs:14). That distinction is what lets the framework decide whether a navigation can be an EF .Include() or must become a manual batch load.
• Walkthrough: three members, each documented with its JOIN capability. CosmosDB (IDataSourceService.cs:9), Sqlite (IDataSourceService.cs:12), SQLServer (IDataSourceService.cs:15). There is no None/Unknown member and no explicit numeric assignment, so CosmosDB is the default 0 value.
• Why it's built this way: encoding the JOIN-capability difference in the enum lets IDataSourceService.HaveIncludeSupport (IDataSourceService.cs:54) answer the include-versus-batch-load question from a value comparison rather than a scattered chain of provider checks, and it keeps that decision in the framework-pure Application layer with no EF Core reference.
• Where it's used: paired with a database name in DataSourceKey (DataSourceKey.cs:15); resolved and compared by IDataSourceService; mapped per entity by EntityDataSourceRegistry; consumed by NavigationMetadataProvider to classify each navigation as an EF include or a manual populate.

IEntityConfigurationAssemblyProvider

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/IEntityConfigurationAssemblyProvider.cs:10 · Level 0 · interface

• What it is: a single-method contract returning the assemblies that hold EF Core entity type configurations, so a DbContext can discover and apply them without hardcoding module assembly-name patterns.
• Depends on: System.Reflection (BCL) only (IEntityConfigurationAssemblyProvider.cs:1).
• Concept introduced, a module-agnostic model surface that keeps EF out of Application. [Rubric §3, Clean Architecture] assesses whether the inner layers declare intent while the outer layers own the technology; here Application declares which assemblies carry configurations and Infrastructure performs the EF scan. [Rubric §7, Microservices Readiness] assesses extraction cost: each module ships its own IEntityTypeConfiguration<T> classes in its own Infrastructure assembly, so removing a module from the returned list removes it from the model, no context rewrite required. The doc comment states exactly this framing (IEntityConfigurationAssemblyProvider.cs:5-9).
• Walkthrough: one method, IReadOnlyList<Assembly> GetConfigurationAssemblies() (IEntityConfigurationAssemblyProvider.cs:15). It takes no arguments and no cancellation token: the assembly set is a composition-time fact, resolved once, not a per-request query.
• Why it's built this way: routing configuration discovery through an injected provider means the active module set determines the model without any context knowing a module by name, which is the extraction invariant behind ADR-006 and ADR-007.
• Where it's used: injected into ApplicationDbContext (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/ApplicationDbContext.cs:44) and each engine subclass (SQLServerDbContext at SQLServerDbContext.cs:18, CosmosDbContext at CosmosDbContext.cs:17, SqliteDbContext at SqliteDbContext.cs:15); consumed by EntityDataSourceRegistry to build the entity-to-source map (EntityDataSourceRegistry.cs:22) and by PhysicalDbContextFactory (PhysicalDbContextFactory.cs:19). The default implementation DefaultEntityConfigurationAssemblyProvider is registered with TryAddSingleton (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:65), and DesignTimeDbContextHelper substitutes its own nested ExplicitAssemblyProvider for dotnet ef runs (DesignTimeDbContextHelper.cs:156 and :185).

IQueryableExecutor

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/IQueryableExecutor.cs:7 · Level 0 · interface

• What it is: an abstraction over the EF Core IQueryable operations the Application layer needs (Include, AsSplitQuery, ToListAsync, CountAsync) that would otherwise require a direct Microsoft.EntityFrameworkCore reference there.
• Depends on: System.Linq (BCL) only; the file declares no using directives.
• Concept introduced, inverting EF's terminal operators out of Application. [Rubric §3, Clean Architecture] assesses whether the inner layers stay free of framework dependencies; EF's async materializers (ToListAsync, CountAsync) and Include are extension methods living in the EF assembly, so calling them directly would drag EF into Application. This interface inverts that: Infrastructure implements each by calling EF, and Application receives the interface by DI. The doc comment (IQueryableExecutor.cs:3-6) states exactly that intent.
• Walkthrough: four methods; the two queryable transforms are constrained where T : class (IQueryableExecutor.cs:15 and :27) because EF requires a reference type there, while the two materializers accept any T so a projection to a scalar or DTO still works.
  • Include<T>(IQueryable<T> query, string navigationPropertyPath) (IQueryableExecutor.cs:14): a string-based include path, for example "Category" or "Order.OrderLines" (IQueryableExecutor.cs:12), deliberately not a lambda, because the generic query pipeline builds include paths at runtime from navigation-property name strings.
  • AsSplitQuery<T>(IQueryable<T> query) (IQueryableExecutor.cs:26): switches EF to split-query mode. The doc comment (IQueryableExecutor.cs:17-22) explains why it matters: paginating (Skip/Take) a query that has collection includes in single-query mode truncates or mis-correlates child rows, so list reads come back with empty collections. It is documented as a no-op for non-EF (in-memory) queryables.
  • ToListAsync<T>(IQueryable<T> query, CancellationToken cancellationToken = default) (IQueryableExecutor.cs:34) and CountAsync<T>(IQueryable<T> query, CancellationToken cancellationToken = default) (IQueryableExecutor.cs:41): the async materializers.
• Why it's built this way: the string include path (rather than Expression<Func<T, TProperty>>) is required because the query pipeline composes includes from runtime navigation metadata, not compile-time lambdas; and naming AsSplitQuery as an explicit operation keeps a well-known EF pagination defect from silently reaching list endpoints.
• Where it's used: implemented by EFQueryableExecutor (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/EFQueryableExecutor.cs:11), registered with TryAddSingleton (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:112). Injected into EntityQueryPipeline (MMCA.Common/Source/Core/MMCA.Common.Application/Services/Query/EntityQueryPipeline.cs:13) and into the framework's own notification handlers, for example GetMyNotificationsHandler (GetMyNotificationsHandler.cs:18).

IUniqueConstraintViolationDetector

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/IUniqueConstraintViolationDetector.cs:31 · Level 0 · interface

• What it is: a one-method classifier that answers whether a failed save was rejected for violating a unique constraint, so a handler whose pre-check lost a race against a concurrent insert can recognise the collision and return the same conflict the pre-check would have produced.
• Depends on: nothing first-party. The file has no using directives at all, and the single method takes a BCL Exception (IUniqueConstraintViolationDetector.cs:42).
• Concept introduced, classifying a provider error without naming the provider. [Rubric §3, Clean Architecture] assesses whether technology details stay outside the inner layers, and the interface remarks make the constraint concrete (IUniqueConstraintViolationDetector.cs:10-20): the error identity lives in a provider type, SQL Server reports the collision as SqlException.Number 2601 (unique index) or 2627 (primary key or unique constraint), and neither that type nor the EF Core DbUpdateException wrapping it is reachable from MMCA.Common.Application, which references MMCA.Common.Domain and no data provider. [Rubric §15, Best Practices & Code Quality] assesses whether a behavior rests on something stable: reading the exception message from a handler is what the layering constraint used to force, and the remarks reject it twice over, because the wording is a provider and locale detail that can change under a working handler, and matching on it drags provider vocabulary into a persistence-neutral layer. [Rubric §29, Resilience & Business Continuity] applies to the failure mode chosen here: an unclassified exception simply propagates, so a miss is safe rather than silent and the caller sees exactly the failure it would have seen with no detection at all (IUniqueConstraintViolationDetector.cs:26-29).
• Walkthrough: one method, bool IsUniqueConstraintViolation(Exception exception) (IUniqueConstraintViolationDetector.cs:42). The contract is stated on the parameter rather than left to the implementation: the answer covers exception or anything in its inner-exception chain (IUniqueConstraintViolationDetector.cs:33-41), which is what makes it usable against EF's wrapping exception. It is synchronous and takes no cancellation token, because it inspects an object already in hand.
• Why it's built this way: the question is declared in Application and answered in Infrastructure, where the provider types are already referenced, so swapping engines swaps the implementation and every handler that recovers from a lost insert race keeps working unchanged (IUniqueConstraintViolationDetector.cs:21-25).
• Where it's used: implemented by SqlServerUniqueConstraintViolationDetector (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/SqlServerUniqueConstraintViolationDetector.cs:31), which walks the inner-exception chain (SqlServerUniqueConstraintViolationDetector.cs:48-68) matching the two error numbers (:34 and :37) with a message fallback for engines that report the same rejection in words (:40, :43, matched at :63-64). It is registered with TryAddSingleton (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:117), deliberately TryAdd so a host on another engine can register its own implementation first and keep it (DependencyInjection.cs:114-116). Consumers inject it into the when clause of a catch: GetOrCreateMyBadgeHandler (MMCA.ADC/Source/Modules/Engagement/MMCA.ADC.Engagement.Application/CheckIns/UseCases/GetOrCreateMyBadge/GetOrCreateMyBadgeHandler.cs:21 and :53), CreateSessionHandler (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.Application/Sessions/UseCases/Create/CreateSessionHandler.cs:27 and :60, where the catch drives a bounded manual-id retry), CreateBookmarkHandler (CreateBookmarkHandler.cs:21), SetLeaderboardParticipationHandler (SetLeaderboardParticipationHandler.cs:34), and PointsAwarder (PointsAwarder.cs:32). The framework-level registration replaced per-module copies: the ADC Conference module records that it no longer carries its own pair (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.Infrastructure/DependencyInjection.cs:25).

IUpdatePropertySetter<TEntity>

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/IUpdatePropertySetter.cs:13 · Level 0 · interface

• What it is: a persistence-agnostic builder for the SET clause of a bulk update. A handler describes which properties change and to what, and Infrastructure translates the description into the provider's set-based UPDATE.
• Depends on: System.Linq.Expressions (BCL, IUpdatePropertySetter.cs:1) only. It is the parameter type of IWriteRepository.ExecuteUpdateAsync (IRepository.cs:450), which the doc comment cross-references (IUpdatePropertySetter.cs:7).
• Concept introduced, describing a SET clause without leaking EF Core. [Rubric §3, Clean Architecture] assesses whether the technology choice stays outside the inner layers; [Rubric §12, Performance & Scalability] assesses whether hot write paths avoid needless round trips, and a single set-based statement replaces the load, mutate, save cycle. The doc comment (IUpdatePropertySetter.cs:5-11) is explicit that the shape mirrors EF Core's SetPropertyCalls without referencing it, which is what keeps MMCA.Common.Application EF-free while still offering EF's most useful bulk primitive.
• Walkthrough: two Set overloads, both generic in TProperty and both returning IUpdatePropertySetter<TEntity> so calls chain.
  • Set<TProperty>(Expression<Func<TEntity, TProperty>> property, TProperty value) (IUpdatePropertySetter.cs:20-22): assigns a fixed value, for example a status or a timestamp.
  • Set<TProperty>(Expression<Func<TEntity, TProperty>> property, Expression<Func<TEntity, TProperty>> valueFactory) (IUpdatePropertySetter.cs:33-35): assigns from an expression over the current database row. The doc comment (IUpdatePropertySetter.cs:24-28) gives the motivating case, quantity => quantity.Amount - 5, which becomes an atomic read-modify-write that the database itself arbitrates, so two racing callers cannot both win and no rowversion retry loop is needed.
• Why it's built this way: passing an Action<IUpdatePropertySetter<TEntity>> (rather than a dictionary of property names or a prebuilt EF expression) keeps the call site strongly typed and refactor-safe while the concrete translation stays swappable per provider.
• Where it's used: implemented by UpdatePropertySetterBuilder<TEntity> (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Repositories/UpdatePropertySetterBuilder.cs:14), which collects each assignment as a delegate (UpdatePropertySetterBuilder.cs:16) and replays them onto EF Core's UpdateSettersBuilder<TSource> (UpdatePropertySetterBuilder.cs:52). It also records assigned property names (UpdatePropertySetterBuilder.cs:17 and :64) and exposes SetsProperty (UpdatePropertySetterBuilder.cs:49) so EFRepository<TEntity, TIdentifierType> can stamp LastModifiedOn and LastModifiedBy only when the caller did not (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Repositories/EFRepository.cs:121-132), keeping audit fields correct on a path that bypasses the save pipeline (EFRepository.cs:19).

OutboxDeadLetter

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/IOutboxAdministration.cs:80 · Level 0 · record (sealed, positional)

• What it is: one dead-lettered outbox row flattened for an operator view: the handle to replay it, which source it came from, what it was, when it happened, how hard delivery was tried, and why the last attempt failed.
• Depends on: nothing first-party (BCL Guid and DateTime). It is the element type returned by IOutboxAdministration.ListDeadLettersAsync (IOutboxAdministration.cs:30) and it shares that interface's file.
• Concept introduced, projecting an operational row without projecting its payload. [Rubric §30, Compliance, Privacy & Data Governance] assesses whether personal data is exposed only where it is needed; the type doc says outright that the event PAYLOAD is deliberately not projected, because it can carry personal data (ADR-005) and nothing an operator decides about a replay depends on reading it (IOutboxAdministration.cs:68-72). [Rubric §13, Observability & Operability] assesses whether an operator can see enough to act: RetryCount and LastError are what turn "this failed" into a decision, and OrderingKey says whether the row belongs to an ordered stream. See OutboxMessage for the persisted row this flattens.
• Walkthrough: seven positional members, each documented on the record (IOutboxAdministration.cs:73-79): Id (:81), the outbox row id and the handle ReplayDeadLettersAsync takes; DataSource (:82), the source whose outbox table holds the row, and the same string the dataSource filters accept; EventType (:83), the stored event type name; OccurredOn (:84); RetryCount (:85), attempts made before the row was abandoned; the nullable LastError (:86) and nullable OrderingKey (:87).
• Why it's built this way: a positional record gives an immutable, structurally comparable read model for free, and keeping it in the Application layer beside its interface means an admin surface can render dead letters without referencing the EF entity or the Infrastructure assembly.
• Where it's used: built by the Infrastructure implementation's projection (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Outbox/Administration/OutboxAdministration.cs:92), from rows matching the dead-letter predicate ProcessedOn == null && RetryCount >= maxRetries (OutboxAdministration.cs:88), collected across sources and returned oldest first (OutboxAdministration.cs:107).

DataSourceKey

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/DataSourceKey.cs:15 · Level 1 · record struct (readonly)

• What it is: the identity of a physical data source, a (DataSource Engine, string Name) pair, where Name distinguishes multiple databases on the same engine ("database per microservice").
• Depends on: DataSource (Level 0, same namespace). No using directives at all.
• Concept, physical-key comparison as the include-support test. [Rubric §8, Data Architecture] assesses explicit storage partitioning and routing. A readonly record struct gives correct structural equality with zero boilerplate, which is the whole point: Application code that needs to know whether two entities can be joined compares their DataSourceKey values. The doc comment (DataSourceKey.cs:6-11) stresses that Name is the physical source name produced by the Infrastructure resolver after collapsing logical names that share a connection string, so two logical names pointing at the same connection string end up with the same physical key (and are joinable), while genuinely distinct databases do not.
• Walkthrough
  • The positional record DataSourceKey(DataSource Engine, string Name) (DataSourceKey.cs:15), parameters documented at DataSourceKey.cs:13-14.
  • DefaultName (DataSourceKey.cs:18): the const string "Default" reserved for the top-level ConnectionStrings section.
  • Default(DataSource engine) (DataSourceKey.cs:23): a static factory building the default key for an engine.
  • ToString() (DataSourceKey.cs:26): an override rendering "{Engine}/{Name}" for diagnostics.
• Why it's built this way: making the key a value type with structural equality reduces the routing decision (same physical database, relational engine) to an equality comparison, and a host with no DataSources configuration collapses everything onto Default and behaves like a single-database monolith (ADR-006).
• Where it's used: EntityDataSourceRegistry maps each entity type to a key and DataSourceResolver performs the logical-to-physical collapse; IDataSourceService resolves and compares them; DbContextFactory caches one context instance per key.

IDataSourceService

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/IDataSourceService.cs:24 · Level 2 · interface

• What it is: resolves which physical data source (DataSourceKey: engine plus database) backs a given entity type, and determines whether two entity types support EF Core .Include() between them, all without the Application layer touching EF or Infrastructure.
• Depends on: DataSource (Level 0) and DataSourceKey (Level 1), both in the same namespace.
• Concept introduced, multi-database routing exposed to the Application layer. [Rubric §8, Data Architecture] assesses deliberate database-per-service design, explicit routing, and the absence of accidental cross-database JOINs. The layer must decide whether a navigation between two entities can use an EF .Include(), which is valid only when both entities live in the same physical database and that engine is relational. This interface answers that question without an EF reference, keeping Application pure (ADR-006). The doc comment names the consumer directly (IDataSourceService.cs:18-23): NavigationMetadataProvider uses it to classify navigation properties as supported or unsupported includes.
• Walkthrough: six members across three concerns, every one of them synchronous, because the resolution is a lookup against an eagerly built registry, not I/O.
  • GetDataSourceKey(Type entityType) (IDataSourceService.cs:29) and GetDataSourceKey(string entityFullName) (IDataSourceService.cs:34): resolve the physical key by CLR type or by full type name (the name overload exists because navigation metadata carries names, not resolved types).
  • GetDataSource(string entityFullName) (IDataSourceService.cs:39) and GetDataSource(Type entityType) (IDataSourceService.cs:44): resolve just the engine.
  • HaveIncludeSupport(DataSourceKey first, DataSourceKey second) (IDataSourceService.cs:54): the crux. The contract documented at IDataSourceService.cs:46-53 is that it returns true only when both keys identify the same physical database and the engine is relational, since Cosmos DB has no cross-document JOINs.
  • HaveIncludeSupport(string firstEntityFullName, string secondEntityFullName) (IDataSourceService.cs:63): the same test by entity name, resolving each side's key first.
• Why it's built this way: ADR-006 replaces cross-service foreign keys with scalar columns and routes consistency through the outbox, so to build a query the Application layer must know the routing topology well enough to classify each navigation as include-able or manual-load-required. Exposing that as a narrow query interface (rather than handing Application the registry) keeps the collapse rules on the Infrastructure side.
• Where it's used: consumed by NavigationMetadataProvider to drive the supported/unsupported include split, and indirectly by the query pipeline's eager-loading decisions. The Infrastructure implementation is a facade over EntityDataSourceRegistry.

IOutboxAdministration

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/IOutboxAdministration.cs:16 · Level 3 · interface

• What it is: the operator surface over the outbox tables a host owns: list the dead letters, replay them, and count the pending backlog.
• Depends on: Result and its generic form (via MMCA.Common.Shared.Abstractions, IOutboxAdministration.cs:1) and OutboxDeadLetter, the record declared in the same file (IOutboxAdministration.cs:80).
• Concept introduced, a way BACK into delivery for an undelivered event. [Rubric §13, Observability & Operability] assesses whether the system can be operated after something goes wrong, not just observed while it works. The interface doc puts the alternative plainly (IOutboxAdministration.cs:5-9): without this surface the only terminal states for a failed message are "eventually deleted by the retention sweep" and "edited by hand in production SQL". [Rubric §29, Resilience & Business Continuity] assesses recovery from partial failure, which is exactly what a replay is: the outbox (ADR-003) guarantees an event is recorded in the same transaction as its state change, and this interface is how a recorded-but-undelivered event gets another chance. [Rubric §9, API & Contract Design] shows up in the return type: every method returns Result, because an unreachable source or an unknown source name is an expected failure an operator screen renders, not an exception (IOutboxAdministration.cs:10-14).
• Walkthrough: three methods, each taking a nullable dataSource filter where null means "every source this host owns", and each with an explicit (non-defaulted) cancellation token.
  • ListDeadLettersAsync(string? dataSource, int skip, int take, CancellationToken cancellationToken) (IOutboxAdministration.cs:30-34): the read. Dead-lettered means unprocessed with retries exhausted, and rows come back oldest first (IOutboxAdministration.cs:18-21) as OutboxDeadLetter records, paged by skip/take.
  • ReplayDeadLettersAsync(string? dataSource, IReadOnlyCollection<Guid>? ids, CancellationToken cancellationToken) (IOutboxAdministration.cs:51-54): returns rows to the pending pool and answers with the number of rows moved. The doc comment (IOutboxAdministration.cs:36-41) pins the semantics: RetryCount back to zero and the claim lease cleared, so the next poll cycle picks the rows up, while LastError is deliberately KEPT (the reason a message failed is the first thing anyone asks after a replay) and OccurredOn is untouched, so a replayed row keeps its place in its ordering key. A null or empty ids replays EVERY dead letter in the selected scope (IOutboxAdministration.cs:45-48), which is a wide operation stated as such.
  • CountPendingAsync(string? dataSource, CancellationToken cancellationToken) (IOutboxAdministration.cs:65): counts rows still awaiting dispatch. The doc comment draws the distinction that matters for operators (IOutboxAdministration.cs:56-61): unlike the outbox.pending.depth gauge, which reports what the processor last observed (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Outbox/Processing/OutboxMetrics.cs:76), this counts the tables at the moment of the call and includes rows currently under a claim lease.
• Why it's built this way: declaring the operator surface in Application means an admin endpoint, a support command, or a scheduled job can drive it without referencing EF or the outbox entity, and the Result return keeps a bad source name on the same rails as any other user error. The retention sweep that would otherwise be a dead letter's only exit is OutboxCleanupService, whose own comment points at IOutboxAdministration.ReplayDeadLettersAsync as the alternative (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Outbox/Administration/OutboxCleanupService.cs:152).
• Where it's used: implemented by OutboxAdministration (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Outbox/Administration/OutboxAdministration.cs:36-43), registered with TryAddScoped (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:202-203), scoped because it creates one child scope per data source it visits and holds no state of its own (DependencyInjection.cs:214-215). The implementation caps one page at 500 rows so an admin call cannot ask for the whole table at once (OutboxAdministration.cs:46), rejects a negative skip or an out-of-range take as validation errors (OutboxAdministration.cs:48-52), and expresses replay as one set-based UPDATE per target (OutboxAdministration.cs:149-150) rather than as loaded entities.
• Caveats / not-in-source: the framework registers the service but ships no controller over it. No MMCA.Common.API endpoint and no ADC or Store call site references ListDeadLettersAsync, ReplayDeadLettersAsync, or CountPendingAsync today; outside the registration the only callers in the workspace are the Infrastructure tests (MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/OutboxAdministrationTests.cs). A host that wants an operator screen wires its own endpoint or command over the injected interface.

IEntityQuerier<TEntity, TIdentifierType>

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/IRepository.cs:80 · Level 4 · interface

• What it is: the set-returning half of the repository split: collection reads, projections, single-row and grouped aggregate reads, lookup pairs, counts, the specification-first block, and keyset paging. Fifteen members in all.
• Depends on: AuditableBaseEntity<TIdentifierType> (the TEntity constraint, IRepository.cs:81), BaseLookup<TIdentifierType> (the lookup projection, from MMCA.Common.Shared.DTOs, IRepository.cs:5 and :222), ISpecification<TEntity, TIdentifierType> (from MMCA.Common.Domain.Interfaces, IRepository.cs:3, first used at :149), Result with KeysetPageRequest and KeysetCollectionResult<T> (from MMCA.Common.Shared.Abstractions, IRepository.cs:4, used at :316-317), and System.Linq.Expressions (IRepository.cs:1).
• Concept introduced, the ISP-split repository ladder. [Rubric §1, SOLID] assesses whether clients depend only on the members they use. IRepository.cs defines a deliberate ladder of ever-wider interfaces so a handler declares exactly the surface it needs: IEntityReader (by-id lookups, IRepository.cs:21), IEntityQuerier (set-returning reads, this type, :80), IReadRepository (reader plus querier plus raw IQueryable, :330), IWriteRepository (mutations, :367), and IRepository (read plus write, :467). The doc comment says it outright (IRepository.cs:68-71): prefer this over IReadRepository when a handler needs GetAllAsync, GetProjectedAsync, or CountAsync. [Rubric §12, Performance & Scalability] also applies: every member here exists so the database answers the question. GetProjectedAsync<TResult> takes an Expression<Func<TEntity, TResult>> translated to SQL, FirstOrDefaultAsync returns one row instead of a materialized set filtered in memory, and CountByAsync/SumByAsync push a GROUP BY down instead of folding rows client-side. The querier is the rung that keeps growing: fifteen members against the reader's five, so "focused" here means reads that return sets or aggregates, not a small interface (ADR-055 and its Revision (2026-08-31), which records the five most recent additions).
• Concept introduced, ignoreQueryFilters means soft-deleted rows and nothing else. [Rubric §11, Security] assesses whether a convenience flag can widen a security boundary. An interface-level <remarks> block (IRepository.cs:75-79) pins the contract: every ignoreQueryFilters parameter here drops the named SoftDelete filter and leaves the named Tenant filter applied, and the wording is repeated on each parameter that carries it (for example IRepository.cs:99-103 and :126-130). That is enforced downstream, where EFReadRepository<TEntity, TIdentifierType> passes a one-element filter-name array to EF's named IgnoreQueryFilters overload (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Repositories/EFReadRepository.cs:33, used at :52, :81, :102, :198, :288, :365, :379, and :445-446) rather than EF's parameterless form; its own comment (EFReadRepository.cs:30) spells out that dropping both would let a caller asking to see deleted rows silently read every tenant's data. The two named filters come from ApplicationDbContext (ApplicationDbContext.cs:388 and :391).
• Walkthrough
  • GetAllAsync(IEnumerable<string> includes, where?, orderBy?, select?, asTracking, ignoreQueryFilters, CancellationToken) (IRepository.cs:85-92): the general collection read with optional includes, filter, ordering, and same-type projection. Note includes is the one non-optional parameter, so a caller must state its eager-loading intent explicitly (pass [] for none).
  • GetProjectedAsync<TResult>(select, where?, asTracking, ignoreQueryFilters, CancellationToken) (IRepository.cs:105-110): SQL-side projection to an arbitrary result type.
  • FirstOrDefaultAsync(where, includes?, asTracking, ignoreQueryFilters, CancellationToken) (IRepository.cs:133-138): the single-row predicate read. The remarks (IRepository.cs:115-122) name the alternative it exists to remove, GetAllAsync followed by an in-memory FirstOrDefault, which materializes the whole matching set to keep one entity, and warn that no ordering is applied, so "first" is whatever the provider returns first.
  • FirstOrDefaultAsync(ISpecification<TEntity, TIdentifierType> specification, CancellationToken) (IRepository.cs:148-150): the deterministic counterpart. Unlike the predicate overload it honors the specification's ORDERING, so "first" means what the specification says it means (IRepository.cs:140-144).
  • CountByAsync<TKey>(keySelector, where?, CancellationToken) (IRepository.cs:167-171): a GROUP BY count, returning one dictionary entry per key that has at least one row. The remarks (IRepository.cs:156-161) explain why the member has to exist at all: the Application layer references no EF Core, so a handler needing a grouped count has no IQueryable to group and would otherwise project every matching row out of the database and group client-side. TKey is constrained notnull (IRepository.cs:171).
  • SumByAsync<TKey>(keySelector, sumSelector, where?, CancellationToken) (IRepository.cs:184-189): the grouped SUM, the counterpart of CountByAsync (IRepository.cs:173-177).
  • FindIncludingDeletedAsync(where, includes?, asTracking, CancellationToken) (IRepository.cs:215-219): the resurrection read (BR-135, IRepository.cs:198), returning a named tuple of Active and SoftDeleted matches. The remarks (IRepository.cs:195-205) give the whole rationale: a create handler whose natural key already exists as a soft-deleted row must reactivate that row rather than insert a duplicate the unique index will reject, and it needs both halves of the answer in one round trip, since an active match is a conflict, a soft-deleted match is the row to bring back, and neither is a plain insert. The asTracking parameter carries its own warning (IRepository.cs:209-212): a caller intending to reactivate wants true, otherwise the reactivation saves nothing. See ADR-005 for the soft-delete policy this read serves.
  • GetAllForLookupAsync(string nameProperty, where?, asTracking, CancellationToken) (IRepository.cs:222-226): returns lightweight BaseLookup<TIdentifierType> id/name pairs for dropdowns without materializing full entities. It has no ignoreQueryFilters parameter: a lookup list never offers deleted rows.
  • CountAsync(CancellationToken) (IRepository.cs:229) and CountAsync(Expression<Func<TEntity, bool>> where, CancellationToken) (IRepository.cs:232-234): total and predicated counts.
  • CountAsync(ISpecification<TEntity, TIdentifierType> specification, CancellationToken) (IRepository.cs:243-245): the specification-shaped count. The doc comment (IRepository.cs:236-239) states that ordering and paging on the specification are ignored deliberately, since a count of "page 3 of the matches" is never what a caller means.
  • ListAsync(ISpecification<TEntity, TIdentifierType> specification, CancellationToken) (IRepository.cs:260-262): runs a specification and returns the matching entities. The remarks (IRepository.cs:250-256) draw the line between the two specification shapes: a plain ISpecification contributes its Criteria only, while a QuerySpecification<TEntity, TIdentifierType> also contributes includes, ordering, paging, tracking, and soft-delete scope, so one object describes the whole read instead of five loose arguments.
  • ListAsync<TResult>(specification, Expression<Func<TEntity, TResult>> select, CancellationToken) (IRepository.cs:279-282): the projecting overload, so only the selected columns leave the database. The remarks (IRepository.cs:268-273) pin the ordering rule: the projection is applied after the specification's ordering and paging, so a paged specification still pages over entity rows and projects only that page, and includes on the specification are redundant here but not harmful.
  • AnyAsync(ISpecification<TEntity, TIdentifierType> specification, CancellationToken) (IRepository.cs:291-293): existence by specification, with ordering and paging ignored for the same reason as the specification CountAsync (IRepository.cs:285-286).
  • GetPageByCursorAsync(KeysetPageRequest request, ISpecification<TEntity, TIdentifierType>? specification = null, CancellationToken) (IRepository.cs:316-319): one keyset ("seek") page plus the cursor for the next one, and the only member here that returns a Result, because an unknown sort column and a malformed cursor are caller errors rather than exceptions and must never come back as a silent first page (IRepository.cs:306-310). The remarks (IRepository.cs:299-311) state the trade in full: one index seek regardless of scroll depth and no skipped or repeated rows, against no random page access and no total count, with exactly one sort key supported and Id as the tie-break.
• Why it's built this way: splitting reads into a focused querier lets a handler signal its access pattern through its constructor dependency and keeps projection, aggregation, and counting off the by-id interface. Declaring the specification-first members here rather than on a separate interface is what keeps a handler that already depends on the querier from needing a second dependency to run a specification.
• Where it's used: query handlers needing collections, aggregates, specifications, or a keyset page; folded into IReadRepository<TEntity, TIdentifierType> (IRepository.cs:331) and implemented concretely by EFReadRepository<TEntity, TIdentifierType> (for example GetProjectedAsync at EFReadRepository.cs:69, CountByAsync at :127, SumByAsync at :150, the projecting ListAsync at :464), with EFReadRepositoryDecorator<TEntity, TIdentifierType> wrapping every call in a MiniProfiler step (EFReadRepositoryDecorator.cs:17, and :45-83 for the newer members). The mechanics behind the specification-first block are walked through later in this chapter rather than repeated here: SpecificationEvaluator turns a specification into an IQueryable, KeysetQueryBuilder builds the ordering, the seek predicate, and the cursor encoding, and EFReadRepository<TEntity, TIdentifierType> owns the tracking and filter-scope policy those two are handed.
• Caveats / not-in-source: GetProjectedAsync carries ignoreQueryFilters before the cancellation token (IRepository.cs:109-110), so any caller or test double that passes arguments positionally has to account for it; the compiler catches positional callers, but a mock configured with a fixed argument count does not fail until run time.

IEntityReader<TEntity, TIdentifierType>

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/IRepository.cs:21 · Level 4 · interface

• What it is: the by-id half of the repository split: GetByIdAsync (two overloads), GetByIdsAsync, and ExistsAsync (two overloads), for handlers whose data access is a point lookup.
• Depends on: AuditableBaseEntity<TIdentifierType> (the TEntity constraint, IRepository.cs:22) and System.Linq.Expressions for the predicate overload (IRepository.cs:1).
• Concept, minimal data access as a declared dependency. [Rubric §1, SOLID] (Interface Segregation, introduced on IEntityQuerier) and [Rubric §8, Data Architecture] (deliberate, minimal access patterns). The doc comment is explicit (IRepository.cs:9-13): prefer this over IReadRepository<> when a handler only needs GetByIdAsync or ExistsAsync, because that signals minimal data access. This interface carries the same <remarks> contract as the querier (IRepository.cs:16-20): ignoreQueryFilters means "include soft-deleted rows" and nothing more, with the Tenant filter left in force. It is also the rung that does not move: every round of specification and aggregate growth has landed on the querier, so the reader is still five members.
• Walkthrough
  • GetByIdAsync(TIdentifierType id, CancellationToken) (IRepository.cs:26-28): plain fetch, returns null when missing.
  • GetByIdAsync(TIdentifierType id, IEnumerable<string> includes, bool asTracking = false, CancellationToken) (IRepository.cs:31-35): the eager-load overload; include paths are navigation-property names.
  • GetByIdsAsync(ids, includes?, asTracking, ignoreQueryFilters, CancellationToken) (IRepository.cs:48-53): a single-query bulk fetch that replaces an N+1 loop of point lookups. The doc comment warns it may return fewer entities than requested when some ids do not exist (IRepository.cs:47), so the caller must reconcile, and the ignoreQueryFilters parameter is documented in full (IRepository.cs:41-45) rather than by reference.
  • ExistsAsync(TIdentifierType id, bool ignoreQueryFilters = false, CancellationToken) (IRepository.cs:56-59) and ExistsAsync(Expression<Func<TEntity, bool>> where, bool ignoreQueryFilters = false, CancellationToken) (IRepository.cs:62-65): existence checks by key or by predicate. The flag is what lets a handler ask whether a soft-deleted row exists, for example to detect a conflict when re-creating a record that was deleted earlier.
• Why it's built this way: a handler that only needs a point lookup takes the narrowest interface, which reads clearly at the constructor and mocks in two lines in a test.
• Where it's used: command handlers that load an aggregate before mutating it; folded into IReadRepository<TEntity, TIdentifierType> (IRepository.cs:331). Note that the GetByIdOrFailAsync extension on ReadRepositoryExtensions, which turns a miss into a Result failure carrying Error.NotFound, hangs off IReadRepository rather than this interface and is implemented over GetAllAsync (MMCA.Common/Source/Core/MMCA.Common.Application/Extensions/ReadRepositoryExtensions.cs:12, :27, and :34-38), so a handler that wants it must take the wider read interface.

IReadRepository<TEntity, TIdentifierType>

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/IRepository.cs:330 · Level 5 · interface

• What it is: the full read surface over an entity, combining IEntityReader<TEntity, TIdentifierType> (by-id lookups) and IEntityQuerier<TEntity, TIdentifierType> (collections, projections, specifications, grouped aggregates, and keyset pages), and adding four IQueryable<TEntity> properties for handlers that need raw LINQ (MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/IRepository.cs:330-346).

• Depends on: IEntityReader<TEntity, TIdentifierType> and IEntityQuerier<TEntity, TIdentifierType>, both declared in the same file and both listed as base interfaces (IRepository.cs:331); AuditableBaseEntity<TIdentifierType> as the TEntity constraint (IRepository.cs:332). Externals: BCL IQueryable<T> only. No EF Core type appears anywhere in the declaration, which is what keeps this interface legal in the Application layer.

• Concept, the composition point of the ISP ladder, and controlled IQueryable exposure. [Rubric §1, SOLID] assesses whether clients depend only on the members they use. IRepository.cs defines a ladder of ever-wider interfaces so a handler declares exactly the surface it needs: IEntityReader (five members, IRepository.cs:21), IEntityQuerier (fifteen members, IRepository.cs:80), this type (both of those plus four properties, twenty-four members in total, IRepository.cs:330), IWriteRepository (IRepository.cs:367), and IRepository (read plus write, IRepository.cs:467). The doc comment records a migration stance rather than a ban (IRepository.cs:322-327): existing code should continue using this interface, and new handlers can depend on the focused sub-interfaces for better ISP compliance.

  [Rubric §12, Performance & Scalability] assesses whether expensive query behavior is a deliberate choice. The four properties turn EF's tracking mode and query-splitting mode into a named decision at the call site: asking for TableNoTrackingSplitQuery is visible in review, where a plain DbSet would silently track every row and emit one cartesian join.

• Walkthrough: this interface declares no methods of its own. Its whole body is four get-only IQueryable<TEntity> properties.

  • Table (IRepository.cs:336): the base queryable with change tracking enabled, the shape a mutation path composes over. Implemented as the raw DbSet (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Repositories/EFReadRepository.cs:406).
  • TableNoTracking (IRepository.cs:339): the no-tracking queryable, documented as best for read-only queries and implemented as Entities.AsNoTracking() (EFReadRepository.cs:409).
  • TableNoTrackingSingleQuery (IRepository.cs:342): no-tracking, pinned to a single SQL statement through AsSingleQuery() (EFReadRepository.cs:412).
  • TableNoTrackingSplitQuery (IRepository.cs:345): no-tracking in split-query mode, which avoids the cartesian explosion that collection includes cause, through AsSplitQuery() (EFReadRepository.cs:415). It is the same concern IQueryableExecutor addresses for callers that hold an IQueryable rather than a repository.
  • The twenty inherited members come from the two base interfaces and are walked through on their own sections: five point-lookup members on IEntityReader, fifteen set-returning members on IEntityQuerier.

• Why it's built this way: the framework needed one interface a query handler can take when it genuinely uses the whole read surface, without forcing every handler to take it. Keeping the composition free of new methods means the two halves stay independently declarable and independently mockable, and it gives the profiling decorator one surface to wrap. Naming the four queryables separately, rather than exposing a DbSet, is what makes tracking and split-query opt-in rather than accidental. The ladder itself is ADR-055.

• Where it's used: obtained through IUnitOfWork.GetReadRepository<TEntity, TIdentifierType>() (MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/IUnitOfWork.cs:29), which is the sanctioned way to get one; implemented by EFReadRepository<TEntity, TIdentifierType> (EFReadRepository.cs:19-23) and wrapped in EFReadRepositoryDecorator<TEntity, TIdentifierType> (EFReadRepositoryDecorator.cs:17) by RepositoryFactory only when MiniProfiler is enabled (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Repositories/Factory/RepositoryFactory.cs:55-63). EntityQueryService<TEntity, TEntityDTO, TIdentifierType> derives its Repository property from the unit of work at construction (MMCA.Common/Source/Core/MMCA.Common.Application/Services/EntityQueryService.cs:88). It is also the receiver of the GetByIdOrFailAsync extension on ReadRepositoryExtensions, which turns a miss into a Result failure carrying Error.NotFound and is implemented over GetAllAsync rather than GetByIdAsync (MMCA.Common/Source/Core/MMCA.Common.Application/Extensions/ReadRepositoryExtensions.cs:12, :27, :34-44), so a handler that wants that convenience must take this wider interface rather than IEntityReader.

• Caveats / not-in-source: a mutation path must not compose its query off TableNoTracking and then expect the save to persist, because one no-tracking source makes the whole composed query untracked. That constraint is not stated in this file; it follows from EF's tracking semantics.

IWriteRepository<TEntity, TIdentifierType>

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/IRepository.cs:367 · Level 5 · interface

• What it is: the write half of the repository abstraction, over an aggregate root: AddAsync, AddRangeAsync, UpdateAsync, UpdateRange, two SetOriginalRowVersion overloads, ExecuteDeleteAsync, and ExecuteUpdateAsync (IRepository.cs:367-454). Eight members, and not one of them saves.

• Depends on: AuditableAggregateRootEntity<TIdentifierType> as the TEntity constraint (IRepository.cs:368), IRowVersioned for the child-concurrency overload (written by its qualified Domain.Interfaces.IRowVersioned name, IRepository.cs:417), and IUpdatePropertySetter<TEntity> for the set-based update builder (IRepository.cs:452). Externals: System.Linq.Expressions (IRepository.cs:1).

• Concept introduced, writes enter through the aggregate root, and the repository never flushes. [Rubric §4, DDD] assesses whether the aggregate boundary is an enforced rule rather than a naming convention. The constraint here is the narrower AuditableAggregateRootEntity<TIdentifierType>, not the AuditableBaseEntity<TIdentifierType> the read side accepts, and the doc comment says exactly why (IRepository.cs:351-358): a write enters the aggregate through its root so that the root's invariants are enforced and its domain events are collected, and a repository over a child entity would let a caller persist a change the root never saw. Reading a child directly stays harmless and stays supported through IReadRepository<TEntity, TIdentifierType>. The rule is enforced by the compiler, not by review: asking for a write repository over a child entity does not compile.

  [Rubric §8, Data Architecture] assesses whether persistence is deliberate: one save boundary, one concurrency story. This interface has no Save and no SaveChangesAsync. The doc comment states the division (IRepository.cs:359-363): the repository stages changes and never flushes them, because persisting is the unit of work's job, so every repository touched in a scope is written as one unit under one audit stamp. A handler that mutates through a repository and then forgets IUnitOfWork.SaveChangesAsync has written nothing.

• Concept introduced, optimistic-concurrency wiring and change-tracking-bypass writes. Four members carry the weight.

  • SetOriginalRowVersion(TEntity entity, byte[] rowVersion) (IRepository.cs:406): plants the client's last-observed RowVersion as the tracked entity's original concurrency token, so the next save emits its WHERE RowVersion = @original and raises DbUpdateConcurrencyException, mapped to 409 Conflict, when the row moved since the client read it (IRepository.cs:399-403). The implementation sets OriginalValue on the tracked entry's RowVersion property and rejects a null token outright (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Repositories/EFRepository.cs:75-84).
  • SetOriginalRowVersion(Domain.Interfaces.IRowVersioned childEntity, byte[] rowVersion) (IRepository.cs:417): the same protection for a tracked child of the aggregate, for example a ProductVariant under a Product. The doc comment explains why a second overload exists at all (IRepository.cs:408-414): the repository's TEntity is the root, so the typed overload cannot reach children, and this one accepts any IRowVersioned entity instead (ADR-035). It reaches the entry through an (object) cast (EFRepository.cs:86-95).
  • ExecuteDeleteAsync(Expression<Func<TEntity, bool>> where, CancellationToken) (IRepository.cs:427-429): a set-based delete run directly in the database, one statement, no change tracker. The doc comment warns in capitals that it does not trigger domain events, audit stamps, or soft delete, and is for maintenance scenarios only (IRepository.cs:419-426). The implementation is a one-liner over the DbSet (EFRepository.cs:97-103).
  • ExecuteUpdateAsync(where, Action<IUpdatePropertySetter<TEntity>> setProperties, CancellationToken) (IRepository.cs:450-453): a set-based UPDATE ... SET ... WHERE ... as one atomic statement. [Rubric §12, Performance & Scalability] applies alongside §8 here, and the long doc comment (IRepository.cs:431-449) is the teaching text for contention-proof conditional updates: guard the update inside where (the worked example is a stock decrement guarded by AvailableQuantity >= @qty), and then zero rows affected means the guard did not hold, so two racing callers can never both win and no rowversion retry loop is needed, because the database itself arbitrates. It also draws the exact boundaries: domain events are bypassed, global query filters (soft delete) DO apply to where, audit fields are NOT bypassed, and the statement runs on the ambient transaction when one is active, so a decrement rolls back with its caller. The audit guarantee is not something the database does; it is compensation code in the implementation, which stamps LastModifiedOn from the injected TimeProvider and LastModifiedBy from ICurrentUserService unless the caller assigned them explicitly, and rejects an empty setter list (EFRepository.cs:114-132, with the two optional constructor dependencies at EFRepository.cs:23-27).

• Walkthrough: the eight members in teaching order.

  • AddAsync(TEntity entity, CancellationToken) (IRepository.cs:375-377) and AddRangeAsync(IEnumerable<TEntity> entities, CancellationToken) (IRepository.cs:383-385): single and batch inserts, staged on the change tracker.
  • UpdateAsync(TEntity entity, CancellationToken) (IRepository.cs:391-393) and UpdateRange(IEnumerable<TEntity> entities) (IRepository.cs:397): mark tracked entities modified. UpdateRange is the one void member of the pair, since batch marking needs nothing awaited.
  • The two SetOriginalRowVersion overloads (IRepository.cs:406, :417) and the two database-side operations (IRepository.cs:427, :450) described above.

• Why it's built this way: keeping writes in a focused interface means a query handler cannot accidentally acquire mutation methods, and the concurrency and set-based escape hatches are declared where a reader meets their warnings rather than buried in a concrete class. Constraining TEntity to the aggregate root mirrors the constraint on IUnitOfWork.GetRepository (MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/IUnitOfWork.cs:20), which is how a handler is meant to obtain one, so the two agree by construction. Leaving Save off the interface entirely is what makes the single save boundary of ADR-006 enforceable: with several physical databases in one host, "save" cannot mean "save this repository".

• Where it's used: command handlers that mutate aggregates, always through IUnitOfWork.GetRepository<TEntity, TIdentifierType>() (IUnitOfWork.cs:19); folded into IRepository<TEntity, TIdentifierType> (IRepository.cs:467); implemented by EFRepository<TEntity, TIdentifierType> (EFRepository.cs:23-29), which derives from EFReadRepository<TEntity, TIdentifierType> and adds only the write surface, and is wrapped in EFRepositoryDecorator<TEntity, TIdentifierType> when MiniProfiler is on (RepositoryFactory.cs:31-41). Both apps exercise the specialized members: in MMCA.Store, ChangeVariantPriceHandler calls the child-typed SetOriginalRowVersion so a race on one product variant conflicts even when the product row itself is untouched (MMCA.Store/Source/Modules/Catalog/MMCA.Store.Catalog.Application/Products/UseCases/ChangeVariantPrice/ChangeVariantPriceHandler.cs:45-47, with the same pattern in ChangeVariantSkuHandler.cs:69); in MMCA.ADC, ScoreEventSessionsHandler uses ExecuteDeleteAsync to clear a session's previous AI scores before re-adding them (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.Application/Sessions/UseCases/DecisionSupport/ScoreEventSessions/ScoreEventSessionsHandler.cs:28, :105-107).

• Caveats / not-in-source: ExecuteDeleteAsync and ExecuteUpdateAsync bypass the domain-event capture that DomainEventSaveChangesInterceptor performs on save, so anything downstream that reacts to an event will not observe those writes. The interface says so in its doc comments; nothing in the type system stops it, so it stays a review rule rather than a compiler rule.

IRepository<TEntity, TIdentifierType>

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/IRepository.cs:467 · Level 6 · interface

• What it is: the combined read-write repository over an aggregate root, extending both IReadRepository<TEntity, TIdentifierType> and IWriteRepository<TEntity, TIdentifierType>, so a command handler that reads an aggregate and then mutates it takes a single dependency (IRepository.cs:467).
• Depends on: IReadRepository<TEntity, TIdentifierType> and IWriteRepository<TEntity, TIdentifierType>, both named as bases on IRepository.cs:467, and AuditableAggregateRootEntity<TIdentifierType> as the TEntity constraint (IRepository.cs:468).
• Concept, the top of the ISP ladder, and where the aggregate-root constraint wins. [Rubric §1, SOLID] and [Rubric §4, DDD]. The interface is purely compositional: it declares no members of its own, only two base interfaces and two constraints (IRepository.cs:467-469). What matters is which constraint survives the composition. The read side accepts any AuditableBaseEntity<TIdentifierType> (IRepository.cs:332) and the write side only aggregate roots (IRepository.cs:368), so the combination inherits the narrower bound, and the doc comment states the consequence for the reader (IRepository.cs:459-463): a handler that only reads, and reads a child entity, depends on IReadRepository instead, which still accepts any auditable entity.
• Walkthrough: no members. The declaration is a semicolon-terminated interface with two bases and two generic constraints (IRepository.cs:467-469), the C# shorthand for an empty body. Everything a caller can do through it is walked through on the two base sections, and beneath them on IEntityReader and IEntityQuerier.
• Why it's built this way: keeping the combined interface empty means the read and write surfaces each stay independently usable and independently mockable, while a handler that genuinely needs both still takes one constructor parameter. Composition rather than a fresh member list is also what keeps the ladder honest: there is exactly one definition of "read" and one of "write" in the codebase, and the widest rung is a deliberate choice a reviewer can see at the constructor rather than a default.
• Where it's used: obtained through IUnitOfWork.GetRepository<TEntity, TIdentifierType>() (IUnitOfWork.cs:19-21), which is the sanctioned way to get one; implemented by EFRepository<TEntity, TIdentifierType> (EFRepository.cs:23-29) and produced, optionally wrapped for profiling, by RepositoryFactory (RepositoryFactory.cs:26-42). UnitOfWork caches the instance per closed generic interface type, so typeof(IRepository<Order, int>) is the cache key for a whole scope (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/UnitOfWork.cs:37, :43).
• Caveats / not-in-source: AddInfrastructure does register the open generic IRepository<,> against EFRepository<,> (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:119), which makes constructor-injecting IRepository<,> look supported. It is not the intended path: EFRepository<TEntity, TIdentifierType> takes a bare DbContext constructor parameter (EFRepository.cs:23-24) and that registration file adds no DbContext service, so a direct injection sidesteps both the data-source resolution and the per-scope repository cache that GetRepository performs (UnitOfWork.cs:37-45). Ask the unit of work.

IUnitOfWork

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/IUnitOfWork.cs:10 · Level 7 · interface

• What it is: the one coordination point a handler uses to touch the database. It hands out typed repositories (read-write for aggregate roots, read-only for any entity), persists everything pending in one call, and exposes controlled transaction and identity-insert operations. The doc comment states the contract in two sentences (IUnitOfWork.cs:5-9): it coordinates persistence across multiple repositories within a single database context, and SaveChangesAsync persists all pending changes and dispatches domain events raised by tracked aggregates.

• Depends on: AuditableAggregateRootEntity<TIdentifierType> and AuditableBaseEntity<TIdentifierType> as the two constraint bounds (IUnitOfWork.cs:1, :20, :30); IRepository<TEntity, TIdentifierType> and IReadRepository<TEntity, TIdentifierType> as the two return types (IUnitOfWork.cs:19 and :29). Externals: BCL IDisposable and IAsyncDisposable, both declared as base interfaces (IUnitOfWork.cs:10). Notably absent: anything from Microsoft.EntityFrameworkCore, which is the point of the type.

• Concept introduced, the Unit of Work as the Application layer's only persistence verb. [Rubric §8, Data Architecture] assesses whether persistence is deliberate: one save boundary, one transaction story, explicit concurrency and audit handling rather than scattered SaveChanges calls. A unit of work is the scope inside which a caller sees a consistent view of the data and inside which all of its changes either land together or not at all. Here that scope is the DI scope: UnitOfWork is registered TryAddScoped (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:121), it caches one repository per closed generic interface type (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/UnitOfWork.cs:23, :37-45), and every repository it hands out is bound to a context obtained from the same IDbContextFactory (UnitOfWork.cs:41), so two handlers in one request share one change tracker instead of racing two.

  [Rubric §3, Clean Architecture] assesses whether the inner layers declare intent while the outer layers own the technology. This interface lives in MMCA.Common.Application and names no EF type, which is exactly what lets the architecture fitness rule "Application must not depend on EF Core, use IRepository/IUnitOfWork" hold (MMCA.Common/Source/Hosting/MMCA.Common.Testing.Architecture/Rules/Layering/ArchitectureRules.Purity.cs:54-64). The EF-shaped work (a context per physical source, execution strategies, identity-insert SQL) sits behind it in MMCA.Common.Infrastructure.

  [Rubric §6, CQRS & Event-Driven] assesses whether events are raised and delivered from a single, reliable place. SaveChangesAsync is that place: the doc comment (IUnitOfWork.cs:7-8) ties persistence and domain-event dispatch into one operation, and the mechanism behind it is the interceptor plus outbox flow described on DomainEventSaveChangesInterceptor.

  [Rubric §14, Testability] assesses whether the abstraction a handler depends on can be replaced without infrastructure. Because a handler asks this interface for its repositories rather than receiving them, one Mock<IUnitOfWork> substitutes the entire data layer; the framework ships that scaffold as HandlerTestBase<THandler>, which pre-stubs SaveChangesAsync to return 1 (MMCA.Common/Source/Hosting/MMCA.Common.Testing/Support/HandlerTestBase.cs:42) and wires each registered repository mock into both GetRepository and GetReadRepository (HandlerTestBase.cs:61-62).

• Walkthrough: nine members, in three groups.

  • GetRepository<TEntity, TIdentifierType>() (IUnitOfWork.cs:19-21): the read-write repository. Its constraint is where TEntity : AuditableAggregateRootEntity<TIdentifierType> (IUnitOfWork.cs:20), so the DDD rule that the doc comment states in prose ("Only aggregate roots can be directly persisted", IUnitOfWork.cs:14) is enforced by the compiler. In the implementation the call resolves the entity's physical data source through IDataSourceService, fetches the matching context, builds the repository through IRepositoryFactory, and caches it under the closed interface type (UnitOfWork.cs:37-45).
  • GetReadRepository<TEntity, TIdentifierType>() (IUnitOfWork.cs:29-31): the read-only repository, constrained only to AuditableBaseEntity<TIdentifierType> (IUnitOfWork.cs:30), so child entities are readable even though they are not independently writable. Same resolution path, different factory method (UnitOfWork.cs:57-65).
  • SaveChangesAsync(CancellationToken cancellationToken = default) (IUnitOfWork.cs:36): persists everything and returns the number of state entries written (IUnitOfWork.cs:35). The implementation is a straight delegation (UnitOfWork.cs:69-70) to DbContextFactory, which saves every cached context, not just one: it snapshots the contexts and loops in bounded passes (three, MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Factory/DbContextFactory.cs:53) so a context materialized by a domain event handler mid-save is still saved (DbContextFactory.cs:238-252), then throws if any tracked change is left behind rather than losing it silently (DbContextFactory.cs:260-271).
  • Save() (IUnitOfWork.cs:40): the synchronous form, with the doc comment preferring the async one in async code paths (IUnitOfWork.cs:38). It delegates to DbContextFactory.SaveChanges() (UnitOfWork.cs:73, DbContextFactory.cs:409-417).
  • RequestIdentityInsert() (IUnitOfWork.cs:49): a one-shot flag saying the next save may insert rows carrying explicit values for database-generated identity columns, for example records imported from an external system with their source ids intact (IUnitOfWork.cs:42-48). The implementation sets a boolean (UnitOfWork.cs:76, DbContextFactory.cs:277); the next SaveChangesAsync reads and immediately clears it (DbContextFactory.cs:228-229, which is what "automatically cleared after the save completes" means) and, for a SQL Server context, routes the save through SaveWithIdentityInsertAsync (DbContextFactory.cs:248-250), which groups the affected entries by table and wraps each group in SET IDENTITY_INSERT ON/OFF because SQL Server allows only one table per session to have it on (DbContextFactory.cs:279-301).
  • BeginTransaction() (IUnitOfWork.cs:52), CommitTransaction() (IUnitOfWork.cs:55), RollbackTransaction() (IUnitOfWork.cs:58): manual transaction control, each fanning out across every transaction-capable cached context (DbContextFactory.cs:419-442). Begin skips a context that already carries a transaction, since EF throws on a second BeginTransaction for the same connection (DbContextFactory.cs:423-428). Rollback additionally drops any deferred in-process event dispatch, because the aggregate changes and their outbox rows just rolled back with it (DbContextFactory.cs:444-448).
  • ExecuteInTransactionAsync<TResult>(Func<CancellationToken, Task<TResult>> operation, CancellationToken cancellationToken = default) (IUnitOfWork.cs:70-72): the member to reach for instead of the three above. Its doc comment (IUnitOfWork.cs:60-66) states the reason: the operation runs wrapped by the active execution strategy, so a retrying strategy such as SqlServerRetryingExecutionStrategy can retry the whole transaction as one retriable unit, committing on success and rolling back before an exception propagates. The implementation adds five behaviors worth knowing (DbContextFactory.cs:500-545, with the attempt runner at :554-609): a nested call joins the ambient transaction instead of opening a second one (DbContextFactory.cs:511-512); a returned failed Result rolls back exactly like an exception (DbContextFactory.cs:564-571); each retry starts from a reset change tracker, so entities a failed attempt added are not inserted twice (DbContextFactory.cs:473-479, :528-529); deferred in-process domain events are flushed only after a successful commit (DbContextFactory.cs:577-584); and a failure of the commit itself is never retried, surfacing as TransactionCommitAmbiguousException thrown outside the strategy instead (DbContextFactory.cs:537-542).
  • The two base interfaces (IUnitOfWork.cs:10) matter at scope teardown: UnitOfWork forwards both disposal paths to the context factory (UnitOfWork.cs:93-119), so the async path awaits _dbContextFactory.DisposeAsync() (UnitOfWork.cs:103) rather than blocking.

• Why it's built this way: under ADR-006 a single host may own several physical databases, so "save" cannot mean "call SaveChanges on the one context". Splitting the responsibility keeps that manageable: IDbContextFactory owns multi-source routing, saving, transactions and disposal, while IUnitOfWork is the narrow per-scope facade the Application layer is allowed to see, adding only repository resolution and caching on top (UnitOfWork.cs:13, :23). Exposing ExecuteInTransactionAsync as a first-class member, rather than leaving callers with BeginTransaction, is what makes the ADR-014 pipeline's transaction rules enforceable in one place: business failures roll back and post-commit event dispatch is deferred. Keeping the interface in Application rather than Infrastructure is the ADR-013 and Clean Architecture pairing, since a handler returns a Result and never sees an EF type on the way there.

• Where it's used: injected into command handlers across the framework and both apps. In MMCA.Common: TransactionalCommandDecorator<TCommand, TResult> takes it in its primary constructor (MMCA.Common/Source/Core/MMCA.Common.Application/UseCases/Decorators/TransactionalCommandDecorator.cs:22) and calls ExecuteInTransactionAsync for any command marked ITransactional (TransactionalCommandDecorator.cs:31); DeleteEntityHandler<TEntity, TIdentifierType> takes it and resolves its write repository from it (MMCA.Common/Source/Core/MMCA.Common.Application/UseCases/Crud/DeleteEntityHandler.cs:37, :70); EntityQueryService<TEntity, TEntityDTO, TIdentifierType> both holds it and derives its read repository from it (MMCA.Common/Source/Core/MMCA.Common.Application/Services/EntityQueryService.cs:33, :43, :87). In MMCA.ADC, RefreshFromSessionizeHandler is the live consumer of the identity-insert path, calling RequestIdentityInsert() immediately before the save because Sessionize imports preserve external ids into tables with IDENTITY columns (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.Application/Events/UseCases/RefreshFromSessionize/RefreshFromSessionizeHandler.cs:139-140). The single implementation is UnitOfWork (UnitOfWork.cs:13), which is internal sealed, so consumers only ever see this interface.

• Caveats / not-in-source: Save() is not the synchronous twin of SaveChangesAsync() in event behavior. The synchronous interceptor path cannot await the in-process dispatcher, so with the outbox enabled it clears the captured events from their aggregates and leaves their outbox rows for OutboxProcessor to deliver; a context without outbox support keeps the older no-op instead, so a later async save can still deliver those events (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Interceptors/DomainEventSaveChangesInterceptor.cs:114-138). Second, ExecuteInTransactionAsync is not a distributed transaction: with several physical sources each gets its own transaction and commits are sequential and best effort, so a commit failure on the second source leaves the first already committed. The doc comment names that limitation and records that the thrown TransactionCommitAmbiguousException reports each source's outcome so the partial state is observable rather than inferred, with the outbox as the cross-source consistency mechanism (DbContextFactory.cs:453-456, :487-497).

EntityConfigurationOptions

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/EntityConfigurationOptions.cs:10 · Level 0 · class (sealed)

• What it is: an options bag that carries extra assemblies whose EF Core entity type configurations should be applied on top of the ones auto-discovered by name. A host or module pushes an Assembly into it during DI so its configurations are picked up without the discovery scan having to match it by naming convention.
• Depends on: System.Reflection.Assembly (BCL); nothing first-party. It is read by DefaultEntityConfigurationAssemblyProvider through IOptions<EntityConfigurationOptions> (DefaultEntityConfigurationAssemblyProvider.cs:12-13).
• Concept introduced, options-object supplementation of convention discovery. [Rubric §3, Clean Architecture] (assesses whether infrastructure discovers its collaborators rather than hardcoding references to them): the persistence layer does not reference every module's Infrastructure project, so a module that does not follow the .Infrastructure naming rule (for example a Common feature like Notification that lives inside Common.Infrastructure itself, which the auto-scan deliberately excludes) still gets its configurations applied by adding its assembly here. The doc comment names exactly that case (EntityConfigurationOptions.cs:5-9).
• Walkthrough: one member, List<Assembly> AdditionalAssemblies { get; } = [] (EntityConfigurationOptions.cs:16). It is get-only and initialized to an empty list, so registration code mutates the list rather than replacing it.
• Why it's built this way: an options object keeps the supplemental-assembly list open for extension without the provider (or the context) taking a compile-time dependency on any specific module. The provider merges these with the name-scanned set and de-duplicates.
• Where it's used: written through the AddEntityConfigurationAssembly(Assembly) extension (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:597-607), which calls services.Configure<EntityConfigurationOptions> with a contains-check so an assembly is added at most once (DependencyInjection.cs:599-605); AddNotificationInfrastructure() (DependencyInjection.cs:614-619) is the one in-framework caller. It is read by DefaultEntityConfigurationAssemblyProvider.

PersistenceSettings

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/PersistenceSettings.cs:10 · Level 0 · class (sealed)

• What it is: the bound Persistence configuration section, currently a single knob: the SQL command timeout applied to every command the SQL Server context issues.
• Depends on: System.ComponentModel.DataAnnotations (for [Range], PersistenceSettings.cs:1); nothing first-party.
• Concept introduced, the defaults-preserve-history rule for a new settings section. [Rubric §15, Best Practices & Code Quality] assesses whether change is additive; the class doc states the policy directly, every property defaults to the value the framework applied implicitly before the section existed, so the section is optional in appsettings.json (PersistenceSettings.cs:5-9). [Rubric §12, Performance & Scalability]: the 30-second default is the previous implicit ADO.NET behavior, and the doc names the case for raising it (reporting-style workloads whose queries legitimately run longer than half a minute, PersistenceSettings.cs:15-20). Making that value configurable rather than constant is the difference between tuning an environment and cutting a release.
• Walkthrough: SectionName = "Persistence" (PersistenceSettings.cs:13); CommandTimeoutSeconds, [Range(1, 600)]-validated (PersistenceSettings.cs:21) and defaulting to 30 (PersistenceSettings.cs:22), is the only property. The consuming side is defensive in a way worth copying: SQLServerDbContext resolves the options with GetService<IOptions<PersistenceSettings>>()?.Value ?? new PersistenceSettings() (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/SQLServerDbContext.cs:35-36), so a context built outside the full DI graph (the design-time provider behind dotnet ef, a test) still gets the documented default rather than a null reference. It then applies it with sql.CommandTimeout(_persistenceSettings.CommandTimeoutSeconds) (SQLServerDbContext.cs:55).
• Why it's built this way: a [Range]-validated option bound with ValidateDataAnnotations() and ValidateOnStart() turns a typo into a startup failure rather than a per-query surprise (ADR-070).
• Where it's used: bound in the infrastructure registration (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:135-138) and read by SQLServerDbContext; no other engine context reads it today.

ProfilingHelper

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/ProfilingHelper.cs:9 · Level 0 · class (internal static)

• What it is: an internal static helper that wraps repository operations in a MiniProfiler timing step when profiling is active and is a no-op when it is not.
• Depends on: StackExchange.Profiling (the MiniProfiler NuGet package); nothing first-party.
• Concept introduced, opt-in per-operation timing via a null-conditional. [Rubric §13, Observability & Operability] (assesses granular timing and instrumentation of persistence): every helper routes through MiniProfiler.Current?.Step(...) (ProfilingHelper.cs:11-12). When MiniProfiler is not registered, MiniProfiler.Current is null, the ?. short-circuits, and the returned Timing? is null, so using var step = ... disposes nothing. The instrumentation can therefore live permanently in the decorators without a build-time toggle; the runtime cost when disabled is a single field read.
• Walkthrough:
  • BeginStep(className, methodName) (ProfilingHelper.cs:11-12): returns a Timing? named MMCA.Common.Infrastructure.{className}: {methodName}, so every step in the profiler tree is self-identifying.
  • Profile(className, methodName, Func<int>) (ProfilingHelper.cs:14-18): opens a step and runs a synchronous delegate returning int (the shape of a sync Save).
  • ProfileAsync(...) non-generic and ProfileAsync<T>(...) (ProfilingHelper.cs:20-24,26-30): the async equivalents, each awaiting the delegate under the step with ConfigureAwait(false).
• Why it's built this way: internal hides the profiling concern from callers outside Infrastructure; the null-conditional pattern means the same wrapper is safe in hot paths whether or not profiling is on.
• Where it's used: the EF repository decorators wrap every call through it, for example EFRepositoryDecorator<TEntity, TIdentifierType> (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Repositories/EFRepositoryDecorator.cs:24-58, covering AddAsync through ExecuteUpdateAsync) and EFReadRepositoryDecorator<TEntity, TIdentifierType> (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Repositories/EFReadRepositoryDecorator.cs:33-111, covering GetAllAsync through CountAsync). ApplicationDbContext opens its own MiniProfiler step directly rather than through this helper (ApplicationDbContext.cs:155). Behavior is pinned by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/ProfilingHelperTests.cs.

ImageContentSniffer

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Storage · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Storage/ImageContentSniffer.cs:10 · Level 0 · class (public static)

• What it is: a dependency-free static helper that decides whether uploaded bytes are a JPEG, PNG, or WebP image by inspecting the leading magic bytes, never the client-declared content type or file extension.
• Depends on: nothing first-party (BCL ReadOnlySpan<byte>; the file has no using directives). It is the upload-side companion to IImageProcessor.
• Concept introduced, magic-byte content sniffing as an upload trust boundary. [Rubric §11, Security] assesses whether untrusted input is validated by its actual content rather than by a spoofable client-supplied MIME type or file extension; this type is the framework's answer for binary uploads. [Rubric §26, Front-End Security] also applies at the origin of an avatar upload, because the browser-supplied Content-Type is exactly what this code refuses to trust. The doc comment (ImageContentSniffer.cs:3-9) frames the division of labor under ADR-045: the sniffer narrows accepted inputs to jpeg/png/webp, then the caller hands content to the processor whose re-encoding keeps only pixels, while app-specific size limits and error codes stay in the calling handler.
• Walkthrough: four span-based predicates, all expression-bodied and all public.
  • IsAllowedImage(ReadOnlySpan<byte> content) (ImageContentSniffer.cs:15-16): the entry point, a short-circuiting IsJpeg || IsPng || IsWebP.
  • IsJpeg (ImageContentSniffer.cs:21-22): length at least 3 and the SOI prefix FF D8 FF checked byte by byte.
  • IsPng (ImageContentSniffer.cs:27-28): length at least 8 and a SequenceEqual against the exact 8-byte PNG signature 89 50 4E 47 0D 0A 1A 0A.
  • IsWebP (ImageContentSniffer.cs:33-36): length at least 12, a RIFF container (bytes 0-3 against the UTF-8 literal "RIFF"u8) declaring the WEBP form type (bytes 8-11 against "WEBP"u8). Bytes 4-7 are the RIFF chunk size and are deliberately not inspected.
• Why it's built this way: ReadOnlySpan<byte> plus UTF-8 literals mean the checks allocate nothing and run directly on the payload prefix, and being a pure static class it is callable from any layer without DI or mocking. Checking bytes rather than the declared type is the security point: a client can rename evil.exe to avatar.png, but it cannot forge a valid leading signature and still survive the re-encode that follows.
• Where it's used: called by SetUserAvatarHandler as the first gate on an upload (MMCA.ADC/Source/Modules/Identity/MMCA.ADC.Identity.Application/Users/UseCases/SetUserAvatar/SetUserAvatarHandler.cs:50) before the bytes reach IImageProcessor (SetUserAvatarHandler.cs:72) and then IFileStorageService (SetUserAvatarHandler.cs:86). It has its own dedicated unit-test class (MMCA.Common/Tests/Core/MMCA.Common.Application.Tests/ImageContentSnifferTests.cs).
• Caveats / not-in-source: sniffing establishes only that the prefix matches a known signature. It is not a decode, so a truncated or malformed body still passes here and is rejected later by IImageProcessor.

DefaultEntityConfigurationAssemblyProvider

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DefaultEntityConfigurationAssemblyProvider.cs:12 · Level 1 · class (sealed)

• What it is: the default implementation of IEntityConfigurationAssemblyProvider. It returns the set of assemblies whose EF entity configurations should be applied: every loaded assembly whose name contains .Infrastructure (excluding Common.Infrastructure itself), plus any assemblies explicitly registered through EntityConfigurationOptions.
• Depends on: IEntityConfigurationAssemblyProvider (the contract it implements), EntityConfigurationOptions via IOptions<> (DefaultEntityConfigurationAssemblyProvider.cs:12-13), and System.AppDomain plus System.Reflection (BCL).
• Concept introduced, name-convention assembly discovery with an explicit escape hatch. [Rubric §3, Clean Architecture] (infrastructure finds module configurations without referencing modules) and [Rubric §7, Microservices Readiness] (each extracted service loads only its own modules' configuration assemblies): scanning AppDomain.CurrentDomain.GetAssemblies() means a host applies exactly the module infrastructure it has loaded, so a monolith gets all modules and an extracted service gets its subset, with no per-host registration list.
• Walkthrough: GetConfigurationAssemblies() (DefaultEntityConfigurationAssemblyProvider.cs:16) builds a collection expression from two spreads: the loaded assemblies whose FullName is non-null, contains .Infrastructure, and does not contain Common.Infrastructure (both matched OrdinalIgnoreCase, DefaultEntityConfigurationAssemblyProvider.cs:17-20), and the distinct options.Value.AdditionalAssemblies (DefaultEntityConfigurationAssemblyProvider.cs:21). The Common.Infrastructure exclusion is why Common-internal feature modules must opt in through EntityConfigurationOptions.
• Why it's built this way: sealed; convention scanning keeps hosts declarative, and the additional-assemblies list covers the one case the convention deliberately excludes. Depending only on the abstraction plus options keeps the persistence layer free of module references.
• Where it's used: registered as the singleton IEntityConfigurationAssemblyProvider via TryAddSingleton (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:65) and resolved by ApplicationDbContext, which iterates its assemblies inside ApplyConfigurationsForEntitiesInContext (ApplicationDbContext.cs:690,707). Covered by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/DefaultEntityConfigurationAssemblyProviderTests.cs.

EFQueryableExecutor

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/EFQueryableExecutor.cs:11 · Level 1 · class (internal sealed)

• What it is: the EF Core bridge for the Application layer's IQueryableExecutor. It exposes Include, AsSplitQuery, ToListAsync, and CountAsync over an IQueryable<T>, guarding each so the same code path works against a real EF queryable and against a plain in-memory IQueryable.
• Depends on: IQueryableExecutor (the Application-layer contract it implements) and Microsoft.EntityFrameworkCore (EntityFrameworkQueryableExtensions).
• Concept introduced, provider-agnostic query execution. [Rubric §14, Testability] (assesses whether query logic can run without a database) and [Rubric §3, Clean Architecture] (keeps EF's async extension methods behind an Application abstraction): the Application layer builds specifications and calls IQueryableExecutor rather than EF directly, so the same handlers execute against a LINQ-to-Objects list in a unit test and against a SQL provider in production.
• Walkthrough:
  • Include<T> (EFQueryableExecutor.cs:14-18): calls EF's string-based Include on an EF queryable, otherwise returns the query unchanged (in-memory queries are already fully loaded).
  • AsSplitQuery<T> (EFQueryableExecutor.cs:21-25): applies EF's split-query behavior only on EF queryables, otherwise a pass-through.
  • ToListAsync<T> (EFQueryableExecutor.cs:28-31): uses EF's async materialization when available, otherwise the synchronous collection expression [.. query].
  • CountAsync<T> (EFQueryableExecutor.cs:34-37): EF async count when available, otherwise Task.FromResult(query.Count()).
  • IsEfQuery<T> (EFQueryableExecutor.cs:43): the discriminator. An EF provider's queryable implements IAsyncEnumerable<T>, a plain LINQ-to-Objects queryable does not, so a single is IAsyncEnumerable<T> test routes every call above.
• Why it's built this way: internal sealed; centralizing the EF versus in-memory branch in one class means every consumer gets the fallback for free and no handler references EF's static extension methods.
• Where it's used: registered as the singleton IQueryableExecutor (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:112) and injected into Application-layer query code: EntityQueryPipeline (MMCA.Common/Source/Core/MMCA.Common.Application/Services/Query/EntityQueryPipeline.cs:13), the Common notification handlers (GetMyNotificationsHandler.cs:18, GetUnreadNotificationCountHandler.cs:15, GetNotificationHistoryHandler.cs:17, MarkNotificationReadHandler.cs:14, MarkAllNotificationsReadHandler.cs:14) and app handlers such as MMCA.ADC/Source/Modules/Identity/MMCA.ADC.Identity.Application/Users/UseCases/GetUsers/GetUsersHandler.cs:19 and MMCA.ADC/Source/Modules/Engagement/MMCA.ADC.Engagement.Application/SessionQuestions/Services/SessionQuestionViewBuilder.cs:12. Covered by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/EFQueryableExecutorTests.cs.

NamespaceConventions

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/NamespaceConventions.cs:11 · Level 1 · class (internal static)

• What it is: the persistence layer's one-method entry point for deriving a module name from an entity type's namespace. It is a thin forwarder: the parsing itself lives in ModuleNameConventions in MMCA.Common.Shared, so SQL schema names, logical database names and the module label the CQRS logging decorators enrich their scopes with all come from one rule.
• Depends on: ModuleNameConventions (NamespaceConventions.cs:1,20-21); nothing else.
• Concept introduced, convention-over-configuration naming with a single shared parser. [Rubric §8, Data Architecture] (assesses schema and database organization), [Rubric §7, Microservices Readiness] (assesses whether the model splits cleanly per module) and [Rubric §15, Best Practices & Code Quality] (one rule, one implementation): MMCA.Store.Sales.Domain.Orders yields "Sales", which becomes both the [Sales] SQL schema and the Sales logical database name (the worked examples are in the doc comment, NamespaceConventions.cs:14-16). A new module that follows the namespace pattern gets a schema and a data-source name with zero configuration; an explicit [UseDatabase("X")] attribute on a configuration overrides it when the pattern does not fit. The parse was lifted into Shared because Application may not reference Infrastructure and the logging decorators need the same answer (NamespaceConventions.cs:6-9).
• Walkthrough: GetModuleName(Type entityType) (NamespaceConventions.cs:20-21) delegates straight to ModuleNameConventions.GetModuleName (MMCA.Common/Source/Core/MMCA.Common.Shared/Conventions/ModuleNameConventions.cs:38-51). That method splits the namespace on ., defaulting to an empty array when Namespace is null (ModuleNameConventions.cs:40), and applies two rules in order:
  • The Domain rule (ModuleNameConventions.cs:41-46): the case-insensitive index of a Domain segment, and when that index is >= 1 the preceding segment wins. This is the original persistence rule, kept byte for byte so schema and data-source naming never move.
  • The other layer segments (ModuleNameConventions.cs:17,48-50): Application, Infrastructure, API and UI match only at the fourth segment or later (layerIndex >= 3), so a framework namespace such as MMCA.Common.Application.* resolves to null rather than to a phantom "Common" module. Shared is deliberately absent from that list.
• Why it's built this way: a single authority for both derivations means the schema name and the database name are computed identically, so they cannot diverge; keeping the parser in Shared lets Application reuse it without a layer violation. NamespaceConventions stays internal because callers inside Infrastructure should consume the resolved name, not re-derive it.
• Where it's used: EntityDataSourceRegistry falls back to it when no [UseDatabase] is present and then to DataSourceKey.DefaultName (EntityDataSourceRegistry.cs:181), and EntityTypeConfiguration<TEntity, TIdentifierType> uses it for the SQL table schema (EntityTypeConfiguration.cs:66, falling back to dbo) and the Cosmos container name (EntityTypeConfiguration.cs:87, falling back to the entity type name). The Shared parser is separately exercised by MMCA.Common/Tests/Core/MMCA.Common.Shared.Tests/Conventions/ModuleNameConventionsTests.cs, and the persistence forwarder by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/DataSources/EntityDataSourceRegistryTests.cs:54,58.

SoftDeleteFilterSql

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/SoftDeleteFilterSql.cs:16 · Level 1 · class (internal static)

• What it is: the two-method internal static class that owns the IsDeleted = 0 index predicate: it builds the predicate in the identifier-quoting style of the target engine, and it recognises when an index filter already carries that predicate. It is the single authority both the automatic convention and the hand-authored opt-in call, so the two can never disagree.
• Depends on: DataSource (the engine enum), IAuditableEntity (for the nameof(IAuditableEntity.IsDeleted) property name), and EF Core's Microsoft.EntityFrameworkCore.Metadata.IReadOnlyEntityType plus the GetColumnName() relational metadata extension.
• Concept introduced, one predicate builder shared by a convention and an explicit extension. [Rubric §8, Data Architecture] (assesses whether soft-delete is honored by the schema, not just by query filters) and [Rubric §15, Best Practices & Code Quality] (assesses whether one rule has one implementation): a filtered unique index that hardcodes the literal "[IsDeleted] = 0" breaks in two ways, on a model that renames the column with HasColumnName and on a provider that quotes identifiers with double quotes rather than brackets. Reading the column name from the EF model and branching on the engine fixes both, and putting that logic in one place means the automatic path (SoftDeleteUniqueIndexConvention) and the opt-in path (IndexBuilderExtensions) emit byte-identical SQL (SoftDeleteFilterSql.cs:8-15).
• Walkthrough:
  • Build(DataSource engine, IReadOnlyEntityType entityType) (SoftDeleteFilterSql.cs:27-37) has three steps. The Cosmos short-circuit (:29-30) returns null for DataSource.CosmosDB, which has no filtered-index support; null is the contract for "leave the index untouched", and both callers check it before doing anything (SoftDeleteUniqueIndexConvention.cs:57-58, IndexBuilderExtensions.cs:57-58). Column-name resolution (:32) delegates to the private ColumnName helper (:57-59), which looks the IsDeleted property up in the entity type and takes its mapped column name, falling back to the CLR property name when the property is not in the model, so a HasColumnName rename follows automatically. Quoting (:34-36): SQL Server gets [Column] = 0, every other relational engine (SQLite today) gets "Column" = 0.
  • ContainsPredicate(string existingFilter, IReadOnlyEntityType entityType) (SoftDeleteFilterSql.cs:52-55) answers the idempotence question: does a filter already declared on an index constrain the soft-delete column? Both sides are pushed through Normalize (:62-63), which strips whitespace and the three identifier quoting styles ([, ], " and a backtick), so a hand-authored [IsDeleted] = 0, a "IsDeleted"=0 and the string Build produces all count as the same clause (:46-51). Without that normalization the convention would append its own predicate to a filter that already had one and a second model build would emit ... AND [IsDeleted] = 0 AND [IsDeleted] = 0.
• Why it's built this way: internal static with a nullable return keeps the engine-capability decision inside the builder rather than duplicated at each call site. The Cosmos null is a deliberate signal instead of an exception, because both callers run over whole models where Cosmos entities are simply skipped. Comparing on a normalized form rather than on the exact string is what lets the two entry points, which do not agree on quoting, still recognise each other's output.
• Where it's used: SoftDeleteUniqueIndexConvention calls Build at model finalization and ContainsPredicate before combining, then joins with AND in the same order the opt-in extension uses (SoftDeleteUniqueIndexConvention.cs:56,74,79), and IndexBuilderExtensions calls Build for a hand-authored index, optionally joining an extra predicate (IndexBuilderExtensions.cs:56-63).
• Caveats / not-in-source: the double-quote branch is reached by any non-SQL-Server, non-Cosmos engine. SQLite is the only such engine registered today, so whether the quoting suits a future provider is Not determinable from source.

SqlServerUniqueConstraintViolationDetector

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/SqlServerUniqueConstraintViolationDetector.cs:31 · Level 1 · class (sealed)

• What it is: the shipped implementation of IUniqueConstraintViolationDetector. Given the exception a failed save threw, it answers whether the database rejected the write for violating a unique constraint, so a handler whose pre-check lost a race against a concurrent insert can return the same conflict result the pre-check would have produced.
• Depends on: IUniqueConstraintViolationDetector (the Application-layer contract it implements) and Microsoft.Data.SqlClient (SqlException). Nothing else: it holds no state and takes no constructor dependencies.
• Concept introduced, classifying a provider error without leaking the provider. [Rubric §3, Clean Architecture] (assesses whether provider vocabulary stays in Infrastructure): the Application layer references MMCA.Common.Domain and no data provider at all, so neither SqlException nor the EF Core DbUpdateException wrapping it is reachable from a handler (MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Persistence/IUniqueConstraintViolationDetector.cs:9-25). Asking a handler to match on the exception message is what that constraint used to force, and that is wrong twice over: the wording is a provider and locale detail, and matching on it drags provider vocabulary into the layer whose purpose is to stay persistence neutral. [Rubric §29, Resilience & Business Continuity] also applies: the pattern turns a lost insert race into a deterministic conflict answer rather than an unhandled 500, and a miss is safe rather than silent, because an unclassified exception simply keeps propagating.
• Walkthrough: one method, IsUniqueConstraintViolation(Exception exception) (SqlServerUniqueConstraintViolationDetector.cs:46-71).
  • Chain walk (:48): a for loop over current = exception then current.InnerException. EF surfaces a rejected insert as a DbUpdateException wrapping the provider exception, so testing only the outermost exception would never match.
  • Number check (:50-54): the link classifies when it is a SqlException whose Number is 2601 (duplicate key rejected by a unique INDEX, :34) or 2627 (duplicate key violating a PRIMARY KEY or UNIQUE constraint, :37). Every other SQL Server error (a foreign-key failure, a deadlock victim, a timeout) is deliberately not a unique violation and must keep propagating (:13-17).
  • Message fallback (:56-67): a link that is not a SqlException still classifies when its message contains duplicate key (:40, the wording SQL Server and PostgreSQL share) or UNIQUE constraint failed (:43, SQLite), both matched OrdinalIgnoreCase. The comment is explicit that this is a fallback only, for a wrapper that captured the provider failure as text (a retry decorator re-throwing its own type, another engine's provider, a test double), and that the error numbers themselves are never matched as text: they do not appear in the message, so searching for them would match nothing real while happily matching an unrelated exception that quoted those digits.
  • Default (:70): false once the chain is exhausted.
• Why it's built this way: sealed and stateless by construction (:26-29), which is what lets the container register it as a singleton. It is also the default registration for hosts running another engine, not just for SQL Server: the number check never matches there and the message fallback carries them, and a dedicated implementation can replace it whenever an engine deserves its own number check (:19-25).
• Where it's used: registered as the singleton IUniqueConstraintViolationDetector via TryAddSingleton (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:117), which the module registrations rely on rather than shipping their own pair (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.Infrastructure/DependencyInjection.cs:25). The consumers are the handlers whose uniqueness pre-check can lose a race: MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.Application/Sessions/UseCases/Create/CreateSessionHandler.cs:27, MMCA.ADC/Source/Modules/Engagement/MMCA.ADC.Engagement.Application/UserSessionBookmarks/UseCases/Create/CreateBookmarkHandler.cs:21, .../CheckIns/UseCases/GetOrCreateMyBadge/GetOrCreateMyBadgeHandler.cs:20, .../Points/Services/PointsAwarder.cs:32 and .../Points/UseCases/SetLeaderboardParticipation/SetLeaderboardParticipationHandler.cs:33. Behavior is pinned by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/SqlServerUniqueConstraintViolationDetectorTests.cs and the registration by DependencyInjectionInfrastructureTests.cs:263-266.
• Caveats / not-in-source: the message fallback is evaluated for every link in the chain, including a SqlException whose number did not match, so any exception whose message happens to contain duplicate key classifies as a collision. That is the deliberate trade the comment describes; whether a real provider emits that wording for a non-unique failure is Not determinable from source.

IFileStorageService

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Storage · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Storage/IFileStorageService.cs:11 · Level 3 · interface

• What it is: the contract for storing and deleting binary blobs, for example user avatar images. Implementations own the container or bucket; callers pass only a blob name scoped within it.
• Depends on: Result and its generic form (via MMCA.Common.Shared.Abstractions, IFileStorageService.cs:1); BCL Stream and Uri.
• Concept introduced, the managed blob-storage boundary. [Rubric §8, Data Architecture] assesses whether data lands in the right store, and binary content belongs in object storage rather than in a relational row. [Rubric §29, Resilience, Reliability & Business Continuity] assesses whether a transport like this is swappable behind an abstraction. Per the doc comment (IFileStorageService.cs:5-10, ADR-045) the default implementation is unconfigured (uploads fail with a clear error) until a host calls AddAzureBlobFileStorage(configuration) with a complete FileStorage section. Returning Result rather than throwing keeps a failed upload on the same error-flow rails as the rest of the stack (see the primer).
• Walkthrough: one property and two methods.
  • IsConfigured (IFileStorageService.cs:14): whether a real store is wired, so a handler can gate a feature on it rather than attempt a doomed upload.
  • UploadAsync(string blobName, Stream content, string contentType, CancellationToken cancellationToken = default) (IFileStorageService.cs:22): uploads or overwrites a blob and returns its public absolute URL as Result<Uri>. The blob name is container-scoped, for example avatars/42-a1b2c3d4.jpg (IFileStorageService.cs:17), and the content is read from the stream's current position (IFileStorageService.cs:18).
  • DeleteAsync(string blobName, CancellationToken cancellationToken = default) (IFileStorageService.cs:28): deletes a blob; unknown names succeed (idempotent, IFileStorageService.cs:24), which matches at-least-once cleanup semantics.
• Why it's built this way: an unconfigured default plus an IsConfigured gate means the framework ships avatar support without forcing every consumer to provision blob storage, and idempotent delete makes cleanup safe to retry after a partial failure.
• Where it's used: SetUserAvatarHandler uploads the normalized JPEG (SetUserAvatarHandler.cs:26 for the injection, :85 for the call), with RemoveUserAvatarHandler and DeleteUserHandler on the cleanup side. NullFileStorageService is the default registration (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:584); AzureBlobFileStorageService replaces it when configured (DependencyInjection.cs:719).

IImageProcessor

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Storage · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Storage/IImageProcessor.cs:11 · Level 3 · interface

• What it is: the contract for normalizing an untrusted uploaded image: decode it (rejecting non-images), correct EXIF orientation, center-crop to a square, strip all metadata, and re-encode as JPEG.
• Depends on: Result (via MMCA.Common.Shared.Abstractions, IImageProcessor.cs:1); BCL Stream.
• Concept introduced, re-encoding as an image trust boundary. [Rubric §11, Security] assesses whether untrusted binary input is neutralized rather than merely inspected; [Rubric §30, Compliance, Privacy & Data Governance] assesses PII handling, and EXIF GPS coordinates are PII that a naive avatar pipeline would happily publish to a public blob URL. The doc comment (IImageProcessor.cs:5-10, ADR-045) makes both points: metadata removal deletes location data, and re-encoding is the defense against polyglot or malformed payloads because only pixels survive the decode and re-encode round trip. This is the processor half of the pair that ImageContentSniffer opens.
• Walkthrough: one method, NormalizeToSquareJpegAsync(Stream content, int size, CancellationToken cancellationToken = default) (IImageProcessor.cs:18), returning Result<byte[]> of the normalized JPEG or a validation failure for undecodable content (IImageProcessor.cs:17). size is the output square edge length in pixels (IImageProcessor.cs:15), so the caller (not the framework) owns the avatar dimension.
• Why it's built this way: returning bytes rather than writing straight to storage keeps the processor a pure transform, so a handler can sniff, then normalize, then hand the result to IFileStorageService; and a Result failure on undecodable input stops a bad upload before it ever reaches storage.
• Where it's used: called by SetUserAvatarHandler between the sniffer and the upload (SetUserAvatarHandler.cs:25 for the injection, :71 for the call). Implemented by ImageSharpImageProcessor, registered with TryAddSingleton (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:585); note this is the one member of the avatar trio with a real default implementation rather than a null object.

UnitOfWork

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/UnitOfWork.cs:13 · Level 13 · class (internal sealed)

• What it is: the concrete implementation of IUnitOfWork, the scoped coordinator every handler injects to obtain repositories and to save. It caches repositories per entity type so all operations in a scope share one change tracker and context.
• Depends on: IDbContextFactory (implemented by DbContextFactory), IDataSourceService, IRepositoryFactory, AuditableAggregateRootEntity<TIdentifierType>, and AuditableBaseEntity<TIdentifierType>.
• Concept introduced, the Unit of Work over a database-per-service topology. [Rubric §2, Design Patterns] (Unit of Work plus Repository) and [Rubric §8, Data Architecture] (transactions and change-tracker scoping): a handler never knows which database an entity lives in. GetRepository resolves the entity's physical source, obtains the matching context, and builds a repository bound to it; caching that repository per scope guarantees one change tracker per database, which is what makes "load aggregate, mutate, one save" correct.
• Walkthrough:
  • Primary constructor (UnitOfWork.cs:13-16): takes the context factory, the data-source service, and the repository factory, null-guarding the context factory and the repository factory into readonly fields (the data-source service is used directly from the primary-constructor parameter).
  • _repositories (UnitOfWork.cs:23): a Dictionary<Type, object> keyed by the closed generic repository interface (for example IRepository<Order, int>), so a repository is created at most once per entity type per scope.
  • GetRepository<TEntity, TIdentifierType>() (UnitOfWork.cs:33-46): on a cache miss, resolves the entity's DataSourceKey via dataSourceService.GetDataSourceKey(typeof(TEntity)) (UnitOfWork.cs:40), asks the context factory for the matching context (:41), and builds a read-write IRepository<TEntity, TIdentifierType> through IRepositoryFactory (:42); constrained to AuditableAggregateRootEntity<TIdentifierType> so only aggregate roots get a mutable repository.
  • GetReadRepository<TEntity, TIdentifierType>() (UnitOfWork.cs:53-66): the same resolution but calls CreateReadOnly (:62) and accepts any AuditableBaseEntity<TIdentifierType>, returning IReadRepository<TEntity, TIdentifierType> for query handlers.
  • Save and transaction methods (UnitOfWork.cs:69-91): SaveChangesAsync, Save, RequestIdentityInsert, BeginTransaction, CommitTransaction, RollbackTransaction, and ExecuteInTransactionAsync all delegate straight to the context factory, because in a multi-database scope the factory is what coordinates saving and transacting across every context the scope touched.
  • Disposal (UnitOfWork.cs:93-119): implements both Dispose and DisposeAsync over a volatile bool _disposed flag (UnitOfWork.cs:25), disposing the context factory exactly once and suppressing finalization on both paths.
• Why it's built this way: the unit of work plus the factory hide the physical topology from handlers (ADR-006), and per-scope repository caching guarantees a single change tracker per database. It is internal sealed because consumers only ever see the IUnitOfWork abstraction (dependency inversion).
• Where it's used: registered as the scoped IUnitOfWork via TryAddScoped (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:121) and injected into virtually every command and query handler in Common and in both apps, and into the module seeders.

AuditTrailEntry

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.AuditTrail · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/AuditTrail/AuditTrailEntry.cs:23 · Level 0 · class (sealed)

• What it is: one recorded change to an entity that opted into change history, written in the same transaction as the change it describes. It is the row shape of the AuditTrailEntries table: what changed, on which entity, from what to what, by whom, when, under which trace and which tenant.
• Depends on: the UserIdentifierType alias for ChangedBy (AuditTrailEntry.cs:80, the solution-wide identifier alias described in the primer) and nothing else first-party. It is written by AuditTrailSaveChangesInterceptor, purged by AuditTrailCleanupJob, and projected by AuditTrailReader.
• Concept introduced, framework bookkeeping rows versus domain state. [Rubric §8, Data Architecture] (assesses whether persistence mechanics are deliberate: keys, soft-delete, concurrency, retention) and [Rubric §30, Compliance, Privacy & Data Governance] (assesses whether history and personal data are governed rather than accumulated). The class comment states the category decision outright (AuditTrailEntry.cs:9-13): this is deliberately not an IAuditableEntity, exactly like OutboxMessage and ScheduledJobEntry. It carries no soft-delete flag (so no global query filter reaches it), no audit stamps of its own (stamping a stamp record is circular), and no concurrency token. Rows are append-only: nothing in the framework updates one, and the only deletion is the retention sweep.
• Walkthrough: every member is init-only except one.
  • Id (AuditTrailEntry.cs:26): a Guid defaulted to Guid.NewGuid(), so a row is addressable the moment it is constructed, before the database sees it. That matters for the key fix-up below, which needs to find the row by id after the save.
  • EntityType (AuditTrailEntry.cs:33): required, the full CLR type name as a string, not a foreign key. The comment gives the two reasons: the trail outlives the row it describes (a deleted entity keeps its history) and one table spans every audited type.
  • EntityKey (AuditTrailEntry.cs:46): required, the invariant string form of the primary key, with a composite key joined by | in the model's key order. This is the one settable property on the class, and the comment at AuditTrailEntry.cs:40-45 records why: an entity with a store-generated key has no key yet when the change is captured, so the interceptor rewrites this single column once the insert has assigned one.
  • PropertyName, OldValue, NewValue (AuditTrailEntry.cs:52,59,67): all nullable. A property carrying PiiAttribute stores the redaction placeholder on both sides instead of its value (AuditTrailEntry.cs:57,65).
  • Operation (AuditTrailEntry.cs:74): required, one of Added, Modified, Deleted. The comment names the consequence that surprises people: a soft delete arrives as Modified on IsDeleted, which is exactly what it is at the database level.
  • ChangedBy, ChangedOn, CorrelationId, TenantId (AuditTrailEntry.cs:80,83,91,99): the provenance block. ChangedBy is null for a save that carried no identity (a background service, a seeder), CorrelationId is the ambient trace id, and TenantId comes from ApplicationDbContext.CurrentTenantId at capture (ApplicationDbContext.cs:119).
  • Row shape (AuditTrailEntry.cs:15-21): a Modified save produces one row per property that actually changed, so a trail reads as a field-level history; an Added or Deleted save produces a single summary row with a null PropertyName, because the interesting fact there is the lifecycle event and one row per column at insert time would multiply the table for no extra information.
• Why it's built this way: ADR-075 chose a same-transaction, field-level trail over a post-commit log or a database trigger, and this entity is the shape that follows from it. Redacting personal data at capture rather than at read keeps the trail from becoming a second copy of a data subject's data that erasure would have to chase (ADR-005).
• Where it's used: mapped by ApplicationDbContext.ConfigureAuditTrail (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/ApplicationDbContext.cs:628-657) to dbo.AuditTrailEntries (ApplicationDbContext.cs:637) with EntityType at 256 non-unicode characters, EntityKey at 128, PropertyName at 128 non-unicode, Operation at 16 non-unicode and both CorrelationId and TenantId at 64 (ApplicationDbContext.cs:639-645), plus two indexes: IX_AuditTrailEntries_Entity over (EntityType, EntityKey, ChangedOn) for the read path and IX_AuditTrailEntries_ChangedOn for the retention sweep (ApplicationDbContext.cs:646-655). The mapping only happens when AuditTrail:Enabled is true: the context resolves that flag once in OnConfiguring (ApplicationDbContext.cs:291) and ConfigureAuditTrail returns immediately when it is false (ApplicationDbContext.cs:630-633), so a host that never opted in has exactly the model it had before the trail shipped (ApplicationDbContext.cs:66-70).

CaptureContext

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.AuditTrail · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/AuditTrail/AuditTrailSaveChangesInterceptor.cs:541 · Level 0 · record struct (private readonly, nested)

• What it is: a four-field value carrying the provenance every trail row of one save shares: the acting user, the capture instant, the trace id, and the tenant.
• Depends on: the UserIdentifierType alias and System.DateTime; nothing else. It is nested inside AuditTrailSaveChangesInterceptor and private to it.
• Concept introduced, resolve-once-per-save provenance. [Rubric §12, Performance & Scalability] (assesses whether per-item work is hoisted out of loops on a hot path): a save can produce dozens of trail rows, and every one of them wants the same four values. Reading Activity.Current, calling TimeProvider.GetUtcNow() and truncating strings once per save rather than once per row is the whole point, and it also guarantees that every row of one save carries an identical ChangedOn, which is what lets a reader group a save back together.
• Walkthrough: the positional members are ChangedBy (nullable user id), ChangedOn (UTC instant), CorrelationId (nullable trace id) and TenantId (nullable), declared at AuditTrailSaveChangesInterceptor.cs:541-545. It is constructed exactly once per capture, in CaptureChanges (AuditTrailSaveChangesInterceptor.cs:189-193), where the trace id and tenant are already truncated to their column widths (MaxCorrelationIdLength 64 and MaxTenantIdLength 64, AuditTrailSaveChangesInterceptor.cs:80,83). It is then passed by value into CaptureEntry and CaptureModifiedProperties, which copy its fields straight onto each new AuditTrailEntry (AuditTrailSaveChangesInterceptor.cs:257-260,312-315).
• Why it's built this way: readonly record struct means no allocation and no defensive copying concerns for a value that exists only for the duration of one SavingChanges call; private keeps it invisible outside the interceptor. Positional syntax gives it structural equality and a useful ToString for free, neither of which the interceptor needs but neither of which costs anything.
• Where it's used: only inside AuditTrailSaveChangesInterceptor.

AuditTrailSettings

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.AuditTrail · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/AuditTrail/AuditTrailSettings.cs:16 · Level 1 · class (sealed)

• What it is: the AuditTrail configuration section: whether entity change history is recorded at all, how long a row is kept, and which engine's Default database the read surface queries. Every property has a default, so a host that opts in only needs AuditTrail:Enabled (AuditTrailSettings.cs:6-9).

• Depends on: DataSource from MMCA.Common.Application.Interfaces.Infrastructure.Persistence (AuditTrailSettings.cs:2), which is what puts it at Level 1, plus System.ComponentModel.DataAnnotations for [Range] (AuditTrailSettings.cs:1).

• Concept introduced, a settings flag that gates the MODEL, not just behavior. [Rubric §8, Data Architecture] (assesses whether the mapped model and its tables are a deliberate decision) and [Rubric §30, Compliance, Privacy & Data Governance] (assesses whether the system can answer "who changed this, and when"). Most feature flags in this codebase decide whether code runs; this one also decides whether a table exists. Enabled is read in ApplicationDbContext with GetService, not GetRequiredService, and cached in a field (ApplicationDbContext.cs:76, :291) that the model builder consults before mapping the entity (ApplicationDbContext.cs:628-633), so a host that leaves it false has exactly the model it had before the trail existed and its migrations never see an AuditTrailEntries table (AuditTrailSettings.cs:10-15). That is what makes an opt-in feature genuinely free for a host that does not want it: a mapped-but-empty table would still have to be migrated. The trail is off by default because recording history is a data-governance decision an application makes deliberately (ADR-075).

  [Rubric §31, Cost & FinOps]: the doc on Enabled names the cost being avoided outright, a table plus a write per change (AuditTrailSettings.cs:21-25). Marking entities with IAuditedEntity is the second gate and, as AddAuditTrail's remarks put it, that is where the write volume is actually decided (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:471-474).

• Walkthrough: one static field and three init properties.

  • SectionName = "AuditTrail" (AuditTrailSettings.cs:19), the binding key.
  • Enabled (AuditTrailSettings.cs:26), defaulting to false. Read by ApplicationDbContext for the model gate (ApplicationDbContext.cs:291) and re-checked by the cleanup job before it does any work (AuditTrailCleanupJob.cs:72-75).
  • RetentionDays (AuditTrailSettings.cs:38), [Range(1, 3650)] (:37), default 90. AuditTrailCleanupJob turns it into a cutoff instant (AuditTrailCleanupJob.cs:77) and purges from every relational source in use, skipping Cosmos (:79-81) and expanding each source across the declared tenants (:83-86).
  • DataSource (AuditTrailSettings.cs:46), default DataSource.SQLServer. Note the asymmetry the doc calls out (AuditTrailSettings.cs:40-45): rows are WRITTEN to every relational source alongside the data they describe, and this value only says which source the v1 reader looks in. AuditTrailReader resolves it against the Default database of that engine (AuditTrailReader.cs:52-53) and returns an empty result when the entity type is not in that model (AuditTrailReader.cs:55-58).

• Why it's built this way: retention is deliberately NOT self-driving. AddAuditTrail registers AuditTrailCleanupJob (DependencyInjection.cs:492) but a job only runs when the host also calls AddScheduledJobs(configuration) and sets Scheduler:Enabled (DependencyInjection.cs:465-470). Without the scheduler the trail still records everything and RetentionDays is inert, which the settings doc states as a supported state rather than leaving it as a surprise (AuditTrailSettings.cs:32-36). Registering the job in AddAuditTrail rather than in AddScheduledJobs keeps the two features independent (DependencyInjection.cs:489-491).

• Where it's used: bound with .ValidateDataAnnotations().ValidateOnStart() at DependencyInjection.cs:478-481, so a bad RetentionDays fails the host at startup rather than at the first sweep. Read by ApplicationDbContext, AuditTrailReader (AuditTrailReader.cs:34-39) and AuditTrailCleanupJob (AuditTrailCleanupJob.cs:48-55, snapshotted at :60). Design-time tooling supplies the options object by hand so a migration can be generated with the table on or off (DesignTimeDbContextHelper.cs:142-143). The recording itself is AuditTrailSaveChangesInterceptor, registered as a singleton at DependencyInjection.cs:485 and resolved by the context with GetService so its absence reads as "not registered" (ApplicationDbContext.cs:278). Covered by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/AuditTrail/AuditTrailModelGateTests.cs and AddAuditTrailTests.cs.

PendingEntityKey

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.AuditTrail · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/AuditTrail/AuditTrailSaveChangesInterceptor.cs:550 · Level 1 · record (private sealed, nested)

• What it is: a two-field pairing of a staged trail row with the entity entry whose primary key the database has not assigned yet. It exists only between SavingChanges and SavedChanges.
• Depends on: AuditTrailEntry and EF Core's Microsoft.EntityFrameworkCore.ChangeTracking.EntityEntry. It is nested inside and private to AuditTrailSaveChangesInterceptor.
• Concept introduced, the store-generated-key fix-up. [Rubric §8, Data Architecture] (assesses whether key strategy and its consequences are handled deliberately): the trail is captured before the save, which is exactly what makes it transactional, but an entity whose key is an identity column has no key at that moment. EF holds a temporary sentinel value that would make the row unfindable by key (AuditTrailSaveChangesInterceptor.cs:263-266). Remembering the pair, then rewriting the one column after the insert, is the price of capturing early; the alternative (capturing after the save) would put the trail outside the transaction and lose the guarantee the whole design exists for.
• Walkthrough: the positional members are Row (the tracked trail row whose EntityKey must be rewritten) and Entry (the audited entry whose key the database assigns), declared at AuditTrailSaveChangesInterceptor.cs:550. Instances are produced by CaptureEntry only when the entry is Added and HasTemporaryKey(entry) returns true (AuditTrailSaveChangesInterceptor.cs:267-269, with the temporary-key test walking every primary key property at :449-466). They are accumulated into a list and parked in a ConditionalWeakTable<DbContext, List<PendingEntityKey>> keyed by the context (AuditTrailSaveChangesInterceptor.cs:92,213-216), then drained in ResolveGeneratedKeysAsync or ResolveGeneratedKeys (:368-396,402-429).
• Why it's built this way: a record gives value semantics and a readable two-name shape for something that is pure bookkeeping; private sealed keeps it invisible. Holding the list in a ConditionalWeakTable rather than in an instance field is what lets the interceptor stay a singleton shared by every context without leaking state across them, and the weak keying means a context that is dropped without a save takes its pending list with it.
• Where it's used: only inside AuditTrailSaveChangesInterceptor.

AuditTrailSaveChangesInterceptor

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.AuditTrail · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/AuditTrail/AuditTrailSaveChangesInterceptor.cs:62 · Level 11 · class (sealed)

• What it is: the EF Core save interceptor that records a field-level change history for every entity marked IAuditedEntity, writing AuditTrailEntry rows into the same transaction as the change they describe.
• Depends on: AuditTrailEntry, CaptureContext, PendingEntityKey, ApplicationDbContext, IAuditedEntity, PiiAttribute, PiiRedactor, OutboxMessage, InboxMessage, ScheduledJobEntry, and the BCL TimeProvider, Activity, ConditionalWeakTable and ConcurrentDictionary.
• Concept introduced, the transactional change trail. [Rubric §6, CQRS & Event-Driven] (the same interceptor-pipeline mechanic the outbox uses, applied to a different payload), [Rubric §8, Data Architecture], [Rubric §13, Observability & Operability] (each row carries the ambient trace id, so a change ties back to the request or job that made it) and [Rubric §30, Compliance, Privacy & Data Governance] (personal data is redacted at capture, never at read). The class comment states the guiding rule (AuditTrailSaveChangesInterceptor.cs:18-23): a trail that can be committed without its data, or the other way round, is worse than no trail. Four mechanics are worth learning here as a set.
  • Opt in twice over (AuditTrailSaveChangesInterceptor.cs:32-36): the host must call AddAuditTrail (the context resolves this interceptor with GetService, so its absence is a silent no-op, ApplicationDbContext.cs:275-280) and set AuditTrail:Enabled so the table is mapped. Then the entity must carry the marker. Nothing about the feature is on by default.
  • Position in the pipeline (AuditTrailSaveChangesInterceptor.cs:25-31): registered last, after AuditSaveChangesInterceptor, the optional TenantSaveChangesInterceptor and DomainEventSaveChangesInterceptor (ApplicationDbContext.cs:256-280), so the values it diffs are final: the audit stamps are already written when it runs.
  • Correlation is the trace id, not the scoped correlation context (AuditTrailSaveChangesInterceptor.cs:43-54): this interceptor is a singleton and the only service provider a context carries is the root one, so a scoped ICorrelationContext is not reachable from here and capturing one would be a lifetime bug. The trace id is ambient and is the same value CorrelationIdMiddleware falls back to when a request carries no X-Correlation-ID header. A caller-supplied header value is therefore NOT recorded today.
  • Tenant is read off the context (AuditTrailSaveChangesInterceptor.cs:55-59), through the live accessor the scoped context factory assigns (ApplicationDbContext.cs:119), so it does reach the interceptor where a scoped service would not.
• Walkthrough:
  • Constants (AuditTrailSaveChangesInterceptor.cs:64-86): the three operation names, the four column widths (MaxEntityTypeLength 256, MaxKeyLength 128, MaxCorrelationIdLength 64, MaxTenantIdLength 64) and the | composite-key separator. They match the model mapping in ApplicationDbContext.ConfigureAuditTrail exactly (ApplicationDbContext.cs:639-645).
  • Static state (AuditTrailSaveChangesInterceptor.cs:88-119): two ConditionalWeakTables keyed by context (pending key fix-ups, and a marker for "a capture staged rows but the save has not finished"), a ConcurrentDictionary caching the PII verdict per (declaring type, property name), and a HashSet<Type> of the framework's own bookkeeping entities. That last set is guarded by CLR type, not by the absence of the marker, which is what keeps the trail from recording its own rows in an unbounded feedback loop and keeps the outbox, inbox and job tables out of a history nobody asked for (AuditTrailSaveChangesInterceptor.cs:107-119). IsFrameworkEntity(Type) (:171) is the internal window onto that set, which is both how ShouldAudit consults it and how a test can assert the exclusion list directly.
  • The four overrides (AuditTrailSaveChangesInterceptor.cs:122-163): SavingChangesAsync and SavingChanges both call CaptureChanges; SavedChangesAsync and SavedChanges both run the key fix-up. Each pattern-matches eventData.Context is ApplicationDbContext first, so a foreign context passes straight through.
  • CaptureChanges (AuditTrailSaveChangesInterceptor.cs:177-219): the first statement is the cheap double gate, context.Model.FindEntityType(typeof(AuditTrailEntry)) is null (:179-185), which covers both a host that never opted in and Cosmos (which skips relational tables), because Set<AuditTrailEntry>() would throw for both. Then it discards an abandoned capture, builds one CaptureContext, snapshots ChangeTracker.Entries().Where(ShouldAudit).ToArray() (:197, materialized before adding, because enumerating the tracker lazily while adding to it would throw), and captures each entry.
  • ShouldAudit (AuditTrailSaveChangesInterceptor.cs:225-228): the entity carries the marker, is not a framework bookkeeping type, and is in state Added, Modified or Deleted.
  • CaptureEntry (AuditTrailSaveChangesInterceptor.cs:238-270): a Modified entry delegates to the per-property diff; an Added or Deleted entry writes one summary row and then, only when the insert's key is still temporary, returns a PendingEntityKey.
  • CaptureModifiedProperties (AuditTrailSaveChangesInterceptor.cs:277-318): one row per property that is IsModified and whose value actually differs. A property EF flagged as modified but whose value is unchanged (the whole-entity Update idiom) writes nothing (:272-276). PiiRedactor.HasPii(entry.Metadata.ClrType) is checked once per entity so a type with no personal data skips the per-property attribute lookup entirely (:286), and a PII property records PiiRedactor.RedactedToken on both sides (:309-310).
  • DiscardAbandonedCapture (AuditTrailSaveChangesInterceptor.cs:339-360): the retry-safety mechanic. An execution strategy that retries a failed save re-runs SavingChanges against a tracker that still holds the previous attempt's Added rows, so without this one transient SQL fault writes the trail twice. It only fires when the marker is present (a completed save leaves none Added), because discarding unconditionally would also throw away trail rows a caller added deliberately.
  • ResolveGeneratedKeysAsync and ResolveGeneratedKeys (AuditTrailSaveChangesInterceptor.cs:368-396,402-429): rebuild the key now that the insert has assigned one, skip rows whose key did not change, and rewrite the one column with a set-based ExecuteUpdate per row, which bypasses the change tracker and the interceptor pipeline and joins the ambient transaction when one is open (the same technique as OutboxFinalizer). SyncTrackedKey (:437-443) then brings the tracked instance and its snapshot in line so a later save does not re-issue the update, and the ordering there is load-bearing: writing OriginalValue must precede clearing IsModified, because clearing the flag reverts the current value to the original.
  • Helpers: AddRow (:325-331, mutation is Add only, because the save runs with automatic change detection off), HasTemporaryKey (:449-466), BuildEntityKey (:473-485, a keyless entity yields an empty string rather than throwing), IsPiiProperty (:492-504, a shadow property has no PropertyInfo so it can never be personal data), FormatValue (:510-511, CultureInfo.InvariantCulture on purpose, so a trail read years later or on a differently localized replica shows the value that was written), ValuesEqual (:517-530, byte arrays such as row versions are compared by content, since reference equality would report every save as a change) and Truncate (:533-534).
• Why it's built this way: ADR-075 chose the interceptor over a repository decorator (which sees intent, not the tracker's diff), an application handler (which sees the command, not the properties EF marked modified) and a database trigger (which sees the diff and nothing else: no user, no correlation id, no PII knowledge). Committing in the caller's transaction is the outbox mechanic of ADR-003 applied to a different payload, and redacting at capture is what keeps the trail compatible with ADR-005.
• Where it's used: registered as a singleton by AddAuditTrail (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:476,483-485, singleton for the same reason as the other two save interceptors: stateless, with per-save state in a ConditionalWeakTable keyed by context), added to the EF pipeline in ApplicationDbContext.OnConfiguring (ApplicationDbContext.cs:275-280), and registered in the design-time pipeline too so dotnet ef matches runtime (DesignTimeDbContextHelper, MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Design/DesignTimeDbContextHelper.cs:142-144). Behavior is pinned by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/AuditTrail/AuditTrailSaveChangesInterceptorTests.cs and AuditTrailModelGateTests.cs. Hosts opting in today include MMCA.Helpdesk (MMCA.Helpdesk/Source/Hosts/MMCA.Helpdesk.Web/Program.cs:78), all three MMCA.Store services (Identity.Service/Program.cs:188, Sales.Service/Program.cs:206, Catalog.Service/Program.cs:210) and all three MMCA.ADC services (Engagement.Service/Program.cs:197, Identity.Service/Program.cs:232, Conference.Service/Program.cs:296).
• Caveats / not-in-source: a caller-supplied X-Correlation-ID is not recorded; honoring it would need a live accessor on the context assigned by the scoped factory, the shape multi-tenancy introduced for TenantId (AuditTrailSaveChangesInterceptor.cs:51-53). Whether that will be done is Not determinable from source.

AuditTrailCleanupJob

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.AuditTrail · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/AuditTrail/AuditTrailCleanupJob.cs:48 · Level 13 · class (internal sealed partial)

• What it is: the framework's own recurring job. It purges AuditTrailEntry rows older than the configured retention window from every relational data source in use, in batches.
• Depends on: IScheduledJob (the contract it implements), IDbContextFactory, IEntityDataSourceRegistry, AuditTrailSettings and TenancySettings via IOptions<>, ITenantContext, TenantDataSourceTargets plus TenantDataSourceTarget, DataSource, TimeProvider, IServiceScopeFactory and ILogger<T>.
• Concept introduced, retention as a first-class part of a history feature. [Rubric §30, Compliance, Privacy & Data Governance] (assesses whether retained data has a bounded lifetime), [Rubric §31, Cost & FinOps] (assesses whether unbounded growth is designed out) and [Rubric §29, Resilience & Business Continuity] (a first sweep over a neglected table must not become one enormous transaction). The class comment makes the argument (AuditTrailCleanupJob.cs:18-22): a change trail grows monotonically and stores values that may describe a data subject, so a retention window is not housekeeping, it is what keeps the table from being both a cost centre and a data-protection liability. It also records the honest limitation (AuditTrailCleanupJob.cs:23-28): AddAuditTrail registers the job, but a job with no runner never executes, so the host must also call AddScheduledJobs and set Scheduler:Enabled. A host that records the trail without the scheduler is fully supported and keeps recording; pruning is then the operator's job.
• Walkthrough:
  • Constructor (AuditTrailCleanupJob.cs:48-55): the last two parameters are optional. The scope factory and the tenancy options default to null, because a host without tenancy never leaves the job's own scope. _settings is snapshotted from options.Value (:60), and RetentionDays defaults to 90 with a [Range(1, 3650)] guard (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/AuditTrail/AuditTrailSettings.cs:36-37).
  • Name and CronExpression (AuditTrailCleanupJob.cs:63,67): "audit-trail-cleanup", daily at 0 3 * * *, chosen to sit off the daily peak for every time zone the framework runs in.
  • ExecuteAsync (AuditTrailCleanupJob.cs:70-87): returns immediately when AuditTrail:Enabled is false (:72-75), computes the cutoff as now minus RetentionDays (:77), enumerates the physical sources in use and filters out DataSource.CosmosDB (:79-81), then expands that set into per-tenant targets through TenantDataSourceTargets and sweeps each one (:83-86).
  • PurgeTargetAsync (AuditTrailCleanupJob.cs:94-112): the shared database is swept on the job's own scope; a tenant that keeps its own database gets a fresh scope with ITenantContext.SetTenant applied (:105-111), because the scoped context factory binds one database per scope and the job's scope is already bound to the shared one.
  • PurgeWithFactoryAsync (AuditTrailCleanupJob.cs:115-136): resolves the target's context and re-checks the model for the trail entity (:125-128). Cosmos is already excluded, but a relational source can still lack the table when the host disabled the trail after writing it, so the model, not the configuration, is the authority.
  • PurgeSourceAsync (AuditTrailCleanupJob.cs:142-179): the batching loop. It reads up to BatchSize (1000, :58) ids with AsNoTracking, ordered by ChangedOn, then deletes those ids with ExecuteDeleteAsync. The comment at :151-153 explains the two-step shape: every relational provider translates an IN list, while a limited DELETE is not universally supported. The loop ends when a page comes back empty (:162-165) or short (:172-175), and it re-checks the cancellation token each turn (:149). No row is ever materialized as an entity.
  • Logging (AuditTrailCleanupJob.cs:181-182): a source-generated LoggerMessage emitted only when a sweep actually removed rows (:131-135), so a quiet night logs nothing.
• Why it's built this way: registering the job in AddAuditTrail rather than in AddScheduledJobs keeps the two features independent, which the DI comment states outright (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:489-491): the trail can be enabled without the scheduler and the scheduler without the trail. Set-based batched deletion is the same discipline the outbox retention sweep uses, for the same reason.
• Where it's used: registered through AddScheduledJob<AuditTrailCleanupJob>() inside AddAuditTrail (DependencyInjection.cs:492, and that helper does a TryAddScoped of the concrete type plus a TryAddEnumerable of IScheduledJob at :426-431), and executed by ScheduledJobRunner when the host runs the scheduler. Covered by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/AuditTrail/AuditTrailCleanupJobTests.cs.

AuditTrailReader

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.AuditTrail · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/AuditTrail/AuditTrailReader.cs:34 · Level 13 · class (internal sealed)

• What it is: the read side of the trail, and the only implementation of IAuditTrailReader. It returns one entity's change history, newest first, as a paged list of AuditTrailEntryDTO.
• Depends on: IAuditTrailReader, IDbContextFactory, IDataSourceResolver, DataSourceKey, AuditTrailEntry, AuditTrailEntryDTO and AuditTrailSettings via IOptions<> (AuditTrailReader.cs:34-39).
• Concept introduced, projecting to a DTO inside the query rather than after it. [Rubric §9, API & Contract Design] (the Application-layer contract returns a DTO, never the persistence entity) and [Rubric §12, Performance & Scalability] (the Select is part of the SQL, so only the projected columns cross the wire, and AsNoTracking keeps the rows out of the change tracker). The ordering is ChangedOn descending with Id as the tie-break (AuditTrailReader.cs:62-63), which matters because every row of one save shares an identical ChangedOn: without the second key, paging over a save's worth of rows would not be stable.
• Walkthrough: GetForEntityAsync(entityType, entityKey, page = 1, pageSize = 50, ct) (AuditTrailReader.cs:42-47).
  • Paging guards (AuditTrailReader.cs:49-50): a page or page size below 1 is coerced to 1 rather than rejected, so a bad caller gets the first page instead of an exception.
  • Source resolution (AuditTrailReader.cs:52-53): resolves the Default database of the engine named by AuditTrail:DataSource (defaulting to SQL Server, AuditTrailSettings.cs:46) and asks the context factory for it.
  • Model gate (AuditTrailReader.cs:55-58): returns an empty list when the trail entity is not in the model. The comment gives the reason (AuditTrailReader.cs:25-29): the read surface is registered by AddAuditTrail, which a host may call before flipping AuditTrail:Enabled per environment, so "not enabled" must read as "no history", not as an exception.
  • The query (AuditTrailReader.cs:60-80): AsNoTracking, filtered on EntityType and EntityKey (exactly the leading columns of IX_AuditTrailEntries_Entity, ApplicationDbContext.cs:648-649), ordered, skipped and taken, then projected column by column into the DTO (AuditTrailReader.cs:66-78). TenantId is not projected, because the DTO has no such member: it declares Id through CorrelationId and stops there (MMCA.Common/Source/Core/MMCA.Common.Application/Auditing/AuditTrailEntryDTO.cs:12-48).
• Why it's built this way: the DTO stops the persistence entity from leaking into the Application contract, and matching the query's predicate and sort to the shipped index is why that index carries the whole predicate plus the sort rather than just the key (ApplicationDbContext.cs:646-649).
• Where it's used: registered as the scoped IAuditTrailReader by AddAuditTrail (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:487). Covered by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/AuditTrail/AuditTrailReaderTests.cs and the registration by AddAuditTrailTests.cs:64,89. A source search across the workspace finds no application or UI consumer of the interface today: it is a shipped read surface that hosts can inject, not a wired-up screen.
• Caveats / not-in-source: the class documents its own v1 limitation (AuditTrailReader.cs:15-24). Trail rows are written to whichever database holds the entity that changed (that is what makes the write atomic), so a host that splits its modules across several databases has several trail tables, and this reader queries exactly one of them: the Default database of the configured engine. For a monolith, where every source collapses onto Default, that is the whole trail. Reading another module's history would need a per-source overload, which the comment says was deliberately deferred rather than guessed at.

ConnectionStringSettings

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DataSources · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/ConnectionStringSettings.cs:12 · Level 0 · class (sealed)

• What it is: the class bound from the top-level ConnectionStrings section, one connection string per supported engine plus the Cosmos database name and the SQL Server migrations assembly. It describes the Default physical data source, the one every unmapped logical name collapses onto.

• Depends on: nothing first-party and nothing beyond string from the BCL, which is what puts it at Level 0. It is read by DataSourceResolver and cross-checked by ConnectionStringSettingsValidator.

• Concept introduced, fail-fast configuration where the rule spans two sections. [Rubric §15, Best Practices & Code Quality] assesses whether misconfiguration is caught early. AddOptions<T>().Bind(...).ValidateDataAnnotations().ValidateOnStart() (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:78-81) is the pattern every validated settings class uses, and ADR-070 makes it the required form: annotations run during host startup rather than lazily on first resolution. ValidateOnStart() is the load-bearing call.

  What this type teaches on top of that is the limit of the annotation approach. No property here is [Required], and the class doc says why (ConnectionStringSettings.cs:5-10): SQL Server is the default engine, but a host may run entirely on SQLite or Cosmos and may declare its databases under DataSources instead of this section. A [Required] attribute can only see one property on one class, so the real invariant ("the host can reach SOME database") is expressed as an IValidateOptions<T> implementation registered alongside the binding, ConnectionStringSettingsValidator (DependencyInjection.cs:88-89). [Rubric §8, Data Architecture]: the rule spans both configuration shapes precisely because the physical topology is a deployment decision, not a compile-time one.

• Walkthrough: one static field and five { get; init; } strings.

  • SectionName = "ConnectionStrings" (ConnectionStringSettings.cs:15), reusing ASP.NET Core's own conventional section so GetConnectionString(...) and this class read the same data.
  • CosmosConnectionString (ConnectionStringSettings.cs:18), empty by default.
  • CosmosDatabaseName (ConnectionStringSettings.cs:21), the one property with a non-empty default, "AtlDevCon".
  • SqliteConnectionString (ConnectionStringSettings.cs:24), documented as typically a file path.
  • SQLServerConnectionString (ConnectionStringSettings.cs:27), the production engine's connection string.
  • SQLServerMigrationsAssembly (ConnectionStringSettings.cs:33), empty by default, which makes EF fall back to the DbContext assembly (ConnectionStringSettings.cs:29-32).
  • The registered validator is the interesting half. ConnectionStringSettingsValidator.Validate succeeds when either the top-level section names a database on any engine (ConnectionStringSettingsValidator.cs:56-59) or any named DataSources entry does (ConnectionStringSettingsValidator.cs:66-71), and otherwise fails with a message that lists both shapes because which one is missing depends on the host (ConnectionStringSettingsValidator.cs:38-43, ConnectionStringSettingsValidator.cs:46-53). Its remarks record the change of rule directly: this replaced a [Required] on SQLServerConnectionString that failed a legitimate SQLite-only host at startup (ConnectionStringSettingsValidator.cs:11-24).

• Why it's built this way: init-only properties make the bound settings immutable after startup, which DataSourceResolver relies on, since it classifies every physical source once in its constructor (DataSourceResolver.cs:53-71). Keeping the "some database" check at boot rather than at first query is what stops a host from reporting healthy while unable to serve a request (ConnectionStringSettingsValidator.cs:20-24).

• Where it's used: bound and validated in AddInfrastructure (DependencyInjection, DependencyInjection.cs:78-89); consumed by DataSourceResolver through IOptions<ConnectionStringSettings> (DataSourceResolver.cs:54, DataSourceResolver.cs:61), which reads it while seeding each engine's Default source (DataSourceResolver.cs:197-232) and while applying the Cosmos database-name fallback (DataSourceResolver.cs:235-236).

• Caveats: the "AtlDevCon" Cosmos default (ConnectionStringSettings.cs:21) is an application-specific name (the ADC conference database) baked into a framework package; every other default here is neutral.

DataSourceEntrySettings

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DataSources · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/DataSourceEntrySettings.cs:19 · Level 0 · class (sealed)

• What it is: the shape of ONE named entry under the DataSources configuration section, the per-logical-source counterpart to the top-level ConnectionStrings block. It carries a connection string per engine plus three per-source overrides (Cosmos database name and a migrations assembly for each relational engine).
• Depends on: nothing first-party and nothing beyond string from the BCL, which is why it sits at Level 0. It is aggregated by DataSourcesSettings and read by DataSourceResolver.
• Concept introduced, configuration as the physical-topology dial. [Rubric §8, Data Architecture] assesses how the logical model maps onto physical stores; [Rubric §7, Microservices Readiness] assesses whether a module can be lifted out with its own database. The declarative half of that story is UseDatabaseAttribute, which names a logical source on an entity configuration. This class is the other half: it says what that logical name physically means in a given deployment. Nothing in the code decides the topology; the same compiled assemblies run as a one-database monolith or as N separate databases depending on how many entries exist here. [Rubric §15, Best Practices & Code Quality]: because every property defaults to string.Empty (DataSourceEntrySettings.cs:22-52), a partially filled entry is legal and each empty value falls back to the corresponding top-level value, so a host adds a database by adding one JSON object and nothing else.
• Walkthrough: six { get; init; } properties, all defaulting to string.Empty.
  • CosmosConnectionString (DataSourceEntrySettings.cs:22) and CosmosDatabaseName (DataSourceEntrySettings.cs:25), the Cosmos pair; the database name falls back to the top-level CosmosDatabaseName when empty (DataSourceResolver applies that fallback at DataSourceResolver.cs:235-236 and again at DataSourceResolver.cs:262-264).
  • SqliteConnectionString (DataSourceEntrySettings.cs:28), the SQLite path (ADR-018 polyglot persistence).
  • SqliteMigrationsAssembly (DataSourceEntrySettings.cs:43), and its doc is worth reading in full (DataSourceEntrySettings.cs:30-42): there is deliberately NO top-level fallback for it. The top-level ConnectionStrings section carries only a SQL Server migrations assembly, so a SQLite host declares its own here through an entry that collapses onto Default. Without that asymmetry a mixed-engine host would silently hand its SQL Server migrations assembly to a SQLite database.
  • SQLServerConnectionString (DataSourceEntrySettings.cs:46), the production engine's connection string.
  • SQLServerMigrationsAssembly (DataSourceEntrySettings.cs:52), the EF Core migrations assembly for THIS source, documented as falling back to the top-level value when empty (DataSourceEntrySettings.cs:48-51).
  • The resolver reads the pair through one engine-keyed switch, GetMigrationsAssembly (DataSourceResolver.cs:405-410), stamps the SQLite value onto the PhysicalDataSource only for SQLite sources (DataSourceResolver.cs:398), and names the offending setting per engine when two logical names collapse onto one database with conflicting values (DataSourceResolver.cs:430).
  • The XML doc carries a worked appsettings.json example for a Conference source (DataSourceEntrySettings.cs:9-18), which is the fastest way to see the intended shape.
• Why it's built this way: init-only properties make a bound entry immutable after startup, and the "empty means inherit" rule is what keeps the single-database default intact: an app that configures no DataSources section behaves exactly as it did before the section existed (ADR-006).
• Where it's used: bound as the value type of the dictionary that AddInfrastructure reads with configuration.GetSection(DataSourcesSettings.SectionName).Get<Dictionary<string, DataSourceEntrySettings>>() (DependencyInjection.cs:92-94); consumed by DataSourceResolver when it classifies logical names into physical sources (DataSourceResolver.cs:251-265) and when it tests whether any entry names a database for an engine (DataSourceResolver.cs:130-135), and by ConnectionStringSettingsValidator when it looks for any configured database (ConnectionStringSettingsValidator.cs:66-71).

DefaultSeed

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DataSources · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/DataSourceResolver.cs:172 · Level 0 · record (sealed, private nested)

• What it is: a three-field carrier describing what the Default physical source of one engine is built from: ConnectionString, MigrationsAssembly, and CosmosDatabaseName (DataSourceResolver.cs:172). It exists only inside DataSourceResolver, where it is computed once per engine and then threaded through the four private methods that build that engine's map.
• Depends on: nothing first-party. It holds three string values, all of which may legitimately be empty. It is produced from ConnectionStringSettings and DataSourcesSettings by ResolveDefaultSeed (DataSourceResolver.cs:197-232).
• Concept introduced, the two-branch answer to "which database is Default". [Rubric §8, Data Architecture] assesses whether the mapping from configuration to physical storage is explicit and has one owner; [Rubric §15, Best Practices & Code Quality] assesses whether a rule that several methods depend on is stated once instead of recomputed at each use. Default is the logical name every framework-owned table resolves to (outbox, inbox, scheduled jobs, audit trail), so "what is Default" has to have an answer even in a host that never wrote a top-level ConnectionStrings entry. The seed is that answer, and computing it into a record rather than passing three loose strings is what lets ClassifyEntries, RegisterDefaultSource, and RegisterNamedSource all agree on it (DataSourceResolver.cs:156-163).
• Walkthrough
  • ConnectionString (DataSourceResolver.cs:169, DataSourceResolver.cs:172) is the connection the Default source uses, and is empty when the engine is unconfigured. Branch one of ResolveDefaultSeed takes it straight from the top-level section when that section names a connection for the engine (DataSourceResolver.cs:202-212). Branch two applies only when the top-level value is absent: the named DataSources entries are filtered down to the ones carrying a connection for this engine (DataSourceResolver.cs:214-216), their connection identities are counted distinctly (DataSourceResolver.cs:218-221), and when exactly ONE distinct database is named that database becomes Default (DataSourceResolver.cs:226-230). With several distinct databases and no top-level value there is no single answer, so the seed stays empty (DataSourceResolver.cs:231) and a genuinely multi-database host names the shared one by adding a DataSources:Default entry.
  • MigrationsAssembly (DataSourceResolver.cs:170) is populated only on the top-level branch, and only for SQL Server: ConnectionStrings carries no SQLite equivalent, and handing a SQLite Default source the SQL Server value in a mixed-engine host would scaffold the wrong schema (DataSourceResolver.cs:207-210). Branch two deliberately leaves it empty (DataSourceResolver.cs:223-225): every entry it considered has the seed's own connection identity, so those entries all collapse onto Default and contribute their declared assemblies through AddExplicitMigrationsAssemblies, conflicts included. A test pins that the single named entry's assembly still reaches the Default source that way (MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/DataSources/DataSourceResolverTests.cs:375).
  • CosmosDatabaseName (DataSourceResolver.cs:171) is the database name entries fall back to when they declare none of their own, applied by CosmosDatabaseNameOf (DataSourceResolver.cs:235-236) and again inline while classifying entries (DataSourceResolver.cs:262-264).
• Why it's built this way: branch two cannot change an existing host's routing, because it fires only where the top-level value is absent (DataSourceResolver.cs:179-185). That is the additive-by-construction property the whole data-source layer is built on (ADR-006): a host that declares its database only under DataSources gets a working Default, and a host that declares it the old way resolves exactly as it always did.
• Where it's used: only within DataSourceResolver. BuildEngineMap computes it (DataSourceResolver.cs:156) and passes it to ClassifyEntries (DataSourceResolver.cs:157), RegisterDefaultSource (DataSourceResolver.cs:158), and RegisterNamedSource (DataSourceResolver.cs:162). The two behaviors it decides are pinned by DataSourceResolverTests.cs:375 and DataSourceResolverTests.cs:396.
• Caveats / not-in-source: a private nested type. It is inventoried because private nested types are, but nothing outside the resolver can name it, and it never leaves the constructor's call graph.

DataSourcesSettings

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DataSources · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/DataSourcesSettings.cs:13 · Level 1 · class (sealed)

• What it is: the bound DataSources section as a whole, a read-only dictionary of logical source name to DataSourceEntrySettings. It is the configuration input to database-per-microservice routing.
• Depends on: DataSourceEntrySettings and DataSourceKey.DefaultName from the Application layer (DataSourceKey), referenced by its fully qualified name Application.Interfaces.Infrastructure.Persistence.DataSourceKey (DataSourcesSettings.cs:34).
• Concept introduced, a settings class that validates in its own constructor. Most settings types here are inert bags validated by data annotations. This one is different, and the reason is stated in its own doc: a root-level dictionary section does not bind through the options pipeline, so AddInfrastructure builds the instance by hand from configuration.GetSection(...).Get<Dictionary<string, DataSourceEntrySettings>>() and registers it as a singleton (DataSourcesSettings.cs:8-11, MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:90-94). With no options pipeline there is no ValidateOnStart, so the constructor becomes the fail-fast gate. [Rubric §15, Best Practices & Code Quality]: rejecting a reserved name at construction is the same guarantee ValidateOnStart would have given, implemented where the type can enforce it itself. [Rubric §8, Data Architecture]: the reserved-name rule protects a real invariant, Default is configured through the top-level ConnectionStrings section, and letting someone also declare a DataSources:Default entry would create two competing definitions of the same physical source.
• Walkthrough
  • SectionName = "DataSources" (DataSourcesSettings.cs:16).
  • The constructor takes an optional IReadOnlyDictionary<string, DataSourceEntrySettings>? (DataSourcesSettings.cs:23) and substitutes an empty ordinal-comparer dictionary when it is null (DataSourcesSettings.cs:25), so "no DataSources section" is a first-class state rather than a null check at every call site.
  • It then walks every key (DataSourcesSettings.cs:27-40) and throws InvalidOperationException twice: on a blank or whitespace name (DataSourcesSettings.cs:29-32), and on any name equal to DataSourceKey.DefaultName under OrdinalIgnoreCase (DataSourcesSettings.cs:34-39). The second message is unusually good operator guidance: it names the offending entry and tells the reader that the Default source is configured via the top-level ConnectionStrings section, so remove or rename the entry.
  • Sources (DataSourcesSettings.cs:44), the get-only dictionary the resolver reads.
• Why it's built this way: throwing during host construction is the earliest possible point at which a duplicate Default definition can be caught; the alternative is a routing bug that surfaces as data landing in the wrong database (ADR-006).
• Where it's used: constructed and registered as a singleton in AddInfrastructure (DependencyInjection.cs:92-94), immediately before DataSourceResolver and EntityDataSourceRegistry (DependencyInjection.cs:95-96). It is consumed by the resolver's constructor (DataSourceResolver.cs:55, DataSourceResolver.cs:63-71), by its "is any database configured for this engine" test (DataSourceResolver.cs:130-135) and its classification pass (DataSourceResolver.cs:251-265), and by ConnectionStringSettingsValidator, which takes it as an optional constructor dependency so that a container binding the settings without AddInfrastructure still validates (ConnectionStringSettingsValidator.cs:26-30, ConnectionStringSettingsValidator.cs:66-71).
• Caveats: the key comparison for reservation is OrdinalIgnoreCase (DataSourcesSettings.cs:34) while the default backing dictionary uses StringComparer.Ordinal (DataSourcesSettings.cs:25). The dictionary that configuration binding actually supplies is created by the binder, so its comparer is not determined by this file.

ConnectionStringSettingsValidator

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DataSources · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/ConnectionStringSettingsValidator.cs:30 · Level 2 · class (sealed, internal)

• What it is: the startup validator for ConnectionStringSettings. It enforces exactly one rule: the host must be able to reach at least one database, declared either in the top-level ConnectionStrings section or on a named DataSources entry (ConnectionStringSettingsValidator.cs:5-9).

• Depends on: DataSourcesSettings as an OPTIONAL primary-constructor parameter (ConnectionStringSettingsValidator.cs:30) and ConnectionStringSettings as the validated type (ConnectionStringSettingsValidator.cs:31). Externals: Microsoft.Extensions.Options for IValidateOptions<T> and ValidateOptionsResult.

• Concept introduced, the rule that cannot be an attribute. A data annotation can only see the object it decorates. This rule spans two independently bound configuration sections, and that is the whole reason the class exists. The class remarks say what it replaced: a [Required] on ConnectionStringSettings.SQLServerConnectionString, which encoded "SQL Server is the only engine a host can boot on" (ConnectionStringSettingsValidator.cs:11-18). That stopped being true once a small application could run entirely on SQLite or Cosmos, declaring its databases through the DataSources section and leaving the top-level section empty; the annotation failed such a host at startup even though every one of its entities resolved to a configured database. The registration comment in the composition root makes the same point at the call site (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:83-87).

  [Rubric §17, DevOps & Deployment] assesses whether configuration is validated centrally rather than defensively at each read. The check runs once, at boot, under ValidateOnStart, so no downstream component has to ask "did anyone configure a database".

  [Rubric §13, Observability and Operability] assesses whether a failure tells the operator what to do. NoDatabaseConfiguredMessage is an internal const (ConnectionStringSettingsValidator.cs:38-43) rather than an inline string, and it lists BOTH shapes (ConnectionStrings:SQLServerConnectionString, ConnectionStrings:SqliteConnectionString, ConnectionStrings:CosmosConnectionString, or DataSources:Tickets:SqliteConnectionString) because which one is missing depends on whether the host is a single-database monolith or a database-per-module one. The final sentence states the design decision itself: a host with no database at all cannot serve a request, so it fails here rather than on its first query.

  [Rubric §8, Data Architecture] shows up in what the rule deliberately does NOT weaken. A host with no connection string anywhere still fails to start (ConnectionStringSettingsValidator.cs:20-24). Silently booting one would trade a clear startup failure for an InvalidOperationException on the first query, or worse, a service reporting healthy while unable to serve a single request.

• Walkthrough: one constant, the interface method, and two predicates.

  • The primary constructor takes DataSourcesSettings? dataSources = null (ConnectionStringSettingsValidator.cs:30). The default is what makes the validator constructible in a container that binds the settings without calling AddInfrastructure (ConnectionStringSettingsValidator.cs:26-29); such a container still gets the top-level check.
  • NoDatabaseConfiguredMessage (ConnectionStringSettingsValidator.cs:38-43): internal const, so tests assert against the same string the host emits.
  • Validate(string? name, ConnectionStringSettings options) (ConnectionStringSettingsValidator.cs:46-53): null-guards the options, then returns Success if either predicate holds and Fail(NoDatabaseConfiguredMessage) otherwise. Note the short-circuit ||: one database anywhere is enough.
  • HasTopLevelConnection (ConnectionStringSettingsValidator.cs:56-59): static, and uses IsNullOrWhiteSpace rather than IsNullOrEmpty across all three engine properties, which matters because ConnectionStringSettings initialises each of them to string.Empty rather than leaving them null (ConnectionStringSettings.cs:18, ConnectionStringSettings.cs:24, ConnectionStringSettings.cs:27).
  • HasNamedConnection (ConnectionStringSettingsValidator.cs:66-71): instance, because it reads the injected sources. It passes when ANY entry under DataSources names a database on any engine. The doc explains why one is enough: an entry carrying a connection string is a physical source the resolver registers, so the host has somewhere to read and write even with the top-level section empty (ConnectionStringSettingsValidator.cs:61-65).

• Why it's built this way: this is one of the two custom IValidateOptions<T> implementations the fail-fast configuration contract (ADR-070) records, the other being TenancySettingsValidator. Relaxing the SQL Server requirement into a cross-section reachability rule is what made the polyglot persistence story (ADR-018) usable by a host that never touches SQL Server, without giving up the boot-time guarantee for the hosts that do.

• Where it's used: registered by AddInfrastructure with TryAddEnumerable(ServiceDescriptor.Singleton<IValidateOptions<ConnectionStringSettings>, ConnectionStringSettingsValidator>()) (DependencyInjection.cs:88-89), immediately after the ValidateOnStart chain that binds the section (DependencyInjection.cs:78-81); TryAddEnumerable, like the tenancy validator, because two modules calling AddInfrastructure must not run the same validation twice. Covered by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Settings/ConnectionStringSettingsValidatorTests.cs, which drives the validator directly for each engine and for the named-source shapes, and end to end through the real ValidateOnStart chain including the SQLite-only host.

• Caveats: the type is internal, so a consumer cannot subclass or replace it; a host needing extra connection-string rules registers its own additional IValidateOptions<ConnectionStringSettings>.

IEntityDataSourceRegistry

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DataSources · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/IEntityDataSourceRegistry.cs:11 · Level 2 · interface

• What it is: the contract for the eagerly-built registry that maps every configured entity type to the physical database it lives in. Four members: GetDataSourceKey(Type) (IEntityDataSourceRegistry.cs:17), GetDataSourceKey(string entityFullName) (IEntityDataSourceRegistry.cs:23), TryGetDataSourceKey(string, out DataSourceKey) (IEntityDataSourceRegistry.cs:29), and GetPhysicalSourcesInUse() (IEntityDataSourceRegistry.cs:35).
• Depends on: DataSourceKey, the (Engine, Name) pair every member trades in.
• Concept introduced, eager entity-to-database mapping. [Rubric §8, Data Architecture] assesses whether database routing is a deliberate, discoverable design rather than an accident of query order; [Rubric §7, Microservices Readiness] assesses whether a module can be lifted into its own service without rewriting application code. The doc comment (IEntityDataSourceRegistry.cs:5-10) states why the interface exists at all: it replaces a legacy lazy cache that was populated as a side effect of EF model building, so routing decisions (unit of work, navigation classification, outbox enumeration) no longer depend on a model having been built first. GetPhysicalSourcesInUse() returns the distinct databases this host actually uses, which is how migrations, EnsureCreated, and the outbox processor know which databases to touch (IEntityDataSourceRegistry.cs:31-35). The two strict GetDataSourceKey overloads are documented to throw InvalidOperationException for an unregistered entity (IEntityDataSourceRegistry.cs:16, IEntityDataSourceRegistry.cs:22), while TryGetDataSourceKey is the non-throwing probe used where a miss is legitimate, for example when ApplicationDbContext decides whether an entity belongs in the model it is currently building (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/ApplicationDbContext.cs:713-715).
• Why it's built this way: database-per-service (ADR-006) needs every entity to resolve to exactly one physical source; deriving that map from configuration classes instead of from a built model turns a misconfiguration into a loud startup failure instead of a silent wrong-database query.
• Where it's used: implemented by EntityDataSourceRegistry and registered as a singleton in AddInfrastructure (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:97). Consumers include DbContextFactory (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Factory/DbContextFactory.cs:41), CrossDataSourceDegradeConvention (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Conventions/CrossDataSourceDegradeConvention.cs:35), DataSourceService (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/DataSourceService.cs:11), the OutboxProcessor (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Outbox/Processing/OutboxProcessor.cs:61), the OutboxCleanupService (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Outbox/Administration/OutboxCleanupService.cs:52), the AuditTrailCleanupJob (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/AuditTrail/AuditTrailCleanupJob.cs:50), both model-building passes of ApplicationDbContext (ApplicationDbContext.cs:317, ApplicationDbContext.cs:705), and the startup database-initialization path (MMCA.Common/Source/Presentation/MMCA.Common.API/Startup/DatabaseInitializationExtensions.cs:54).

PhysicalDataSource

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DataSources · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/PhysicalDataSource.cs:17 · Level 2 · record (sealed)

• What it is: the fully-resolved connection information for one physical database. Four positional members, Key (its engine plus name identity), ConnectionString, SqlServerMigrationsAssembly? and CosmosDatabaseName (PhysicalDataSource.cs:17-21), plus two members declared in the record body: the init-only SqliteMigrationsAssembly? (PhysicalDataSource.cs:34) and the computed UsesMigrations (PhysicalDataSource.cs:48-54).
• Depends on: DataSourceKey and, through it, DataSource.
• Concept, a logical name resolved into a real connection. [Rubric §8, Data Architecture] covers the step from a configured name like DataSources:Conference to an actual database. The record's doc comment (PhysicalDataSource.cs:5-9) explains that it is produced by IDataSourceResolver from the top-level ConnectionStrings section (the Default source) plus the named DataSources entries. Two members are engine-scoped: SqlServerMigrationsAssembly is null for non-SQL-Server engines and lets each SQL database own its own EF migration history (PhysicalDataSource.cs:12-15); CosmosDatabaseName is ignored for relational engines (PhysicalDataSource.cs:16). Being a positional record buys two things at once here: value equality, so two resolutions of the same source compare equal, and non-destructive mutation, which is exactly how per-tenant routing is implemented.
• Walkthrough
  • Key is the identity the rest of the stack routes on, and it is deliberately not recomputed when the connection changes. DbContextFactory.ResolveTenantOverride clones the shared source with shared with { ConnectionString = ..., CosmosDatabaseName = ... } and keeps the original key, because the key is what EF's model cache is keyed on, so swapping only the connection string is what lets one compiled model serve every tenant's database (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Factory/DbContextFactory.cs:144-169, ADR-073).
  • ConnectionString may legitimately be empty. Both the startup initializer and EnsureCreatedAsync treat an empty connection string as "this source is not configured in this host" and skip it rather than failing (DatabaseInitializationExtensions.cs:75, DbContextFactory.cs:203-204).
  • SqliteMigrationsAssembly (PhysicalDataSource.cs:34) sits in the record body rather than in the positional parameter list on purpose, and the comment says why (PhysicalDataSource.cs:26-32): the constructor and deconstruction shape of this shipped record stay exactly as they were, so a consumer that builds or deconstructs it positionally is unaffected, and the resolver sets the property through an object initializer instead (DataSourceResolver.cs:397-399). Only one of the two migrations-assembly properties is ever populated, since a physical source belongs to exactly one engine.
  • UsesMigrations (PhysicalDataSource.cs:48-54) is the switch that decides Migrate versus EnsureCreated for this one database. SQL Server always migrates, including the single-database monolith whose Default source names no migrations assembly at all and lets EF look next to the context (PhysicalDataSource.cs:50). SQLite migrates only once a SqliteMigrationsAssembly is configured for it (PhysicalDataSource.cs:51), because a SQLite source wired by hand before that setting existed has no migrations to apply and must keep being created outright. Cosmos never does: the provider has no migrations pipeline (PhysicalDataSource.cs:52). All four branches are pinned by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/DataSources/PhysicalDataSourceTests.cs:21, PhysicalDataSourceTests.cs:33, PhysicalDataSourceTests.cs:52, and PhysicalDataSourceTests.cs:81, including the case where a SQLite source carries only the SQL Server assembly and therefore still does not migrate (PhysicalDataSourceTests.cs:69).
• Where it's used: produced by DataSourceResolver through BuildPhysicalSource (DataSourceResolver.cs:386-399) for both the Default source (DataSourceResolver.cs:308-313) and named ones (DataSourceResolver.cs:353-358), and handed back by GetPhysical (DataSourceResolver.cs:138-143); consumed by PhysicalDbContextFactory, whose Create(DataSourceKey) resolves it and whose Create(DataSourceKey, PhysicalDataSource) overload accepts an already-resolved one, which is the entry point the tenant clone uses (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Factory/PhysicalDbContextFactory.cs:34-37). DesignTimeDbContextHelper resolves one for dotnet ef commands and hands the same record to the design-time context (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Design/DesignTimeDbContextHelper.cs:117), and the startup initializer branches on both ConnectionString and UsesMigrations (DatabaseInitializationExtensions.cs:75, DatabaseInitializationExtensions.cs:80, DatabaseInitializationExtensions.cs:150).

Snapshot

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DataSources · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/EntityDataSourceRegistry.cs:25 · Level 2 · record (sealed, private nested)

• What it is: the immutable point-in-time view of EntityDataSourceRegistry's state, with three members: FrozenDictionary<string, (DataSourceKey Key, Type ConfigurationType)> Entities, FrozenSet<Assembly> ScannedAssemblies, and the precomputed IReadOnlyCollection<DataSourceKey> PhysicalSources (EntityDataSourceRegistry.cs:25-28).
• Depends on: DataSourceKey; System.Collections.Frozen and System.Reflection.Assembly (BCL).
• Concept introduced, the lock-free volatile-snapshot pattern. [Rubric §12, Performance & Scalability] assesses whether hot-path reads avoid contention. The registry holds private volatile Snapshot? _snapshot (EntityDataSourceRegistry.cs:31) and reads it without a lock, relying on volatile for the store/load barrier so every thread sees a fully-published reference. Writes (the initial build and any rescan) take Lock _rebuildLock (EntityDataSourceRegistry.cs:30) for mutual exclusion and then swap in a brand-new Snapshot. Because FrozenDictionary and FrozenSet cannot change once built, any number of readers share one snapshot with zero synchronization, and a rescan never mutates the instance a reader is holding.
• Walkthrough
  • Entities maps an entity's full CLR type name to a tuple of the resolved DataSourceKey and the configuration type that produced it (EntityDataSourceRegistry.cs:26). The configuration type plays no part in routing; it exists so the duplicate-registration failure can name both conflicting configuration classes in its message (EntityDataSourceRegistry.cs:145-148).
  • ScannedAssemblies records which assemblies the snapshot covered, so the registry can tell a genuine lookup miss from a merely stale scan (EntityDataSourceRegistry.cs:104).
  • PhysicalSources is the distinct-key list computed once at build time (EntityDataSourceRegistry.cs:160). The remark on GetPhysicalSourcesInUse explains why it is materialized rather than projected per call (EntityDataSourceRegistry.cs:74-80): the outbox processor and the outbox cleanup service both ask for it on every poll cycle, and re-running Select().Distinct() over every registered entity allocated a fresh list each time, forever, on a loop that usually finds nothing to do.
• Where it's used: exclusively inside EntityDataSourceRegistry: built by BuildSnapshot (EntityDataSourceRegistry.cs:157-160), published by GetOrBuildSnapshot (EntityDataSourceRegistry.cs:94) and replaced by RescanIfAssembliesChanged (EntityDataSourceRegistry.cs:109-111).
• Caveats / not-in-source: a private nested type. It appears in this inventory because private nested types are inventoried, but it is not part of the public API and nothing outside the registry can name it.

TenantDataSourceTarget

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DataSources · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/TenantDataSourceTargets.cs:13 · Level 2 · record struct (readonly)

• What it is: one unit of work for a background sweep, a (DataSourceKey Source, string? TenantId) pair. TenantId is null for the shared database and set when the target is a tenant that keeps its own copy of that source (TenantDataSourceTargets.cs:6-13).
• Depends on: DataSourceKey.
• Concept introduced, the sweep unit under database-per-tenant. [Rubric §8, Data Architecture] assesses whether the storage topology is modelled explicitly rather than assumed, and [Rubric §29, Resilience & Business Continuity] assesses whether background work reaches every store it is responsible for. Once multi-tenancy (ADR-073) is in play, "the databases this host owns" is no longer the same set as "the units a background job must visit": a physical source can exist once as the shared database and again as one private database per tenant that overrides it. Making that pair a value type means the sweep loops over a flat list instead of nesting a tenant loop inside a source loop, and readonly record struct gives structural equality for free, which is what the tests assert against (MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/Tenancy/TenantDataSourceTargetTests.cs:30-32).
• Walkthrough
  • The positional declaration TenantDataSourceTarget(DataSourceKey Source, string? TenantId) (TenantDataSourceTargets.cs:13); the null-versus-set convention on TenantId is the whole vocabulary of the type (TenantDataSourceTargets.cs:11-12).
  • ToString() (TenantDataSourceTargets.cs:17-20) renders the bare source name for a shared target and appends " (tenant {TenantId})" for a per-tenant one, so a log line says which of two visits to the same source it is describing. That rendering is pinned by a test (TenantDataSourceTargetTests.cs:93-94), which is a small [Rubric §13, Observability & Operability] point: without it, two consecutive log lines for the same source would be indistinguishable.
• Why it's built this way: consumers branch on TenantId to decide whether they need a fresh DI scope. A null target runs on the caller's own scope; a non-null one creates a scope, calls ITenantContext.SetTenant(...) before asking for the context, because the tenant is what routes the scoped factory to that tenant's connection string (OutboxCleanupService.cs:107, AuditTrailCleanupJob.cs:106).
• Where it's used: produced only by TenantDataSourceTargets.Expand and consumed as the loop variable of every host-owned sweep: OutboxProcessor (OutboxProcessor.cs:202, iterated at OutboxProcessor.cs:216), OutboxCleanupService (OutboxCleanupService.cs:220), AuditTrailCleanupJob (AuditTrailCleanupJob.cs:83, and as a parameter at AuditTrailCleanupJob.cs:95 and AuditTrailCleanupJob.cs:117), and the startup initializer (DatabaseInitializationExtensions.cs:138-139).

IDataSourceResolver

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DataSources · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/IDataSourceResolver.cs:15 · Level 3 · interface

• What it is: the contract that maps a logical data source name (from a [UseDatabase] attribute, a module namespace, or a setting such as Outbox:DatabaseName) to a physical DataSourceKey, and hands back the resolved PhysicalDataSource for such a key. Two members: ResolveLogical(DataSource engine, string logicalName) (IDataSourceResolver.cs:34) and GetPhysical(DataSourceKey key) (IDataSourceResolver.cs:42).
• Depends on: DataSource, DataSourceKey, PhysicalDataSource.
• Concept introduced, logical-to-physical collapse as the backward-compatibility guarantee. [Rubric §8, Data Architecture] and [Rubric §7, Microservices Readiness] both apply, because routing is reconfigurable purely through settings. The interface comment (IDataSourceResolver.cs:5-14) states the collapse rule precisely: in a host with no DataSources configuration every logical name resolves to Default, yielding one DbContext per engine with an identical change tracker, FK constraints, transactions, and EF model to a plain single-database monolith. ResolveLogical's contract (IDataSourceResolver.cs:17-30) spells out the collapse cases: a name with no DataSources entry, a name with no connection string for the engine, and a name whose connection equals the top-level one all fall to DataSourceKey.Default(engine); entries sharing a connection with each other collapse to one physical source named after the alphabetically-first logical name.
• Concept introduced, engine substitution. The second paragraph of the same contract (IDataSourceResolver.cs:24-29) adds a rule that is easy to miss and load-bearing for single-engine hosts: a request naming an engine the host configures no connection string for anywhere, neither top-level nor on a named entry, is served from an engine it does configure, preferring SQL Server, then SQLite, then Cosmos DB. That is what lets a SQLite-only host serve the framework's own tables, whose engine settings all default to SQL Server. A host that configures the requested engine, including a polyglot host configuring several (ADR-018), is never redirected. GetPhysical (IDataSourceResolver.cs:36-42) is the reverse lookup and is documented to throw when handed a key that did not come from ResolveLogical.
• Why it's built this way: the collapse is what makes "build the monolith now, extract a service later" a configuration change rather than a rewrite (ADR-006). One interface owns the rule, so no caller reimplements the defaulting logic and no caller can disagree about what Default means.
• Where it's used: implemented by DataSourceResolver and registered as a singleton (DependencyInjection.cs:110); injected into EntityDataSourceRegistry (EntityDataSourceRegistry.cs:23) to resolve each entity's derived logical name, into PhysicalDbContextFactory and DbContextFactory to open connections (PhysicalDbContextFactory.cs:18, DbContextFactory.cs:42), into the inbox store and both event buses so each can locate its own database (EfInboxStore MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Inbox/EfInboxStore.cs:40, InProcessEventBus MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Messaging/InProcessEventBus.cs:36, BrokerEventBus MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Messaging/BrokerEventBus.cs:34), into AuditTrailReader (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/AuditTrail/AuditTrailReader.cs:36) and ScheduledJobRunner (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Scheduling/ScheduledJobRunner.cs:42), and optionally into TenancySettingsValidator, which uses ResolveLogical to check that a tenant override is keyed by a name that actually round-trips as a physical source (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Tenancy/TenancySettingsValidator.cs:23, TenancySettingsValidator.cs:119).

DataSourceService

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DataSources · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/DataSourceService.cs:11 · Level 3 · class (public sealed)

• What it is: the Application-facing facade over IEntityDataSourceRegistry. It answers two questions: which physical data source (engine plus database) does this entity live in, and can these two entities be joined with an EF Include (DataSourceService.cs:5-11).
• Depends on: IEntityDataSourceRegistry as its single primary-constructor parameter (DataSourceService.cs:11), IDataSourceService as the contract it implements, and the DataSourceKey and DataSource types it returns.
• Concept introduced, routing as a first-class query. [Rubric §7, Microservices Readiness] assesses whether "where does this entity actually live" is answerable at runtime rather than being baked into code, and [Rubric §3, Clean Architecture] assesses whether the Application layer can ask that question without referencing EF. Database-per-service (ADR-006) means two entities written in the same module's code may or may not share a physical database depending on how the deployment is configured. Every consumer that needs to make a decision about that (which DbContext to open, whether a navigation can be eager-loaded or must go through a populator) asks this service. The class doc records an important property of the current design (DataSourceService.cs:8-10): the registry is built eagerly from configuration assemblies, so resolution no longer depends on an EF model having been built first, which is what makes it safe to consult from the Application layer at any point in startup.
• Walkthrough
  • The four resolution members (DataSourceService.cs:14-23) are pure forwarders to the registry, in two pairs: GetDataSourceKey by Type and by full type name, and GetDataSource by the same two, each projecting .Engine off the resolved key. The name-based overloads exist because a caller holding only a metadata string (an EF entity type name, a message payload's type name) should not have to resolve a Type first.
  • HaveIncludeSupport(first, second) (DataSourceService.cs:30-31) is the whole classification rule in one expression: the two keys must be equal and the engine must not be DataSource.CosmosDB. The remarks at :27-30 state both halves: EF Include requires both entities in the same physical database on a relational engine, and Cosmos has no cross-document include.
  • HaveIncludeSupport(firstEntityFullName, secondEntityFullName) (DataSourceService.cs:34-37) is the name-based overload, and it uses TryGetDataSourceKey rather than the throwing form: an entity the registry does not know about yields false, which degrades to "use the populator path" rather than to an exception during navigation classification.
• Why it's built this way: putting the include decision here rather than inside a repository is what lets NavigationMetadataProvider classify each navigation once and route it to either an EF Include or an INavigationPopulator (ADR-002) without knowing anything about deployment topology. The engine carve-out keeps the same code correct on a non-relational store (ADR-018). It is registered as a singleton (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:66), which is safe because both the service and the registry behind it are immutable after construction.
• Where it's used: UnitOfWork resolves an entity's key before choosing a context (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/UnitOfWork.cs:13, doc at :29); NavigationMetadataProvider uses it for navigation classification (MMCA.Common/Source/Core/MMCA.Common.Application/Services/Query/NavigationMetadataProvider.cs:20); in MMCA.Store, InventoryAllocationService (MMCA.Store/Source/Modules/Sales/MMCA.Store.Sales.Infrastructure/Services/InventoryAllocationService.cs:35) and ProductImageStorageService (MMCA.Store/Source/Modules/Catalog/MMCA.Store.Catalog.Infrastructure/Services/ProductImageStorageService.cs:28) both resolve a key before opening the right context. Covered by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Services/DataSourceServiceTests.cs and .../DataSourceServiceAdditionalTests.cs.

DataSourceResolver

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DataSources · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/DataSourceResolver.cs:15 · Level 4 · class (sealed, partial)

• What it is: the singleton implementation of IDataSourceResolver. It builds the logical-to-physical map once at construction from the connection-string settings and the named DataSources entries, validates migrations-assembly conflicts, works out which engine to substitute for engines the host does not configure, and then serves both lookups from in-memory dictionaries.
• Depends on: DataSource, DataSourceKey, PhysicalDataSource, IDataSourceResolver, its own nested DefaultSeed, ConnectionStringSettings (taken as IOptions<T>), DataSourcesSettings and DataSourceEntrySettings; ILogger<T> and the [LoggerMessage] source generator, which is why the class is partial.
• Concept introduced, eager and validated data-source resolution. [Rubric §8, Data Architecture] (deliberate multi-database routing) and [Rubric §7, Microservices Readiness] (ADR-006, database-per-service). The resolver realizes the collapse rule described on IDataSourceResolver. Two guardrails are worth calling out. First, conflicting migrations-assembly declarations on logical names that collapse to the same physical database throw at construction (DataSourceResolver.cs:429-435), a loud fail-fast rather than a silent pick. Second, [Rubric §13, Observability & Operability] shows up in the two source-generated log methods: LogMigrationsAssemblyFallback (DataSourceResolver.cs:470-471) warns when a named SQL Server source has no dedicated migrations assembly and therefore falls back to another database's, whose snapshot describes a different schema, and LogSubstituteEngine (DataSourceResolver.cs:467-468) states at startup that requests for an unconfigured engine are being served from another one.
• Walkthrough
  • State (DataSourceResolver.cs:17-41): AllEngines is the build order, CosmosDB, Sqlite, SQLServer (DataSourceResolver.cs:17); EnginePreference is the substitution order, SQL Server, SQLite, Cosmos DB, relational first because every table the framework owns is relational (DataSourceResolver.cs:19-25). The lookups are _logicalToPhysical, keyed by (engine, logical name) (DataSourceResolver.cs:28), and _physicalSources, keyed by DataSourceKey (DataSourceResolver.cs:31). _configuredEngines (DataSourceResolver.cs:34) and _substituteEngine (DataSourceResolver.cs:41) carry the substitution decision.
  • Constructor (DataSourceResolver.cs:53-85): null-guards its two settings arguments (DataSourceResolver.cs:58-59), then loops all three engines calling BuildEngineMap and recording which engines carry a connection string anywhere (DataSourceResolver.cs:63-71). It picks the substitute as the first configured engine in preference order, or null when the host configures no database at all (DataSourceResolver.cs:73-76), and logs once when the substitute is not SQL Server (DataSourceResolver.cs:78-84). Every field is written only here, which is what makes the singleton safe to share without locking.
  • ResolveLogical (DataSourceResolver.cs:88-102): substitutes the engine first (DataSourceResolver.cs:92), then short-circuits the Default name case-insensitively (DataSourceResolver.cs:94-97), then does a dictionary lookup whose miss returns DataSourceKey.Default(effectiveEngine) (DataSourceResolver.cs:99-101), which is the monolith default.
  • SubstituteUnconfiguredEngine (DataSourceResolver.cs:123-124) is one line, and its doc comment (DataSourceResolver.cs:104-120) carries the failure it removes: every engine choice the framework makes for its own tables comes from a setting defaulting to SQL Server (Outbox:DataSource, Scheduler:DataSource, AuditTrail:DataSource), and honoring that literally in a SQLite-only host handed those components a source with an empty connection string, so their first query failed with "The ConnectionString property has not been initialized". HasAnyConnectionString (DataSourceResolver.cs:130-135) is what decides "configured", and it deliberately looks at named entries as well as the top-level section.
  • GetPhysical (DataSourceResolver.cs:138-143): a _physicalSources lookup that throws with an actionable message when the key was not produced by ResolveLogical.
  • BuildEngineMap (DataSourceResolver.cs:150-164): computes the DefaultSeed (DataSourceResolver.cs:156), splits the engine's named entries with ClassifyEntries (DataSourceResolver.cs:157), then registers the Default source and one named source per group (DataSourceResolver.cs:158-163).
  • ClassifyEntries (DataSourceResolver.cs:242-283): computes a per-connection identity string via GetIdentity (DataSourceResolver.cs:446-449), where a Cosmos identity appends the database name because one account hosts many databases, relational engines use the connection string alone, and the comparison is ordinal, so semantically-equal-but-textually-different connection strings deliberately do not collapse. Entries with no connection string for the engine are skipped entirely (DataSourceResolver.cs:255-260), because ResolveLogical already defaults on a map miss; entries matching the seed's identity go to the collapsed list (DataSourceResolver.cs:267-271) and the rest are grouped by identity (DataSourceResolver.cs:273-280).
  • RegisterDefaultSource (DataSourceResolver.cs:289-319): registers the Default key for the engine, letting entries that collapsed onto it contribute an explicit migrations assembly alongside the seed's own (DataSourceResolver.cs:296-306), and maps each collapsed logical name onto that key (DataSourceResolver.cs:315-318).
  • RegisterNamedSource (DataSourceResolver.cs:325-364): names the physical key after the alphabetically-first member (Order(...).First(), DataSourceResolver.cs:331) so routing is deterministic regardless of configuration key order, then warns and falls back when a SQL Server source declares no migrations assembly of its own (DataSourceResolver.cs:338-346). The group's Cosmos database name comes from the canonical entry, falling back to the seed (DataSourceResolver.cs:348-351).
  • BuildPhysicalSource (DataSourceResolver.cs:386-399): places the resolved migrations assembly in the slot of the engine it belongs to, SqlServerMigrationsAssembly positionally for SQL Server and SqliteMigrationsAssembly through the object initializer for SQLite, which is what stops a SQL Server assembly from being handed to UseSqlite (DataSourceResolver.cs:381-385).
  • ResolveMigrationsAssembly (DataSourceResolver.cs:417-438): returns null for Cosmos and when no explicit value exists (DataSourceResolver.cs:422-425), and throws when logical names sharing a database declare conflicting assemblies, naming the offending setting per engine and every declaration in the message (DataSourceResolver.cs:427-435). GetMigrationsAssembly (DataSourceResolver.cs:405-411) is the per-engine reader that feeds it: SQLite and SQL Server have their own entry settings, Cosmos migrates nothing.
• Why it's built this way: resolving eagerly at construction turns a misconfiguration into a startup failure rather than a mid-request surprise, and the deterministic canonical-name rule keeps routing stable across configuration orderings (ADR-006). The ordinal identity comparison is the conservative choice: collapsing two connection strings that only look different would silently merge two databases. Engine substitution is scoped the same conservative way, since it can only fire for a request that could not have been served at all (DataSourceResolver.cs:116-119).
• Where it's used: registered as the singleton IDataSourceResolver (DependencyInjection.cs:110); consumed by EntityDataSourceRegistry, the context factories, and DesignTimeDbContextHelper, which constructs its own instance for dotnet ef commands and registers it in a hand-built container (DesignTimeDbContextHelper.cs:108-111, DesignTimeDbContextHelper.cs:157). Its rules are pinned by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/DataSources/DataSourceResolverTests.cs:12, including the alphabetically-first canonical name (DataSourceResolverTests.cs:84), the two Cosmos cases where the same account with a different database stays distinct while the same database collapses (DataSourceResolverTests.cs:99, DataSourceResolverTests.cs:118), the SQLite-only host being served the framework's SQL Server default from SQLite (DataSourceResolverTests.cs:336), the polyglot host routing each engine to itself (DataSourceResolverTests.cs:425), the SQL-Server-only host being unchanged (DataSourceResolverTests.cs:414), and the host with no database at all passing the engine straight through (DataSourceResolverTests.cs:480).

EntityDataSourceRegistry

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DataSources · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/EntityDataSourceRegistry.cs:21 · Level 5 · class (sealed)

• What it is: the singleton implementation of IEntityDataSourceRegistry. It reflects over the configuration assemblies, finds every entity type configuration, derives each entity's physical database from the configuration class's attributes and the entity's namespace, and freezes the result into a lock-free lookup that it rescans lazily when new assemblies appear.
• Depends on: DataSourceKey, IEntityDataSourceRegistry, IDataSourceResolver, IEntityTypeConfigurationBase<TEntity, TIdentifierType>, NamespaceConventions, UseDataSourceAttribute, UseDatabaseAttribute, IEntityConfigurationAssemblyProvider, and its own nested Snapshot; System.Reflection, System.Collections.Frozen, and System.Threading.Lock (BCL).
• Concept introduced, deriving routing from configuration classes rather than from the EF model. [Rubric §8, Data Architecture] (ADR-006: an entity lives in exactly one database) and [Rubric §15, Best Practices & Code Quality] (fail fast on an ambiguous configuration). The doc comment (EntityDataSourceRegistry.cs:8-19) states the design: the map is derived from configuration classes, so it exists before any model is built; it is built lazily on first access and rescanned once on a lookup miss to pick up module assemblies loaded later; and duplicate registrations of one entity are tolerated when they agree on the physical source and rejected when they conflict.
• Walkthrough
  • Primary constructor (EntityDataSourceRegistry.cs:21-23) takes the IEntityConfigurationAssemblyProvider that decides which assemblies are scanned and the IDataSourceResolver that performs the final collapse. _rebuildLock (EntityDataSourceRegistry.cs:30) and the volatile _snapshot (EntityDataSourceRegistry.cs:31) implement the pattern taught under Snapshot.
  • GetDataSourceKey(Type) (EntityDataSourceRegistry.cs:34-38) null-guards and forwards to the string overload via FullName; GetDataSourceKey(string) (EntityDataSourceRegistry.cs:41-47) is TryGetDataSourceKey plus a throw whose message names the exact remedy, adding an EntityTypeConfigurationSQLServer/Cosmos/Sqlite for the entity in a discovered configuration assembly.
  • TryGetDataSourceKey (EntityDataSourceRegistry.cs:50-72): probes the current snapshot; on a miss it calls RescanIfAssembliesChanged once (EntityDataSourceRegistry.cs:63) and retries, then returns default and false. The two-step shape keeps the common hit path entirely off the lock.
  • GetPhysicalSourcesInUse (EntityDataSourceRegistry.cs:81-82): returns the snapshot's precomputed PhysicalSources, which is how migrations, EnsureCreated, and outbox draining enumerate this host's databases without allocating per call.
  • GetOrBuildSnapshot (EntityDataSourceRegistry.cs:84-96) reads the volatile field first and only takes the lock when it is null; RescanIfAssembliesChanged (EntityDataSourceRegistry.cs:98-113) rebuilds only when the provider reports assemblies not already in ScannedAssemblies (EntityDataSourceRegistry.cs:103-107), so a genuinely unknown entity costs one set comparison, not one rescan per lookup.
  • BuildSnapshot (EntityDataSourceRegistry.cs:115-161): for every loadable type in every configuration assembly it skips abstract and open-generic types (EntityDataSourceRegistry.cs:122-125), finds the closed IEntityTypeConfigurationBase<,> interface (EntityDataSourceRegistry.cs:127-132), takes the entity type from the first generic argument (EntityDataSourceRegistry.cs:134), and calls DeriveDataSourceKey. A second configuration registering the same entity against a different key throws with a message naming both configuration classes and both keys (EntityDataSourceRegistry.cs:141-152); an agreeing duplicate is simply ignored. The frozen dictionary, the scanned-assembly set, and the distinct physical-source list are built together at the end (EntityDataSourceRegistry.cs:157-160).
  • DeriveDataSourceKey (EntityDataSourceRegistry.cs:172-185): reads the engine from UseDataSourceAttribute and returns null when it is absent (EntityDataSourceRegistry.cs:174-178), deliberately skipping configurations that implement a provider interface directly instead of deriving from the attributed base classes. It then resolves the logical name in priority order, UseDatabaseAttribute first, then NamespaceConventions.GetModuleName, then DataSourceKey.DefaultName (EntityDataSourceRegistry.cs:180-182), and delegates the collapse to IDataSourceResolver.ResolveLogical (EntityDataSourceRegistry.cs:184).
  • GetLoadableTypes (EntityDataSourceRegistry.cs:190-200): wraps assembly.GetTypes() and tolerates ReflectionTypeLoadException by keeping the types that did load, mirroring module discovery, so a partially-loaded assembly does not abort the whole scan.
• Why it's built this way: building from configuration classes at startup rather than per query means a missing or conflicting configuration surfaces early, which matters most in a multi-database system where the alternative failure mode is a silent read against the wrong database. The skip for configurations without [UseDataSource] is documented as matching legacy behavior (EntityDataSourceRegistry.cs:168-170): those entities land in the Default model but are not routable through the unit of work, which is the same fallback ApplicationDbContext applies when filtering configurations into a model (ApplicationDbContext.cs:700-715).
• Where it's used: registered as the singleton IEntityDataSourceRegistry (DependencyInjection.cs:97) and rebuilt by hand for design-time commands (DesignTimeDbContextHelper.cs:112, DesignTimeDbContextHelper.cs:158); consumed by CrossDataSourceDegradeConvention, DataSourceService, DbContextFactory, both ApplicationDbContext model passes (ApplicationDbContext.cs:317, ApplicationDbContext.cs:705), and the outbox, audit-trail and migrations enumerations. Its behavior is pinned by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/DataSources/EntityDataSourceRegistryTests.cs:15, covering the agreeing and conflicting duplicate cases (EntityDataSourceRegistryTests.cs:94, EntityDataSourceRegistryTests.cs:104), the attribute-less skip (EntityDataSourceRegistryTests.cs:121), the unknown-entity throw and probe (EntityDataSourceRegistryTests.cs:130, EntityDataSourceRegistryTests.cs:140), and the distinct source enumeration (EntityDataSourceRegistryTests.cs:149).

TenantDataSourceTargets

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DataSources · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/TenantDataSourceTargets.cs:40 · Level 5 · class (static)

• What it is: a one-method static class that expands the physical data sources a background service owns into the TenantDataSourceTarget units it must actually visit once database-per-tenant is configured (TenantDataSourceTargets.cs:23-49).
• Depends on: DataSourceKey, TenantDataSourceTarget, TenancySettings with its nested TenantEntrySettings and TenantDataSourceOverrideSettings, and TenancySettingsValidator.ConnectionStringFor for the per-engine connection-string lookup (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Tenancy/TenancySettingsValidator.cs:122).
• Concept introduced, why a per-tenant database is invisible to a shared sweep. [Rubric §8, Data Architecture] and [Rubric §29, Resilience & Business Continuity] both apply, and the class remarks (TenantDataSourceTargets.cs:27-39) carry the reasoning. A shared-schema tenant needs nothing here: its rows live in the shared database that the null-tenant target already drains, and the outbox deliberately has no tenant column precisely so that adopting tenancy never forces a migration on an existing consumer. A tenant with its own database is the opposite case: its outbox rows and its audit-trail rows sit in a database nothing else opens, so without an extra target its events would sit undelivered and its rows unpurged forever. Each such tenant therefore contributes one extra target per source it overrides, and the sweep sets the tenant on its scope before asking for the context, which is what routes that context at the tenant's connection string (ADR-073).
• Walkthrough
  • Expand(IEnumerable<DataSourceKey> sources, TenancySettings? settings) (TenantDataSourceTargets.cs:49-51) takes a nullable settings argument, because a host that never registered tenancy passes null and must still get a usable list.
  • It materializes the source sequence only when it is not already a collection (sources as IReadOnlyCollection<DataSourceKey> ?? [.. sources], TenantDataSourceTargets.cs:53) and sizes the result list from that count (TenantDataSourceTargets.cs:54), since the common no-tenancy case produces exactly one target per source.
  • Pass one adds the shared target for every source, new TenantDataSourceTarget(source, null) (TenantDataSourceTargets.cs:56-59). This is the entire result when settings are null or declare no tenants (TenantDataSourceTargets.cs:61-64), which is the ordering guarantee the callers rely on: shared targets always come first.
  • Pass two walks the declared tenants and, for each, every source the caller owns (TenantDataSourceTargets.cs:66-76). A pair is added only when the tenant declares an override keyed by that physical source name and that override carries a non-blank connection string for that source's engine (TenantDataSourceTargets.cs:70-71). Both halves of that test matter: an override for a source this host does not own adds nothing, and an override that only declares, say, a SQLite connection adds nothing for a SQL Server source. Both cases have their own test (TenantDataSourceTargetTests.cs:64, TenantDataSourceTargetTests.cs:78).
• Why it's built this way: it is a pure function over settings, with no DI and no I/O, so every sweep can share one expansion rule and each can unit-test its own target list without a database (TenantDataSourceTargetTests.cs:20). Keeping the tenant loop outside the sweeps also keeps the tenancy feature additive: a host with no Tenancy section gets byte-identical behavior to the pre-tenancy code path (TenantDataSourceTargetTests.cs:26, TenantDataSourceTargetTests.cs:36).
• Where it's used: by all four host-owned sweeps: OutboxProcessor (OutboxProcessor.cs:202), OutboxCleanupService (OutboxCleanupService.cs:220), AuditTrailCleanupJob (AuditTrailCleanupJob.cs:83), and DatabaseInitializationExtensions, which filters the expansion down to t.TenantId is not null because the shared sources were already initialized in the pass above it (DatabaseInitializationExtensions.cs:138-139). Two of the sweeps are pinned against the same expansion in tests (TenantDataSourceTargetTests.cs:100, TenantDataSourceTargetTests.cs:118).
• Caveats / not-in-source: the expansion is driven purely by declared configuration. A tenant whose database exists but is not declared under Tenancy:Tenants produces no target, and nothing in this class detects that; the round-trip check that a source name is a real physical name lives in TenancySettingsValidator, not here.

DetectChangesScope

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DbContexts · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/ApplicationDbContext.cs:243 · Level 0 · struct (private readonly, nested)

• What it is: a two-field disposable struct nested inside ApplicationDbContext whose only job is to put EF's ChangeTracker.AutoDetectChangesEnabled flag back the way it found it when a save finishes.
• Depends on: Microsoft.EntityFrameworkCore.ChangeTracking.ChangeTracker and System.IDisposable (both external/BCL); nothing first-party beyond its enclosing context class.
• Concept introduced, the scoped-setting guard (restore-on-dispose). [Rubric §12, Performance & Scalability] (assesses whether hot paths avoid repeated O(n) work) and [Rubric §15, Best Practices & Code Quality] (assesses whether temporary global-state mutation is bounded rather than leaked). EF's ChangeTracker.Entries<T>() runs a full DetectChanges pass on every call and memoizes nothing. Interceptors scan the tracker during SavingChanges and EF then detects once more on its own before building the save, so a single save paid three O(tracked entities x properties) snapshot comparisons where one suffices (ApplicationDbContext.cs:216-223). Turning detection off for the duration of the save is the optimization; a using-scoped struct is what makes turning it back on unforgettable, including on the exception path.
• Walkthrough: the primary constructor DetectChangesScope(ChangeTracker changeTracker, bool previousSetting) (ApplicationDbContext.cs:243) captures the tracker and the flag value that was in force before suppression. Dispose() (ApplicationDbContext.cs:245) is a single expression-bodied assignment that writes previousSetting back onto changeTracker.AutoDetectChangesEnabled. It is created only by DetectChangesOnce() (ApplicationDbContext.cs:233-241), which reads the current setting (:235), calls ChangeTracker.DetectChanges() once when detection was on (:236-237), sets the flag to false (:239), and hands back the scope (:240).
• Why it's built this way: readonly struct means no heap allocation on a path that runs on every save, and private keeps the mechanism invisible to callers. Restoring the previous value rather than hardcoding true is the load-bearing detail: a caller that had deliberately disabled auto-detect keeps its choice and never gets an unexpected detection pass on the way out (ApplicationDbContext.cs:228-230). Suppressing the remaining passes is safe because everything the interceptors do afterwards bypasses detection anyway: the audit interceptor writes through entry.Property(...).CurrentValue (AuditSaveChangesInterceptor.cs:57-60) and the domain-event interceptor adds outbox rows through Add, both of which take effect on the entry immediately.
• Where it's used: both save overrides that EF funnels through, SaveChangesAsync(bool, CancellationToken) (ApplicationDbContext.cs:173-179) and SaveChanges(bool) (ApplicationDbContext.cs:206-210), open one with using var detection = DetectChangesOnce(). The behavior is pinned by SaveChangeDetectionTests (MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/Interceptors/SaveChangeDetectionTests.cs:31, :47, :64, :78, :90), which asserts detection runs exactly once, that an untracked property edit still persists, that audit stamps still land, that a caller's explicit false survives the save, and that a default context is left with detection enabled for the next caller.
• Caveats / not-in-source: the remarks name two tracker-scanning interceptors (AuditSaveChangesInterceptor at AuditSaveChangesInterceptor.cs:52 and DomainEventSaveChangesInterceptor at DomainEventSaveChangesInterceptor.cs:221), which are the two that are always registered. Two optional interceptors enumerate the tracker as well when a host opts into them (TenantSaveChangesInterceptor at TenantSaveChangesInterceptor.cs:74 and AuditTrailSaveChangesInterceptor at AuditTrailSaveChangesInterceptor.cs:197), so the suppression saves strictly more than the comment claims; the comment is narrower than the code, not wrong about the mechanism.

IdentityInsertGroup

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DbContexts.Factory · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Factory/DbContextFactory.cs:406 · Level 0 · record (private sealed, nested)

• What it is: a three-member private record nested in DbContextFactory, (string Schema, string Table, List<EntityEntry> Entries) (DbContextFactory.cs:406). It names one batch of pending inserts that all target the same table and all carry explicit identity values, which is exactly the unit SQL Server's SET IDENTITY_INSERT operates on.
• Depends on: EF Core's EntityEntry, and nothing else.
• Concept introduced, importing rows that already have ids. [Rubric §8, Data Architecture] (assesses whether persistence mechanics are deliberate): normally a database-generated identity column means the application never supplies the id. An import from an external system (ADC's Sessionize refresh) must preserve the source's ids, and SQL Server only allows that with SET IDENTITY_INSERT <table> ON, one table at a time per session (DbContextFactory.cs:279-284). Grouping the affected entries by table is what turns that constraint into a loop.
• Walkthrough:
  • GetIdentityInsertGroups (DbContextFactory.cs:363-404) builds the list: it walks the change tracker for Added entries (:366-369), skips anything without a single-property primary key (:372-374), keeps only properties whose SQL Server value-generation strategy is IdentityColumn (:376-381), and then skips entries whose id is still an EF temporary value (:386-387), since a temporary value means the application did not set one. Survivors are bucketed by (schema, table) with "dbo" as the schema fallback (:389-402).
  • SaveWithIdentityInsertAsync (DbContextFactory.cs:285-357) consumes the groups: with none it falls back to a plain save (:290-291); otherwise, per group, it flips every Added entry belonging to the other groups to Unchanged so this round's batch touches one table only (:300-306), runs SET IDENTITY_INSERT [schema].[table] ON, saves, and turns it OFF in a finally (:324-337), then restores the hidden entries' states in an outer finally (:340-346). Any remaining changes get a final ordinary save (:350-353).
  • Capture exclusion (DbContextFactory.cs:315-317, :342): before each round it calls DomainEventSaveChangesInterceptor.BeginCaptureExclusion with exactly the hidden entities and ends the exclusion afterwards. The comment (:308-313) explains the bug this prevents: capture serializes an aggregate's events to the outbox and clears them, so without the exclusion a row written a round later would have published its event a round early. It names the hidden entries explicitly rather than filtering by state, because "skip every Unchanged aggregate" would also drop events legitimately raised on an already-saved aggregate, which is how the identity module publishes registration events.
• Why it's built this way: the whole dance is confined to the SQL Server path of one private method, guarded by an opt-in flag, so the normal save path pays nothing. The raw SQL is covered by a justified CA2100 suppression (DbContextFactory.cs:224-225) and an S2077 pragma (:323, :338), both stating that schema and table names come from EF model metadata rather than user input, and SET IDENTITY_INSERT cannot take a parameterized identifier.
• Where it's used: only inside DbContextFactory, reached when a caller has invoked RequestIdentityInsert() (:276) before the save, which the save path reads and immediately clears (:227-228). The one first-party caller is ADC's Sessionize refresh, which signals the unit of work before saving imported entities (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.Application/Events/UseCases/RefreshFromSessionize/RefreshFromSessionizeHandler.cs:139), through IUnitOfWork.RequestIdentityInsert (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/UnitOfWork.cs:76).

ModelBuilderExtensions

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DbContexts · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/ModelBuilderExtensions.cs:10 · Level 0 · class (internal static)

• What it is: an internal static class holding a single extension member, ApplyAllConfigurations, that scans an assembly for concrete classes implementing a provider-specific configuration interface, instantiates each through DI, and applies it to the EF model, with an optional per-entity filter.
• Depends on: Microsoft.EntityFrameworkCore.ModelBuilder, System.Reflection, and Microsoft.Extensions.DependencyInjection.ActivatorUtilities (all BCL/EF/NuGet). It is called by ApplicationDbContext; it does not itself reference NamespaceConventions or EntityConfigurationOptions.
• Concept introduced, reflection-driven configuration application with a DI-aware activator. [Rubric §8, Data Architecture] (assesses deliberate, discoverable model configuration) and [Rubric §2, Design Patterns] (a generic apply-all built over EF's ApplyConfiguration<TEntity>): because the entity CLR type is only known at runtime, the method resolves EF's open generic ModelBuilder.ApplyConfiguration<TEntity>(IEntityTypeConfiguration<TEntity>) once, then closes it per entity via MakeGenericMethod. Configurations are created with ActivatorUtilities.CreateInstance (ModelBuilderExtensions.cs:62), so a configuration class may constructor-inject services rather than needing a parameterless ctor. The member is declared inside a C# extension(ModelBuilder modelBuilder) block (ModelBuilderExtensions.cs:12), the preview extension-member syntax this workspace uses instead of this-parameter extension methods.
• Walkthrough:
  • Guards all four required arguments with ArgumentNullException.ThrowIfNull (ModelBuilderExtensions.cs:31-34).
  • Resolves the single-parameter ApplyConfiguration overload by reflection (ModelBuilderExtensions.cs:38-40).
  • Selects concrete, non-generic-definition types in the assembly whose interface set contains a closed form of interfaceType (the open generic like IEntityTypeConfigurationSQLServer<,>) (ModelBuilderExtensions.cs:42-51).
  • For each, takes the first generic argument as the entity type, skips it when entityFilter returns false (ModelBuilderExtensions.cs:56-60), then instantiates via ActivatorUtilities and invokes the closed ApplyConfiguration (ModelBuilderExtensions.cs:62-64).
• Why it's built this way: internal keeps this a framework detail; modules never call it. The entityFilter parameter is the boundary that keeps each physical database's model to only its own entities (see ApplicationDbContext), and DI-based activation lets configurations depend on services without a parameterless-ctor constraint.
• Where it's used: called from ApplicationDbContext.ApplyConfigurationsForEntitiesInContext (ApplicationDbContext.cs:709-715), which passes the engine's configuration interface (for example IEntityTypeConfigurationSQLServer<TEntity, TIdentifierType>) and a filter that matches each entity's registry-resolved DataSourceKey.

TransactionCommitAmbiguousException

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DbContexts.Factory · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Factory/TransactionCommitAmbiguousException.cs:22 · Level 0 · class (sealed)

• What it is: the exception DbContextFactory.ExecuteInTransactionAsync throws when the commit phase fails, meaning the transaction may or may not have become durable because a commit can fail after the database applied it but before the acknowledgement reached the client (TransactionCommitAmbiguousException.cs:3-7).
• Depends on: the BCL Exception only.
• Concept introduced, an unknown outcome is a distinct failure mode. [Rubric §29, Resilience, Reliability & Business Continuity Concerns] (resilience policies applied through a shared mechanism rather than per call) and [Rubric §29, Resilience & Business Continuity] (assesses whether failure modes are identified and handled deliberately): a generic failure would be wrong twice over. First, mechanically: SQL Server's EnableRetryOnFailure strategy (configured at MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/SQLServerDbContext.cs:63-66 with five retries and a 10 second ceiling) classifies most commit-phase errors (timeouts, dropped connections) as transient, and EF decides retriability by walking an exception's whole inner chain, so any wrapper carrying the transient error would still be retried, re-running every write of an operation whose commit may already be durable, including its outbox rows (TransactionCommitAmbiguousException.cs:8-14, DbContextFactory.cs:537-540). That is why the commit failure is returned rather than thrown from RunTransactionalAttemptAsync and TryCommit (DbContextFactory.cs:550-554, :572-574, :617-620) and only converted into this exception past the strategy (DbContextFactory.cs:541-542). Second, semantically: "it failed" and "nobody can say whether it failed" call for different recovery, so the type itself is the signal.
• Concept introduced, naming the partial outcome. [Rubric §13, Observability & Operability] (assesses whether an operator can tell what actually happened from what the system reports): commits across several physical sources are sequential and independent, so a failure part-way through leaves earlier sources durable. Rather than leave that inferable only from timing, the exception carries three lists that partition every source the failed commit touched.
• Walkthrough:
  • DefaultMessage (TransactionCommitAmbiguousException.cs:24-26): states both halves, the unknown durability and the deliberate non-retry.
  • Five constructors (:29-69): the parameterless, (string) and (string, Exception) standard set; (Exception innerException) (:45-46), which pairs the provider's failure with the default message; and the four-argument diagnostic one (:57-69), which additionally takes the committed, ambiguous and rolled-back sources and composes them into the message. That last one is the one DbContextFactory actually constructs (DbContextFactory.cs:647); it null-coalesces both lists to empty (:63, :66-68) so a caller passing null gets an empty group rather than a second exception.
  • CommittedSources (:76), AmbiguousSource (:85), RolledBackSources (:93): the three outcome groups, each with doc comments stating what a reader may conclude. Committed sources are durable, so the ambiguity is a partial commit and reconciliation means replaying only what the remaining sources owed (:71-75). The ambiguous source alone is unknowable, and with a single transactional source (the case every host runs today) it is the whole outcome while the other two groups are empty (:78-84). Rolled-back sources wrote nothing that survives, with "best-effort" spelled out literally: a rollback that itself throws is swallowed and the transaction abandoned to the server (:87-92).
  • ComposeMessage (:99-118): builds at most three clauses, skipping any empty group, and appends " Per-source outcome: ..." to the default text; with nothing to report it returns the default message unchanged (:115-117), so a single-source failure reads as one clause rather than three.
• Why it's built this way, and what a caller does about it: the exception's own doc comment assigns recovery to the caller (TransactionCommitAmbiguousException.cs:15-20). An API request marked [Idempotent] replays safely; whatever the transaction wrote to the outbox is delivered by the OutboxProcessor if the commit did land (ADR-003); and the deferred in-process dispatch is dropped, so no handler acts on state that may not exist (DbContextFactory.cs:663-684). The source comment records that a witness row (a marker written inside each source's transaction that a replay could read) would close the multi-source gap entirely, and that it is deliberately not built, because the single transactional source every host runs today needs none (DbContextFactory.cs:488-498).
• Where it's used: thrown at DbContextFactory.cs:542, constructed at :646; pinned by DbContextFactoryCommitAmbiguityTests (MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/DbContexts/DbContextFactoryCommitAmbiguityTests.cs:73, :105, :129, :149, :168), which drives a context whose execution strategy retries on any exception and asserts the operation runs exactly once, that nothing is dispatched in-process, that the transaction is abandoned, that an ordinary success path still commits and flushes, that a failure inside the operation is still retried, and that a second-source commit failure reports each source's outcome.
• Caveats / not-in-source: nothing in the framework catches this type. Whether a host's exception middleware maps it to a specific HTTP status is Not determinable from source: no first-party handler references it outside the throw site and its tests.

ValReturn<T>

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DbContexts · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/ApplicationDbContext.cs:125 · Level 0 · class (internal sealed, nested)

• What it is: a keyless container class, nested in ApplicationDbContext, used to materialize a scalar SQL result (a bool, int, DateTime, or string) from a raw query without a backing table.
• Depends on: Microsoft.EntityFrameworkCore and its host ApplicationDbContext, which registers it as a keyless entity type.
• Concept introduced, keyless entity types for raw scalar queries. [Rubric §8, Data Architecture] (assesses whether persistence mechanics are deliberate): EF Core's FromSql-style scalar materialization needs a CLR class to project into. Rather than one ad-hoc class per scalar shape, ValReturn<T> is a single generic holder with one Value property that any raw query can select into as SELECT ... AS Value.
• Walkthrough: one mutable property, T Value { get; set; } = default! (ApplicationDbContext.cs:128). ApplicationDbContext.OnModelCreating registers four closed forms as keyless views with HasNoKey().ToView(null) (ApplicationDbContext.cs:338-341), so they map to no table and exist only to shape raw-query output. CosmosDbContext deliberately skips base.OnModelCreating partly because of this registration (CosmosDbContext.cs:89-93).
• Why it's built this way: internal sealed keeps it a persistence-layer detail; the generic parameter avoids a proliferation of single-property result classes. ToView(null) marks the type as query-only with no schema object behind it.
• Where it's used: registered by ApplicationDbContext. The four closed forms are baked into every generated migration model snapshot (for example MMCA.Helpdesk/Source/Hosting/MMCA.Helpdesk.Migrations.SqlServer.Tickets/Migrations/SQLServerDbContextModelSnapshot.cs:86, :96, :106, :116, which emit ApplicationDbContext+ValReturn<System.DateTime>, <bool>, <int> and <string>), which is how you can see them without a table.
• Caveats / not-in-source: only the four closed forms registered in OnModelCreating are usable; a fifth scalar type would need its own HasNoKey().ToView(null) registration. A source search across the workspace finds ValReturn only in generated migration snapshots and designer files, with no first-party call site that projects into it today: it is a provided extension point for raw scalar SQL, not a currently exercised path.

ApplicationDbContext

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DbContexts · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/ApplicationDbContext.cs:41 · Level 11 · class (abstract)

• What it is: the single abstract DbContext base that every engine-specific context (SQLServerDbContext, CosmosDbContext, SqliteDbContext) inherits. One instance exists per physical database: the same class is instantiated multiple times, each carrying a different PhysicalDataSource and building a model that contains only that database's entities (ApplicationDbContext.cs:30-35).
• Depends on: AuditSaveChangesInterceptor, DomainEventSaveChangesInterceptor, TenantSaveChangesInterceptor, AuditTrailSaveChangesInterceptor, DataSourceModelCacheKeyFactory, CrossDataSourceDegradeConvention, SoftDeleteUniqueIndexConvention, IEntityDataSourceRegistry, IEntityConfigurationAssemblyProvider, PhysicalDataSource, DataSourceKey, IAuditableEntity, ITenantEntity, AuditableBaseEntity<TIdentifierType>, OutboxMessage, InboxMessage, ScheduledJobEntry, AuditTrailEntry, RefreshSessionModelBuilderExtensions, and SchedulerSettings, AuditTrailSettings and RefreshSessionSettings via IOptions<>, plus MiniProfiler and EF Core.
• Concept introduced, DbContext as Unit of Work + Change Tracker. [Rubric §8, Data Architecture] (assesses transactions, migrations, soft-delete, audit, concurrency): EF's DbContext is the unit of work, tracking every Added/Modified/Deleted entity since the last save and writing them in a single transaction. This is also [Rubric §3, Clean Architecture] (the EF detail stays in Infrastructure; domain entities carry no EF attributes) and [Rubric §6, CQRS & Event-Driven] (domain events are captured transactionally with the aggregate write). The interceptors registered in OnConfiguring run around base.SaveChangesAsync to stamp audit fields, stamp and guard the tenant, serialize domain events into the outbox, and diff the change trail, so those cross-cutting concerns live in the interceptor pipeline rather than inline in every handler.
• Concept introduced, named global query filters. [Rubric §11, Security] and [Rubric §30, Compliance, Privacy & Data Governance] (both assess whether isolation of other parties' data is structural rather than per-query discipline): this class declares two filters by name, SoftDelete (ApplicationDbContext.cs:388) and Tenant (:391). EF composes named filters with AND, so a tenant-owned soft-deletable entity is filtered on both without either filter knowing about the other, and a caller asking to see deleted rows drops exactly SoftDelete and leaves Tenant in force (:383-387, :405-412). Isolation therefore cannot be forgotten at a call site.
• Walkthrough:
  • Primary constructor (ApplicationDbContext.cs:41-46): takes DbContextOptions, an IServiceProvider, an IEntityConfigurationAssemblyProvider, and the PhysicalDataSource this instance targets, delegating to DbContext(options).
  • DataSourceKey (:49): exposes the (engine, database name) pair this context serves; PhysicalSource (:97) exposes the resolved connection info to subclasses as internal.
  • Model-gate fields (:63, :76, :94): _schedulerTableEnabled, _auditTrailTableEnabled and _refreshSessionTableEnabled, all three resolved in OnConfiguring and read by the model-building methods. Their remarks state the rule that keeps them correct: OnModelCreating must not depend on anything the model cache key does not cover, so the settings lookups happen once, up front, in the same place the interceptors are resolved.
  • TenantIdAccessor (:112) and CurrentTenantId (:119): an internal Func<string?>? assigned by the scoped DbContextFactory at context creation (DbContextFactory.cs:104, :134), and the public property that invokes it. The remarks (:105-111) explain why it is an accessor and not a copied value: a context can be created before the request's tenant is resolved, and a copy taken at that moment would pin the context to the wrong answer for its whole life. null reads as "no tenant", which makes the Tenant filter inert for background services, seeders and admin flows.
  • ValReturn<T> (:125-129): the nested keyless scalar holder, documented in its own section above.
  • SupportsOutbox (:136): internal virtual, true by default; the Cosmos subclass overrides it to false. Read by DomainEventSaveChangesInterceptor (DomainEventSaveChangesInterceptor.cs:127, :235).
  • CurrentSaveUserId (:143): internal audit user id with a private setter, written by the save overloads and read by AuditSaveChangesInterceptor; null marks a system operation and the interceptor resolves it to default (AuditSaveChangesInterceptor.cs:50).
  • SaveChangesAsync(userId, ct) (:153-167): the mutation entry point. Opens a MiniProfiler step (:155), sets CurrentSaveUserId, calls base.SaveChangesAsync, and clears the id again in a finally (:161-166) so a later plain base.SaveChangesAsync on the same instance (an internal outbox write, for example) cannot silently reuse the previous caller's identity for its stamps.
  • SaveChanges(userId) (:189-200): the synchronous counterpart with the same set/reset discipline. Its doc comment records the behavioral difference (:181-186): the sync path cannot dispatch events in-process, so captured events are delivered by the outbox processor instead.
  • Change-detection overrides (:173-179, :206-210): both EF save overloads wrap the base call in using var detection = DetectChangesOnce(), the optimization taught under DetectChangesScope.
  • OnConfiguring (:249-306): resolves the two always-present interceptors from DI (:256-257) and adds them, inserting TenantSaveChangesInterceptor between them when it is registered (:264-271). Registration order is execution order, and the comment (:259-263) states why the tenant interceptor belongs in the middle: after the audit stamps (it must not run against half-stamped entries) and before the domain-event interceptor serializes outbox rows, so those rows describe an entity whose tenant is already final. AuditTrailSaveChangesInterceptor is appended last when present (:278-281), because it diffs the final values. Both optional interceptors are fetched with GetService, not GetRequiredService: a host that never opted in, a design-time context, or a directly constructed test context must still build. The method then resolves the three model gates (:286-298) and replaces EF's IModelCacheKeyFactory with DataSourceModelCacheKeyFactory (:303) so each database gets its own model.
  • ConfigureConventions (:309-324): adds two model-finalization conventions. CrossDataSourceDegradeConvention (:318) strips FK constraints and navigations between entities in different physical databases (a structural no-op in the collapsed-monolith case), and SoftDeleteUniqueIndexConvention (:323) makes unique indexes on soft-deletable entities exclude deleted rows, so a soft-deleted row does not block re-creating the "same" record.
  • Set<TEntity>() (:326-328): a public override that forwards straight to base.Set<TEntity>() and adds no behavior of its own.
  • OnModelCreating (:331-358): applies soft-delete filters, tenant filters and concurrency tokens, registers the four keyless ValReturn<T> views (:338-341), then configures the outbox, the inbox, the scheduler table, the audit-trail table and the refresh-session table.
  • ApplySoftDeleteFilters (:367-381): protected static; iterates every non-owned IAuditableEntity type and builds an expression-tree HasQueryFilter("SoftDelete", e => e.IsDeleted == false) (:373-379). Expression trees are required because the CLR type is only known at runtime; owned types are excluded because they inherit the parent filter. [Rubric §5, Vertical Slice] (a global filter removes per-query Where(!IsDeleted) boilerplate from every slice).
  • ApplyTenantFilters (:428-488): protected (instance, because the filter body reads this context). For every non-owned ITenantEntity it configures the discriminator column as required, capped at TenantIdMaxLength of 64 (:397) and non-Unicode (:445-448), indexes it for every engine except Cosmos (:457-467), and builds HasQueryFilter("Tenant", e => CurrentTenantId == null || EF.Property<string>(e, "TenantId") == CurrentTenantId) (:469-486). Three mechanisms are worth internalizing here. The filter embeds this context as a constant typed as ApplicationDbContext (:435), which EF rewrites to the executing context at query compile time and lifts CurrentTenantId into a SQL parameter, so two scopes on two tenants share one compiled model and still read disjoint rows. It reads the column through EF.Property rather than a CLR member access (:473-478), which works for an explicitly implemented interface member and for a shadow property alike. And the supporting index follows the filter composition: an entity that is also an IAuditableEntity gets (TenantId, IsDeleted) because every read of it carries TenantId = @tenant AND IsDeleted = 0, while a tenant-only entity keeps the single-column index (:450-466).
  • ConfigureConcurrencyTokens (:501-521): protected (instance, because it reads Database.ProviderName at :504). It applies IsRowVersion() on SQL Server (database-generated rowversion, :514) or IsConcurrencyToken() elsewhere (application-managed, :518) to the RowVersion property of every non-owned auditable entity. EF then includes the token in UPDATE/DELETE WHERE clauses and throws DbUpdateConcurrencyException on conflicts. [Rubric §8, Data Architecture].
  • ConfigureOutbox (:528-563): maps OutboxMessages in dbo with length/unicode constraints, plus three purpose-built filtered indexes. IX_OutboxMessages_Pending covers the poll path over (ProcessedOn, OccurredOn) filtered to [ProcessedOn] IS NULL and includes RetryCount and LockedUntil so the processor's extra predicates do not force a key lookup per candidate row (:542-545); IX_OutboxMessages_Processed covers the retention sweep over rows the pending index deliberately excludes (:550-552); and IX_OutboxMessages_Ordering over (OrderingKey, OccurredOn), filtered to keyed pending rows, answers the claim predicate's "is there an earlier unprocessed row with this key?" question with a seek instead of a scan per candidate row (:559-562). [Rubric §12, Performance & Scalability].
  • ConfigureInbox (:570-584): maps InboxMessages in dbo with a unique IX_InboxMessages_MessageId (the consumer-side idempotency key, :576-578) and an IX_InboxMessages_ProcessedOn index so the age-based purge has something to seek (:582-583).
  • ConfigureScheduler (:594-619): the first gated table. It returns immediately unless _schedulerTableEnabled (:596-599), then maps ScheduledJobEntry to ScheduledJobs in dbo keyed by JobName, with IX_ScheduledJobs_NextRunOn including the lease columns (:615-617). The index comment (:610-614) records the load-bearing decision: it is deliberately not filtered to unlocked rows, because the poll must also find rows whose lease has expired, which is how a dead replica's work is reclaimed.
  • ConfigureAuditTrail (:628-657): the second gated table, mapping AuditTrailEntry to AuditTrailEntries in dbo with a read index over (EntityType, EntityKey, ChangedOn) (:648-649) and a retention index over ChangedOn (:654-655). Note the asymmetry with the scheduler, stated at :69-73 and :621-627: the job table is host-scoped and lives in the Default source only, while the trail table belongs in every relational source, because a trail row must commit in the same transaction as the change it describes and a transaction does not span databases (the outbox precedent).
  • ConfigureRefreshSessions (:673-681): the third gated table, and the one gated on a configurable source rather than a fixed one. It returns unless _refreshSessionTableEnabled (:675-678), which requires both RefreshSessions:Enabled and this context targeting the source named by RefreshSessions:DataSourceName (:295-298); when it passes it simply calls RefreshSessionModelBuilderExtensions.ApplyRefreshSessionConfiguration (:680). The doc comment states why the mapping lives in the framework base rather than in a consumer's context class (:664-671): under ADR-006 downstream apps run on the sealed engine contexts and have no context class of their own to override, and RefreshSession is not an AuditableBaseEntity, so the module entity-configuration mechanism does not reach it either.
  • ApplyConfigurationsForEntitiesInContext (:690-717): the discovery method subclasses call from their OnModelCreating. It maps the engine to its configuration interface (:692-698), resolves IEntityDataSourceRegistry (:705), then for each assembly from the provider calls ModelBuilderExtensions.ApplyAllConfigurations with a filter that keeps only entities whose registry-resolved key equals this DataSourceKey, or, for unregistered entities, only when this context is the engine's Default source (:709-715).
• Why it's built this way: ADR-006 (database-per-service) requires the same context class per database; without a specialized model-cache key EF would build one model and silently reuse it, so queries would hit tables that do not exist in the other databases. The single ApplicationDbContext is deliberately never split into per-module context classes (also ADR-006). The interceptor pipeline keeps audit, tenancy and outbox concerns out of every handler (ADR-073 for the tenancy model, ADR-075 for the trail, ADR-074 for the job store). The three optional tables are settings-gated rather than always mapped so a host that never opted in keeps the exact model it had before those features shipped, and its migrations never see the tables. The comment at :700-704 records one more deliberate fallback: an entity configured without the attributed base classes lands in the Default model but is not routable through the unit of work.
• Where it's used: inherited by the three concrete contexts below; created per source by PhysicalDbContextFactory (PhysicalDbContextFactory.cs:43-45), cached per scope and given its tenant accessor by DbContextFactory (DbContextFactory.cs:104), and consumed by the interceptors and the outbox processor. The model gates are pinned by SchedulerModelGateTests (MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Scheduling/SchedulerModelGateTests.cs:28, :38, :48, :59), AuditTrailModelGateTests (MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/AuditTrail/AuditTrailModelGateTests.cs:29, :39, :49, :63) and RefreshSessionModelGateTests (MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/DbContexts/RefreshSessionModelGateTests.cs:42, :51, :60, :73, :89); the tenant filter by ApplicationDbContextTenantFilterTests (MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/Tenancy/ApplicationDbContextTenantFilterTests.cs:27, :41, :59, :74, :96, :116, :131, :143, :156, :171, :184, :196), which covers cross-tenant hiding, composition with soft delete, the null-tenant escape, two tenants sharing one cached model, the live accessor being read at query time, the composite (TenantId, IsDeleted) index and the single-column one, and owned types getting no filter of their own.

DataSourceModelCacheKeyFactory

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DbContexts · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/DataSourceModelCacheKeyFactory.cs:16 · Level 11 · class (sealed)

• What it is: a replacement for EF Core's default IModelCacheKeyFactory. Where the default keys the model cache by context type alone, this keys by (context type, data source name, design-time flag), so each physical database gets its own EF model.
• Depends on: ApplicationDbContext (to read DataSourceKey.Name) and EF Core's IModelCacheKeyFactory.
• Concept introduced, model caching under one-context-class-per-engine. [Rubric §8, Data Architecture]: EF builds an in-memory model per DbContext type and caches it. When the same class serves two databases, EF would reuse the first model and the second database's entities would be missing. Inserting DataSourceKey.Name into the cache key makes EF treat "SQL Server / Conference" and "SQL Server / Identity" as distinct models. The class comment states the failure mode plainly (DataSourceModelCacheKeyFactory.cs:11-14): without it, queries would target tables that do not exist in the other databases. This is the critical enabler for ADR-006.
• Walkthrough: Create(DbContext context, bool designTime) (DataSourceModelCacheKeyFactory.cs:19-22) returns (context.GetType(), applicationDbContext.DataSourceKey.Name, designTime) when the context is an ApplicationDbContext, otherwise falls back to (context.GetType(), designTime). The value tuple's structural equality is all EF needs to key its cache dictionary.
• Why it's built this way: the fix is minimal and lives entirely in Infrastructure through EF's supported extension point; no EF internals are subverted. Note what is deliberately absent from the key: the tenant. One compiled model serves every tenant, and the tenant value enters as a SQL parameter through the Tenant query filter instead (see ApplicationDbContext.ApplyTenantFilters and its remarks at ApplicationDbContext.cs:414-420), which is what keeps a multi-tenant host from building one model per tenant.
• Where it's used: registered in ApplicationDbContext.OnConfiguring via optionsBuilder.ReplaceService<IModelCacheKeyFactory, DataSourceModelCacheKeyFactory>() (ApplicationDbContext.cs:303), so every engine context inherits it.

CosmosDbContext

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DbContexts · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/CosmosDbContext.cs:14 · Level 12 · class (sealed)

• What it is: the sealed ApplicationDbContext subclass targeting Azure Cosmos DB. One instance exists per physical Cosmos data source (account plus database). It is the most divergent of the three concrete contexts because Cosmos is non-relational: no outbox table, no relational indexes, and a truncated OnModelCreating path.
• Depends on: ApplicationDbContext, PhysicalDataSource, DataSource, OutboxMessage, IEntityConfigurationAssemblyProvider, and the Cosmos EF provider (Microsoft.Azure.Cosmos). [Rubric §8, Data Architecture] (one concrete context per engine) and [Rubric §11, Security] (the emulator-only certificate bypass).
• Walkthrough:
  • 4-arg constructor (CosmosDbContext.cs:14-19): forwards options, service provider, assembly provider, and physical source to the base.
  • Emulator detection (CosmosDbContext.cs:22-64): checks the connection string for the well-known emulator account-key prefix "C2y6yDjf5" (:29). The emulator path uses ConnectionMode.Gateway and an HttpClientFactory whose handler installs DangerousAcceptAnyServerCertificateValidator for the self-signed cert, guarded by a #pragma warning disable S4830 and a comment that this is safe only in local dev (:41-52). The production path uses ConnectionMode.Direct with MaxRequestsPerTcpConnection(20) and MaxTcpConnectionsPerEndpoint(32) (:57-59). The database name comes from PhysicalSource.CosmosDatabaseName (:34).
  • SupportsOutbox => false (CosmosDbContext.cs:69): overrides the base; Cosmos has no relational outbox table, so domain events are dispatched in-process only.
  • OnModelCreating (CosmosDbContext.cs:72-96): applies the Cosmos configurations (:74), then Ignore<OutboxMessage>() (:77), then removes every index from every entity type (:83-87) because the provider does not support relational HasIndex/HasFilter, then calls ApplySoftDeleteFilters (:94) and ApplyTenantFilters (:95) directly. It deliberately does not call base.OnModelCreating (:89-93) because the base registers the keyless ValReturn<T> views, a relational-only construct the Cosmos provider rejects. Skipping the base is also why the inbox, scheduler, audit-trail and refresh-session tables never reach this engine.
• Why it's built this way: pushing all provider differences into this subclass keeps the base and the entity configuration bodies engine-agnostic; stripping indexes lets one configuration body serve both SQL Server and Cosmos. Calling the two filter helpers directly rather than through the base is what keeps soft delete and tenancy in force on an engine that cannot run the rest of the base pipeline (the tenant helper skips only its index for Cosmos, ApplicationDbContext.cs:457-467).
• Where it's used: instantiated per Cosmos source by PhysicalDbContextFactory when a data source resolves to the CosmosDB engine (PhysicalDbContextFactory.cs:45). It is also the single fact behind DbContextFactory.SupportsTransactions, which is literally context is not CosmosDbContext (DbContextFactory.cs:756-757).
• Caveats / not-in-source: the certificate bypass is scoped by an ordinal substring match on the emulator key prefix; whether any production connection string could contain that substring is Not determinable from source. Per ADR-018 the plumbing ships and is tested, but no host in this workspace configures a Cosmos source today.

IDbContextFactory

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DbContexts.Factory · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Factory/IDbContextFactory.cs:10 · Level 12 · interface

• What it is: the framework's own context-factory contract, the scoped object that hands out one ApplicationDbContext per physical DataSourceKey and then coordinates saving, transactions, schema lifecycle, and disposal across every context a scope touched (IDbContextFactory.cs:5-10). It is deliberately not EF Core's IDbContextFactory<TContext>: the two names collide, which is why consumers that need both add a using IDbContextFactory = ...DbContexts.Factory.IDbContextFactory; alias (InProcessEventBus.cs:8, BrokerEventBus.cs:8, EfInboxStore.cs:8) or fully qualify it (OutboxProcessor.cs:269).
• Depends on: ApplicationDbContext, DataSourceKey, and the BCL IDisposable plus IAsyncDisposable it extends (IDbContextFactory.cs:10).
• Concept introduced, addressing a context by physical source rather than by type. [Rubric §8, Data Architecture] (assesses whether transaction boundaries and unit-of-work scope are deliberate, and whether per-service data isolation is real): EF's own factory answers "give me a context of type T". This one answers "give me the context for this database", which is the only question that makes sense once ADR-006 splits storage along a Name axis and ADR-018 adds an orthogonal Engine axis. The interface also owns the honest statement of what a multi-source save can and cannot promise, in the ExecuteInTransactionAsync doc comment (IDbContextFactory.cs:60-65): each physical source gets its own transaction, commits are sequential and best-effort, there is no two-phase commit, a failure mid-commit leaves earlier sources committed, and the outbox is the cross-source consistency mechanism.
• Walkthrough:
  • GetDbContext(DataSourceKey) (IDbContextFactory.cs:16): the only accessor, documented to create the context if this scope does not already have one for that source.
  • EnsureCreatedAsync (:22), MigrateAsync (:81), HasPendingMigrationsAsync (:87): schema lifecycle across every source the host uses. The contract states the asymmetry: EnsureCreatedAsync skips sources with no configured connection string (:18-21), while the two migration members cover only the sources a migrations pipeline owns, which is every SQL Server source plus any SQLite source with a configured SqliteMigrationsAssembly; Cosmos and assembly-less SQLite are created by EnsureCreatedAsync instead (:74-80).
  • SaveChangesAsync (:27) and SaveChanges (:32): save across all active contexts, the async overload documented as carrying audit stamping and domain-event dispatch.
  • RequestIdentityInsert (:40): a one-shot flag for the next save, documented as automatically cleared once the save completes (see IdentityInsertGroup).
  • BeginTransaction / CommitTransaction / RollbackTransaction (:45, :50, :55): applied to every active context that supports transactions.
  • ExecuteInTransactionAsync<TResult> (:70-72): the member handlers actually reach, running the operation under the active execution strategy so a retrying strategy retries the whole unit.
• Why it's built this way: the application layer already talks to IUnitOfWork; this second interface exists so the physical-topology coordination (which databases, which transactions, which migrations) has a home that Infrastructure can implement and tests can mock, without leaking EF Core upward.
• Where it's used: registered scoped as DbContextFactory (DependencyInjection.cs:95). UnitOfWork delegates its whole save and transaction surface to it (UnitOfWork.cs:70-91), the startup path resolves it to create, migrate, or verify databases (MMCA.Common/Source/Presentation/MMCA.Common.API/Startup/DatabaseInitializationExtensions.cs:58, :242, and per tenant at :144), and the background and messaging paths resolve it per scope to reach a specific source (OutboxProcessor at OutboxProcessor.cs:269, OutboxCleanupService.cs:110, OutboxAdministration.cs:244, EfInboxStore.cs:39, InProcessEventBus.cs:34, BrokerEventBus.cs:32, ScheduledJobRunner.cs:213, AuditTrailReader.cs:35, AuditTrailCleanupJob.cs:49, EFRefreshSessionStore.cs:31, and RefreshSessionCleanupService.cs:109).

IPhysicalDbContextFactory

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DbContexts.Factory · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Factory/IPhysicalDbContextFactory.cs:15 · Level 12 · interface

• What it is: the contract for constructing a raw context for a given physical data source. Its doc comment states the split precisely: the engine selects the context class (SQL Server, Cosmos, SQLite) and the source name selects the database (connection string, migrations assembly, EF model), and contexts created here are neither scoped nor cached (IPhysicalDbContextFactory.cs:6-13).
• Depends on: ApplicationDbContext as the return type, DataSourceKey as the addressing type, and PhysicalDataSource on the second overload (IPhysicalDbContextFactory.cs:22, :37).
• Concept introduced, construction split from lifetime. [Rubric §2, Design Patterns] (assesses whether patterns are applied where they earn their keep): this is the Abstract Factory half of the pair. Deciding which class to new up for which database is a pure function of the key and needs no per-request state, so it lives in a singleton; deciding how long a context lives, when it saves, and what transaction it is in is per-request state and lives in the scoped IDbContextFactory layered on top (IPhysicalDbContextFactory.cs:10-13).
• Walkthrough: two members. Create(DataSourceKey key) (IPhysicalDbContextFactory.cs:22) returns a new instance targeting the database the resolver maps that key to. Create(DataSourceKey key, PhysicalDataSource physicalDataSource) (IPhysicalDbContextFactory.cs:37) is the database-per-tenant overload: the caller clones the resolved PhysicalDataSource with the tenant's connection string and passes the same key, so EF's model cache still serves one compiled model per (context type, source name) across every tenant (IPhysicalDbContextFactory.cs:24-35).
• Why it's built this way: keeping the construction decision behind a two-method interface is what makes the scoped coordinator testable without a database ([Rubric §14, Testability]): the commit-ambiguity tests hand DbContextFactory a Mock<IPhysicalDbContextFactory> that returns a SQLite in-memory context (MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/DbContexts/DbContextFactoryCommitAmbiguityTests.cs:49-55). The two-overload shape is also what keeps tenancy (ADR-073) a routing decision in the scoped layer rather than a second factory.
• Where it's used: registered singleton as PhysicalDbContextFactory (DependencyInjection.cs:96); injected into DbContextFactory (DbContextFactory.cs:40), which calls both overloads at :94-96.

SqliteDbContext

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DbContexts · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/SqliteDbContext.cs:12 · Level 12 · class (sealed)

• What it is: the sealed ApplicationDbContext subclass targeting SQLite, the minimal concrete context. One instance exists per physical SQLite data source (database file), useful for lightweight local development or testing without a SQL Server instance (SqliteDbContext.cs:7-10).
• Depends on: ApplicationDbContext, PhysicalDataSource, DataSource, IEntityConfigurationAssemblyProvider, and the SQLite EF provider.
• Walkthrough: the 4-arg constructor forwards to the base (SqliteDbContext.cs:12-17). OnConfiguring guards its argument, then calls UseSqlite(PhysicalSource.ConnectionString, ...) with one option: it sets sqlite.MigrationsAssembly(PhysicalSource.SqliteMigrationsAssembly) when that value is configured (SqliteDbContext.cs:31-34). The comment above it states the contract this shares with SQL Server (:28-30): without an explicit assembly EF looks for migrations next to the context, which lives in MMCA.Common.Infrastructure and has none, so a per-source migrations project would never be found. There is no retry policy (the store is file-local) and no command-timeout override. OnModelCreating calls ApplyConfigurationsForEntitiesInContext(DataSource.Sqlite, modelBuilder) then base.OnModelCreating (SqliteDbContext.cs:40-44), so unlike Cosmos it keeps the full base pipeline: soft-delete and tenant filters, concurrency tokens as application-managed tokens rather than rowversion, the outbox and inbox tables, the three settings-gated tables, and the ValReturn<T> views. See SQLServerDbContext for the shared subclass shape.
• Why it's built this way: SQLite needs none of the SQL Server hardening (transient-failure retry, a per-environment command timeout), so the override is intentionally sparse, but the migrations assembly is not optional hardening: it is what lets a SQLite source participate in IDbContextFactory.MigrateAsync at all, since PhysicalDataSource.UsesMigrations returns true for SQLite only when that assembly is configured (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/PhysicalDataSource.cs:48-51). Keeping the full base pipeline is what makes this context a faithful stand-in for SQL Server in tests, which is how the framework's own tenancy and model-gate suites run without a database (for example MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/Tenancy/ApplicationDbContextTenantFilterTests.cs:24, which holds one SQLite connection open for the fixture's lifetime). [Rubric §14, Testability].
• Where it's used: instantiated per SQLite source by PhysicalDbContextFactory when a data source resolves to the Sqlite engine (PhysicalDbContextFactory.cs:44). Its migration behavior is pinned by DbContextFactoryMigrationTargetTests (MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/DbContexts/DbContextFactoryMigrationTargetTests.cs:94, :106, :115, :126), which asserts that a SQLite source with a migrations assembly is migrated, one without is skipped, HasPendingMigrationsAsync considers only the migrated source, and EnsureCreatedAsync still covers both.

SQLServerDbContext

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DbContexts · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/SQLServerDbContext.cs:15 · Level 12 · class (sealed)

• What it is: the sealed ApplicationDbContext subclass targeting SQL Server, the production-primary context. One instance exists per physical SQL Server data source (database); its connection string and migrations assembly come from the resolved PhysicalDataSource.
• Depends on: ApplicationDbContext, PhysicalDataSource, DataSource, IEntityConfigurationAssemblyProvider, PersistenceSettings via IOptions<>, and the SQL Server EF provider (RelationalEventId). [Rubric §8, Data Architecture] (one concrete context per engine, one instance per database) and [Rubric §29, Resilience & Business Continuity] (the retry policy and the command timeout are baked into the SQL Server path).
• Walkthrough:
  • 4-arg constructor (SQLServerDbContext.cs:15-20): forwards to the base.
  • _persistenceSettings (SQLServerDbContext.cs:35-36): a readonly field resolved in the field initializer as serviceProvider.GetService<IOptions<PersistenceSettings>>()?.Value ?? new PersistenceSettings(). Two details are deliberate and documented at :23-35. It is resolved once per instance rather than read from the primary-constructor parameter inside OnConfiguring, because referencing that parameter from a member body would capture it into the type's state while the base constructor also receives it (CS9107); caching per instance is safe precisely because these contexts are never pooled. And it uses GetService, not GetRequiredService, because the design-time provider behind dotnet ef registers no options at all and must not be made to throw: both a missing registration and a null value fall back to the defaults.
  • OnConfiguring (SQLServerDbContext.cs:39-82): calls UseSqlServer(PhysicalSource.ConnectionString, sql => ...). The options action does three things: conditionally sets sql.MigrationsAssembly(PhysicalSource.SqlServerMigrationsAssembly) (:49-52) so each extracted service can point at its own per-module migrations project; applies sql.CommandTimeout(_persistenceSettings.CommandTimeoutSeconds) (:56), because without it every command silently inherits ADO.NET's 30 second default with no way to tune it per environment (the setting's own default is 30, range-validated to 1-600, at MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/PersistenceSettings.cs:21-22); and enables sql.EnableRetryOnFailure(maxRetryCount: 5, maxRetryDelay: TimeSpan.FromSeconds(10), errorNumbersToAdd: null) (:64-67). An inline comment (:61-63) records the retry caveat: with retry enabled, any manual BeginTransactionAsync must be wrapped in Database.CreateExecutionStrategy().ExecuteAsync, which TransactionalCommandDecorator<TCommand, TResult> already does through DbContextFactory. Finally ConfigureWarnings(w => w.Ignore(RelationalEventId.PendingModelChangesWarning)) (:80) suppresses EF Core's pending-model error.
  • OnModelCreating (SQLServerDbContext.cs:85-89): calls ApplyConfigurationsForEntitiesInContext(DataSource.SQLServer, modelBuilder) then base.OnModelCreating, so the full base pipeline (soft-delete and tenant filters, rowversion concurrency tokens, outbox/inbox tables, the three settings-gated tables, and the ValReturn<T> views) runs.
• Why it's built this way: the PendingModelChangesWarning suppression is required by the microservices-extraction design: each extracted host registers only its enabled modules' configurations, so its runtime model is a strict subset of the migration snapshot (the union of all modules), and EF Core 9+ would otherwise promote that mismatch to an error inside Migrator.ValidateMigrations during MigrateAsync (SQLServerDbContext.cs:68-74). The documented trade-off (:77-79): monolith hosts lose the "you forgot a migration" safety net, so CI should run dotnet ef migrations has-pending-model-changes against the migrations assembly with the full model loaded as a separate gate. Retry-on-failure exists so cold-replica startup connections and platform replica replacements do not surface as user-facing 5xx (ADR-006, ADR-009).
• Where it's used: instantiated per SQL Server source by PhysicalDbContextFactory (PhysicalDbContextFactory.cs:43); built at design time by DesignTimeDbContextHelper.CreateSqlServer (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Design/DesignTimeDbContextHelper.cs:51), which is what makes one migrations project per database possible. It is also the type DbContextFactory tests for on the identity-insert path (DbContextFactory.cs:248). It is the primary production context in both MMCA.ADC and MMCA.Store, and the context type every committed migration snapshot is generated against.
• Caveats / not-in-source: whether any repository's CI actually runs the has-pending-model-changes gate the comment recommends is Not determinable from this file.

DbContextFactory

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DbContexts.Factory · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Factory/DbContextFactory.cs:39 · Level 13 · class (sealed)

• What it is: the scoped implementation of IDbContextFactory and the busiest type in this group. It caches one ApplicationDbContext per physical DataSourceKey for the life of the scope, coordinates save, transaction, migration, and disposal across all of them, and is also the database-per-tenant routing point (DbContextFactory.cs:17-26).
• Depends on: IPhysicalDbContextFactory, IEntityDataSourceRegistry, IDataSourceResolver, and ICurrentUserService, all null-guarded from the primary constructor into readonly fields (DbContextFactory.cs:39-58), plus two tenancy parameters read directly off the primary constructor: ITenantContext and IOptions<TenancySettings> (:43-44, with their contracts documented at :31-37). It also calls four internal static members of DomainEventSaveChangesInterceptor (BeginCaptureExclusion, EndCaptureExclusion, DropDeferred, FlushDeferredAsync, at DbContextFactory.cs:315, :342, :447, and :581).
• Concept introduced, coordinating one logical save across several physical databases. [Rubric §8, Data Architecture] (transaction boundaries, unit-of-work scope, per-service isolation) and [Rubric §12, Performance & Scalability] (transactions handled once in a shared mechanism, never copy-pasted into handlers): every hard question raised by ADR-006 lands here. How many contexts does a request have (one per source it touches)? What does "commit" mean when there are two (sequential, best-effort, no two-phase commit)? When are in-process domain events allowed to run (only after a successful commit)? What happens when the commit itself fails with an unknown outcome (see TransactionCommitAmbiguousException)?
• Concept introduced, per-tenant routing without a second EF model. [Rubric §11, Security] and [Rubric §30, Compliance, Privacy & Data Governance]: under ADR-073 a tenant may declare its own connection string for a source, and this class is where that declaration turns into a different database. The trick is that only the connection string changes: the DataSourceKey stays the same, which is what EF's model cache is keyed on, so one compiled model serves every tenant (DbContextFactory.cs:138-143).
• Walkthrough:
  • State (DbContextFactory.cs:48-85): MaxSavePasses (3, :52); _dbContexts, the per-scope Dictionary<DataSourceKey, ApplicationDbContext> that guarantees every repository in a scope shares one change tracker per database (:62); _routedContextTenants, recording which tenant each per-tenant-routed context was created for and holding only overridden sources (:64-69); _transactionActive (:75); the one-shot _identityInsertRequested flag (:82); and a volatile bool _disposed (:84).
  • GetDbContext(DataSourceKey) (DbContextFactory.cs:88-118): throws if disposed (:89), then on a cache miss asks ResolveTenantOverride for the tenant's own connection information and creates the context through whichever Create overload applies (:93-96), records the creating tenant when the source was routed (:100-101), attaches the tenant accessor (:103), and enlists the new context in an already-active transaction (:107-108), so a source first touched inside a transactional command still shares the boundary. On a cache hit it calls GuardRoutedTenantUnchanged (:113).
  • AttachTenantAccessor (DbContextFactory.cs:130-136): hands the context a delegate rather than a copied value, because a context can be created before the request's tenant is resolved and the query filter must read the answer that holds at query time (:119-128). It null-guards inside rather than at the call site so the null tolerance a mocked physical factory needs does not leak a maybe-null flow state back into the caller (:124-128).
  • ResolveTenantOverride (DbContextFactory.cs:144-169): returns null (source stays shared) unless there is a tenant, bound settings, an entry for that tenant, and an entry for this source name (:145-151); otherwise it takes the engine-appropriate connection string through TenancySettingsValidator.ConnectionStringFor (:153), still returning null when the tenant overrides only a different engine (:154-158), and finally clones the shared PhysicalDataSource with the tenant's connection string and Cosmos database name (:160-167).
  • GuardRoutedTenantUnchanged (DbContextFactory.cs:177-194): if the cached context was routed for a tenant and the scope's tenant has since changed, it throws with both tenant ids named (:185-192). The comment states the stakes (:170-175): serving that context to a second tenant would read and write the first tenant's data under the second tenant's filter value.
  • GetSourcesInUse (DbContextFactory.cs:214-215): the union of every source backing a registered entity (from IEntityDataSourceRegistry) and every source already materialized in this scope, which is what EnsureCreatedAsync (:196-207) and GetMigrationTargets (:705-723) iterate. EnsureCreatedAsync skips sources with an empty connection string (:200-203).
  • GetMigrationTargets (DbContextFactory.cs:706-724): the shared filter behind MigrateAsync (:686-690) and HasPendingMigrationsAsync (:726-735). It keeps a source only when its resolved PhysicalDataSource.UsesMigrations is true (:713-714), then skips a non-SQL-Server target whose connection string is empty (:716-717). The asymmetry is deliberate and documented (:697-702): an optional SQLite source a test host leaves unconfigured stays silently absent, while a SQL Server source with no connection string still fails loudly at startup, because for SQL Server that is a misconfiguration rather than an option.
  • SaveChangesAsync (DbContextFactory.cs:226-274): reads and immediately clears the identity-insert flag (:227-228), then loops at most MaxSavePasses times over the contexts it has not yet saved (:237-251), passing _currentUserService.UserId into each context's audit-aware SaveChangesAsync overload (:247-249). The re-loop exists because saving dispatches domain events in-process, and a handler that resolves a repository for a source nobody had touched yet calls GetDbContext mid-enumeration (:233-236). After the loop it asserts that no cached context still has changes and throws an InvalidOperationException naming the offending sources if any does (:259-270), because anything still tracked when the unit of work returns would be silently lost. The comment at :253-258 explains why the assertion reads the change tracker rather than the saved set: it must catch both a context materialized past the pass bound and a handler that dirtied an already-saved context.
  • SaveChanges (DbContextFactory.cs:409-417): the synchronous path, a single pass over a snapshot of the cached contexts with no re-loop.
  • Identity-insert path (DbContextFactory.cs:277, :284-403): covered in IdentityInsertGroup above.
  • BeginTransaction / CommitTransaction / RollbackTransaction (DbContextFactory.cs:419-449): each filters to contexts that support transactions and, symmetrically, to those that do or do not already carry one (:426, :433, :440), because EF throws on a second BeginTransaction for the same connection and GetDbContext may already have enlisted a late-created context (:422-425). Rollback additionally calls DomainEventSaveChangesInterceptor.DropDeferred on every context (:446-447): the aggregate changes and their outbox rows just rolled back, so the deferred in-process dispatch must never run, and must not survive into a retry.
  • ExecuteInTransactionAsync<TResult> (DbContextFactory.cs:500-545): re-entrancy first, a nested call simply runs the operation on the ambient transaction (:510-511), because an inner commit would make the outer scope's earlier work durable ahead of its own decision (:503-509). Otherwise it picks the execution strategy from the first transaction-capable context, materializing the Default source through the resolver if none exists yet (:519-520, deliberately resolved rather than taken literally so a host with no SQL Server connection does not open a connection string that does not exist, :513-518), and runs the attempt under strategy.ExecuteAsync (:526-534), calling ResetForRetry before every attempt after the first (:528-529).
  • RunTransactionalAttemptAsync (DbContextFactory.cs:555-610): one attempt, begin to commit. A failed Result rolls back and returns (:563-570), which is what makes ADR-013's Result-over-exceptions rule safe for partial persistence. On success it commits through TryCommit and only then flushes the deferred dispatch on every context, snapshotting the dictionary first because a handler can still materialize a new source (:576-583). A cancellation attempts a best-effort rollback and, if even that throws, clears the flag and drops every deferred dispatch by hand (:587-603); any other exception rolls back and rethrows (:604-608).
  • TryCommit (DbContextFactory.cs:622-654) and AbandonAfterCommitFailure (:662-683): a commit failure is returned, not thrown (:646). TryCommit snapshots the enlisted contexts first, because that order is the commit order (:625-630), then commits them one by one, accumulating the successes; on a throw it names the failing source, treats everything past it in the snapshot as rolled back (:644), and hands all three groups to TransactionCommitAmbiguousException. AbandonAfterCommitFailure rolls back whatever has not committed yet, drops every deferred dispatch, and swallows secondary rollback failures so the commit ambiguity stays the reported failure (:666-682).
  • ResetForRetry (DbContextFactory.cs:743-750): before the strategy re-runs the operation it drops deferred dispatch and calls ChangeTracker.Clear() on every context, so entities the aborted attempt added are not inserted a second time (with a duplicate outbox row per event).
  • SupportsTransactions (DbContextFactory.cs:756-757): context is not CosmosDbContext, the single place the Cosmos "no multi-document transactions" fact is encoded; HasActiveTransaction (:758-759) is Database.CurrentTransaction is not null.
  • Disposal (DbContextFactory.cs:762-792): Dispose and DisposeAsync both dispose every cached context, clear the dictionary, set _disposed, and suppress finalization.
• Why it's built this way: ADR-006 makes "one scope, several databases" the normal case, so somebody has to own the cross-context bookkeeping; putting it here keeps handlers writing SaveChangesAsync exactly as they would against a single database, and ADR-073 then reuses that one chokepoint for per-tenant routing. The five subtleties (bounded re-loop plus the unsaved assertion, deferred dispatch released only after commit, a commit failure exempted from retry and reported per source, the routed-tenant guard, and the re-entrancy short circuit) are each a correctness fix with the reasoning written into the source next to the code.
• Where it's used: registered scoped as IDbContextFactory (DependencyInjection.cs:95) and consumed through that interface everywhere (see the interface's section). Directly instantiated in tests, for example MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/DbContexts/DbContextFactoryCommitAmbiguityTests.cs:55 and :195; the save-loop invariants are pinned by DbContextFactorySaveIntegrityTests (MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/DbContexts/DbContextFactorySaveIntegrityTests.cs:81, :101, :120), which assert that a handler mutating an already-saved context throws naming that context, that an extra read-only context does not, and that a clean scope returns the written count.
• Caveats / not-in-source: the MaxSavePasses bound of 3 is documented as "two passes cover the realistic case, the third is slack" (DbContextFactory.cs:48-52); whether any production workload has ever needed the third pass is Not determinable from source. The routed-tenant guard also implies a usage rule the code can only enforce after the fact: a scope serves one tenant, and switching tenants means a fresh scope (:185-192).

PhysicalDbContextFactory

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DbContexts.Factory · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Factory/PhysicalDbContextFactory.cs:16 · Level 13 · class (sealed)

• What it is: the singleton implementation of IPhysicalDbContextFactory. It resolves the key's connection information through IDataSourceResolver (or accepts it from the caller) and constructs the matching engine context directly with new (PhysicalDbContextFactory.cs:34-48).
• Depends on: IServiceProvider, IDataSourceResolver, and IEntityConfigurationAssemblyProvider, all taken through a primary constructor (PhysicalDbContextFactory.cs:16-19), plus the three context classes SQLServerDbContext, SqliteDbContext, and CosmosDbContext.
• Concept introduced, the never-pool rule. [Rubric §8, Data Architecture] and [Rubric §12, Performance & Scalability] (which assesses whether performance work is deliberate rather than reflexive): EF Core's AddPooledDbContextFactory is the standard way to avoid re-allocating contexts, and it is explicitly forbidden here. The class comment says why (PhysicalDbContextFactory.cs:10-14): each instance carries per-source constructor state (its PhysicalDataSource), so a pool would hand a context configured for one database to a caller asking for another and silently point repositories at the wrong database. The same warning is repeated at the registration site (DependencyInjection.cs:90-96), which is where someone optimizing DI would look first. Under database-per-tenant the rule is load-bearing twice over, since a pooled context could then cross a tenant boundary rather than only a module one.
• Walkthrough:
  • Three static empty options objects (PhysicalDbContextFactory.cs:24-31): one DbContextOptions<T> per engine, built once and reused. The comment above them explains the emptiness (:21-23): provider, connection, interceptors, and model cache key are all set inside each context's OnConfiguring, so these options exist only to satisfy the DbContext constructor and match what the previous AddDbContextFactory<T>() registrations produced.
  • Create(DataSourceKey key) (PhysicalDbContextFactory.cs:34): a one-liner that resolves the PhysicalDataSource with resolver.GetPhysical(key) and forwards to the two-argument overload, so the resolver path and the tenant path share one construction switch.
  • Create(DataSourceKey key, PhysicalDataSource physicalDataSource) (PhysicalDbContextFactory.cs:37-48): null-guards the supplied source (:39), then switches on key.Engine to construct SQLServerDbContext, SqliteDbContext, or CosmosDbContext, passing options, the service provider, the assembly provider, and the physical source into each four-argument constructor (:43-45). An unmapped engine throws an InvalidOperationException naming the offending value (:46).
• Why it's built this way: this is the single point where the two storage axes meet, the Engine axis of ADR-018 picking the class and the Name axis of ADR-006 picking the database, so adding an engine is a new case plus a context class rather than a change anywhere in application code. Taking the connection information as a parameter is what let ADR-073 add a third, per-tenant axis without touching the switch.
• Where it's used: registered singleton (DependencyInjection.cs:96); DbContextFactory.GetDbContext calls one overload or the other on every cache miss (DbContextFactory.cs:95-97), which is the only first-party call site.

CrossTenantWriteException

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.Interceptors · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Interceptors/CrossTenantWriteException.cs:24 · Level 0 · class (sealed, exception)

• What it is: the single failure type of the write side of multi-tenancy. It is thrown when a save would insert, update or delete a row owned by a tenant other than the one the current scope resolved, or would insert an untenanted row from a scope that resolved no tenant at all (CrossTenantWriteException.cs:5-9).
• Depends on: the BCL only (InvalidOperationException, string.Format with CultureInfo.InvariantCulture). It is thrown exclusively by TenantSaveChangesInterceptor; it does not reference it.
• Concept introduced, why isolation fails loudly on the write side and silently on the read side. [Rubric §11, Security] assesses whether authorization boundaries are enforced by construction rather than by caller discipline, and [Rubric §30, Compliance and Data Governance] assesses whether tenant data separation is demonstrable. Read isolation is a query filter, and a filter that disagrees with the caller simply returns nothing: a wrong tenant sees an empty list, which is the correct and harmless outcome. A save has no equivalent harmless outcome. By the time the interceptor sees the entry, the row is about to be written, and the only honest results are "the correct tenant" or "no write at all", so this type throws instead of filtering (CrossTenantWriteException.cs:11-18). The message names the entity type and both tenants because the realistic cause is a scope that was never given a tenant (a background job, a queued handler) rather than a genuine attempt to cross the boundary.
• Walkthrough:
  • DefaultMessage (:26-27): the parameterless-constructor text, "The save would write across the tenant boundary and was rejected."
  • The three public constructors (:30-31, :35-36, :41-42): parameterless, message, and message-plus-inner. They exist so the type satisfies the standard exception shape the analyzers require, even though the framework itself never calls them.
  • The private constructor (:44-54): the one the factories use. It takes the formatted message plus the three diagnostic values and assigns them to the properties.
  • EntityType, CurrentTenantId, EntityTenantId (:57, :62, :68): all string?, all get-only. A catch site can branch on the data instead of parsing the message. CurrentTenantId is null exactly when the scope resolved no tenant; EntityTenantId is null when the entity carried none.
  • ForMismatch(entityType, operation, currentTenantId, entityTenantId) (:78-94): builds the "the entity belongs to tenant X but this scope resolved tenant Y" message. operation is the literal insert, update or delete passed by the interceptor, so one factory covers all three write shapes.
  • ForUnresolvedTenant(entityType) (:101-111): builds the message for the other failure, an untenanted insert from an untenanted scope, and names the two ways out in the message itself: resolve a tenant for the scope via ITenantContext.SetTenant, or assign the tenant on the entity before saving. Both tenant ids are passed as null.
• Why it's built this way: it derives from InvalidOperationException (:19-22) so existing handler and middleware catch sites treat it exactly as they treat the framework's other save-time invariant failures, with no new catch clause anywhere. Both factories are internal, which keeps the interceptor the only thing that can produce a populated instance while leaving the type public for consumers to catch. See ADR-073 for the multi-tenancy model this enforces.
• Where it's used: thrown at three call sites in TenantSaveChangesInterceptor (TenantSaveChangesInterceptor.cs:110 for the unresolved-tenant insert, :123 for a mismatched insert, :150-151 for a mismatched update or delete); asserted by TenantSaveChangesInterceptorTests (MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/Tenancy/TenantSaveChangesInterceptorTests.cs:12, with the unresolved-tenant case at :34, the mismatched insert at :59, and the mismatched update and delete at :73 and :90).

EncryptedStringConverter

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.Encryption · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Encryption/EncryptedStringConverter.cs:72 · Level 0 · class (sealed)

• What it is: an EF Core ValueConverter<string, string> that encrypts a string property with AES-256-GCM on the way to the database and decrypts it on the way back, transparently to the entity (EncryptedStringConverter.cs:8-11). It is applied per property in an entity configuration, not globally (:12-18), and the value it stores is a versioned envelope: the key it decrypts with is named by a byte inside the stored value itself, not by whatever key the converter was built with.
• Depends on: System.Security.Cryptography (AesGcm, RandomNumberGenerator, CryptographicException), System.Collections.Frozen (FrozenDictionary, :1), System.Text.Encoding, and EF Core's ValueConverter<TModel, TProvider>. No first-party type.
• Concept introduced, authenticated encryption at rest, and what it costs you. [Rubric §11, Security] (assesses whether sensitive data is protected in transit and at rest with sound primitives) and [Rubric §30, Compliance, Privacy & Data Governance] (assesses whether personal data is classified and handled deliberately). AES-GCM is an authenticated mode: it gives confidentiality and integrity in one pass, so tampering with a stored value makes decryption throw instead of silently yielding garbage, and no separate HMAC step is needed. The price is stated at length in the class comment (:19-32) and is the part worth internalizing: every write draws a fresh random nonce (:193), so the same plaintext produces a different column value each time. A non-deterministic column cannot carry an equality or range predicate (the comparison is against a ciphertext that never matches, and the query returns no rows rather than failing), cannot carry a unique index, and cannot be sorted or grouped server side. Anything that must stay searchable needs a second, deterministic surface such as a keyed hash beside the encrypted column. This is the counterpart to the erasure story taught by IAnonymizable and PiiAttribute (ADR-005): erasure overwrites a field you never need again, encryption protects one you still have to read back.
• Concept introduced, a self-describing envelope is what makes key rotation possible. [Rubric §8, Data Architecture] (assesses whether persistence mechanics are deliberate) and again [Rubric §11, Security]. A stored value is Base64 of [key version (1)] [nonce (12)] [ciphertext (N)] [tag (16)] (:38-44, laid out at :203-208), so the row carries everything needed to read it back except the key material: 29 bytes of overhead before Base64 inflation (:75, :78, :81). Two properties fall out of that one byte. First, a converter can hold a whole key ring keyed by version with one version nominated as current (:109): writes stamp the current version (:116, :205), reads take their key from the version byte in the data (:223-224), so a rotation is add the new key as current, deploy, re-encrypt rows in the background, then retire the old version, with no maintenance window and no rows left unreadable in between (:45-61). Second, the version byte is authenticated, not merely stored: it is passed to AES-GCM as associated data on both sides (:198, :231), so rewriting it fails the tag check rather than silently selecting another key, and it fails even when the substituted version happens to map to the same key. That last property is the one a "just prefix the version" design usually misses.
• Walkthrough:
  • Sizes and the default version (EncryptedStringConverter.cs:75, :78, :81, :84, :87): VersionSize = 1, NonceSize = 12 bytes (96 bits, the NIST recommendation for GCM), TagSize = 16 bytes (128 bits), KeySize = 32 bytes, and DefaultKeyVersion = 1, the version the single-key constructor stamps.
  • Two public constructors over one private one (:94-97, :109-112, :114-119): the byte[] constructor is sugar for a one-entry ring at version 1, built by CreateSingleKeyRing (:95, :127-138), which null-guards the key (:129) and rejects anything that is not exactly 32 bytes with a message naming the length it got (:130-135). The ring constructor takes an IReadOnlyDictionary<byte, byte[]> plus the version to write with. Both funnel into the private constructor, which passes the two lambdas up to ValueConverter, Encrypt as the to-provider direction bound to the current version and Decrypt as the from-provider direction (:116-117). The frozen ring is captured by those lambdas.
  • ValidateAndFreeze (:146-182): the ring is validated once, at construction. Not null (:150), not empty (:152-155), no null entry (:159-164), every key exactly 32 bytes (:166-171), and the nominated current version actually present (:174-179), which is what lets Encrypt index the ring without a lookup guard (:189-190). Then ToFrozenDictionary() (:181) takes a defensive copy, so mutating the dictionary the caller passed in afterwards cannot change which keys the converter uses (:140-145).
  • GenerateKey() (:125): RandomNumberGenerator.GetBytes(32), the convenience path for producing a valid key during setup.
  • Encrypt (:184-211): empty and null pass through unchanged (:186-187), otherwise resolve the current key (:190), UTF-8 encode (:192), draw a 12-byte nonce (:193), and encrypt into a same-length ciphertext buffer with a 16-byte tag, handing the single version byte over as associated data (:194-201). The four regions are then laid into one buffer in envelope order (:203-208) and Base64-encoded (:210). Storing the version and nonce alongside the ciphertext is what makes each row self-describing: no side table of nonces and no out-of-band record of which key wrote which row.
  • Decrypt (:213-239): Base64 decode (:218), reject anything shorter than version plus nonce plus tag with a CryptographicException (:220-221), read the version from position 0 and fail with a message naming only the version number (never key material) when the ring has no key for it (:223-225), then slice nonce, ciphertext, tag, and the associated-data byte by fixed offsets and decrypt (:227-236). A wrong key, a tampered ciphertext byte, and a rewritten version byte all fail inside AesGcm.Decrypt, which is the integrity guarantee doing its job.
• Why it's built this way: GCM over CBC removes the "encrypt then MAC" bookkeeping that is easy to get wrong, and putting the whole scheme behind a ValueConverter means an entity property stays a plain string in the domain model. ADR-037 records the decision and is explicit that this is a second layer above transparent database encryption: TDE decrypts for anyone who can query, this converter keeps the value ciphertext the moment it leaves the application. The key never lives in the converter's own configuration: the comment (:33-37) points at Key Vault, user-secrets, or environment variables. The converter is also deliberately stateless and context-free (:62-70): version resolution is data-driven from the envelope and nothing consults the DbContext, the current user, or any ambient scope, because a value converter is a pair of compiled expressions running in the provider's materialization path and cannot reach them. Per-tenant or per-request key selection is therefore out of scope here by design and needs a SaveChanges interceptor or application-layer encryption above EF Core.
• Where it's used: nowhere in application code today. A workspace-wide search of *.cs for the type finds only its own file, its 21 unit tests (MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/Encryption/EncryptedStringConverterTests.cs:6, covering the plaintext round trip at :10, non-determinism at :24 and :38, key generation at :52 and :61, the invalid-length and null-key guards at :71 and :123, the empty-string passthrough at :82 and :95, the too-short value at :108, Unicode at :129, the version byte the single-key constructor stamps at :145, a key-ring round trip at :157, a full rotation in which pre-rotation ciphertext stays readable while new writes carry the new version at :175, an unregistered version at :205, the tampered-version-byte failure at :226, the four ring-validation guards at :244, :250, :259, and :268, and the defensive copy of the caller's dictionary at :281), and one prose mention in the IAnonymizable doc comment (MMCA.Common/Source/Core/MMCA.Common.Domain/Interfaces/IAnonymizable.cs:17-19) recommending it for personal fields that must survive erasure in readable form. No entity configuration calls HasConversion(new EncryptedStringConverter(...)) in any of the repos, and no DI registration supplies a key or a ring.
• Caveats / not-in-source: this is therefore a shipped but unadopted extension point, a posture ADR-037 states outright and still records as zero adoption after the versioned envelope shipped in MMCA.Common v1.153.0. Zero adoption is also what made the format change affordable: there is no legacy decode path, so a value written in the earlier un-versioned [nonce] [ciphertext] [tag] layout does not read back under the current converter (its first byte is a nonce byte, not a version), and the window in which the envelope is free to change closes at the first adopted column. Three further limits are worth knowing before adopting it. The version space is a single byte (:75), ample for annual or quarterly rotation but wrapping rather than growing, and a reused version number is exactly the ambiguity the byte exists to prevent. The suite covers the short-value, unregistered-version, and rewritten-version failures but never flips a bit inside the ciphertext body or decrypts under a wrong key at the same version, so integrity over the ciphertext rests on the primitive rather than on a test. And the searchability constraint stands: the Identity User stores Email as a queried column (see IdentityModuleDbSeederBase<TUser>, whose existence check is an EF predicate on that column), so encrypting it with this converter would silently break that lookup rather than fail loudly.

IDbSeeder

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DbContexts.Seeding · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Seeding/IDbSeeder.cs:7 · Level 0 · interface

• What it is: the one-method contract for an Infrastructure-layer seeder, Task SeedAsync(CancellationToken) (IDbSeeder.cs:13). Implementations populate a module's tables with initial reference data at startup (IDbSeeder.cs:3-5).
• Depends on: nothing but the BCL Task and CancellationToken.
• Concept introduced, two seeding contracts at two layers. [Rubric §3, Clean Architecture] (assesses whether each concern sits in the layer that owns it, with dependencies pointing inward): the framework has two seeding interfaces and they are not competitors. IModuleSeeder lives in Application, takes an IServiceProvider, and is the unit ModuleLoader knows about; IDbSeeder lives in Infrastructure, takes nothing, and is the unit that actually writes rows. The apps compose them: the module seeder reads configuration, resolves what it needs, and calls the database seeder (MMCA.ADC/Source/Modules/Identity/MMCA.ADC.Identity.API/IdentityModuleSeeder.cs:33-36). That keeps the configuration gate in the layer that can see IConfiguration and the row writing in the layer that can see the unit of work.
• Walkthrough: a single member. There is no IsEnabled, no ordering property, and no result type: a seeder either runs to completion or throws, and ordering comes from the caller.
• Why it's built this way: keeping the Infrastructure contract this thin is what lets the same seeder be invoked from a module seeder, from a test, or by hand, without dragging a service provider along.
• Where it's used: implemented once in the framework, by the abstract DbSeeder (DbSeeder.cs:7); every concrete seeder in the apps derives from that class rather than from this interface directly.
• Caveats / not-in-source: nothing registers IDbSeeder in DI and nothing resolves it. Concrete seeders are constructed with new inside their module's IModuleSeeder (for example IdentityModuleSeeder.cs:35-36), which ModuleLoader runs through SeedAllAsync at startup, after schema initialization (MMCA.Common/Source/Presentation/MMCA.Common.API/Startup/DatabaseInitializationExtensions.cs:111). There is no reflection-based discovery of IDbSeeder and no hosted service that drains a list of them.

SeedAccount

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DbContexts.Seeding · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Seeding/SeedAccount.cs:17 · Level 0 · record (sealed)

• What it is: the five-member positional record describing one development or test account for IdentityModuleDbSeederBase<TUser> to create: (string Email, string Password, string Role, string? FirstName = null, string? LastName = null) (SeedAccount.cs:17-22).
• Depends on: nothing. It is a pure data carrier with no framework types in its signature, which is what lets each app spell its own role vocabulary as a plain string.
• Concept introduced: none new. It is the parameter object of the template-method seeder taught in IdentityModuleDbSeederBase<TUser>; [Rubric §11, Security] applies only through the notice below.
• Walkthrough: the doc comments carry the contract for each member. Email is also the idempotency key, the value the "already seeded?" check compares against (:12). Password is plaintext and is hashed by the seeder before persistence (:13). Role is the role as the app's own vocabulary spells it (:14), so ADC passes UserRole.Organizer.Value and Store passes its own admin role without the framework knowing either. FirstName and LastName are nullable because not every app's User carries them (:15-16).
• Why it's built this way: a record rather than a tuple gives the five values names at every call site, and positional construction keeps an account list readable as a literal array (see the app lists cited below).
• Where it's used: the abstract Accounts property of IdentityModuleDbSeederBase<TUser> (IdentityModuleDbSeederBase.cs:51); supplied by ADC's IdentityModuleDbSeeder as three accounts (MMCA.ADC/Source/Modules/Identity/MMCA.ADC.Identity.Infrastructure/Persistence/DbContexts/Seeding/IdentityModuleDbSeeder.cs:34-39) and by Store's through a StoreAccounts array (MMCA.Store/Source/Modules/Identity/MMCA.Store.Identity.Infrastructure/Persistence/DbContexts/Seeding/IdentityModuleDbSeeder.cs:27, :34).
• Caveats / not-in-source: the record's own remarks (SeedAccount.cs:6-11) call the security property out: seed credentials are plaintext by construction, so an account list is development-only data that must be gated or replaced with environment-sourced secrets before a seeder runs in a deployed environment. Both apps' lists contain deliberately weak passwords.

DbSeeder

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.DbContexts.Seeding · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Seeding/DbSeeder.cs:7 · Level 1 · class (abstract)

• What it is: the abstract base every concrete database seeder derives from. It implements IDbSeeder by re-declaring SeedAsync as abstract (DbSeeder.cs:10) and adds exactly one piece of shared machinery: a converter from an int seed id to whatever identifier type the module uses (DbSeeder.cs:3-5).
• Depends on: IDbSeeder, plus the BCL Guid, BitConverter, and Span<byte>.
• Concept introduced, seed data across two identifier strategies. [Rubric §15, Best Practices & Code Quality] (assesses whether shared mechanics live in one place rather than being restated per module): the identifier-type alias taught in the primer means one module's key is int and another's is Guid (ADC's SpeakerIdentifierType is a Guid, its UserIdentifierType is an int). Seed data, however, is naturally written with small readable literals: category 1, room 2. GetId<T>(int) is the bridge, so a seeder can write GetId<SpeakerIdentifierType>(3) and stay correct whichever alias the module picked.
• Walkthrough:
  • SeedAsync (DbSeeder.cs:10): abstract, public, no default behavior. The base deliberately does not template the seeding flow itself; that is IdentityModuleDbSeederBase<TUser>'s job for the one flow that repeated across apps.
  • GetId<TIdentifier>(int id) (DbSeeder.cs:20-39): protected static, constrained to notnull. For Guid it writes the int's four bytes into the start of a zeroed 16-byte stackalloc span and constructs a Guid from it (:23-31), which is deterministic: the same seed integer always produces the same Guid, so re-running a seeder against an existing database matches the rows it wrote last time. For int it is a boxed pass-through (:33-36). Anything else throws NotSupportedException naming the type (:38).
• Why it's built this way: protected static keeps the helper out of the public surface (a seeder is not a general-purpose id converter) while still allowing every derived seeder to use it without an instance. Determinism, not uniqueness, is the property that matters: seeders must be idempotent across restarts, which is what production hosts rely on when they run the seeder on every boot (MMCA.Common/Source/Presentation/MMCA.Common.API/Startup/DatabaseInitializationExtensions.cs:111).
• Where it's used: the base of every module seeder in both apps, for example ADC's ConferenceModuleDbSeeder (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.Infrastructure/Persistence/DbContexts/Seeding/ConferenceModuleDbSeeder.cs:24), Store's CatalogModuleDbSeeder (MMCA.Store/Source/Modules/Catalog/MMCA.Store.Catalog.Infrastructure/Persistence/DbContexts/Seeding/CatalogModuleDbSeeder.cs:15) and SalesModuleDbSeeder (MMCA.Store/Source/Modules/Sales/MMCA.Store.Sales.Infrastructure/Persistence/DbContexts/Seeding/SalesModuleDbSeeder.cs:27), and the framework's own IdentityModuleDbSeederBase<TUser> (IdentityModuleDbSeederBase.cs:39-42). Pinned by DbSeederTests (MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/DbContexts/Seeding/DbSeederTests.cs:6, :9, :17, :27, :36, :45), which assert the int pass-through, Guid determinism, distinctness across different ints, the unsupported-type throw, and that SeedAsync can be implemented.
• Caveats / not-in-source: the Guid mapping consumes only the first four of sixteen bytes, so the produced values are structurally recognizable rather than random. That is intentional for seed data and is not a source of production ids: entity ids come from the database or from CosmosIntIdValueGenerator.

AggregateCapture

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.Interceptors · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Interceptors/DomainEventSaveChangesInterceptor.cs:373 · Level 2 · record (private sealed, nested)

• What it is: a two-field pairing of one tracked aggregate root and the exact array of domain events snapshotted from it for the current save (DomainEventSaveChangesInterceptor.cs:370-375).
• Depends on: EF Core's EntityEntry<IAggregateRoot> and IDomainEvent via IAggregateRoot.
• Concept introduced, snapshot-then-remove instead of clear. The naive move after dispatching events is entity.ClearDomainEvents(). That is wrong here, and this record is the fix. An in-process handler running during dispatch can raise a new event on the same aggregate; a wholesale clear would wipe that new event before any later capture could see it, so it would never dispatch and never reach the outbox. Holding the exact snapshot lets the interceptor remove precisely what it captured and leave everything else in place (DomainEventSaveChangesInterceptor.cs:355-365).
• Walkthrough:
  • Entry (:373): the EntityEntry<IAggregateRoot>, not the bare entity. Keeping the entry means the record still has EF's view of the aggregate available if the flush path ever needs it, and capture.Entry.Entity reaches the aggregate itself (:363).
  • Events (:374): an IDomainEvent[] materialized with a collection expression at capture time (:223, [.. e.Entity.DomainEvents]), which is what makes it a snapshot rather than a live view of the aggregate's mutable list.
• Why it's built this way: a positional record gives value semantics and an immutable pair for free, and private sealed keeps it invisible outside the interceptor. It is data, not behavior: the only method that touches it is ClearDomainEvents, which calls capture.Entry.Entity.RemoveDomainEvents(capture.Events) on each (:362-363, against the contract member at MMCA.Common/Source/Core/MMCA.Common.Domain/Interfaces/IAggregateRoot.cs:32).
• Where it's used: constructed once per event-carrying aggregate in CaptureEventsAndPersistToOutbox (:220-224), stored inside CapturedState (:382), and consumed by ClearDomainEvents (:360-364).

CapturedState

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.Interceptors · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Interceptors/DomainEventSaveChangesInterceptor.cs:382 · Level 10 · record (private sealed, nested)

• What it is: the whole of what DomainEventSaveChangesInterceptor learns before a save and needs again after it: which aggregates it captured, which events it will dispatch in process, which outbox rows back those events, and whether any integration events are in the batch (DomainEventSaveChangesInterceptor.cs:377-386).
• Depends on: AggregateCapture, IDomainEvent, OutboxMessage.
• Concept introduced, why per-save state cannot live in a field. The interceptor is registered as a singleton (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:71), and one singleton serves every context in every scope concurrently. Anything it remembers between SavingChanges and SavedChanges therefore has to be keyed by the context, not stored on the instance. That is exactly what this record is: the value side of a ConditionalWeakTable<DbContext, CapturedState> (:61). [Rubric §12, Performance and Scalability] assesses whether shared components stay safe and cheap under concurrency; the weak table adds no lock and no lifetime bookkeeping, because an entry disappears when its context is collected.
• Walkthrough (all four members are positional and immutable):
  • Captures (:382): the AggregateCapture[], used only to remove exactly the captured events afterwards.
  • LocalEvents (:383): the events that get in-process dispatch. On a context that writes outbox rows this deliberately excludes every IIntegrationEvent (:248-256); on a context without outbox support, or in a host that turned the outbox off, it is simply every captured event (:266).
  • LocalOutboxEntries (:384): the List<OutboxMessage> rows backing LocalEvents, in the same order they were added. After a successful dispatch these are the rows stamped processed (:333).
  • HasIntegrationEvents (:385): a bool rather than a second list, because integration events are never dispatched here. The only thing the flush needs to know is whether to wake the outbox processor (:335-336).
• Why it's built this way: splitting local events from integration events at capture time, and recording the split in this one value, is what makes AddDomainEvent(integrationEvent) broker-correct (ADR-003). Before this routing existed, an integration event was dispatched locally and its row marked processed, so it silently never reached the wire (:19-24).
• Where it's used: created at the end of CaptureEventsAndPersistToOutbox (:269-270), read by DispatchAndFinalizeAsync (:303), carried across a commit boundary inside DeferredDispatch (:313), consumed by FlushStateAsync (:324-352), and read on the synchronous path by SavedChanges (:127-133).

AuditSaveChangesInterceptor

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.Interceptors · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Interceptors/AuditSaveChangesInterceptor.cs:22 · Level 11 · class (sealed)

• What it is: the EF Core interceptor that stamps CreatedOn/CreatedBy, LastModifiedOn/LastModifiedBy and DeletedOn/DeletedBy on every IAuditableEntity entry immediately before the write (AuditSaveChangesInterceptor.cs:9-20). It is the first of the interceptors the framework installs and the reason no handler anywhere in ADC or Store sets an audit field by hand.
• Depends on: ApplicationDbContext (for CurrentSaveUserId and the change tracker), IAuditableEntity, and the BCL TimeProvider, injected through the primary constructor (:22).
• Concept introduced, the EF SaveChangesInterceptor as the cross-cutting hook of the persistence layer. [Rubric §13, Observability & Operability] assesses whether audit, correlation and logging are wired once centrally rather than repeated per handler. An EF SaveChangesInterceptor is a hook EF calls at fixed points of the save pipeline: SavingChanges/SavingChangesAsync before the write and SavedChanges/SavedChangesAsync after it. Choosing an interceptor over an override of SaveChangesAsync buys three things: the logic runs on the synchronous and asynchronous paths alike, several interceptors compose in a defined order rather than fighting over one method body, and the concern lives in one class the module authors never see. [Rubric §8, Data Architecture] is engaged too, because "every row knows who wrote it and when" is a schema-level guarantee here, not a convention.
• Concept introduced, stamping a transition rather than a value. The soft-delete stamps are not driven by what IsDeleted is but by whether it changed during this save (:14-18). That distinction is what makes the delete stamp behave like the creation stamp: it is written once, by the save that flipped the flag, and every later update of the same already-deleted row leaves it untouched. Reading the flag's value instead would rewrite DeletedOn on every subsequent write to a deleted row, which destroys the one fact the column exists to record.
• Walkthrough:
  • SavingChangesAsync (:25-34) and SavingChanges (:37-45): identical two-line bodies. Each pattern-matches eventData.Context against ApplicationDbContext, calls StampAuditFields, then delegates to base. The type test is the guard: a context that is not the framework's own is left completely alone.
  • StampAuditFields (:47-81): reads the clock once per save via timeProvider.GetUtcNow().UtcDateTime (:49) so every row in one save carries the same instant, and resolves the user once as context.CurrentSaveUserId ?? default (:50). CurrentSaveUserId is the nullable user id the context was handed for this save (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/ApplicationDbContext.cs:143, set at :156 and :191), so default is the sentinel for a system-originated write with no user behind it.
  • The Added branch (:56-65): sets all four creation and modification properties through entry.Property(nameof(...)).CurrentValue, going through the change tracker rather than the CLR setters so the fields can stay init-only or privately settable on the entity, then calls StampSoftDeleteTransition with wasDeleted: false. A brand new row has no prior state, so an entity inserted already soft-deleted still gets its delete stamp (:62-64).
  • The Modified branch (:66-73): the interesting one. It sets LastModifiedBy/ LastModifiedOn, and explicitly marks CreatedBy and CreatedOn as IsModified = false (:67-68). That is the invariant: an update can never rewrite creation provenance, even if the caller mutated those properties on a tracked instance. It then runs the same soft-delete transition check, this time against the flag's stored value (:72).
  • Detached, Unchanged, Deleted and the default (:74-78): deliberate no-ops. Note what Deleted means here: a hard delete, which the framework does not use for auditable entities. A soft delete arrives as Modified, because the entity only set a flag (see ADR-005 for soft delete versus erasure).
  • WasDeleted (:84-85): the flag as the database has it, read from the property's OriginalValue. The is true test rather than a cast is what keeps an unset or shadow value from throwing.
  • StampSoftDeleteTransition (:92-106): compares the current flag against the prior one and returns immediately when they agree (:98-102), so no transition means no write at all. On a transition it writes both stamps in one direction: the resolved user and the save's instant on a delete, and null on both columns on an undelete (:104-105).
• Why it's built this way: taking TimeProvider instead of calling DateTime.UtcNow makes the stamps deterministic under test ([Rubric §14, Testability]), which is what AuditSaveChangesInterceptorTests relies on (MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/Interceptors/AuditSaveChangesInterceptorTests.cs:13, with the four soft-delete transitions pinned at :128 (delete stamps written), :144 (an update after a delete keeps the original stamp), :165 (undelete clears both), :186 (an active entity keeps them null) and :195 (an insert that is already deleted is stamped)). The class is registered as a singleton because it holds no per-save state at all (DependencyInjection.cs:68-70), unlike its neighbours.
• Where it's used: resolved from DI and attached in ApplicationDbContext.OnConfiguring (ApplicationDbContext.cs:256, added at :266 or :270). It is always first in the interceptor chain, which is what lets TenantSaveChangesInterceptor, the domain-event interceptor and the optional AuditTrailSaveChangesInterceptor assume the audit stamps are already final when they run (ApplicationDbContext.cs:259-263, :273-277).

DeferredDispatch

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.Interceptors · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Interceptors/DomainEventSaveChangesInterceptor.cs:389 · Level 11 · record (private sealed, nested)

• What it is: one unit of post-commit work: a CapturedState plus the interceptor instance that captured it (DomainEventSaveChangesInterceptor.cs:388-389).
• Depends on: DomainEventSaveChangesInterceptor and CapturedState.
• Concept introduced, carrying the owner so a static entry point can flush. DbContextFactory is the type that knows when a transaction committed, so it is the type that must trigger the deferred dispatch. It calls a static method, DomainEventSaveChangesInterceptor.FlushDeferredAsync (:144), rather than resolving the interceptor from DI: the factory therefore has no constructor dependency on the interceptor, which keeps the persistence graph acyclic. But a flush needs the instance (the dispatcher and logger it was constructed with), so each queued item carries its own owner and the static entry point simply calls back through it: dispatch.Owner.FlushStateAsync(...) (:152).
• Walkthrough:
  • Owner (:388): the interceptor instance that produced the state. In a normal host this is the one singleton, but the record does not assume that.
  • State (:388): the captured state to flush.
  • Instances live in a second weak table, ConditionalWeakTable<DbContext, List<DeferredDispatch>> (:68), so a context can accumulate several deferrals when a transactional command saves more than once (:313, via DeferredTable.GetOrCreateValue(context).Add(...)).
• Why it's built this way: the ordering rule it implements is that in-process handlers must never act on state that could still roll back. Email, cache writes and pushes issued from a handler are not transactional, so dispatching them before the commit would leave real side effects behind an aborted transaction, and an execution-strategy retry would repeat them once per attempt (:26-33). See ADR-003 and the Transactional decorator of ADR-014.
• Where it's used: enqueued by DispatchAndFinalizeAsync when context.Database.CurrentTransaction is not null (:308-314); drained by FlushDeferredAsync after a successful commit (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Factory/DbContextFactory.cs:582); discarded wholesale by DropDeferred on every rollback path (DbContextFactory.cs:448, :599, :668, :746).

DomainEventSaveChangesInterceptor

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.Interceptors · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Interceptors/DomainEventSaveChangesInterceptor.cs:46 · Level 11 · class (sealed, partial)

• What it is: the interceptor that turns domain events into durable messages. Before the write it captures every pending event off the tracked aggregate roots and adds an OutboxMessage row for each, so events commit in the same transaction as the data. After the write it routes them: local events are dispatched in-process and their rows stamped processed, while integration events are left unprocessed for the OutboxProcessor to publish (DomainEventSaveChangesInterceptor.cs:13-35).
• Depends on: IDomainEventDispatcher, IOutboxSignal, ILogger<T>, a TimeProvider and an optional MessageBusSettings options object, all through the primary constructor (:46-51); ApplicationDbContext, IAggregateRoot, IDomainEvent, IIntegrationEvent, OutboxMessage, and OutboxFinalizer (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Outbox/Processing/OutboxFinalizer.cs:12). BCL: ConditionalWeakTable, ReferenceEqualityComparer.
• Concept introduced, the dual-dispatch outbox (ADR-003) and its two failure modes. [Rubric §6, CQRS and Event-Driven] assesses whether events are delivered reliably rather than optimistically, and [Rubric §29, Resilience and Business Continuity] assesses whether a crash at any point leaves the system recoverable. The mechanism has three moves. One, persistence: every captured event becomes an outbox row added to the same DbContext before base.SaveChangesAsync runs, so the row and the aggregate change commit or fail together and no crash can lose an event that the data implies happened. Two, the in-process fast path: after the write, local events go straight to the dispatcher and their rows are stamped processed, so the background processor finds nothing to do. Three, the fallback: if that dispatch throws, the rows stay unprocessed and outboxSignal.Signal() wakes the processor to retry. The routing split is what makes the pattern correct for extracted services: an integration event never takes the fast path, because in-process delivery would mark it processed and it would never reach the broker (:20-25).
• Concept introduced, the outbox is a posture, not a constant. The interceptor reads IsOutboxEnabled off the injected message-bus options once, into the _outboxEnabled field (:55), and that field is passed into every capture (:86, :97). The resolved posture is the explicit MessageBus:EnableOutbox value when a host sets one, and otherwise "on for any transport other than in-process" (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Messaging/MessageBusSettings.cs:159), so a monolith running the in-process bus writes no outbox rows at all and dispatches everything directly, while a host on a broker keeps the durable path. A host that resolves no options at all keeps the outbox (:42-45, :55). This is why the type has two behavioral axes rather than one: context.SupportsOutbox (does this engine have the table) and _outboxEnabled (does this host want it), and both must be true to take the durable branch (:236).
• Walkthrough (this is the densest type in the group; read it as capture, then route, then defer):
  • Two instance fields and three static weak tables (:53, :55, :62, :69, :77). The fields are the clock (defaulting to TimeProvider.System, so an existing host keeps the old constructor shape while a test can drive the ProcessedOn stamp) and the resolved outbox posture. StateTable holds the CapturedState between saving and saved; DeferredTable holds the DeferredDispatch list for a context inside a transaction; CaptureExclusionTable holds the aggregate instances a save must skip. ConditionalWeakTable is chosen throughout so the interceptor can stay a singleton without ever keeping a context alive or needing cleanup code (:57-61).
  • SavingChangesAsync / SavingChanges (:80-89, :92-100): both call CaptureEventsAndPersistToOutbox for an ApplicationDbContext, then delegate to base. Capture is synchronous by necessity: the outbox rows must be in the change tracker before EF generates the SQL.
  • CaptureEventsAndPersistToOutbox (:207-272), the heart of the type:
    • It first calls DiscardAbandonedCapture (:213, defined at :279-296). A previous SavingChanges that never reached SavedChanges (a failed save, then an execution-strategy retry) left its outbox rows tracked as Added. Re-capturing on top would write a second row per event and publish everything twice, so every Added OutboxMessage on the context is detached first. The comment justifies the blanket detach: this interceptor is the only writer of outbox rows, and a completed save leaves none Added (:286-289).
    • It reads the exclusion set (:219) and projects the tracked aggregate roots that have events and are not excluded into AggregateCapture values (:221-225), taking a snapshot copy of each event list, and returns early when nothing carried an event (:227-228).
    • When context.SupportsOutbox and _outboxEnabled are both true (:236), it walks the flattened event list once (:242-258): every event gets OutboxMessage.FromDomainEvent and is added to the outbox set, then the event is sorted. An IIntegrationEvent only flips hasIntegrationEvents; anything else joins both locals and localOutboxEntries. The Add call carries a targeted VSTHRD103 suppression (:245-247) because EF's DbSet.Add is intentionally synchronous.
    • Otherwise, when the context has no outbox table (Cosmos being the example named in the comment) or the host turned the outbox off, every event is treated as local (:262-268): nothing could carry it to a processor anyway, and for the in-process transport that is the whole delivery path rather than a degradation.
    • Finally it stores the CapturedState under the context (:270-271).
  • SavedChangesAsync (:103-112) calls DispatchAndFinalizeAsync (:302-319), which pulls the state, removes it from the table, and then forks. With an active transaction it clears the captured events now (so a second save in the same transaction cannot re-capture them) and queues a DeferredDispatch (:309-315). Without one it flushes immediately (:318).
  • FlushStateAsync (:325-353): dispatches LocalEvents if any (:329-330), clears the captured events (:332), stamps the local rows processed through OutboxFinalizer.MarkProcessedAsync (:334, a single set-based ExecuteUpdate plus a tracker sync rather than a nested save, OutboxFinalizer.cs:26-30, :38-41, :43-50), and signals the outbox when integration events are present (:336-337). The catch logs through the source-generated LogDispatchError (:367-368) and signals the processor so the unprocessed rows get retried (:339-347); the finally clears the events again, idempotently (:348-352).
  • SavedChanges, the synchronous path (:124-138): it cannot await the dispatcher, so it does not try. For a host with the outbox on and an outbox-capable context it removes the state, clears the captured events (which is what stops a later async save from re-capturing and duplicating them) and signals the processor, leaving delivery entirely to the outbox. A context without outbox support, and a host running with the outbox off, keep the legacy no-op, because with no rows written there is nothing for a processor to pick up and clearing the events here would lose them outright (:115-123).
  • ClearDomainEvents (:361-365): removes exactly the captured events via RemoveDomainEvents, never a wholesale clear, for the reason AggregateCapture exists.
  • FlushDeferredAsync / DropDeferred (:145-154, :162): the two internal static entry points DbContextFactory calls at commit and at rollback. A missed flush is explicitly safe: the rows stay unprocessed and the outbox delivers them (:140-144).
  • BeginCaptureExclusion / EndCaptureExclusion (:179-188, :195): the narrow hook for IDENTITY_INSERT batching. DbContextFactory splits a save into one round per identity table and temporarily marks the other tables' entries Unchanged (DbContextFactory.cs:301-317); those rows are not written this round, so capturing their events now would persist and clear an event ahead of the insert that justifies it. The exclusion set is built with ReferenceEqualityComparer.Instance (:187) and cleared in a finally (DbContextFactory.cs:341-347). The remarks explain why exclusion is by instance and not by entity state (:172-176): skipping every Unchanged aggregate would also drop events raised on an already-saved aggregate, which is how the identity module publishes its registration events.
• Why it's built this way: ADR-003 specifies at-least-once delivery, with the in-process path as an optimization and the outbox as the guarantee. Deferring past the commit is ADR-014's Transactional decorator honored at the persistence layer: business failures roll back, and a rolled-back save must deliver nothing. The type is partial for the source-generated [LoggerMessage] (:367-368), and singleton-safe because every piece of per-save state lives in a weak table keyed by context.
• Where it's used: registered as a singleton (DependencyInjection.cs:71), attached last of the save-time trio in ApplicationDbContext.OnConfiguring (ApplicationDbContext.cs:257, :266, :270) so it sees final audit stamps and final tenant values; driven at transaction boundaries by DbContextFactory. Pinned by DomainEventSaveChangesInterceptorTests (MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/Interceptors/DomainEventSaveChangesInterceptorTests.cs:17), DomainEventSaveChangesInterceptorOutboxRoutingTests (.../DomainEventSaveChangesInterceptorOutboxRoutingTests.cs:27), DomainEventSaveChangesInterceptorOutboxDisabledTests (.../DomainEventSaveChangesInterceptorOutboxDisabledTests.cs:21) and DomainEventCaptureExclusionTests (.../DomainEventCaptureExclusionTests.cs:26).
• Caveats / not-in-source: DiscardAbandonedCapture detaches every Added OutboxMessage on the context, which is correct only while this interceptor remains the sole writer of outbox rows. That is true in the current source, and the comment states the assumption (:286-289), but it is an invariant a future outbox writer would have to respect.