Persistence

Requirement A command handler MUST reach persistence only through a Domain repository, never through the session directly.

Rationale Infrastructure implements each repository with the scoped session. A repository loads one aggregate type and exposes no session, generic query, or save operation.

Requirement A query handler MUST project through the read session, applying filter, scope, ordering, and limit before materialization.

Rationale A read-store interface per aggregate, a generic read repository, or a callback wrapper adds a layer that the session already provides. Ordering and paging follow litespec/backend/api#bound-collection-queries.

Requirement Exactly one global command post-handler MUST commit the session for a command pipeline.

Rationale A failed command then leaves the scoped session uncommitted. Handlers, repositories, validators, reactions, and endpoints never commit.

Example In the library circulation product, use-case/lending.borrow-copy stages the loan and the copy through their Domain repositories, and one post-handler commits once after the handler returns:

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

A failed borrow leaves the session uncommitted, so no partial loan is stored. Handlers, repositories, validators, reactions, and endpoints never commit.

Requirement A repository MUST register each touched aggregate with the internal scoped event buffer that the post-handler drains.

Rationale The post-handler collects pending events before committing, so you need no public unit-of-work type. Best-effort delivery publishes after the commit succeeds.

Requirement Each stored aggregate MUST declare a stable document alias, typed-identifier mapping, and the indexes its accepted queries need.

Rationale A code rename then cannot change a document type or collection name. Infrastructure owns the store configuration.

Requirement Infrastructure MUST own the JSON contract for stored documents, including member names, constructors, converters, and polymorphic registration.

Rationale Domain stays free of serialization metadata. You register every concrete type behind a base or interface, 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 does not persist a type reachable only through an identifier here, and it needs no registration.

Requirement A rename, removal, type change, member move, or discriminator change MUST have a reviewed data transformation or an expand-and-contract rollout.

Rationale JSON member names, required values, and discriminator values are database schema. 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.

Requirement An aggregate document MUST NOT embed a collection that has no accepted business bound.

Rationale Unbounded growth belongs in another aggregate, an owned document record, or a separate query-shaped document, depending on the consistency boundary it needs.

Requirement A PostgreSQL schema, table, column, index, constraint, document alias, or SQL identifier MUST use snake_case.

Rationale Code types keep normal language naming, so the mapping layer performs the conversion once. Under the baseline provider the store configuration sets the casing. Under the efcore extension a naming plugin applies it, so no configuration repeats the rule per entity.

Requirement A hosted environment MUST apply schema changes through a reviewed step before traffic shifts, not from a starting replica.

Rationale Development and disposable integration databases may still apply schema automatically. Replicas competing to alter a schema during startup produce nondeterministic results.

A reviewed step is one that produces an artifact you approve before it runs. A deployment step applies that generated schema migration. A tool that alters the schema from application startup is not a reviewed step whichever provider runs it.

Requirement Repository behavior, projections, mappings, correctness indexes, commit behavior, and schema application MUST run against the pinned PostgreSQL through Testcontainers.

Rationale An in-memory substitute cannot prove persistence behavior, because it does not run the query planner or the constraints. litespec/backend/testing#test-http-integration-through-the-real-application-host covers HTTP integration through the real host.