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, PostgreSQLDbContext, CosmosDbContext, SqliteDbContext) and a stateless engine registry (IDataSourceEngine, DataSourceEngines) that answers every engine-specific question as data; 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 durable job queue (InternalCommandMessage, InternalCommandScheduler, InternalCommandProcessor) that commits a unit of deferred work in the same transaction as the change that asked for it; 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; three model-finalizing conventions that keep that routing, its unique indexes and its delete behavior 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, InternalCommandsSettings) 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:46) 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:454-468, name at :475); it applies a second named "Tenant" filter to every non-owned ITenantEntity (ApplicationDbContext.cs:515-575); it configures the RowVersion optimistic-concurrency token by the engine's RowVersionStrategy, mapped as a SQL Server rowversion or as a plain token the audit interceptor stamps on PostgreSQL and SQLite (ApplicationDbContext.cs:577-608, strategy read at :592); and it maps the framework's own bookkeeping tables so every relational database carries its own (OutboxMessage (indexes at :695-714), InboxMessage (indexes at :730-735), InternalCommandMessage at :753, ScheduledJobEntry at :818, AuditTrailEntry at :855), each with the filtered indexes its poll path and its retention sweep need (IX_OutboxMessages_Pending at :695, IX_OutboxMessages_Processed at :702, the keyed-ordering index IX_OutboxMessages_Ordering at :714, IX_InboxMessages_MessageId at :730, IX_InboxMessages_ProcessedOn at :735, IX_InternalCommands_Pending at :780, IX_InternalCommands_Processed at :787, IX_InternalCommands_DeadLettered at :792, IX_ScheduledJobs_NextRunOn at :837, IX_AuditTrailEntries_Entity at :869, IX_AuditTrailEntries_ChangedOn at :875). Four of the seven 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, :327-329), 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, :332), the refresh-session table only when RefreshSessions:Enabled is set AND this context targets the source that setting names (:336-339, applied at :893), and the permission-grant table only when the host called AddStoredPermissionGrants AND this context targets the source Authentication:PermissionGrants:DataSourceName names (:343, resolved at :915-918, applied at :937). That fourth gate has no configuration flag of its own: the DI call itself is the opt-in, expressed as the marker type PermissionGrantModelGate (.../Persistence/Auth/PermissionGrantModelGate.cs:19, reasoning at :6-12). 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 outbox, the inbox and the internal-command queue are deliberately not gated: they are mapped into every relational source whether or not this host drains them, so flipping InternalCommands:Enabled is never a migration (:738-753).

Its SaveChangesAsync(userId, ...) overload (ApplicationDbContext.cs:194-208) 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 (:197, :206). 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 (:212-218, :245-249, helper at :274): 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 when the scope is disposed (:274).

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:34-40). 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:350). This is deliberately not a per-module context split: one sealed context per engine over the abstract base is ADR-006's ruling. Each instance also exposes the engine it targets as an internal Engine property resolved through DataSourceEngines (ApplicationDbContext.cs:61), which is how the base, the interceptors and the factory ask an engine question without naming an engine. 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, :63-66), and a suppressed PendingModelChangesWarning (:79) 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 (:68-78). 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 (:60-62). SqliteDbContext (.../DbContexts/SqliteDbContext.cs:12) is the same shape with UseSqlite and its own migrations assembly (:24-33), and CosmosDbContext (.../DbContexts/CosmosDbContext.cs:15) 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 (:139-145). PostgreSQLDbContext (.../DbContexts/PostgreSQLDbContext.cs:23) is the fourth engine class (ADR-113), and its mapping conventions deliberately match SQLServerDbContext rather than PostgreSQL house style: PascalCase identifiers and the module schema, so an entity configuration body is portable between the two engines with no edits, and a consumer that wants snake_case adds a naming plugin in its own host (:15-21). It maps every DateTime to timestamp with time zone (:34) through UtcDateTimeConverter (.../Persistence/Conversions/UtcDateTimeConverter.cs:25), because Npgsql refuses to write a value whose Kind is not Utc and a consumer property, a JSON round-trip or a legacy row can arrive Unspecified; the process-wide Npgsql.EnableLegacyTimestampBehavior switch is rejected precisely because it changes the mapping for connections the framework does not own and stores timestamps without a zone (:5-24). One more base-context decision belongs here: SensitiveDataLoggingGate (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/SensitiveDataLoggingGate.cs:24) decides whether EF may render parameter values into logs and exception messages, and the answer is an AND rather than a single switch: the host must both ask for it and report itself as Development (ApplicationDbContext.cs:345, :367-371). A null IHostEnvironment, which is what design-time tooling and a directly-constructed test context have, counts as not Development, so unknown fails closed (SensitiveDataLoggingGate.cs:10-22). That is [Rubric §11, Security] in one helper.

SaveChanges as an interceptor pipeline

The base context resolves its interceptors from DI in OnConfiguring (ApplicationDbContext.cs:290-322), 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, :300-312), and the change-trail interceptor last, because it diffs the final values (:314-322). 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:38) runs on SavingChanges: it walks every tracked IAuditableEntity, stamps CreatedOn/By plus LastModifiedOn/By on Added (:79-83), and on Modified marks the two Created* properties unmodified before re-stamping LastModified* (:90-94), reading the timestamp from an injected TimeProvider and the user id from CurrentSaveUserId (falling back to default as the system-operation sentinel, :65-66). An owner whose only edit is to an owned value object (an OwnsOne address, an OwnsMoney price) is still Unchanged to EF, because the change is tracked on the owned entry, so the interceptor asks OwnedDependents.HaveChanges and stamps that owner as Modified (:71-75). That helper (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Interceptors/OwnedDependents.cs:12, HaveChanges at :24-26) walks the owner's owned references and owned collection items for an entry being inserted, updated or deleted, and its remarks name the one blind spot: an optional owned reference set to null leaves no entry to read, so clearing one is not detected (:18-21). 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 (StampSoftDeleteTransition, doc at :125-129, with the original value read by WasDeleted at :122-123), 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. On an engine whose RowVersionStrategy is ClientStamped (PostgreSQL, SQLite) it also writes a fresh RowVersion on every insert and update, so the UPDATE's WHERE clause detects a concurrent writer where no server-generated row version exists (:67, :88, :97, StampRowVersion at :113-119). 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:54) 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 (:242-246, record at :445), 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 (:228-302). 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 (:274-283). On the async path that local row is inserted already leased: NewLocalLease builds a LocalLease record struct (:465) of now plus Outbox:LeaseSeconds under a fresh token (:315-316, the seconds read once into a field at :66), and ApplyLocalLease writes it onto the row's LockedUntil and LockToken (:305-312). No replica's poller can therefore deliver the event a second time while this process is still dispatching it, a crash leaves the row to be retried once the lease expires, and a failed dispatch hands it back early (:18-23). Only the async path leases, because only it dispatches in-process (:96-98). Before capturing, DiscardAbandonedCapture detaches the Added outbox rows left by a previous SavingChanges that never reached SavedChanges (:323-340), which is what stops an execution-strategy retry from writing a second row per event and publishing every integration event twice. The captured state, including the lease token its local rows were written under, is parked in a CapturedState record (:455-460) held in a ConditionalWeakTable keyed by context (:73), so it is cleaned up automatically when the context is disposed. A third weak table (:88) holds a per-context capture exclusion set: BeginCaptureExclusion / EndCaptureExclusion (:194, :210) let DbContextFactory name exactly the entries it hides from an explicit-key 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 (:187-191).

After the save, the post-save path DispatchAndFinalizeAsync (DomainEventSaveChangesInterceptor.cs:346-363, reached from SavedChangesAsync at :117-126) does one of two things. With no ambient transaction it flushes immediately through FlushStateAsync (:369-400): 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 (:373-381). 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 (:468) in a second weak table (:80, parked at :353-359); DbContextFactory then calls the static FlushDeferredAsync only after a successful commit (:154-170) and DropDeferred on rollback (:177). 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 (:424-434), 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, releases the lease its local rows were inserted under through ReleaseLocalLeaseAsync (guarded by the save's lease token and run with CancellationToken.None, so a dispatch that failed by cancellation still hands its rows back, :402-422), and signals the outbox, so the processor retries from the persisted rows after the processing delay rather than after the full lease (:383-394). A failed release is itself only logged, and the rows then wait out the lease (:418-421, :439-440). 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 (:128-152). Two conditions take the everything-in-process branch instead: Cosmos DB has no relational outbox table, so the interceptor asks the context's engine whether it is relational (DataSourceEngineCapabilities.IsRelational, read at :141 and :257), which is false only for CosmosDbContext's engine; and a host can turn the outbox off outright, which the interceptor reads once from the message-bus options into _outboxEnabled (:64) and honors at the same branch (:257, :292-298). 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.

Deferred work, the internal-command queue

The same "write it in the transaction, run it afterwards" reasoning the outbox applies to events is applied to work by the internal-command queue (ADR-114). InternalCommandMessage (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/InternalCommands/InternalCommandMessage.cs:21) is one unit of deferred work persisted to the InternalCommands table, and its doc comment states the kinship plainly: like OutboxMessage it is framework bookkeeping rather than domain state, so it is deliberately not an IAuditableEntity, carries no soft-delete flag (no global query filter applies to it), no audit stamps and no concurrency token; its concurrency control is an explicit claim lease (:9-19). InternalCommandScheduler (.../InternalCommands/InternalCommandScheduler.cs:36) writes that row on the same scoped IDbContextFactory the calling handler's repositories use, which is the whole atomicity story: inside an ITransactional command the factory has already begun a transaction on every context it hands out, so the row commits with the aggregate change or rolls back with it, and outside a transaction the row is saved immediately and the processor is signalled (:19-25, :118-125). An enrolled row cannot signal at enrollment, because nothing can read it until the commit, so the scheduler records the wake it owes in EnrolledCommandWake (.../InternalCommands/EnrolledCommandWake.cs:14, Defer called at InternalCommandScheduler.cs:113), a static class over a ConditionalWeakTable keyed weakly on the context, like the deferred domain-event dispatch (EnrolledCommandWake.cs:7-16). The unit of work that owns the transaction calls Release once every commit has succeeded, which signals each distinct processor wake exactly once however many rows or contexts enrolled (:24-49), and Drop on rollback or retry (:51-53), so a rolled-back row never wakes the processor and a context nobody commits leaves nothing behind. Each row also carries an InternalCommandOrigin (.../InternalCommands/InternalCommandOrigin.cs:16): the scheduling user, roles, tenant, correlation id and trace context, because without it a deferred command would run as an anonymous tenant-less system call, which is both an authorization hole (an IRequiresPermission command would be denied) and an audit hole (its writes would carry the system sentinel, :1-9). The snapshot is taken by the scoped InternalCommandOriginCapture (.../InternalCommands/InternalCommandOriginCapture.cs:21, Capture at :28-39), which the scheduler calls as it builds the row (InternalCommandScheduler.cs:40, :88). It is scoped like the request services it reads, because the snapshot must describe this request's caller, and it flattens roles through the same helper the outbox capture uses, so the two hops store one shape (InternalCommandOriginCapture.cs:13-17).

InternalCommandProcessor (.../InternalCommands/Processing/InternalCommandProcessor.cs:43) is the drain: a background service that claims due rows with a lease, executes each in a fresh DI scope, and records the outcome. Every relational physical source this host uses has its own queue table and each cycle drains them all, so a service only ever runs the work queued in its own databases, and the lease is what makes scale-out safe, since two replicas racing for a row issue the same conditional update and exactly one matches (:20-35). Execution is explicitly at-least-once: a replica that dies after its handler committed and before the row was stamped releases the row when the lease expires and the command runs again, which is the same idempotency contract the outbox already places on event handlers (:30-34). The batch claim is renewed row by row just before each command runs, in a statement guarded on the claim token, so a slow batch cannot outlive its lease and let another replica start a later row, and a row another replica has taken over is skipped rather than run twice (:197-208, RenewClaimAsync doc at :329-333). Execution itself goes through InternalCommandDispatcher (.../Processing/InternalCommandDispatcher.cs:21), and the load-bearing detail is that it resolves the closed ICommandHandler<TCommand, Result> interface: Scrutor's decorators are registered against the open generic, so what comes back is already wrapped in the feature gate, the authorization check, logging, cache invalidation, validation, the timeout budget and the transaction. A deferred execution is therefore the same execution a controller would have got, not a parallel path that re-implements any of it (:10-20). The rest of the processing namespace is the machinery that loop needs: IInternalCommandSignal and its InternalCommandSignal implementation (.../Processing/InternalCommandSignal.cs:10), a thin wrapper over the same WakeUpSignal the outbox signal wraps (:5-9, :12); InternalCommandCycleResult (.../Processing/InternalCommandCycleResult.cs:17), the record struct that lets a cycle report whether more due work is waiting and when the oldest not-yet-due row comes due, so the loop smart-waits to that instant instead of sleeping a full interval (:7-16); InternalCommandNameResolver (.../Processing/InternalCommandNameResolver.cs:19), the job-queue counterpart of EventNameResolver that stores a command under its InternalCommandNameAttribute name when it declares one and under its assembly-qualified name otherwise, so a rename or a namespace move does not orphan queued rows (:7-18); and InternalCommandMetrics (.../Processing/InternalCommandMetrics.cs:17), the one meter (MMCA.Common.InternalCommands, :20) carrying completions, dead letters, execution latency and observed backlog depth.

The loop mechanics themselves are not the processor's own code. They live in the Polling namespace, shared with the outbox drain in Group 04, so both table-draining services wait, drain and back off identically while every log, metric and activity name stays with the processor that owns it (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Polling/PollingLoop.cs:5-11). PollingLoop (PollingLoop.cs:12) is a static class with three pieces. RunAsync (:40-91) waits a 5-second StartupDelay (:18), returns early when the host owns no relational source, then runs cycles until shutdown: a cycle that reports more ready work re-polls at once, a failed cycle is reported and treated as one with nothing pending, and every other cycle waits on the wake-up signal for ComputeWaitTime (:104-122), which is the moment the earliest upcoming row becomes ready plus the processing delay, capped at the polling interval and floored at one second so an overdue row cannot hot-loop the processor (:21). DrainAllAsync (:135-171) drains every TenantDataSourceTarget in order and aggregates the results, and a source that throws is reported and contributes nothing, so one unreachable database cannot starve the others (:162-167). ComputeRetryBackoffSeconds (:183-197) is the exponential backoff for a failed row, base * 2^(attempts - 1) with the exponent clamped at 16, multiplied by a jitter factor in [0.8, 1.2] before the per-processor cap, so a batch that failed together in one dependency outage does not retry in lockstep, and a capped backoff stays exactly at the ceiling (:173-178, :188-196). The processor calls all three (InternalCommandProcessor.cs:76, :106, :127, :633). The wake-up it waits on is WakeUpSignal (.../Polling/WakeUpSignal.cs:16), a SemaphoreSlim created with a maximum count of one (:18) whose Signal swallows the SemaphoreFullException a second pending wake-up raises (:21-31). The cap is the point: each processor drains a whole batch per cycle, so one pending wake-up is all the information a burst of writes carries, and an uncapped semaphore made N writes cost N candidate-fetch cycles per relational source that found nothing (:3-15).

The administration namespace is the operational half. InternalCommandsSettings (.../InternalCommands/Administration/InternalCommandsSettings.cs:15) binds the InternalCommands section with a default for every property: Enabled defaults to true, the outbox's posture (:27), a batch of 50 (:31), 5 attempts before dead-lettering, where a Result.Failure counts exactly like a thrown exception because both mean the work did not happen (:39), a 2-second fallback poll that is only the backstop for a wake that never arrives (a row another process wrote, a commit path that released no signal), since even a transaction-scheduled row is woken by the unit of work once its commit succeeds (:41-50), a processing delay of 0 rather than the outbox's 5, because the queue has no in-process fast path to race (:52-59), and a 300-second claim lease that must sit comfortably above the longest expected handler duration and, being renewed before each row runs, bounds one handler rather than the whole batch (:61-70). A host that sets Enabled=false registers neither the processor nor the sweep, so InternalCommandsDisabledNoticeService (.../Administration/InternalCommandsDisabledNoticeService.cs:20) states that once at startup at Information: a web front end queueing work for a dedicated worker is a legitimate posture and the wrong thing to discover from an absent background service (:6-18). InternalCommandCleanupService (.../Administration/InternalCommandCleanupService.cs:44) purges completed rows past RetentionDays, because the table stores serialized command payloads that may contain personal data and the pending index every poll re-scans grows with it, and deletes dead-lettered rows on their own wider window, logging every such deletion at Warning because it destroys the only record that the work was ever asked for (:13-28). InternalCommandAdministration (.../Administration/InternalCommandAdministration.cs:37) is the operator surface over the same targets, visiting each in its own DI scope (a tenant target only routes correctly once ITenantContext is set for that scope) and expressing requeue and purge as one set-based statement per target, because an operator clearing a backlog touches thousands of rows and none of the values written depend on the row's current state (:15-26). Both background services and the administration type expand their target list per tenant that keeps its own copy of a source, for the same reason the audit-trail sweep does: that database has a queue table nothing else would drain.

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:515-574). 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 (:502-507, :519-523); 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 (:509-511, :567-571); 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 (:532-554, width constant at :484). 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 (:537-553). 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 (:558-565). 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:41).

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:13), 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:24) 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:52-82), which emits the shared target for every source plus one extra TenantDataSourceTarget (:15) per tenant that overrides a source, because a tenant with its own database is invisible to the shared sweep (:36-40). The sweeps do not each assemble that list themselves: FrameworkTableTargets (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/FrameworkTableTargets.cs:32) is the one answer to "which databases hold the framework's own relational tables on this host", shared by the outbox and internal-command processors, both cleanup services, both operator surfaces and the audit-trail sweep (:14-19). Relational() returns every relational source backing a registered entity, deduplicated and expanded per tenant (:43-44), and its overload adds the source the caller's own settings name as the table's home when that engine is relational (:54-60). It is recomputed per call, so late-loading module assemblies are seen, and Cosmos sources are skipped because they host none of those tables (:21-22).

Recording what changed, the audit trail

AuditTrailSaveChangesInterceptor (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/AuditTrail/AuditTrailSaveChangesInterceptor.cs:64) 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 (:20-24). 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:17-23, class at :23). An owner left Unchanged whose owned value object changed is recorded too, through the same OwnedDependents check the audit interceptor uses (AuditTrailSaveChangesInterceptor.cs:233-240), with the owned property named navigation.property (:394). 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 (:35-37, model check at :184). 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 (:40-43, applied at :324-325, 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 (FrameworkEntityTypes at :115, checked at :230). 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 (:46-55). The values every row of one save shares (user, instant, trace id, tenant) are gathered once into a CaptureContext record struct (:190-195, declared at :663), and a row describing an insert whose key the database has not assigned yet is parked as a PendingEntityKey (:672) until the store-generated key exists (parked at :205-217, read back after the save at :491). Every free-text value a row carries (entity type, key, property name, trace id, tenant) is cut to its column width through ColumnWidth.Truncate (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Conversions/ColumnWidth.cs:4, body at :10-11), an internal helper that truncates and preserves null (AuditTrailSaveChangesInterceptor.cs:194-195, :255, :323, :602); the internal-command processor and the scheduled-job runner reuse it for their error columns (InternalCommandProcessor.cs:549, :573). 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:47) 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 (:57, :62, :66, :69-82, :152-166), expanding that source list through TenantDataSourceTargets so a tenant with its own database gets swept too (:78, per-tenant scope at :94-105). 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-26).

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:20) 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> (:332) combines both plus four IQueryable surfaces (tracking, no-tracking, single-query, split-query, :336-345), IWriteRepository<TEntity, TIdentifierType> (:369) adds mutation, and IRepository<TEntity, TIdentifierType> (:497) 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:21) and EFRepository<TEntity, TIdentifierType> (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Repositories/EFRepository.cs:24) wrap an EF DbSet; the read side keeps its GROUP BY projections in the private GroupedCount<TKey> and GroupedSum<TKey> records (EFReadRepository.cs:185, :190) so the aggregation happens in the database rather than in memory. Its lookup read (GetAllForLookupAsync, EFReadRepository.cs:223) follows the same rule for a non-string display property: a string property projects straight onto BaseLookup<TIdentifierType>, while any other type projects onto LookupRow<TId, TName> (EFReadRepository.cs:735), the id plus the raw name value in its own CLR type (:343-362), because EF can translate that projection for any mapped property but cannot translate a ToString() on a value object (:712-716). The rows are ordered and capped server-side at EntityQueryPipeline.MaxUnboundedResultLimit (1000, MMCA.Common/Source/Core/MMCA.Common.Application/Services/Query/EntityQueryPipeline.cs:23) and formatted to display strings only after materialization (:280-297). The compiled selectors are cached by the property's canonical name and capped at 512 entries (:30, :313-341), so the case permutations of one column name sent to an anonymous endpoint cannot mint unbounded cache entries (:305-311). The write side patches already-tracked entities in place through an O(1) Local.FindEntry lookup instead of re-attaching (EFRepository.cs:53-65) and seeds RowVersion original values for optimistic concurrency on both the aggregate and any child implementing IRowVersioned (:75-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:455), and ExecuteUpdateAsync (:480), 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:141-155).

The read repository does not compose queries by hand. SpecificationEvaluator (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Repositories/SpecificationEvaluator.cs:21) turns an ISpecification<TEntity, TIdentifierType> into an IQueryable: criteria always, then the includes, the OrderExpression chain, and the paging a QuerySpecification<TEntity, TIdentifierType> carries (:40-68), with the shape deliberately skipped for aggregate reads because joining includes to count rows costs a join per navigation (:30-34). Tracking and soft-delete scope are not its business: those choose the base queryable, which only the repository can do (:15-19). It also owns the one split-query heuristic in the framework, opting into AsSplitQuery as soon as any include targets a collection navigation (:93-101), and EFReadRepository.ApplyIncludes delegates to it so the string-include path and the specification path cannot drift (:78-79, EFReadRepository.cs:562-565). 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 (:50-51), and builds the composite seek predicate against the last row of the previous page (BuildSeekPredicate at :118), so GetPageByCursorAsync (IRepository.cs:318, implemented at EFReadRepository.cs:632) 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:49) is the scoped coordinator: it caches one ApplicationDbContext per DataSourceKey so every repository in a scope shares one change tracker (:99-133), gives each new context live scope accessors rather than copied values (:115, doc at :135-141), and enlists a late-created context into an already-open transaction (:117-120). 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 (ResolveTenantOverride, :163-169), and a cached routed context is refused to a second tenant rather than silently serving the first tenant's rows (:124-125, guard at :202-219), just as a shared context created before the tenant resolved is refused to a tenant that overrides that source (:127-129, :227-230). Its save loop runs up to MaxSavePasses (3, :64) passes over the cached contexts, because dispatching events in-process can materialize a context for a source nobody had touched yet (:279-297), 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 (:299-316).

Because there can be more than one physical source in play, ExecuteInTransactionAsync (:551) 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 :719); 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 (:540-549). 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 (:555-563). A returned failed Result rolls back exactly like an exception (:615-622), which is what makes ADR-013's Result-over-exceptions rule safe for partial persistence; rollback also drops the deferred event dispatch (:617-620), the deferred flush runs only after every commit has succeeded (:636-643), and a retry resets the change tracker first so the aborted attempt's Added entities are not inserted twice (ResetForRetry at :836, called at :581). Before committing, the unit also refuses to discard work: anything still tracked but unsaved throws, except an internal-command row that was only enrolled on the context while the transaction was open, which is saved inside the transaction so it commits with the change that scheduled it (FlushEnrolledCommandsBeforeCommitAsync, :671-707, called at :625). Once every commit has succeeded it releases the processor wakes those enrolled rows owe through EnrolledCommandWake, before the deferred event flush so a throwing in-process handler cannot swallow them (:631-634), and DropDeferredWork forgets both the deferred dispatch and the owed wake on rollback or retry (:850-854). DbContextFactory further carries the engine-neutral half of the explicit-key insert (RequestExplicitKeyInsert at :322, SaveWithExplicitKeyInsertAsync at :330): when one is requested and the context's engine has an IExplicitKeyInsertDialect, the save is split into one ExplicitKeyInsertGroup round per table with the toggle on (:264-270, :293-294), for importing entities with explicit database-generated ids. The rounds run principals first: ExplicitKeyInsertRoundOrder (.../Factory/ExplicitKeyInsertRoundOrder.cs:17) derives the order from the EF model's foreign keys rather than from the order entities were added to the change tracker, because each round hides every other round's added rows, so EF's own per-command ordering cannot help across rounds and a dependent table written first would fail its foreign key (:6-15, applied at DbContextFactory.cs:340-344). Its Order is Kahn's algorithm over the table dependency graph: lowest ready index first so independent rounds keep their original order, a self-reference is no edge because EF orders rows within one round itself, and a cycle is broken deterministically at the lowest remaining index (ExplicitKeyInsertRoundOrder.cs:19-34, :70-99). The factory also pins one connection for the whole sequence, because the toggle is session state and EF would otherwise hand the connection back to the pool between commands (DbContextFactory.cs:349-359). It also runs the MigrateAsync / HasPendingMigrationsAsync sweeps (:784, :820) over every source whose resolved PhysicalDataSource.IsMigrationTarget holds: the source UsesMigrations under its engine's MigrationPolicy, and it is not an optional source left without a connection string (PhysicalDataSource.cs:42-60, target selection at DbContextFactory.cs:804-817).

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:48-81). The physical creation itself runs through PhysicalDbContextFactory (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Factory/PhysicalDbContextFactory.cs:19), a singleton that hands construction to the key's engine through IDataSourceEngine.CreateDbContext (:32) and whose doc comment warns it must never be pooled, because each instance carries per-source constructor state that pooling would smear across databases (:13-17). 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 type that exists only because of what the coordinator does, 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:719-744). That exception is thrown outside the execution strategy on purpose (DbContextFactory.cs:592-593), 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, SQL Server, or PostgreSQL, 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:16), the IDataSourceResolver singleton (.../DataSources/IDataSourceResolver.cs:15), builds the logical-to-physical map once per engine from configuration and hands out the resolved PhysicalDataSource (BuildEngineMap at :195, ResolveLogical at :93, GetPhysical at :183). 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:295-345), and sources sharing a connection identity collapse onto one canonical key named after their alphabetically-first member (:380-411, canonical name at :386). 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 (:219-285, captured in the private DefaultSeed record at :217). Identity is the connection string compared ordinally, with the database name appended on an engine whose ConnectionIdentityIncludesDatabaseName is set (Cosmos, because one account hosts many databases, :496). The resolver fails fast when two logical names collapsing to one database declare conflicting migrations assemblies (:464-480) and logs a warning when a separate source on an Always MigrationPolicy engine (SQL Server) falls back to the Default migrations assembly (:401, message at :509). 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 ranked by each engine's SubstitutionPriority (:35-36, applied through SubstituteUnconfiguredEngine at :128), 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 and PostgreSQL migrations assemblies, 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 SQL Server and PostgreSQL migrations assemblies but no SQLite one, 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 (:42-55). 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:12) 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 relational (DataSourceService.cs:32).

One registry answers every engine question

Four engines would otherwise mean a four-way switch in every component that maps a key, quotes a column, picks a migrations assembly or decides whether a source has an outbox. The framework keeps exactly one place that knows engines apart. IDataSourceEngine (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/Engines/IDataSourceEngine.cs:18) is the internal contract, and its doc comment states the goal: no call site branches on DataSource (:9-16). Its members fall into three groups. The descriptive ones say how the engine is configured: its rank when the resolver substitutes it for an unconfigured engine (:29), the open generic entity-configuration interface whose implementations belong to its model (:32), the setting that names its migrations assembly (:38), whether connection identity includes the database name (:44), and how to read its connection string and migrations assembly from the top-level section, a named entry or a tenant override (:49-69). The capabilities are one value (:74). The behavior hooks are the few places the engine has to act rather than answer: build its sealed context over one physical source, never pooled (:83-86), apply its table or container mapping and key generation to one entity (:95-97), add covering index columns (:103), quote a column and build the soft-delete index predicate (:108-113), and expose an explicit-key insert dialect, or none (:119).

DataSourceEngines (.../Engines/DataSourceEngines.cs:19) is the registry: a static class holding the four engines (:22-28) in a frozen dictionary keyed by the shipped DataSource value (:30-31), whose For throws on an unregistered value (:40-43). It is static rather than a DI service on purpose: several consumers run where no container is reachable (the model-building conventions, EntityTypeConfiguration.ApplyEngineConventions, SoftDeleteFilterSql, IndexBuilderExtensions), and the engines are stateless facts about a closed enum only Common can extend, so a DI extension point would buy no extensibility; adding a fifth engine is one class plus one line (:6-18). The four implementations are SQLServerDataSourceEngine (.../Engines/SQLServerDataSourceEngine.cs:19), PostgreSQLDataSourceEngine (.../Engines/PostgreSQLDataSourceEngine.cs:17), SqliteDataSourceEngine (.../Engines/SqliteDataSourceEngine.cs:16) and CosmosDataSourceEngine (.../Engines/CosmosDataSourceEngine.cs:18), with substitution priorities 0, 1, 2 and 3 (SQLServerDataSourceEngine.cs:29, PostgreSQLDataSourceEngine.cs:27, SqliteDataSourceEngine.cs:26, CosmosDataSourceEngine.cs:28), which is the relational-first order the resolver substitutes in.

What differs between engines is a DataSourceEngineCapabilities record (.../Engines/DataSourceEngineCapabilities.cs:23) of five values (:24-28). Only facts whose values genuinely differ get a member, and everything that splits the engines exactly along the relational line is the single IsRelational flag: same-source .Include(), transactions, raw parameterized SQL, indexes, foreign keys whose delete behavior matters, Any(predicate) translation and the framework's own relational tables (:3-20). That one flag is what the outbox capture, the transaction coordinator, the conventions and the .Include() check read (DomainEventSaveChangesInterceptor.cs:257, DbContextFactory.cs:860-861, SoftDeleteUniqueIndexConvention.cs:43, DataSourceService.cs:32). MigrationPolicy (.../Engines/MigrationPolicy.cs:8) decides whether a source is migrated or created outright: Never for Cosmos, WhenAssemblyConfigured for SQLite and PostgreSQL, and Always for SQL Server, where a named source with no assembly falls back to the Default source's with a warning (:10-20; values at SQLServerDataSourceEngine.cs:42, PostgreSQLDataSourceEngine.cs:40, SqliteDataSourceEngine.cs:39, CosmosDataSourceEngine.cs:42). RowVersionStrategy (.../Engines/RowVersionStrategy.cs:8) decides the concurrency token: None on Cosmos, StoreGenerated (a rowversion, never stamped) on SQL Server, and ClientStamped on PostgreSQL and SQLite, where the audit interceptor writes it (:10-17). ConnectionStringRequired is true only for SQL Server, so a SQL Server source with no connection string is a startup failure rather than an optional source to skip (DataSourceEngineCapabilities.cs:10-13, SQLServerDataSourceEngine.cs:43), and NullsSortFirstAscending is false only for PostgreSQL, which keyset pagination has to know (DataSourceEngineCapabilities.cs:21, PostgreSQLDataSourceEngine.cs:43).

The explicit-key insert shows the split between engine-specific and engine-neutral work most clearly. IExplicitKeyInsertDialect (.../Engines/IExplicitKeyInsertDialect.cs:13) is the engine half, and only an engine that refuses an explicit value for a store-generated key without a session toggle has one: SQL Server, whose engine class implements the dialect itself (SQLServerDataSourceEngine.cs:19, :49) and emits SET IDENTITY_INSERT [schema].[table] ON or OFF (:163). Every other engine returns null and the save runs unchanged (PostgreSQLDataSourceEngine.cs:47, SqliteDataSourceEngine.cs:46, CosmosDataSourceEngine.cs:49). The dialect finds the added entries carrying explicit store-generated keys, grouped by table (IExplicitKeyInsertDialect.cs:21), each group an ExplicitKeyInsertGroup record of schema, table and entries (.../Engines/ExplicitKeyInsertGroup.cs:12), and builds the toggle statement (IExplicitKeyInsertDialect.cs:28); grouping the rounds, hiding other tables' entries, excluding their domain events and pinning the connection stay in DbContextFactory (:5-12). Every engine type is internal, so a consumer never sees one: the public surface is still the DataSource value on an attribute, and this registry is what turns that value into behavior.

Three model-finalizing conventions and the identifier mapping

The base context adds all three of its conventions in ConfigureConventions (ApplicationDbContext.cs:378-400), 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:34, added at ApplicationDbContext.cs:387) 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:39-90, :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, which the convention reads as the engine's IsRelational capability (:66). 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:34, added at ApplicationDbContext.cs:393) 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 (:43, any non-relational engine). 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:18, Build at :35), which reads the column name from the model and asks the engine for the predicate and the quoting (IDataSourceEngine.BuildSoftDeleteFilter and QuoteColumn, :35, :70; null where filtered indexes are unsupported, which is Cosmos), with a normalized comparison for the already-present check (:57-58), 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.

The third convention is RestrictDeleteByDefaultConvention (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Conventions/RestrictDeleteByDefaultConvention.cs:42, added last of the three at ApplicationDbContext.cs:400 so it never stamps a relationship the cross-source convention has already removed, ADR-119). EF's own default is the opposite posture: a required relationship cascades, so deleting a parent silently deletes its children in the database, below the aggregate's invariants, below the soft-delete filter and below the domain events the framework raises. Restricting by default inverts that, so a delete that would orphan rows fails loudly and a genuine cascade becomes a decision recorded with .OnDelete(DeleteBehavior.Cascade) in the entity configuration (:9-19). Two things are left alone: an ownership foreign key keeps its cascade, because an owned type has no identity apart from its owner and EF requires it, and any behavior anybody configured (fluent OnDelete or the [DeleteBehavior] attribute) is kept exactly as configured. Both are stamped rather than changed: every foreign key carries a MMCA:DeleteBehaviorSource annotation naming which of the three sources decided it, so a finalized model can be audited without re-running the convention, and DeleteBehaviorConventionTestsBase reads exactly that annotation to assert every cascading relationship was opted into on purpose (:21-31). Like its siblings it is a no-op for Cosmos, which has no foreign key constraints to restrict and where stamping a decision the provider cannot enforce would only make the audit lie (:33-37, checked at :66).

ConfigureConventions ends with the one piece that is not a convention at all: StronglyTypedIdModelConfiguration.Apply (.../Persistence/Conventions/StronglyTypedIdModelConfiguration.cs:21, called at ApplicationDbContext.cs:402-410, ADR-115). A host that calls AddStronglyTypedIds registers a StronglyTypedIdRegistry, and this declares one pre-convention type mapping per declared identifier, so every property of that type maps to the primitive it wraps: keys, cross-module scalar references, owned-type members and framework-table columns alike, on SQL Server, PostgreSQL, SQLite and Cosmos, because it runs on the one base context (:7-20). Absent the registry it is a no-op, which is the default posture: the primitive identifier aliases stay the identifier model and no existing entity changes (ApplicationDbContext.cs:402-410). Pre-convention is the load-bearing word. The actual conversion is StronglyTypedIdValueConverter<TSelf, TValue> (.../Persistence/Conversions/StronglyTypedIdValueConverter.cs:28), with NullableStronglyTypedIdValueConverter<TSelf, TValue> (:56) and StronglyTypedIdValueComparer<TSelf> (:80) beside it, and a converter attached at model finalization would arrive after the provider's value-generation conventions had already inspected the property, so a wrapped int key would silently lose its IDENTITY strategy. Declared pre-convention, the provider CLR type is known before any of that runs, the column stays the same int, bigint, uniqueidentifier or nvarchar it was, and adopting a wrapper is therefore neither a schema change nor a migration (StronglyTypedIdValueConverter.cs:7-25).

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:27) 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) and EntityTypeConfigurationPostgreSQL<TEntity, TIdentifierType> (.../EntityTypeConfigurationPostgreSQL.cs:22) as its three 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 (:69-77), which hands the mapping to the engine's ApplyKeyAndTableMapping hook (:77): SQL Server gets a table in a module schema (SQLServerDataSourceEngine.cs:94-103), SQLite a plain table, and Cosmos a per-module container with the entity id as partition key (CosmosDataSourceEngine.cs:86-99), each mapping key generation according to the entity's EntityTypeExtensions.IsIdValueGenerated marker (SQLServerDataSourceEngine.cs:103, CosmosDataSourceEngine.cs:98-99): 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 four provider marker interfaces (IEntityTypeConfigurationSQLServer<TEntity, TIdentifierType>, IEntityTypeConfigurationSqlite<TEntity, TIdentifierType>, IEntityTypeConfigurationCosmos<TEntity, TIdentifierType>, IEntityTypeConfigurationPostgreSQL<TEntity, TIdentifierType> (.../EntityTypeConfiguration/IEntityTypeConfigurationPostgreSQL.cs:13), 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:9-23). 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:13) 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 (:26, mapping at :63-94, fallback at :84), and its OwnsAddress sibling flattens an Address into six columns on the owner's table with the lengths and required-ness the framework's consumers already configured by hand (:96-99, method at :131); 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:954-988, 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.

Two tables one database owns, refresh sessions and permission grants

Most of the framework's own tables are infrastructure every relational source needs. Two are not: both are Identity-module data that exactly one database owns, so both are mapped on request rather than everywhere. The stored permission grants are the smaller half. PermissionGrantModelBuilderExtensions (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Auth/PermissionGrantModelBuilderExtensions.cs:15, table name at :18) maps the PermissionGrants table into one model, and its doc comment gives the same reason the refresh-session mapper gives: mapping them everywhere would leave an empty PermissionGrants table in every other module's migrations (:6-14). The opt-in is the AddStoredPermissionGrants DI call, expressed as the PermissionGrantModelGate marker rather than a second configuration flag (.../Auth/PermissionGrantModelGate.cs:19, :6-12). EFPermissionGrantStore (.../Auth/EFPermissionGrantStore.cs:34) reads and writes that table, resolving which database holds it exactly as EFRefreshSessionStore does (the registry first, then the source Authentication:PermissionGrants:DataSourceName names, :15-22), and reads untracked, the mirror image of the refresh-session store's choice: a grant is inserted or deleted, never edited, so tracking would only cost the change detector work on every snapshot load (:23-27). That snapshot is PermissionGrantCache (.../Auth/PermissionGrantCache.cs:35), a singleton that rebuilds the whole set in one query rather than lazy-loading per role, because the authorization read is synchronous and a miss cannot go and fetch; a role whose last grant was deleted is evicted in the same pass rather than left to expire, since a revoke that keeps granting until a TTL runs out is the one staleness direction that is not safe (:14-31). PermissionGrantRefreshService (.../Auth/PermissionGrantRefreshService.cs:31) primes that snapshot at startup and rebuilds it on the configured interval, so a grant added by another replica takes effect here without a restart, and a failed load is logged and retried rather than fatal: authorization keeps working off the compiled registry while the table is unreachable, so a database blip degrades the feature to "no stored grants", a denied request an operator can see rather than a granted one nobody notices (:8-23).

Multi-device refresh sessions (ADR-097) are the other half. 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:893-901) precisely because a downstream app runs on the sealed engine contexts and has no OnModelCreating of its own to override. EFRefreshSessionStore (.../Auth/EFRefreshSessionStore.cs:31) 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, :15-23) and reads tracked on purpose, because the caller revokes by mutating the instances it hands back, with one read-only exception, FindByIdUntrackedAsync, the re-read for the rotation loser (:25-29). 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, :14-23). 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 (:25-30). 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). Three more dependency-free helpers sit beside them, all ADR-045. DocumentContentSniffer (MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Storage/DocumentContentSniffer.cs:49) is the document sibling of the image sniffer: a payload is accepted only when the actual bytes and the file-name extension agree on one of the formats the caller allowed, so a .pdf name over zip bytes or an executable renamed .docx is rejected, and the client-declared content type is never consulted (:42-48). What a caller may allow is the [Flags] DocumentFormats enum in the same file (:9-39, All at :39); an Office Open XML package is told from an ordinary renamed zip by the [Content_Types].xml entry every package carries at its root (:51-55), and an archive declaring more entries than the cap is rejected without inspecting them, because a genuine Office document holds tens of parts and never thousands (:57-61). BlobNames (.../Storage/BlobNames.cs:10) reduces a user-supplied file name to a blob-safe segment, since a blob name is part of a URL and of a storage path: anything outside A-Z a-z 0-9 . _ - collapses to a single -, consecutive dots collapse so no .. can appear, and nothing surviving means the file fallback (:5-9, :12, :21-25). FileUploadOptions (.../Storage/FileUploadOptions.cs:13) carries the response headers stored with the blob, because how a browser treats the bytes on the way back out is a header decision: an RFC 6266 Content-Disposition for a document download (:28), a long Cache-Control for a content-addressed asset (:34), and None (:21) to leave the store's own defaults in place. 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.

IChannelJoinAuthorizer

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

• What it is: an optional entitlement check consulted before a SignalR connection is allowed to join a live channel, so channel membership is not decided by the channel-key shape pattern alone.
• Depends on: ClaimsPrincipal (BCL) for the caller's identity; otherwise no first-party types.
• Concept introduced, closing the gap between a shape-valid channel key and an authorized one. [Rubric §11, Security] assesses whether an authorization decision that a hub cannot make structurally (any well-formed key like event:42 passes the configured pattern) is pushed out to a pluggable check rather than left implicit. The doc comment (IChannelJoinAuthorizer.cs:18-25) frames the contract as a single yes/no gate: given the connection's principal and the requested channelKey, decide whether the connection may join. Because the parameter is optional and defaults to null on the consuming hub, an existing host that never registers an implementation keeps working unchanged and every authenticated caller may join any well-formed channel key; a host that publishes anything not public to every signed-in user must register one deliberately.
• Walkthrough: one method.
  • CanJoinAsync(ClaimsPrincipal? user, string channelKey, CancellationToken cancellationToken = default) (IChannelJoinAuthorizer.cs:26-29): returns true to admit the connection to channelKey. user is the connection's principal (the hub requires authentication, so this is never null in practice); channelKey is the caller-requested channel, already validated against the shape pattern before this check runs.
• Why it's built this way: keeping the check as a single optional interface, rather than a required constructor argument, lets NotificationHub ship with a permissive default (NotificationHub.cs:18-23) while still giving a host with tenant- or role-scoped channels a single extension point to close the gap; the doc comment is explicit that the shape pattern alone is not authorization. See ADR-039 for the live-channel-push design this sits inside.
• Where it's used: injected as the optional joinAuthorizer parameter of NotificationHub (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Notifications/NotificationHub.cs:27), consulted before admitting a join (NotificationHub.cs:160-165). MMCA.ADC is the first registered implementation: LiveChannelJoinAuthorizer (MMCA.ADC/Source/Services/MMCA.ADC.Notification.Service/Live/LiveChannelJoinAuthorizer.cs:43-45) is wired with AddScoped<IChannelJoinAuthorizer, LiveChannelJoinAuthorizer>() (MMCA.ADC/Source/Services/MMCA.ADC.Notification.Service/Program.cs:239).

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:47) alongside the SignalR sender. NullNativePushSender is registered by default with TryAddTransient (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:331) and AzureNotificationHubNativePushSender replaces it when a hub is configured (DependencyInjection.Notifications.cs:98).

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:332); AzureNotificationHubDeviceRegistrar replaces it when a hub is configured (DependencyInjection.Notifications.cs:99).

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 four-value enum (CosmosDB, Sqlite, SQLServer, PostgreSQL) 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:31.
• 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), SQLServer has "full relational JOIN support" (IDataSourceService.cs:14), and PostgreSQL has the same full relational JOIN support (IDataSourceService.cs:18). That distinction is what lets the framework decide whether a navigation can be an EF .Include() or must become a manual batch load. ADR-113 records PostgreSQL's addition as a first-class engine alongside the original three.
• Walkthrough: four members, each documented with its JOIN capability. CosmosDB (IDataSourceService.cs:9), Sqlite (IDataSourceService.cs:12), SQLServer (IDataSourceService.cs:15), and PostgreSQL (IDataSourceService.cs:22). PostgreSQL is appended after SQLServer rather than inserted alphabetically: the doc comment on the member says why (IDataSourceService.cs:17-21), the three original members are shipped public API with fixed ordinal values, and renumbering them would break every consumer that persisted or serialized one. 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:61) 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.

IConcurrencyConflictDetector

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

• What it is: a one-method classifier that answers whether a failed save was rejected because of an optimistic-concurrency conflict, so a handler recovering from a lost race can recognise the collision without depending on the provider exception type that reported it.
• Depends on: nothing first-party. The single method takes a BCL Exception (IConcurrencyConflictDetector.cs:23).
• Concept introduced, classifying a concurrency failure without naming the provider. [Rubric §3, Clean Architecture] assesses whether technology details stay outside the inner layers: EF Core's DbUpdateConcurrencyException is a provider type, and this interface lets Application recognise the failure by asking the question rather than catching the concrete type. [Rubric §29, Resilience & Business Continuity] applies to how a handler reacts to a lost race: the interface mirrors IUniqueConstraintViolationDetector in shape and intent, one boolean classifier over an exception chain, so the same recovery pattern serves two different failure modes.
• Walkthrough: one method, bool IsConcurrencyConflict(Exception exception) (IConcurrencyConflictDetector.cs:25). The doc comment states the contract on the parameter (IConcurrencyConflictDetector.cs:16-19): the answer covers exception or anything in its inner-exception chain, which is what makes it usable against a wrapped save failure. It is synchronous and takes no cancellation token, since it inspects an object already in hand.
• Why it's built this way: declaring the question in Application and answering it in Infrastructure, where the provider exception type is already referenced, keeps the classification swappable per engine while every handler that recovers from a concurrency conflict keeps working unchanged (ADR-035).
• Where it's used: implemented by EfCoreConcurrencyConflictDetector (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/EfCoreConcurrencyConflictDetector.cs:2), registered in MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs. Consumed by MMCA.ADC's RefreshFromSessionizeHandler to distinguish a concurrency conflict from other save failures during a Sessionize refresh (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.Application/Events/UseCases/RefreshFromSessionize/RefreshFromSessionizeHandler.cs:1), registered by MMCA.ADC.Conference.Infrastructure's DependencyInjection.

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:49) and each engine subclass (SQLServerDbContext at SQLServerDbContext.cs:18, CosmosDbContext at CosmosDbContext.cs:18, SqliteDbContext at SqliteDbContext.cs:15); consumed by EntityDataSourceRegistry to build the entity-to-source map (EntityDataSourceRegistry.cs:22) and by PhysicalDbContextFactory (PhysicalDbContextFactory.cs:22). The default implementation DefaultEntityConfigurationAssemblyProvider is registered with TryAddSingleton (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:59), and DesignTimeDbContextHelper substitutes its own nested ExplicitAssemblyProvider for dotnet ef runs (DesignTimeDbContextHelper.cs:193 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:111). 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).

IRawSqlQueryExecutor

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

• What it is: an escape hatch for interpolated raw SQL reads, materializing rows into a scalar or an unmapped DTO, for the cases a Queryable-based repository cannot express.
• Depends on: nothing first-party; the interpolated statement type is the BCL FormattableString.
• Concept introduced, raw SQL as a declared, parameterized escape hatch. [Rubric §11, Security] assesses whether raw SQL access is disciplined rather than ad hoc: both methods take a FormattableString, so every interpolation hole becomes a command parameter rather than a string-concatenated value, which is what keeps this interface off the path to SQL injection. [Rubric §3, Clean Architecture] assesses whether the inner layers stay technology-free; declaring the contract here and executing it in Infrastructure keeps MMCA.Common.Application free of a direct ADO.NET or EF Core reference while still giving a handler a way to run a statement the query pipeline cannot translate.
• Walkthrough: two methods, both generic in the row shape T.
  • QueryAsync<T>(FormattableString sql, CancellationToken cancellationToken = default) (IRawSqlQueryExecutor.cs:32): runs the statement and materializes every row into T, empty when none match.
  • QuerySingleOrDefaultAsync<T>(FormattableString sql, CancellationToken cancellationToken = default) (IRawSqlQueryExecutor.cs:40): runs a statement expected to select at most one row, throwing InvalidOperationException when the statement selected more than one (IRawSqlQueryExecutor.cs:39).
  • Neither method documents a runtime "not relational" failure. The type-level remarks (IRawSqlQueryExecutor.cs:18-21) move that check to registration instead: the executor is registered only when the host's default physical data source is on a relational engine, so a Cosmos-default host (its own query language, no SQL command surface to parameterize) has no registration at all, and a service that injects this interface there fails when the container is validated. The gate is DataSourceEngines.For(defaultEngine).Capabilities.IsRelational in MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:411-413.
• Why it's built this way: an interpolated FormattableString parameter, rather than a plain string plus a parameter array, keeps the parameterization automatic at the call site: a developer writes ordinary string interpolation and the implementation is responsible for turning each hole into a command parameter before the statement reaches the database.
• Where it's used: implemented by EFRawSqlQueryExecutor (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/EFRawSqlQueryExecutor.cs:2), registered conditionally as scoped in MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:413 (covered by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/DependencyInjectionInfrastructureTests.cs). Exercised by the architecture fitness base MMCA.Common/Source/Hosting/MMCA.Common.Testing.Architecture/Bases/Cqrs/RawSqlConventionTestsBase.cs and its ADC concrete test MMCA.ADC/Tests/Architecture/MMCA.ADC.Architecture.Tests/Cqrs/RawSqlConventionTests.cs.

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:121), deliberately TryAdd so a host on another engine can register its own implementation first and keep it (DependencyInjection.cs:118-120). 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:20), SetLeaderboardParticipationHandler (SetLeaderboardParticipationHandler.cs:35), 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:28).

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:480), 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:143-159), keeping audit fields correct on a path that bypasses the save pipeline (EFRepository.cs:20).

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:86), from rows matching the dead-letter predicate ProcessedOn == null && RetryCount >= maxRetries (OutboxAdministration.cs:82), collected across sources and returned oldest first (OutboxAdministration.cs:101).

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:31 · 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:25-30): 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:36) and GetDataSourceKey(string entityFullName) (IDataSourceService.cs:41): 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:46) and GetDataSource(Type entityType) (IDataSourceService.cs:51): resolve just the engine.
  • HaveIncludeSupport(DataSourceKey first, DataSourceKey second) (IDataSourceService.cs:61): the crux. The contract documented at IDataSourceService.cs:53-60 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:70): 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:142).
• Where it's used: implemented by OutboxAdministration (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Outbox/Administration/OutboxAdministration.cs:35-42), registered with TryAddScoped (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:216-217), scoped because it creates one child scope per data source it visits and holds no state of its own (DependencyInjection.cs:228-229). The implementation caps one page at 500 rows so an admin call cannot ask for the whole table at once (OutboxAdministration.cs:40), rejects a negative skip or an out-of-range take as validation errors (OutboxAdministration.cs:42-46), and expresses replay as one set-based UPDATE per target (OutboxAdministration.cs:143-144) 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 :224), ISpecification<TEntity, TIdentifierType> (from MMCA.Common.Domain.Interfaces, IRepository.cs:3, first used in a signature at :151), Result with KeysetPageRequest and KeysetCollectionResult<T> (from MMCA.Common.Shared.Abstractions, IRepository.cs:4, used at :318-319), 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, :332), IWriteRepository (mutations, :369), and IRepository (read plus write, :495). 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:41, used at :52, :81, :102, :198, :288, :365, :379, and :445-446) rather than EF's parameterless form; its own comment (EFReadRepository.cs:38) 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:475 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:134-139): 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:150-152): the deterministic counterpart. Unlike the predicate overload it honors the specification's ORDERING, so "first" means what the specification says it means (IRepository.cs:141-145).
  • CountByAsync<TKey>(keySelector, where?, CancellationToken) (IRepository.cs:169-173): a GROUP BY count, returning one dictionary entry per key that has at least one row. The remarks (IRepository.cs:158-163) 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:173).
  • SumByAsync<TKey>(keySelector, sumSelector, where?, CancellationToken) (IRepository.cs:186-191): the grouped SUM, the counterpart of CountByAsync (IRepository.cs:175-179).
  • FindIncludingDeletedAsync(where, includes?, asTracking, CancellationToken) (IRepository.cs:217-221): the resurrection read (BR-135, IRepository.cs:199), returning a named tuple of Active and SoftDeleted matches. The remarks (IRepository.cs:197-208) 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:211-214): 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:224-228): 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:231) and CountAsync(Expression<Func<TEntity, bool>> where, CancellationToken) (IRepository.cs:234-236): total and predicated counts.
  • CountAsync(ISpecification<TEntity, TIdentifierType> specification, CancellationToken) (IRepository.cs:245-247): the specification-shaped count. The doc comment (IRepository.cs:238-241) 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:262-264): runs a specification and returns the matching entities. The remarks (IRepository.cs:252-258) 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:281-284): the projecting overload, so only the selected columns leave the database. The remarks (IRepository.cs:270-275) 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:293-295): existence by specification, with ordering and paging ignored for the same reason as the specification CountAsync (IRepository.cs:287-288).
  • GetPageByCursorAsync(KeysetPageRequest request, ISpecification<TEntity, TIdentifierType>? specification = null, CancellationToken) (IRepository.cs:318-321): 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:308-312). The remarks (IRepository.cs:301-313) 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:333) and implemented concretely by EFReadRepository<TEntity, TIdentifierType> (for example GetProjectedAsync at EFReadRepository.cs:75, 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. The two FirstOrDefaultAsync overloads are public overloads that both carry optional parameters, which the RS0026 public-API analyzer rule forbids; each is annotated with a targeted [SuppressMessage("ApiDesign", "RS0026...")] (IRepository.cs:133 and :149) whose justification records them as grandfathered: released after the v1.152 baseline while RS0026/RS0027 were off, so changing either signature now would be a breaking change. A new overload on this interface does not inherit that exemption.

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:333). 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:332 · 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:332-348).

• Depends on: IEntityReader<TEntity, TIdentifierType> and IEntityQuerier<TEntity, TIdentifierType>, both declared in the same file and both listed as base interfaces (IRepository.cs:333); AuditableBaseEntity<TIdentifierType> as the TEntity constraint (IRepository.cs:334). 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:332), IWriteRepository (IRepository.cs:369), and IRepository (read plus write, IRepository.cs:497). The doc comment records a migration stance rather than a ban (IRepository.cs:324-329): 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:338): 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:526).
  • TableNoTracking (IRepository.cs:341): the no-tracking queryable, documented as best for read-only queries and implemented as Entities.AsNoTracking() (EFReadRepository.cs:529).
  • TableNoTrackingSingleQuery (IRepository.cs:344): no-tracking, pinned to a single SQL statement through AsSingleQuery() (EFReadRepository.cs:532).
  • TableNoTrackingSplitQuery (IRepository.cs:347): no-tracking in split-query mode, which avoids the cartesian explosion that collection includes cause, through AsSplitQuery() (EFReadRepository.cs:535). 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:21-25) 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:369 · Level 5 · interface

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

• Depends on: AuditableAggregateRootEntity<TIdentifierType> as the TEntity constraint (IRepository.cs:370), IRowVersioned for the child-concurrency overload (written by its qualified Domain.Interfaces.IRowVersioned name, IRepository.cs:419), and IUpdatePropertySetter<TEntity> for the set-based update builder (IRepository.cs:482). 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:353-360): 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:361-365): 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. Five members carry the weight.

  • SetOriginalRowVersion(TEntity entity, byte[] rowVersion) (IRepository.cs:408): 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 when the row moved since the client read it (IRepository.cs:401-405). The token only ever arrives through If-Match, so [SupportsIfMatch] answers that exception as 412 Precondition Failed, and the doc comment itself names that status and the attribute (IRepository.cs:403-404; the child overload's comment likewise promises "the same stale-token 412 protection", IRepository.cs:413) (MMCA.Common/Source/Presentation/MMCA.Common.API/Concurrency/SupportsIfMatchAttribute.cs:130-138, ADR-035). 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:76-85).
  • SetOriginalRowVersion(Domain.Interfaces.IRowVersioned childEntity, byte[] rowVersion) (IRepository.cs:419): 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:410-416): 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:87-96).
  • TouchConcurrencyToken(TEntity entity) (IRepository.cs:442): forces the aggregate ROOT to take part in the next save when a conditional write left it untouched, so the precondition the caller sent is actually evaluated (SEC-Common-77). The remarks explain the gap it closes (IRepository.cs:426-441): SetOriginalRowVersion only stamps the tracked entry's ORIGINAL value, it does not make the entry dirty, so an applier that changes only child rows leaves the root Unchanged, EF emits no root UPDATE, no WHERE RowVersion = @token reaches the database, and the stale-token check silently does not fire, letting two administrators editing different children of the same aggregate from the same ETag both get 200 while the second silently discards the first's edit. Touching the root restores the 412 ADR-035 promises. It is declared with a default no-op body (IRepository.cs:442-445) so an existing implementer stays source- and binary-compatible; a repository that does not override it keeps the pre-hardening behaviour rather than failing to compile. EFRepository<TEntity, TIdentifierType> overrides it.
  • ExecuteDeleteAsync(Expression<Func<TEntity, bool>> where, CancellationToken) (IRepository.cs:455-457): 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:447-454). The implementation is a one-liner over the DbSet (EFRepository.cs:119-125).
  • ExecuteUpdateAsync(where, Action<IUpdatePropertySetter<TEntity>> setProperties, CancellationToken) (IRepository.cs:480-483): 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:459-479) 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, rejects an empty setter list, and, on an engine with an application-stamped row version (PostgreSQL, SQLite, RowVersionStrategy.ClientStamped), re-stamps RowVersion with a fresh GUID unless the caller set it, so a client still holding the pre-update token gets a concurrency conflict instead of passing its If-Match check (SQL Server's rowversion moves by itself; IRepository.cs:469-471, EFRepository.cs:157, :162-176) (EFRepository.cs:136-159, with the two optional constructor dependencies at EFRepository.cs:24-28).

• Walkthrough: the nine members in teaching order.

  • AddAsync(TEntity entity, CancellationToken) (IRepository.cs:377-379) and AddRangeAsync(IEnumerable<TEntity> entities, CancellationToken) (IRepository.cs:385-387): single and batch inserts, staged on the change tracker.
  • UpdateAsync(TEntity entity, CancellationToken) (IRepository.cs:393-395) and UpdateRange(IEnumerable<TEntity> entities) (IRepository.cs:399): 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:408, :419), TouchConcurrencyToken (IRepository.cs:442), and the two database-side operations (IRepository.cs:455, :478) 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:497); implemented by EFRepository<TEntity, TIdentifierType> (EFRepository.cs:24-30), 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/SessionScoringRunner.cs:29, :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:497 · 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:497).
• Depends on: IReadRepository<TEntity, TIdentifierType> and IWriteRepository<TEntity, TIdentifierType>, both named as bases on IRepository.cs:497, and AuditableAggregateRootEntity<TIdentifierType> as the TEntity constraint (IRepository.cs:498).
• 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:497-499). What matters is which constraint survives the composition. The read side accepts any AuditableBaseEntity<TIdentifierType> (IRepository.cs:334) and the write side only aggregate roots (IRepository.cs:370), so the combination inherits the narrower bound, and the doc comment states the consequence for the reader (IRepository.cs:489-493): 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:497-499), 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:24-30) 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:52, :43).
• Caveats / not-in-source: AddInfrastructure does register the open generic IRepository<,> against EFRepository<,> (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:128), which makes constructor-injecting IRepository<,> look supported. It is not the intended path: EFRepository<TEntity, TIdentifierType> takes a bare DbContext constructor parameter (EFRepository.cs:24-25) 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:52-60). 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 explicit-key-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:130), it caches one repository per closed generic interface type (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/UnitOfWork.cs:34, :37-45), and every repository it hands out is bound to a context obtained from the same IDbContextFactory (UnitOfWork.cs:56), 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:53-63). The EF-shaped work (a context per physical source, execution strategies, the engine-specific explicit-key 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: five 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:52-60).
  • 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:72-80).
  • 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:84-85) 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:64) so a context materialized by a domain event handler mid-save is still saved (DbContextFactory.cs:283-297), then throws if any tracked change is left behind rather than losing it silently (DbContextFactory.cs:305-316).
  • RequestExplicitKeyInsert() (IUnitOfWork.cs:45): a one-shot flag saying the next save may insert rows that carry explicit values for store-generated keys, for example rows imported from an external system with their source ids intact (IUnitOfWork.cs:38-44). The contract is engine-neutral: on an engine that refuses such a value unless it is switched on per table, the save pipeline does that around those inserts, and on every other engine the save runs unchanged (IUnitOfWork.cs:41-42). The implementation sets a boolean (UnitOfWork.cs:88, DbContextFactory.cs:322); the next SaveChangesAsync reads and immediately clears it (DbContextFactory.cs:273-274, which is what "automatically cleared after the save completes" means) and, for a context whose engine exposes an IExplicitKeyInsertDialect through IDataSourceEngine.ExplicitKeyInsert (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/Engines/IDataSourceEngine.cs:119), routes the save through SaveWithExplicitKeyInsertAsync (DbContextFactory.cs:293-295). Only SQLServerDataSourceEngine supplies a dialect (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/Engines/SQLServerDataSourceEngine.cs:49, the SET IDENTITY_INSERT ON/OFF toggle per DbContextFactory.cs:264-267); the SQLite, PostgreSQL and Cosmos engines return null, so their save is the plain one. With a dialect, the save asks it for the affected entries grouped by table as ExplicitKeyInsertGroup values (DbContextFactory.cs:335), pins one open connection for the whole save because the toggle is session state (DbContextFactory.cs:349-359, closed again at :364-368), and saves each group in its own round with the toggle on, because SQL Server allows only one table per session to have it on (DbContextFactory.cs:324-329, SaveExplicitKeyGroupsAsync at :377).
  • ExecuteInTransactionAsync<TResult>(Func<CancellationToken, Task<TResult>> operation, CancellationToken cancellationToken = default) (IUnitOfWork.cs:63-65): the interface's only transaction-control member; the manual Save(), BeginTransaction(), CommitTransaction(), and RollbackTransaction() members it used to sit alongside are gone from the interface. Its doc comment (IUnitOfWork.cs:47-59) 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 same comment carries the save rule (IUnitOfWork.cs:53-58): the commit does not save the operation's work, so the operation must save before it returns; the one exception is an internal-command row scheduled after the last save, which is saved just before the commit, and any other change still tracked at that point throws InvalidOperationException and rolls the unit back rather than being silently discarded. The implementation adds six behaviors worth knowing (DbContextFactory.cs:551-596, with the attempt runner at :589-647): a nested call joins the ambient transaction instead of opening a second one (DbContextFactory.cs:562-563); a returned failed Result rolls back exactly like an exception (DbContextFactory.cs:615-622); before committing, FlushEnrolledCommandsBeforeCommitAsync (DbContextFactory.cs:625, :659-685) saves the unit when every pending entry is an added InternalCommandMessage and otherwise throws the unsaved-changes exception (DbContextFactory.cs:690-704); each retry starts from a reset change tracker, so entities a failed attempt added are not inserted twice (DbContextFactory.cs:580-581, ResetForRetry at :814-821); deferred in-process domain events are flushed only after a successful commit (DbContextFactory.cs:636-643); and a failure of the commit itself is never retried, surfacing as TransactionCommitAmbiguousException thrown outside the strategy instead (DbContextFactory.cs:588-593).
  • The two base interfaces (IUnitOfWork.cs:10) matter at scope teardown: UnitOfWork forwards both disposal paths to the context factory (UnitOfWork.cs:96-122), so the async path awaits _dbContextFactory.DisposeAsync() (UnitOfWork.cs:106) 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 the interface's only transaction-control member, rather than the manual BeginTransaction/CommitTransaction/RollbackTransaction/Save set it replaced, 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:24) and calls ExecuteInTransactionAsync for any command marked ITransactional (TransactionalCommandDecorator.cs:33); 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 explicit-key insert path, calling RequestExplicitKeyInsert() immediately before the save because Sessionize imports preserve external ids into tables with store-generated keys (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.Application/Events/UseCases/RefreshFromSessionize/RefreshFromSessionizeHandler.cs:192-193). The single implementation is UnitOfWork (UnitOfWork.cs:13), which is internal sealed, so consumers only ever see this interface.

• Caveats / not-in-source: 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 names each source's outcome (committed, ambiguous, or rolled back) so the partial state is observable rather than inferred, and that the caller's replay is what reconciles it (DbContextFactory.cs:539-549). A witness row that would let a replay learn what landed is deliberately not built, since a single transactional source needs none (DbContextFactory.cs:545-548); the outbox delivers whatever the commit did make durable (DbContextFactory.cs:536-537).

BlobNames

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

• What it is: a dependency-free static helper that reduces a user-supplied file name to a blob-safe segment built only from A-Z a-z 0-9 . _ - (BlobNames.cs:33-119).
• Depends on: nothing first-party; BCL StringBuilder.
• Concept introduced, file-name sanitization as an upload trust boundary. [Rubric §11, Security] assesses whether untrusted input (here, a caller-chosen file name that becomes part of a storage path and later a Content-Disposition header) is normalized before use rather than passed through. This is the naming half of the document-upload path; DocumentContentSniffer and FileUploadOptions are its companions, mirroring how ImageContentSniffer and IImageProcessor pair up for avatars.
• Walkthrough: one public method plus two private helpers.
  • SanitizeFileName(string fileName, int maxLength = 100) (BlobNames.cs:48-89): trims trailing separators, splits the last . into stem and extension, falls back to the literal file when nothing safe survives, lower-cases the extension, and truncates the stem so the whole result fits maxLength; the extension itself is never sacrificed, so a result can exceed maxLength only when the extension alone is longer than the budget.
  • KeepSafeCharacters(string fileName) (BlobNames.cs:95-117): rewrites the name over the safe alphabet, collapsing any run of unsafe characters to one - and any run of dots to one ..
  • ToLowerAscii(string value) (BlobNames.cs:108-116): a hand-rolled ASCII lower-case so the result is independent of the host's culture.
• Why it's built this way: collapsing runs rather than dropping characters one-by-one keeps a long run of spaces or path separators from producing a long run of dashes, and preserving the extension unconditionally keeps a sanitized name usable by whatever later code inspects it (for example DocumentContentSniffer, which reads only the extension).
• Where it's used: UploadSessionAssetHandler sanitizes the caller's file name before building the blob name (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.Application/SessionAssets/UseCases/UploadFile/UploadSessionAssetHandler.cs:1). It has its own dedicated unit-test class (MMCA.Common/Tests/Core/MMCA.Common.Application.Tests/BlobNamesTests.cs).

DocumentFormats

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Storage · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Storage/DocumentContentSniffer.cs:9 · Level 0 · enum

• What it is: a [Flags]-shaped enum of the document formats DocumentContentSniffer can recognize: None, Pdf, Presentation, WordDocument, Spreadsheet, a combined OfficeOpenXml, Zip, PlainText, Markdown, and a combined All (DocumentContentSniffer.cs:155-186).
• Depends on: nothing; it is a plain BCL enum with bitwise-combinable members.
• Concept introduced: none on its own; it is the vocabulary DocumentContentSniffer.Detect uses to let a caller declare which formats it accepts and to report which one it found.
• Walkthrough: OfficeOpenXml is the bitwise-or of Presentation | WordDocument | Spreadsheet, and All is the bitwise-or of every leaf value; both let a caller pass one flag to accept a whole family instead of enumerating members.
• Why it's built this way: [Flags] lets a caller such as the session-asset upload path accept exactly the subset it wants (for example documents and zips but not plain text) with a single value.
• Where it's used: the allowed parameter of both DocumentContentSniffer.Detect overloads; passed by UploadSessionAssetHandler and UploadSessionAssetCommandValidator (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.Application/SessionAssets/UseCases/UploadFile/UploadSessionAssetCommandValidator.cs:1).

FileUploadOptions

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Storage · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Storage/FileUploadOptions.cs:13 · Level 0 · record (sealed)

• What it is: an immutable options record carrying the response headers a blob upload should be stored with, ContentDisposition and CacheControl (FileUploadOptions.cs:28-34), plus factory methods that build a correctly-encoded Content-Disposition from a user-facing file name.
• Depends on: nothing first-party; BCL StringBuilder, Encoding.UTF8.
• Concept introduced, RFC 6266/5987-correct Content-Disposition encoding. [Rubric §8, Data Architecture] assesses whether a storage-layer concern (here, the HTTP headers a blob is served with) is centralized in one place rather than hand-built at each call site. The static None instance (FileUploadOptions.cs:21) sets no headers, so a caller only reaches for Attachment/Inline when it actually wants a download disposition.
• Walkthrough: two public factory methods and three private helpers.
  • Attachment(string fileName, string? cacheControl = null) (FileUploadOptions.cs:48-49): builds an attachment disposition, so the browser downloads the blob under fileName instead of rendering it.
  • Inline(string fileName, string? cacheControl = null) (FileUploadOptions.cs:59-60): builds an inline disposition, so the browser renders the blob when it can and otherwise downloads it under fileName.
  • ForDisposition(string dispositionType, string fileName, string? cacheControl) (FileUploadOptions.cs:62-85): trims the name (falling back to file when blank), then emits both an ASCII filename="..." fallback and a percent-encoded UTF-8 filename*=UTF-8''... parameter in the same header, per RFC 6266.
  • ToAsciiFallback(string fileName) (FileUploadOptions.cs:91-106) and ToRfc5987(string fileName) (FileUploadOptions.cs:112-129): the two encodings behind the header; the ASCII fallback drops quotes, backslashes, semicolons and line breaks and replaces the rest of non-printable-ASCII with _, while the RFC 5987 form percent-encodes every UTF-8 byte outside the attr-char alphabet (FileUploadOptions.cs:135-139).
• Why it's built this way: emitting both an ASCII fallback and the UTF-8 filename* parameter in one header lets older clients that ignore filename* still get a usable name, while modern clients get the exact, non-ASCII-safe original; centralizing the encoding here keeps IFileStorageService implementations from having to get RFC 5987 right themselves.
• Where it's used: the options parameter of IFileStorageService's document-upload overload (MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Storage/IFileStorageService.cs:37), implemented by AzureBlobFileStorageService and NullFileStorageService; called by UploadSessionAssetHandler to attach a download name to an uploaded document.

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:63) before the bytes reach IImageProcessor (SetUserAvatarHandler.cs:103) and then IFileStorageService (SetUserAvatarHandler.cs:117). 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.

DocumentContentSniffer

MMCA.Common.Application · MMCA.Common.Application.Interfaces.Infrastructure.Storage · MMCA.Common/Source/Core/MMCA.Common.Application/Interfaces/Infrastructure/Storage/DocumentContentSniffer.cs:49 · Level 1 · class (public static)

• What it is: a dependency-free static helper that decides the canonical MIME type of uploaded document bytes by checking both the file name's extension and the content's actual bytes, refusing to trust either one alone.
• Depends on: DocumentFormats; BCL ZipArchive, Utf8.IsValid. It is the document-side counterpart to ImageContentSniffer.
• Concept introduced, extension-plus-signature agreement as an upload trust boundary. [Rubric §11, Security] assesses whether untrusted input is validated by its actual content rather than a spoofable extension or client-declared content type; this type requires both the extension and the bytes to agree before it will return a MIME type, which ImageContentSniffer does not need because an image has no user-visible extension trust decision to make. A zip-bomb guard (MaxInspectedEntries = 4096, DocumentContentSniffer.cs:61) caps how many zip central-directory entries are inspected, and only entry names are read, never entry streams (DocumentContentSniffer.cs:175-177), so a hostile archive costs nothing to refuse.
• Walkthrough: a lookup table plus detection and signature-checking members.
  • KnownExtensions (DocumentContentSniffer.cs:68-79): the one place extension, DocumentFormats flag and canonical MIME type are tied together, compared case-insensitively.
  • Detect(ReadOnlySpan<byte> content, string fileName, DocumentFormats allowed) (DocumentContentSniffer.cs:91-106): resolves the extension, then for Office Open XML formats copies the span to an array (ZipArchive needs a seekable stream) and calls IsOfficeOpenXml; otherwise checks the format's byte signature directly.
  • Detect(ReadOnlyMemory<byte> content, string fileName, DocumentFormats allowed) (DocumentContentSniffer.cs:119-131): the same contract without the defensive copy, for callers that already hold a Memory<byte>.
  • IsPdf (DocumentContentSniffer.cs:136-137): leading bytes match %PDF-.
  • IsZip (DocumentContentSniffer.cs:142-143): leading bytes match the zip local-file-header signature PK 03 04.
  • IsOfficeOpenXml(ReadOnlyMemory<byte> content) (DocumentContentSniffer.cs:153-188): opens the bytes as a ZipArchive and checks for a [Content_Types].xml entry, the marker every Office Open XML package carries at its root; a malformed or truncated archive answers false rather than throwing (DocumentContentSniffer.cs:179-187).
  • IsPlainUtf8Text (DocumentContentSniffer.cs:197-211): strips an optional UTF-8 BOM, then rejects empty content, any embedded NUL byte, or anything Utf8.IsValid rejects.
  • TryResolve/MatchesSignature/Extension (DocumentContentSniffer.cs:216-267): the private glue that looks up the extension, checks it against allowed, and routes to the right signature check.
• Why it's built this way: requiring extension and signature to agree stops both a renamed executable and a correctly-named file with forged content; reading only zip entry names (never opening entry streams) and capping inspected entries at 4096 make the Office Open XML check itself resistant to a zip bomb rather than merely fast.
• Where it's used: UploadSessionAssetHandler and UploadSessionAssetCommandValidator call Detect to accept or reject an uploaded document (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.Application/SessionAssets/UseCases/UploadFile/UploadSessionAssetCommandValidator.cs:1, UploadSessionAssetHandler.cs:1); SessionAssetValidationRules and SessionAssetLimits also reference it (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.Application/SessionAssets/Validation/SessionAssetValidationRules.cs:1, MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.Shared/SessionAssets/SessionAssetLimits.cs:1). It has its own dedicated unit-test class (MMCA.Common/Tests/Core/MMCA.Common.Application.Tests/DocumentContentSnifferTests.cs).

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); FileUploadOptions; 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 three 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).
  • UploadAsync(string blobName, Stream content, string contentType, FileUploadOptions options, CancellationToken cancellationToken = default) (IFileStorageService.cs:37): the overload a document upload wants, storing the response headers carried by FileUploadOptions (a Content-Disposition, for example, is what makes a stored blob come back as a download under its original file name). It has no default body: every implementation must honor the headers directly rather than falling back to the three-argument overload. It carries a SuppressMessage for analyzer RS0026 (multiple public overloads with optional parameters) (IFileStorageService.cs:36): the justification records it as a grandfathered public overload shipped after the v1.152 public-API baseline, so changing its signature would be a breaking change.
  • DeleteAsync(string blobName, CancellationToken cancellationToken = default) (IFileStorageService.cs:43): deletes a blob; unknown names succeed (idempotent, IFileStorageService.cs:39), 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. The headers-aware overload is a plain interface member with no default implementation (IFileStorageService.cs:37), so every IFileStorageService implementation is forced to honor the response headers rather than silently dropping them via a forwarding default.
• Where it's used: SetUserAvatarHandler uploads the normalized JPEG (SetUserAvatarHandler.cs:30 for the injection, :117 for the call). Deletes run through DeleteBlobInternalCommandHandlerBase<TCommand>, which takes the service (MMCA.Common/Source/Core/MMCA.Common.Application/InternalCommands/DeleteBlobInternalCommandHandlerBase.cs:29) and calls DeleteAsync (DeleteBlobInternalCommandHandlerBase.cs:45): DeleteAvatarBlobInternalCommandHandler derives from it (DeleteAvatarBlobInternalCommandHandler.cs:20) and is the cleanup side scheduled by SetUserAvatarHandler, RemoveUserAvatarHandler and DeleteUserHandler. UploadSessionAssetHandler uses the headers-aware overload for document uploads (UploadSessionAssetHandler.cs:166), with DeleteSessionAssetBlobInternalCommandHandler on its cleanup side (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.Application/SessionAssets/UseCases/DeleteSessionAssetBlob/DeleteSessionAssetBlobInternalCommandHandler.cs:20). NullFileStorageService is the default registration (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:336); AzureBlobFileStorageService replaces it when configured (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.Notifications.cs:139).

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:29 for the injection, :71 for the call). Implemented by ImageSharpImageProcessor, registered with TryAddSingleton (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:337); note this is the one member of the avatar trio with a real default implementation rather than a null object.

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:349-359), which calls services.Configure<EntityConfigurationOptions> with a contains-check so an assembly is added at most once (DependencyInjection.cs:351-357); AddNotificationInfrastructure() (DependencyInjection.Notifications.cs:26-31) 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). A second property, EnableSensitiveDataLogging, defaults to false (PersistenceSettings.cs:44) and asks EF to render parameter VALUES into its logs and exception messages (EnableSensitiveDataLogging, PersistenceSettings.cs:25-26); SensitiveDataLoggingGate is the class that decides whether the request is actually honored.
• 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). EnableSensitiveDataLogging is deliberately a request, not a switch: the doc comment is explicit that setting it true matters only when the host also reports the Development environment, and a host with no IHostEnvironment registered (design time, a directly-constructed test context) counts as not Development (PersistenceSettings.cs:29-34), so the flag cannot by itself put parameter values (customer data, tokens, password hashes) into a log sink in Staging or Production (ADR-122). The flag also does not by itself make EF log statements: the doc comment pairs it with setting Logging:LogLevel:Microsoft.EntityFrameworkCore.Database.Command to Information in appsettings.Development.json only (PersistenceSettings.cs:37-41).
• Where it's used: bound in the infrastructure registration (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:144-147) and read by SQLServerDbContext for the command timeout; no other engine context reads that property today. EnableSensitiveDataLogging is read by SensitiveDataLoggingGate, which ApplicationDbContext calls from ConfigureSensitiveDataLogging (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/ApplicationDbContext.cs:367-375) so the guarantee applies on the shared base rather than per engine.

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-62, 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:196). Behavior is pinned by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/ProfilingHelperTests.cs.

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:59) and resolved by ApplicationDbContext, which iterates its assemblies inside ApplyConfigurationsForEntitiesInContext (ApplicationDbContext.cs:954,973). Covered by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/DefaultEntityConfigurationAssemblyProviderTests.cs.

EfCoreConcurrencyConflictDetector

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

• What it is: the shipped implementation of IConcurrencyConflictDetector. Given the exception a failed save threw, it answers whether the failure was an optimistic-concurrency conflict (a row-version mismatch), the same role SqlServerUniqueConstraintViolationDetector plays for unique-constraint violations, but for a condition EF itself already classifies rather than one that has to be inferred from a provider error number.
• Depends on: IConcurrencyConflictDetector (the Application-layer contract it implements) and Microsoft.EntityFrameworkCore.DbUpdateConcurrencyException.
• Concept introduced, classifying a framework exception without leaking it past Application. [Rubric §3, Clean Architecture] (provider and framework vocabulary stays out of Application) and [Rubric §29, Resilience & Business Continuity] (a lost optimistic-concurrency race becomes a deterministic conflict answer rather than an unhandled exception): DbUpdateConcurrencyException is an EF Core type, so a handler cannot catch it directly without referencing EF; this detector is the one place that does, behind the same abstraction the unique-constraint detector uses.
• Walkthrough: one method, IsConcurrencyConflict(Exception exception) (EfCoreConcurrencyConflictDetector.cs:20-31). A for loop walks the exception chain (current = exception, then current.InnerException) and returns true on the first link that is a DbUpdateConcurrencyException (:22-28), false once the chain is exhausted (:30). Unlike SqlServerUniqueConstraintViolationDetector there is no provider-number or message fallback: EF raises DbUpdateConcurrencyException directly when a SaveChanges call affects zero rows for a concurrency-token-checked entity, so no wrapping or translation step needs covering.
• Why it's built this way: sealed and stateless, so it can be registered as a singleton. The chain walk exists because SaveChangesAsync can be called from inside a transaction helper that wraps the original exception; checking only the outermost exception would miss that case.
• Where it's used: registered as the singleton IConcurrencyConflictDetector via TryAddSingleton (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:126). Covered by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/EfCoreConcurrencyConflictDetectorTests.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:111) 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> hands mapping to the engine (EntityTypeConfiguration.cs:77), which uses it for the SQL table schema (SQLServerDataSourceEngine.cs:101, PostgreSQLDataSourceEngine.cs:100, falling back to dbo) and the Cosmos container name (CosmosDataSourceEngine.cs:95, 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.

SensitiveDataLoggingGate

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/SensitiveDataLoggingGate.cs:24 · Level 1 · class (static)

• What it is: the one-method static class that answers whether EF Core is allowed to render parameter VALUES into its logs and exception messages. It is the enforcement point for the and-gate PersistenceSettings.EnableSensitiveDataLogging documents: the setting alone is a request, this gate is what turns it into an actual true.
• Depends on: PersistenceSettings (the setting it reads) and Microsoft.Extensions.Hosting.IHostEnvironment (IsDevelopment()).
• Concept introduced, fail-closed AND-gating of a dev-only relaxation. [Rubric §17, Security & Compliance] and [Rubric §29, Resilience & Business Continuity]: a configuration value that leaks into a Staging or Production file, container image, or environment variable must not by itself enable logging of parameter values (customer data, tokens, password hashes). Requiring both the setting AND IHostEnvironment.IsDevelopment() means either absence, including a host that registers no IHostEnvironment at all (design time, a directly-constructed test context), reads as "off" (ADR-122).
• Walkthrough: IsEnabled(PersistenceSettings? settings, IHostEnvironment? environment) (SensitiveDataLoggingGate.cs:33-34) is one expression: settings?.EnableSensitiveDataLogging == true && environment?.IsDevelopment() == true. Both parameters are nullable and both null-conditional comparisons resolve to false rather than throwing, so a caller that could not resolve either dependency from DI still gets a safe answer instead of a NullReferenceException.
• Why it's built this way: static because the method is a pure function of its two inputs with no state to hold; comparing with == true rather than ?? false keeps the short-circuit reading left to right as "did the host ask, AND is it Development".
• Where it's used: called from ApplicationDbContext's ConfigureSensitiveDataLogging (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/ApplicationDbContext.cs:369-371), which calls optionsBuilder.EnableSensitiveDataLogging() only when the gate returns true (ApplicationDbContext.cs:373); the method sits on the shared base rather than in each engine's context class so the guarantee holds identically for every engine. Covered by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/SensitiveDataLoggingGateTests.cs.

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:121), which the module registrations rely on rather than shipping their own pair (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.Infrastructure/DependencyInjection.cs:28). 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:20, .../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.

SoftDeleteFilterSql

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

• What it is: the internal static class that owns the soft-delete index predicate for unique and opted-in indexes. It resolves which column carries the flag, hands that column to the target engine to spell the predicate, recognises when an index filter already carries that predicate, and quotes a single column name the way the engine expects. It is the single authority both the automatic convention and the hand-authored opt-in call, so the two can never disagree (SoftDeleteFilterSql.cs:9-17).
• Depends on: DataSource (the engine enum), DataSourceEngines and IDataSourceEngine (the per-engine strategy that owns the quoting and the predicate spelling), 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 entry point 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 asking the engine strategy for the spelling fixes both, and putting that entry point in one place means the automatic path (SoftDeleteUniqueIndexConvention) and the opt-in path (IndexBuilderExtensions) emit byte-identical SQL. The engine-specific text itself no longer lives in this class: it is one member per engine on IDataSourceEngine, so this class carries no switch over DataSource.
• Walkthrough:
  • Build(DataSource engine, IReadOnlyEntityType entityType) (SoftDeleteFilterSql.cs:35-36) is one expression: DataSourceEngines.For(engine).BuildSoftDeleteFilter(ColumnName(entityType)). The private ColumnName helper (:72-74) 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. The engine then answers the spelling: SQL Server [Column] = 0 (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DataSources/Engines/SQLServerDataSourceEngine.cs:117), PostgreSQL "Column" = false (PostgreSQLDataSourceEngine.cs:116), because it maps the flag to a real boolean column and refuses to compare one with an integer, the only place the predicate differs by engine beyond quoting (SoftDeleteFilterSql.cs:29-34), Sqlite "Column" = 0 (SqliteDataSourceEngine.cs:115), and Cosmos null (CosmosDataSourceEngine.cs:117), since it has no filtered-index support. null is the contract for "leave the index untouched", and both callers check it before doing anything (SoftDeleteUniqueIndexConvention.cs:58-59, IndexBuilderExtensions.cs:59-60).
  • ContainsPredicate(string existingFilter, IReadOnlyEntityType entityType) (SoftDeleteFilterSql.cs:53-60) answers the idempotence question: does a filter already declared on an index constrain the soft-delete column? Both the integer spelling ({column} = 0) and the PostgreSQL boolean spelling ({column} = false) are checked, each pushed through Normalize (:77-78), which strips whitespace and the three identifier quoting styles ([, ], " and a backtick), so a hand-authored [IsDeleted] = 0, a "IsDeleted"=0, the PostgreSQL "IsDeleted" = false and the predicate Build produces all count as the same clause. Without that normalization, and without checking both spellings, the convention could append its own predicate to a filter that already had one, or append the integer and boolean spellings of the same predicate to one another.
  • QuoteColumn(DataSource engine, string column) (SoftDeleteFilterSql.cs:70-71) forwards to DataSourceEngines.For(engine).QuoteColumn(column): brackets on SQL Server, the SQL-standard double-quoted form on PostgreSQL (which rejects brackets) and SQLite (:61-68). It exists for filtered-index predicates over columns other than IsDeleted, such as an IS NOT NULL clause.
• Why it's built this way: internal static with a nullable Build return keeps the engine-capability decision out of the call sites; delegating the spelling to the engine strategy keeps the per-engine text in one place per engine rather than in a switch here. 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 (SoftDeleteUniqueIndexConvention.cs:57,75), and IndexBuilderExtensions calls Build for a hand-authored index (IndexBuilderExtensions.cs:58). QuoteColumn is called by PushNotificationConfiguration for its DedupKey IS NOT NULL filter (PushNotificationConfiguration.cs:73) and by ApplicationDbContext through a private wrapper (ApplicationDbContext.cs:619-620) for the outbox and internal-command partial-index predicates (ApplicationDbContext.cs:665-666,755-756).
• Caveats / not-in-source: a fifth engine would need its own IDataSourceEngine implementation to answer BuildSoftDeleteFilter and QuoteColumn; how DataSourceEngines.For (DataSourceEngines.cs:40) treats an unmapped value is not covered by this section.

EFRawSqlQueryExecutor

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

• What it is: the EF Core implementation of IRawSqlQueryExecutor, the Application-layer escape hatch for a query that is easier to express as literal SQL than as a specification. It builds a parameterized IQueryable<T> from an interpolated FormattableString over the host's default physical data source, then either lists or single-or-defaults it (EFRawSqlQueryExecutor.cs:8-26).
• Depends on: IRawSqlQueryExecutor (the Application-layer contract it implements), IDbContextFactory, IDataSourceResolver, and Microsoft.EntityFrameworkCore (Database.SqlQuery<T>, EntityFrameworkQueryableExtensions).
• Concept introduced, an escape hatch that is absent, not refused, on the wrong engine. [Rubric §3, Clean Architecture] (the raw-SQL surface is still an abstraction, not a direct DbContext reference from Application) and [Rubric §8, Data Architecture] (a relational-only capability is never silently mis-executed on Cosmos): the class itself carries no engine check. The engine gate lives at registration: AddRawSqlQueryExecutor resolves the framework default engine and registers the executor only when DataSourceEngines.For(defaultEngine).Capabilities.IsRelational (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:402-415). A Cosmos-default host therefore has no IRawSqlQueryExecutor at all, so a service that injects it fails when the container validates rather than on its first statement (EFRawSqlQueryExecutor.cs:19-25).
• Walkthrough: a primary constructor takes IDbContextFactory and IDataSourceResolver (EFRawSqlQueryExecutor.cs:29-31). QueryAsync<T>(FormattableString sql, CancellationToken) (:33-34) and QuerySingleOrDefaultAsync<T>(...) (:37-38) both call the private SqlQueryable<T>(sql) and materialize it with ToListAsync/SingleOrDefaultAsync. SqlQueryable<T> (:46-52) null-guards sql (:48), resolves the default source with dataSourceResolver.ResolveLogical(DataSource.SQLServer, DataSourceKey.DefaultName) (:50), the same way the framework's own tables resolve theirs, letting the resolver substitute the engine a single-engine host actually configured (:13-15), and returns dbContextFactory.GetDbContext(dataSourceKey).Database.SqlQuery<T>(sql) (:51), EF's own parameterized raw-SQL queryable, composable with further LINQ before materialization. Because the context comes from the scoped factory, the statement shares the caller's connection and any transaction an ITransactional command opened (:16-17).
• Why it's built this way: internal sealed, with no engine branching in the body, so the relational-only constraint is decided once, at composition, from the engine's declared capabilities rather than re-checked on every call. The FormattableString parameter is the parameterization guarantee: interpolated values become SQL parameters through EF's own handling, not string-concatenated SQL (ADR-125).
• Where it's used: registered as the scoped IRawSqlQueryExecutor via TryAddScoped (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.cs:413), the helper being invoked from the infrastructure registration at DependencyInjection.cs:116. Covered by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/EFRawSqlQueryExecutorTests.cs, and named by MMCA.Common/Tests/Architecture/MMCA.Common.Architecture.Tests/Governance/DataSourceBranchingFitnessTests.cs.

UnitOfWork

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/UnitOfWork.cs:20 · 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:20-24): takes the context factory, the data-source service, the repository factory, and an optional IUniqueConstraintViolationDetector (default null), null-guarding the context factory and the repository factory into readonly fields (UnitOfWork.cs:26-27; the data-source service and the detector are used directly from the primary-constructor parameters).
  • IsUniqueConstraintViolation (UnitOfWork.cs:39-40): the type also implements IUniqueConstraintViolationDetector and forwards to the host's registered detector, returning false when none is registered. This lets a framework handler base that only holds the unit of work recognise a save that lost an insert race without taking a new constructor dependency (which would break every subclass); with no detector the exception propagates unchanged.
  • _repositories (UnitOfWork.cs:34): 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:48-61): on a cache miss, resolves the entity's DataSourceKey via dataSourceService.GetDataSourceKey(typeof(TEntity)) (UnitOfWork.cs:55), asks the context factory for the matching context (:56), and builds a read-write IRepository<TEntity, TIdentifierType> through IRepositoryFactory (:57); constrained to AuditableAggregateRootEntity<TIdentifierType> so only aggregate roots get a mutable repository.
  • GetReadRepository<TEntity, TIdentifierType>() (UnitOfWork.cs:68-81): the same resolution but calls CreateReadOnly (:77) and accepts any AuditableBaseEntity<TIdentifierType>, returning IReadRepository<TEntity, TIdentifierType> for query handlers.
  • Save and transaction methods (UnitOfWork.cs:84-94): SaveChangesAsync (:84-85), RequestExplicitKeyInsert (:88), and ExecuteInTransactionAsync (:91-94) 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. RequestExplicitKeyInsert forwards to IDbContextFactory.RequestExplicitKeyInsert(), the engine-neutral signal that the next save may carry explicit values for store-generated keys: each context's engine decides whether those inserts need a per-table toggle (its IExplicitKeyInsertDialect), an engine with none saves unchanged, and the flag clears after the save (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Factory/IDbContextFactory.cs:34-40). There is no synchronous Save and no manual begin/commit/rollback on this type.
  • Disposal (UnitOfWork.cs:96-122): implements both Dispose (:96-100) and DisposeAsync (:102-110) over a volatile bool _disposed flag (UnitOfWork.cs:36), 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:130) 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:25 · 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:82, 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:28): 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:35): 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:48): 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:42-47 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:54,61,69): all nullable. A property carrying PiiAttribute stores the redaction placeholder on both sides instead of its value (AuditTrailEntry.cs:59,67).
  • Operation (AuditTrailEntry.cs:76): 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:82,85,93,101): 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:154).
  • Row shape (AuditTrailEntry.cs:17-23): 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:848-877) to dbo.AuditTrailEntries (ApplicationDbContext.cs:857) 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:859-865), plus two indexes: IX_AuditTrailEntries_Entity over (EntityType, EntityKey, ChangedOn) for the read path and IX_AuditTrailEntries_ChangedOn for the retention sweep (ApplicationDbContext.cs:866-875). The mapping only happens when AuditTrail:Enabled is true: the context resolves that flag once in OnConfiguring (ApplicationDbContext.cs:332) and ConfigureAuditTrail returns immediately when it is false (ApplicationDbContext.cs:850-853), so a host that never opted in has exactly the model it had before the trail shipped (ApplicationDbContext.cs:84-88).

CaptureContext

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.AuditTrail · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/AuditTrail/AuditTrailSaveChangesInterceptor.cs:663 · 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:663-667. It is constructed exactly once per capture, in CaptureChanges (AuditTrailSaveChangesInterceptor.cs:191-195), where the trace id and tenant are already truncated to their column widths through ColumnWidth.Truncate (MaxCorrelationIdLength 64 and MaxTenantIdLength 64, AuditTrailSaveChangesInterceptor.cs:82,85). It is then passed by value into CaptureEntry and CaptureModifiedProperties, which copy its fields straight onto each new AuditTrailEntry (AuditTrailSaveChangesInterceptor.cs:270-273,327-330).
• 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.

PermissionGrantModelGate

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.Auth · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Auth/PermissionGrantModelGate.cs:19 · Level 0 · class (internal sealed)

• What it is: an empty marker class registered as a singleton whose sole purpose is its own presence in the service provider. ApplicationDbContext asks whether one is registered to decide whether to map the PermissionGrants table on this instance (PermissionGrantModelGate.cs:19).
• Depends on: nothing; it carries no members.
• Concept introduced, presence-as-opt-in, the refresh-session precedent applied to a second table. [Rubric §8, Data Architecture] (assesses whether the mapped model is a deliberate decision) and [Rubric §11, Security] (whether stored permission grants are an explicit choice rather than an always-on table). ApplicationDbContext.ResolvePermissionGrantGate reads serviceProvider.GetService<PermissionGrantModelGate>() is not null (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/ApplicationDbContext.cs:915) and ANDs it with a check that this context's physical source name matches Authentication:PermissionGrants:DataSourceName (ApplicationDbContext.cs:916-919). Registering the class IS the opt-in the context reads: no flag, no boolean setting, just whether the type was registered at all. This is the same mechanic RefreshSessionModelBuilderExtensions's gate uses for the RefreshSessions table, applied to a second framework-owned table.
• Walkthrough: internal sealed class PermissionGrantModelGate; (PermissionGrantModelGate.cs:19), a single empty declaration with no members, no constructor logic, and nothing to walk through beyond its own existence.
• Why it's built this way: an empty class is the cheapest possible presence check: no state to get out of sync, no boolean to forget to flip back, and TryAddSingleton makes registering it twice free. A dedicated marker type (rather than reusing, say, an IOptions<PermissionGrantSettings> presence check) keeps "the table is mapped" and "the settings are bound" as two independently answerable questions, since a host could bind the settings section without ever calling AddStoredPermissionGrants.
• Where it's used: registered as a singleton by AddStoredPermissionGrants (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.Auth.cs:147), read by ApplicationDbContext.ResolvePermissionGrantGate (ApplicationDbContext.cs:914-919) and by ConfigurePermissionGrants which calls PermissionGrantModelBuilderExtensions.ApplyPermissionGrantConfiguration behind that gate. Covered by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/DbContexts/PermissionGrantModelGateTests.cs and referenced by design-time tooling in MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/Design/DesignTimeDbContextHelper.cs.

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:94, :291) that the model builder consults before mapping the entity (ApplicationDbContext.cs:848-853), 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.Jobs.cs:104-106).

• 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:332) and re-checked by the cleanup job before it does any work (AuditTrailCleanupJob.cs:68-71).
  • RetentionDays (AuditTrailSettings.cs:38), [Range(1, 3650)] (:37), default 90. AuditTrailCleanupJob turns it into a cutoff instant (AuditTrailCleanupJob.cs:73) 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.Jobs.cs:124) but a job only runs when the host also calls AddScheduledJobs(configuration) and sets Scheduler:Enabled (DependencyInjection.Jobs.cs:97-101). 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.Jobs.cs:121-123).

• Where it's used: bound with .ValidateDataAnnotations().ValidateOnStart() at DependencyInjection.Jobs.cs:110-113, 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:47-54, 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:165-166). The recording itself is AuditTrailSaveChangesInterceptor, registered as a singleton at DependencyInjection.Jobs.cs:117 and resolved by the context with GetService so its absence reads as "not registered" (ApplicationDbContext.cs:319). 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:672 · 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:276-279). 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:672. Instances are produced by CaptureEntry only when the entry is Added and HasTemporaryKey(entry) returns true (AuditTrailSaveChangesInterceptor.cs:280-282, 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:94,215-218), 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.

PermissionGrantRefreshService

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.Auth · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Auth/PermissionGrantRefreshService.cs:31 · Level 1 · class (internal sealed partial, PeriodicBackgroundService)

• What it is: the background loop that keeps PermissionGrantCache warm. It calls RefreshAsync on an interval for the lifetime of the host, so the cache never goes stale by more than one PermissionGrants:CacheSeconds window (PermissionGrantRefreshService.cs:31-63).
• Depends on: IPermissionGrantCache (the interface it refreshes through, not the concrete PermissionGrantCache directly), IOptions<PermissionGrantSettings>, ILogger<PermissionGrantRefreshService>, an optional TimeProvider, and PeriodicBackgroundService it extends (PermissionGrantRefreshService.cs:31-36).
• Concept introduced, a cache that survives its own reload failing. [Rubric §29, Resilience & Business Continuity] (assesses whether a background loop degrades rather than crashes the host) and [Rubric §13, Observability & Operability] (a failed reload is logged, not silent). The class remarks state the direction deliberately (PermissionGrantRefreshService.cs:13-17): a failed load is logged and retried, never fatal, because a database blip must degrade authorization to "no stored grants" rather than take the host down.
• Walkthrough: the whole interval loop, its cancellation handling and its catch-log-continue behavior live once in PeriodicBackgroundService; this type supplies only four overrides. Interval returns _settings.CacheSeconds (PermissionGrantRefreshService.cs:41). StartupDelay returns TimeSpan.Zero (:44-47): the snapshot is primed immediately at startup, because until the first load authorization sees no stored grants at all, unlike RefreshSessionCleanupService, whose first sweep waits a full interval. ExecuteCycleAsync is one line, cache.RefreshAsync(stoppingToken) (:54), and LogCycleFailure routes a cycle's exception to the source-generated LogRefreshFailed message (:57, :59-62); the base class is what turns a thrown exception there into "log and keep looping" rather than a host crash.
• Why it's built this way: registering it through TryAddEnumerable rather than AddHostedService (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/DependencyInjection.Auth.cs:161-164) is what keeps two modules calling AddStoredPermissionGrants from starting two refresh loops in one process, the same idempotent-registration discipline RefreshSessionCleanupService and AuditTrailCleanupJob use for their own recurring work. Catching broadly and logging rather than crashing follows ADR-116: a stored-grant feature that takes the host down on a transient database fault would be worse than the fallback it exists to layer over.
• Where it's used: registered as a singleton IHostedService by AddStoredPermissionGrants (DependencyInjection.Auth.cs:163-164), started and stopped by the generic host alongside every other BackgroundService. Its only collaborator is PermissionGrantCache through IPermissionGrantCache.RefreshAsync.

RefreshSessionModelBuilderExtensions

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.Auth · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Auth/RefreshSessionModelBuilderExtensions.cs:16 · Level 4 · class (public static)

• What it is: the single place the RefreshSessions table is mapped. One extension method, ApplyRefreshSessionConfiguration(this ModelBuilder, string? schema = "dbo"), configures the RefreshSession entity: table, key, column widths and the two indexes the auth flows read through (RefreshSessionModelBuilderExtensions.cs:16-75).
• Depends on: RefreshSession from MMCA.Common.Domain.Auth (including its length constants) and EF Core's ModelBuilder.
• Concept introduced, the opt-in framework table. [Rubric §8, Data Architecture] assesses whether each database holds exactly the data it owns, and [Rubric §11, Security] assesses whether credential storage is designed rather than incidental. The framework owns two kinds of table. The outbox is cross-cutting: every relational source needs one, so it is configured on ApplicationDbContext unconditionally and every module's database gets it. Refresh sessions are the other kind: they are Identity-module data, exactly one database owns them, and mapping them everywhere would put an empty RefreshSessions table in every other module's migrations. The class doc draws that contrast explicitly (RefreshSessionModelBuilderExtensions.cs:8-14). Keeping the mapping in a callable extension method rather than inlining it in a context is what makes "one database, chosen by configuration" expressible at all.
• Walkthrough
  • Three public constants name the objects so tests and callers do not restate strings: TableName = "RefreshSessions" (RefreshSessionModelBuilderExtensions.cs:19), TokenHashIndexName (:22) and UserIndexName (:25).
  • The method null-guards, maps the table with the caller's schema defaulting to dbo (RefreshSessionModelBuilderExtensions.cs:36-40), and keys on Id (:41).
  • TokenHash is IsRequired, HasMaxLength(RefreshSession.TokenHashLength), IsUnicode(false), IsFixedLength() (RefreshSessionModelBuilderExtensions.cs:45-49). The constant is 64 (MMCA.Common/Source/Core/MMCA.Common.Domain/Auth/RefreshSession.cs:46), the length of a SHA-256 digest rendered as hex. The comment at :43-44 gives the reason for the three facets: the value is always a 64-character hex digest, so a Unicode or variable-width column would double the index it has to fit in for nothing.
  • ReplacedByTokenHash gets the same three facets minus IsRequired (RefreshSessionModelBuilderExtensions.cs:51-54), because it is null until the session is rotated.
  • ReasonRevoked, IpAddress and UserAgent take their lengths from the domain constants (64, 45 and 512 at RefreshSession.cs:55, :37, :40), the first two non-Unicode (RefreshSessionModelBuilderExtensions.cs:56-58). 45 is the length of a full IPv6 text form; UserAgent stays Unicode because a user-agent string is arbitrary client text.
  • The unique index over TokenHash (RefreshSessionModelBuilderExtensions.cs:64-66) is the validation path: every refresh presents a token and must be answered by exactly one row. The comment at :60-63 gives two reasons for the uniqueness, and both are security reasons rather than performance ones: a hash collision across users would let one account's token validate against another's session, and a double-insert of the same token becomes a database error instead of an ambiguity the reuse check has to resolve.
  • The composite index on (UserId, RevokedAt) (RefreshSessionModelBuilderExtensions.cs:70-71) serves the family question, "every live session for this user", which is asked on the per-user session cap, on reuse detection and on sign-out-everywhere. Without it each of those scans the table (:68-69).
  • The builder is returned for chaining (RefreshSessionModelBuilderExtensions.cs:74).
• Why it's built this way: hashing the token rather than storing it, and rotating per device, is ADR-097, which supersedes the single-plaintext-column storage model of ADR-050 while keeping its rotation and reuse-detection policy. The column shapes here are what make that model cheap: a fixed-width non-Unicode digest keeps the unique index narrow, and the two indexes are exactly the two questions the auth service asks. Nothing here is soft-deletable and nothing is audit-stamped, which is deliberate and is why the table needs its own mapping method rather than riding the module entity-configuration mechanism.
• Where it's used: called by ApplicationDbContext from ConfigureRefreshSessions (MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/DbContexts/ApplicationDbContext.cs:893-901) behind the two-part gate computed in the constructor: RefreshSessions:Enabled is true and this context's physical source name equals RefreshSessions:DataSourceName (ApplicationDbContext.cs:336-339). At design time the same gate is fed by DesignTimeDbContextOptions.EnableRefreshSessions. Covered by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/Auth/RefreshSessionModelBuilderExtensionsTests.cs and, for the gate itself, .../Persistence/DbContexts/RefreshSessionModelGateTests.cs:89.
• Caveats / not-in-source: the class doc says the consumer's Identity context calls this from its own OnModelCreating (RefreshSessionModelBuilderExtensions.cs:12-13), which describes an earlier arrangement. The base context now calls it directly behind the gate, and the doc on ConfigureRefreshSessions explains why (ApplicationDbContext.cs:884-891): downstream apps run on the sealed engine contexts and have no context class to override (ADR-006). Calling it by hand remains supported for a host that does have its own context class; trust the context, not the older sentence.

PermissionGrantModelBuilderExtensions

MMCA.Common.Infrastructure · MMCA.Common.Infrastructure.Persistence.Auth · MMCA.Common/Source/Core/MMCA.Common.Infrastructure/Persistence/Auth/PermissionGrantModelBuilderExtensions.cs:15 · Level 4 · class (public static)

• What it is: the single place the PermissionGrants table is mapped. One extension method, ApplyPermissionGrantConfiguration(this ModelBuilder, string? schema = "dbo"), configures the PermissionGrant entity: table, key, column widths, and the unique index that makes a grant idempotent (PermissionGrantModelBuilderExtensions.cs:15-64).
• Depends on: PermissionGrant from MMCA.Common.Domain.Auth (including its RoleMaxLength/PermissionMaxLength constants) and EF Core's ModelBuilder.
• Concept introduced, the same opt-in-table mapping shape as refresh sessions, applied to a second framework table. [Rubric §8, Data Architecture] and [Rubric §11, Security] (assesses whether stored authorization data is deliberately keyed and constrained). The class sits beside RefreshSessionModelBuilderExtensions in Persistence.Auth and follows the identical pattern: a callable extension method rather than an inline mapping in a context, so the table only appears in a host's model when something calls it.
• Walkthrough
  • Two public constants: TableName = "PermissionGrants" (PermissionGrantModelBuilderExtensions.cs:18) and RolePermissionIndexName = "IX_PermissionGrants_Role_Permission" (:117).
  • The method null-guards, maps the table with the caller's schema defaulting to dbo (:126-132), and keys on Id (:133).
  • Role and Permission are both IsRequired, length-bounded by the domain's own RoleMaxLength/PermissionMaxLength, and IsUnicode(false) (:137-145): the comment gives the reason, role and permission names are ASCII identifiers by convention, so a Unicode column would double the index width for nothing.
  • GrantedBy gets HasMaxLength(256) and nothing else (:147), since it is nullable provenance, not a validated identifier.
  • The unique index over (Role, Permission) (:153-155) is what makes granting the same permission to the same role twice a no-op rather than a duplicate row: the comment frames a grant as set membership, not a log, so two rows saying the same thing mean nothing extra and would turn "revoke" into a question of how many rows to delete (:149-152). It is also what lets EFPermissionGrantStore's idempotent grant rely on the database rather than a read-then-write race.
  • The builder is returned for chaining (:158).
• Why it's built this way: ADR-116 layers stored grants over the compiled IPermissionRegistry as a union-only decorator, and the column shapes here are what make that layer cheap to query: a non-Unicode fixed-shape pair with one unique index answers both "does this role have this permission" reads and idempotent writes without a second lookup.
• Where it's used: called by ApplicationDbContext.ConfigurePermissionGrants behind PermissionGrantModelGate's presence check plus the physical-source match (ApplicationDbContext.cs:914-929). Covered by MMCA.Common/Tests/Core/MMCA.Common.Infrastructure.Tests/Persistence/Auth/PermissionGrantModelBuilderExtensionsTests.cs and .../Persistence/DbContexts/PermissionGrantModelGateTests.cs, and consumed by EFPermissionGrantStore through the DbSet<PermissionGrant> the mapping creates.