.NET Persistence

Infrastructure implements each Domain repository with the scoped session, so the handler stages work without naming a provider type. A repository that exposed the session, a generic query, or a save operation would hand the handler the provider surface the layer exists to hide. This provision binds litespec/backend/persistence#stage-aggregate-writes-through-domain-repositories for .NET.

Checked bydotnet build reports LS2004 for a command handler writing through a document session or database context.

Marked checkable: the tool named here checks it.

The read session already filters, orders, pages, and projects; a read-store interface per aggregate, a generic read repository, or a callback wrapper adds a layer that repeats it. Ordering and paging follow litespec/backend/api#bound-collection-queries. This provision binds litespec/backend/persistence#query-through-the-read-session for .NET.

The table names the binding per provider. The obligation to project with filter, scope, ordering, and limit holds under each.

A table the project keeps beside its documents, such as a counter or an append-only ledger written through plain SQL, is read through the same session. Under Marten, AdvancedSql.QueryAsync<TRow> returns any JSON-serializable type, so the SQL selects one JSON object per row, keyed in the casing the store's serializer uses, with the filter, ordering and limit in its WHERE, ORDER BY and LIMIT. The handler keeps no repository for such a table, and the project adds no read interface for it.

In the Claimwick product, each spending owner's running totals live in a spending_totals table that a command updates in place. The read-spending-totals query reads it through the session:

internal sealed record SpendingTotalRow(Guid OwnerId, string Currency, decimal Submitted, decimal Approved);

var rows = await session.AdvancedSql.QueryAsync<SpendingTotalRow>(
    """
    select jsonb_build_object(
        'ownerId', owner_id, 'currency', currency, 'submitted', submitted, 'approved', approved)
    from spending_totals
    where owner_id = ?
    order by currency
    limit 100
    """,
    cancellationToken,
    query.OwnerId.Value);

Reviewed forWhich query handlers project outside IQuerySession, or apply filter, scope, ordering, or limit after materialization? Look at each query handler file.

Marked guidance: a reviewer answers this question.

Exactly one post-handler commits, so a failed command leaves the scoped session uncommitted and no partial work persists. A second committer, in a handler, repository, validator, reaction, job, or endpoint, would store work the pipeline later refuses. This provision binds litespec/backend/persistence#commit-each-command-pipeline-once for .NET.

The obligation is one commit for one pipeline, not one named method. Under the baseline provider that commit is IDocumentSession.SaveChangesAsync. For aggregates the efcore extension names it is DbContext.SaveChangesAsync. The pipeline wraps the call in an explicit transaction when it writes through more than one context. Under consistency: atomic that commit covers everything the handler staged. Other modes split work across commands: each command still commits once, and the job resumes from its cursor or runs the declared compensation.

Reviewed forWhich pipelines commit outside one post-handler file calling SaveChangesAsync? Look at the SaveChangesAsync calls in each pipeline.

Marked guidance: a reviewer answers this question.

A unique index makes the store arbitrate the race at commit, where every concurrent write is visible. The index is declared with options.Schema.For<T>().UniqueIndex, or as a computed index carrying IsUnique, and the index name follows litespec/backend/persistence#use-database-naming-conventions. A record that exists at most once per owner takes a document id equal to the owner id instead, so a second record for the same owner collides on identity. This provision binds litespec/backend/persistence#enforce-uniqueness-in-the-store for .NET.

The payout number is unique per spending owner:

options.Schema.For<PayoutDocument>().UniqueIndex(
    UniqueIndexType.Computed,
    "uq_payout_owner_number",
    x => x.PayoutNumber);

A payout exists at most once per expense, so its document id is the expense id:

// The payout document id equals the expense id: one payout per expense.
session.Store(new PayoutDocument(expense.Id, payoutNumber));

Reviewed forWhich Marten aggregate documents with a uniqueness rule lack a unique index or an owner-derived identity? Look at the store configuration.

Marked guidance: a reviewer answers this question.

Store upserts, so it overwrites a competing claim instead of colliding with it; Insert fails when the key document already exists, which is the arbitration the rule needs. The repository compares the aggregate keys at load with the keys at commit, inserts the added key documents and deletes the removed ones in the same transaction. Marten cannot index elements of a list inside a document, cannot enforce uniqueness across document types, and computed indexes do not work on DateTime or DateTimeOffset members; those cases use the claims document. This provision binds litespec/backend/persistence#claim-a-cross-record-key-at-commit for .NET.

In the library product, each copy barcode belongs to one book, while a book holds its barcodes in a list:

public sealed record BarcodeClaim(string Barcode);

// The claim document id is the barcode text; Insert fails on a duplicate.
session.Insert(new BarcodeClaim(barcode));

Reviewed forWhich cross-record keys bypass the claims document with session.Insert, or use Store on the claims type? Look at each key claim.

Marked guidance: a reviewer answers this question.

The LiteBus.Storage.PostgreSql.PostgreSqlConstraintRefusalClassifier carries the map from index name to refusal code and is registered through UseFaultRefusalClassifierInstance, so the pipeline fault classification turns a unique violation into the use case named conflict refusal under litespec/backend/application#refuse-a-lost-race-as-a-conflict. This provision binds litespec/backend/persistence#map-a-constraint-violation-to-its-refusal for .NET.

The barcode and payout number indexes map to their refusals:

services.UseFaultRefusalClassifierInstance(
    new PostgreSqlConstraintRefusalClassifier(new Dictionary<string, string>
    {
        ["uq_book_barcode"] = "book-barcode-taken",
        ["uq_payout_owner_number"] = "spending.payout-number-taken",
    }));

Reviewed forWhich unique index names lack a conflict refusal code in the PostgreSQL refusal classifier? Look at the service registration.

Marked guidance: a reviewer answers this question.

The store compares the version each command loaded with the version it commits against, so a stale write fails the commit instead of silently overwriting newer work. Each aggregate document type enables it with UseOptimisticConcurrency(true), or one Policies.ForAllDocuments policy covers every aggregate document type at once; no aggregate document type is left without it. This provision binds litespec/backend/persistence#version-every-aggregate for .NET.

The expense document enables the check on its own type:

options.Schema.For<ExpenseDocument>().UseOptimisticConcurrency(true);

Reviewed forWhich Marten aggregate document types skip optimistic concurrency? Look at each document type and the document policy.

Marked guidance: a reviewer answers this question.

A ConcurrencyException names a provider type that Application does not expose. The registered classifier translates it into the use case named conflict refusal, following litespec/backend/application#refuse-a-lost-race-as-a-conflict, so a version race and a uniqueness race reach the caller through the same refusal path. This provision binds litespec/backend/application#refuse-a-lost-race-as-a-conflict for .NET.

Two approvers race on one submitted expense; the loser throws ConcurrencyException at commit, and the classifier returns the approve conflict refusal so the caller re-reads the expense before deciding again.

Reviewed forWhich ConcurrencyException paths at commit escape the use case conflict refusal? Look at the registered classifier.

Marked guidance: a reviewer answers this question.