Persistence

The repository is the only path from a handler to the store, so every write passes a reviewable boundary that loads one aggregate type. Infrastructure implements each repository with the scoped session, and the repository exposes no session, generic query, or save operation. A handler that reached the session directly bypasses aggregate loading and scatters store calls through Application.

Checked bylitespec model check reports repository-unimplemented (level S) for an aggregate a use case changes that has no Infrastructure repository implementing its domain repository.

Marked checkable: the tool named here checks it.

The session already projects, filters, and pages, so a read-store interface per aggregate, a generic read repository, or a callback wrapper adds a layer that only repeats it. Applying filter, scope, ordering, and limit before materialization keeps that work in the database; materializing first loads rows the caller does not see. Ordering and paging follow litespec/backend/api#bound-collection-queries.

Reviewed forWhich query handlers project outside the read session, or apply filter, scope, ordering, or limit after materialization? Look at each query handler body.

Marked guidance: a reviewer answers this question.

One commit point makes the transaction boundary visible: everything the handler staged succeeds or fails together, and a failed command leaves the session uncommitted. If handlers or repositories committed, a later failure in the same pipeline leaves a partial write behind. Handlers, repositories, validators, reactions, jobs, and endpoints commit nothing. A declared consistency mode other than atomic splits work across commands; each command still commits once.

In the Claimwick product, use-case/spending.submit-expense stages the expense through its Domain repository, and one post-handler commits once after the handler returns:

handler stages the expense through its repository
post-handler collects the pending events
post-handler commits the session once

A failed submission leaves the session uncommitted, so no partial expense is stored. Handlers, repositories, validators, reactions, jobs, and endpoints commit nothing.

Reviewed forWhich pipelines commit outside one command post-handler, or which handlers, repositories, validators, reactions, jobs, or endpoints commit? Look at the commit calls in each pipeline.

Marked guidance: a reviewer answers this question.

atomic commits everything the handler staged in one unit of work, citing the rule in cites when changes names more than one aggregate. per-record commits each record's command alone, with the job resuming from its cursor after a failure. compensated commits each step alone, and a failure runs the compensation the step declares. A second commit in one command splits one unit of work across two transactions, so the failure between them leaves a partial write.

The erase-expired-data job commits each expense alone under per-record; the submit-expense command commits its staged aggregates together under atomic.

Reviewed forWhich commands commit outside their record's consistency mode? Look at each commit beside the record's mode.

Marked guidance: a reviewer answers this question.

Pending events leave the process exactly when their write commits, so the post-handler drains the buffer and commits in one place. A public unit-of-work type exposes that mechanics to every handler; the internal buffer keeps it inside the pipeline. Async delivery leaves after the commit succeeds.

Reviewed forWhich repositories skip the internal event buffer, or which event mechanics escape into a public type? Look at the repository staging calls beside the post-handler.

Marked guidance: a reviewer answers this question.

Document types and collection names are storage identity: if they followed code names, renaming a class orphans every stored document. An explicit alias, identifier mapping, and index list keeps storage identity independent of code names, with the store configuration owned in Infrastructure.

Reviewed forWhich stored aggregates lack a stable document alias, typed-identifier mapping, or index list? Look at the store configuration for each aggregate.

Marked guidance: a reviewer answers this question.

Serialization metadata on Domain types couples the business model to one store's format, so changing the format means editing the rules. Infrastructure owns member names, constructors, converters, and polymorphic registration, and Domain stays free of serialization metadata. Every concrete type behind a base or interface is registered, because an unregistered subtype fails at read time.

Registration covers the types this store actually persists. The store that writes a union referenced from another aggregate registers it once, rather than every store that names the referencing type. The store persists no type reachable only through an identifier here, and it needs no registration.

Reviewed forWhich Domain types carry serialization metadata, or which stored JSON contracts escape Infrastructure? Look at the Domain types beside the Infrastructure JSON contract.

Marked guidance: a reviewer answers this question.

Stored JSON member names, required values, and discriminator values are database schema: old documents stay on disk after the code changes. Without a reviewed transformation or an expand-and-contract rollout, a rename or type change makes old documents unreadable. An additive member still defines its behavior for documents written earlier.

An additive change is the only kind that needs no transformation, and it is additive only when every earlier document stays valid. A new member with a defined absent-value behavior qualifies. A new required member, a narrowed type, and a new discriminator value that an earlier reader rejects do not.

Reviewed forWhich renames, removals, type changes, member moves, or discriminator changes lack a reviewed transformation or an expand-and-contract rollout? Look at each stored-contract change.

Marked guidance: a reviewer answers this question.

A document grows with every write to its collection, so an unbounded embedded collection eventually exceeds size limits and slows every load of its aggregate. Data without an accepted business bound belongs in another aggregate, an owned document record, or a separate query-shaped document, depending on the consistency boundary it needs.

Reviewed forWhich aggregate documents embed a collection with no accepted business bound? Look at the embedded collections in each document.

Marked guidance: a reviewer answers this question.

One casing rule lets anyone predict a table or column name from the code type without opening the mapping. Code types keep normal language naming while the mapping layer converts once: under the baseline provider the store configuration sets the casing, and under the efcore extension a naming plugin applies it, so no configuration repeats the rule per entity.

Reviewed forWhich generated database identifiers break snake_case? Look at the schemas, tables, columns, and indexes.

Marked guidance: a reviewer answers this question.

A schema change that runs from a starting replica races every other starting replica, and the winner is nondeterministic. A reviewed step produces the migration artifact, and a deployment step applies that artifact before traffic shifts. Development and disposable integration databases still apply schema automatically.

A tool that alters the schema from application startup is not a reviewed step whichever provider runs it.

Reviewed forWhich hosted schema changes run outside a reviewed step before traffic shifts? Look at the deployment steps beside the startup paths.

Marked guidance: a reviewer answers this question.

Only the pinned PostgreSQL runs the real query planner, constraints, and type behavior. An in-memory substitute proves the test's own model of the database, so a query that passes against it fails in production. HTTP integration through the real host is covered under litespec/backend/testing#test-http-integration-through-the-real-application-host.

Reviewed forWhich persistence tests run outside the pinned PostgreSQL, or against an in-memory substitute? Look at the persistence test fixtures.

Marked guidance: a reviewer answers this question.

A query that loads a whole list to filter, sort, or page it in memory pays the full read on every call and breaks when the data grows. Repository list methods take the scope and the page and filter in the database, through the shared page request and page shapes.

The list-expenses query passes its employee scope and page to the repository, while a handler applying Where to a ListAsync result is reported.

Checked bylitespec model check reports query-filter-invalid (level A) for a query handler filtering a repository list in memory.

Marked checkable: the tool named here checks it.

A number computed from a count plus one hands two concurrent issues the same legal number. A per-owner counter row taken in the command transaction allocates each number once, whatever races it.

The reimburse-expense command takes its number from the spending payout sequence, never from a list count.

Reviewed forWhich legal document numbers allocate outside a per-owner sequence taken in the command transaction? Look at each number allocation.

Marked guidance: a reviewer answers this question.

The store is the only place that sees every concurrent write, while a check in code sees only its own transaction: two commands that both check and then both write store the same value twice. A unique index or an owner-derived identity makes the second write fail in the store instead. When the rule ignores case or spacing, the stored value is normalized before writing and the index covers the normalized field, so differently cased writes still collide.

In the Claimwick product, each payout carries a legal document number that is unique per spending owner; the store holds a unique index over the owner and number pair, so two concurrent reimbursements collide on the index and the loser ends with the use case conflict refusal instead of sharing one number. In the library product, each book barcode is unique across books; two clerks registering the same barcode at once collide on the barcode unique index, and the second commit refuses with book-barcode-taken.

Reviewed forWhich uniqueness rules lack a store unique index or an owner-derived identity, or index a denormalized field? Look at the store configuration for each rule.

Marked guidance: a reviewer answers this question.

A flag on the aggregate travels with the record it guards, so the rule is checked where the record is changed: the aggregate sees the earlier action in its own state and refuses the repeat or leaves it without effect. A counter or marker kept anywhere else splits the rule from the record, and the two disagree under concurrent writes.

In the library product, a loan charges its overdue fee at most once: the loan records that it charged the fee, and a repeat command finds the flag and refuses with the loan conflict refusal. In the Claimwick product, an expense is reimbursed at most once: the reimbursed state carries the fact, so a second reimbursement finds an expense that is already reimbursed and ends with spending.not-approved.

Reviewed forWhich at-most-once rules live outside their aggregate's state, or which repeats escape the refusal? Look at each such rule beside its aggregate.

Marked guidance: a reviewer answers this question.

Some rules fit no single-record constraint: a value held in a list inside the aggregate, or a value that is unique across two record kinds. For those, the aggregate declares its current keys through UniquenessKeys (see litespec/backend/domain#declare-cross-record-keys-on-the-aggregate), and persistence compares the keys at load with the keys at commit, inserting the added keys and deleting the removed ones in the same transaction, so the database still arbitrates the race.

In the library product, a book holds a list of copy barcodes and each barcode belongs to one book: the book declares each barcode as a key, and the commit that adds a copy claims the new barcode while releasing a removed one. In the Claimwick product, a payout reference that is unique across payouts and adjustments is declared by each aggregate that carries it, so a reference already used by either record blocks the other at commit.

Reviewed forWhich cross-record uniqueness rules miss declared keys, or claim and release them outside the committing transaction? Look at each such rule beside its commit.

Marked guidance: a reviewer answers this question.

A reservation made in a handler runs outside the commit that needs it: it can leak when the command fails later, and it teaches every later handler to coordinate with the store directly. The store enforces the rule at commit through litespec/backend/persistence#enforce-uniqueness-in-the-store and litespec/backend/persistence#claim-a-cross-record-key-at-commit, and the pipeline turns a lost race into the use case conflict refusal under litespec/backend/application#refuse-a-lost-race-as-a-conflict, so the handler carries no reservation, check, or cleanup.

The register-reader handler creates the reader aggregate and stages it through its Domain repository, reserving no card number and checking no registry first. When two registrations race for one card number, the second commit violates the unique index and refuses with the use case conflict, with no reservation or cleanup code in the handler. The submit-expense handler likewise stages the expense and leaves the payout number to the store sequence.

Checked bydotnet build reports LS2016 for a handler whose constructor takes a pipeline-owned type.

Marked checkable: the tool named here checks it.

The pipeline fault classification turns a store fault into the use case named conflict refusal, following litespec/backend/application#refuse-a-lost-race-as-a-conflict. The map keys each unique constraint by name, so the classifier knows which refusal the violation answers. An unmapped violation still fails the commit, but it reaches the caller as a generic conflict that names no rule and suggests no next step. A classifier that builds the code from the lost key, one code per key scope, declares its template in the project file refusals.composed, so the model checks read each code as raised where its key scope is declared.

The barcode unique index is named uq_book_barcode, and the map pairs it with book-barcode-taken: a registration that loses the barcode race refuses with that code. The payout number index is named uq_payout_owner_number, and the map pairs it with the reimburse conflict refusal, so each racing command names the number it lost.

Reviewed forWhich unique constraints lack a conflict refusal mapping for their violating use cases? Look at the fault classification map.

Marked guidance: a reviewer answers this question.

Without a compared version, two commands that load the same aggregate both commit, and the second silently overwrites the first. The store compares the version each command loaded with the version it commits against, so a stale write fails the commit instead of erasing newer work. A failed comparison ends with the use case conflict refusal, following litespec/backend/application#refuse-a-lost-race-as-a-conflict.

Two approvers open the same submitted expense; the first approval commits and moves the version forward, and the second approval fails its version comparison and refuses with the approve conflict instead of overwriting the first decision. In the library product, two clerks extending one loan race the same way, and the loser re-reads the loan before deciding again.

Reviewed forWhich stored aggregates lack a compared version at commit, or which stale writes escape the use case conflict refusal? Look at each stored aggregate beside its commit.

Marked guidance: a reviewer answers this question.