Domain Layer

Domain that references only the language standard library and its own types compiles and tests with no infrastructure at all. Each banned reference would drag one outer concern into the business model: persistence metadata couples a rule to a store format, and dispatch plumbing couples it to delivery. Infrastructure registers a persisted discriminator instead, so Domain carries no serialization metadata.

Reviewed forWhich Domain references reach beyond the language standard library and project-owned Domain types? Look at the references in the Domain code.

Marked guidance: a reviewer answers this question.

When code and specification share names, a reader moves between them without translation. A business action named Publish in the glossary is not SetStatus in code, because the second name hides which business action ran. The glossary holds each term meaning, labels per language, rejected words, and broader and narrower links; records cite the terms they use, following litespec/core/domain-model#define-every-behavior-term-in-the-glossary.

Reviewed forWhich Domain names match no term in the project glossary? Look at the Domain names beside glossary.yaml.

Marked guidance: a reviewer answers this question.

If outside code could set properties or call child mutations, it could change data without passing the root's checks. The root stands as the only public mutation entry point, so every change passes the invariant the transaction protects. A command with consistency: atomic changes every aggregate its changes names in one transaction, citing the rule in cites when it changes more than one.

Reviewed forWhich invariants admit a public mutation outside their aggregate root? Look at the public mutation entry points of each aggregate.

Marked guidance: a reviewer answers this question.

One root contract gives every aggregate the same identity and event mechanics, so Infrastructure collects events from any aggregate the same way. The contract owns typed identity, pending events, recording, and clearing, and carries the aggregate version only as persistence metadata that Domain never reads or sets: no timestamp, audit, tenant, lifecycle, or other persistence behavior, because any of those would couple every aggregate to a concern only some need.

Reviewed forWhich aggregate roots take identity or event mechanics outside the project-owned root contract? Look at each aggregate root declaration.

Marked guidance: a reviewer answers this question.

Each lifecycle state can carry different facts: a published post carries its publication time, a draft does not. An enumeration, string discriminator, boolean flag, parallel nullable field, or computed state carries no state-specific data. State types hold that data, and aggregate methods own the transitions between them. A switch over the state types names each case in its own arm where the language requires a fallback, and a case with no arm reaches that fallback at run time.

A post defines one abstract post state with draft and published cases, where the published case carries its publication time. Even an aggregate with one current state defines its hierarchy.

In the Claimwick product, aggregate/spending.expense records the Submitted, Approved, Refused, and Reimbursed states with their transitions: Submit from use-case/spending.submit-expense creates Submitted, Approve from use-case/spending.approve-expense moves Submitted to Approved, Refuse from use-case/spending.refuse-expense moves Submitted to Refused, and Reimburse from use-case/spending.reimburse-expense moves Approved to Reimbursed. The approved case carries the approver and the decided time, and the reimbursed case carries the reimbursed time.

Reviewed forWhich aggregates expose their lifecycle outside one state property and one closed hierarchy of per-state types? Look at the lifecycle declarations in each aggregate.

Marked guidance: a reviewer answers this question.

A closed set with case data needs a type per case: an enumeration carries no case data, admits undefined values, and forces parallel nullable fields when one case gains data. A closed hierarchy gives each case a named type that a switch can name in its own arm, and a case with no arm reaches the switch fallback at run time. A boundary converts a label to its case through a named lookup rather than through a string conversion, and an unrecognized label is a validation failure rather than a default case.

A refund outcome defines pending, succeeded, failed, and reversed cases, where each case carries its own data.

This provision owns the Domain form. The same set is mirrored in Application under litespec/backend/application#mirror-a-domain-closed-set-in-the-result, on the wire under litespec/backend/api#mirror-a-domain-closed-set-as-a-transport-model-of-the-same-shape, and in storage under litespec/backend/persistence#keep-serialization-behavior-out-of-domain. Label-only sets cross the boundary as plain enumerations under litespec/backend/api#publish-label-only-sets-as-string-enums. A transport label converts to its type case before it reaches a Domain method.

Reviewed forWhich closed sets escape one type hierarchy with named label lookups? Look at each closed set and its boundary lookups.

Marked guidance: a reviewer answers this question.

A constructor carries no business name, so construction through constructors spreads creation rules across call sites. The factory is named for its business action, accepts typed identifiers, rejects empty identity and violated creation rules, selects the initial state, records required events, and returns a complete aggregate.

A root created with its children composes them inside the same factory call. The children are built from typed values the caller supplies: a caller holding an already constructed child could mutate it after the invariant was checked, so the factory builds the children itself from those values.

In the Claimwick product, use-case/spending.submit-expense creates its expense through a factory named for submitting: the factory takes the expense and employee identifiers, rejects an empty identity, selects the submitted state, and records the submitted event.

Reviewed forWhich aggregate roots create instances outside a factory named for their business action? Look at the creation paths of each root.

Marked guidance: a reviewer answers this question.

A business-named method lets the handler call the publish behavior without testing the state first: the method checks the current state and protects its invariants, then replaces state and records the transition event when it moves the lifecycle. A generic Set, Update, Process, or Handle name hides which business action ran. A mutation that changes no lifecycle state, such as ChangeTitle on a draft, checks state and assigns without recording a transition.

Checks run before replacement, and replacement runs before recording. A method that replaces state before checking an invariant leaves a rejected aggregate holding the new state.

In the Claimwick product, use-case/spending.reimburse-expense ends with result/reimburse-expense.reimbursed when the expense is approved, and with result/reimburse-expense.not-approved when it is not. The handler calls one business method, and the method checks the state, replaces it, and records event/expense.reimbursed.

An unapproved expense keeps its state, and the refusal carries the stable code spending.not-approved.

Reviewed forWhich public mutations skip the state check or the invariant, or which lifecycle moves skip replacement or the transition event? Look at the public mutation methods of each aggregate.

Marked guidance: a reviewer answers this question.

The use case names an act, and the aggregate performs it: the mark on the root method says which act the method is. A handler that changes its aggregate only through methods marked for other use cases performs an act its record never named, and a reader cannot tell from the use case which method to open. The use-case verb, the method name, and the raised event's tense agree under litespec/backend/dotnet/domain#raise-the-past-tense-of-a-methods-own-verb. This provision states the marked form of litespec/backend/application#keep-command-handlers-to-load-call-and-stage. A command that changes only stores, or that only runs other commands and lists nothing in changes, performs no act on a root, so it needs no marked call.

The reimburse-expense handler calls Reimburse on the expense root, and Reimburse carries the mark use-case/spending.reimburse-expense.

Checked bylitespec model check reports use-case-act-missing (level S) for a command handler changing an entity or saga aggregate that calls no root method marked with its use case. The check runs in the CLI only, with no analyzer rule: the handler and the root method sit in different projects, and one compilation sees one project.

Marked checkable: the tool named here checks it.

Each use case is its own path: its own caller, setup, refusals, events and scenarios. A method two use cases share couples them, so a change made for one silently changes the other, and neither scenario set describes the method. One method per act keeps each path readable on its own; logic the acts share moves into a private method of the root that each act calls. A method that only reads or computes performs no act and carries no mark.

In the Claimwick product, a manager approving an expense and a delegate approving it for an absent manager both record an approval. The expense root offers Approve marked use-case/spending.approve-expense and ApproveOnBehalf marked use-case/spending.approve-expense-on-behalf, each raising its own event, and both call a private RecordApproval.

Checked bylitespec model check reports mark-count-invalid (level S), and dotnet build reports LS5003, for a root method carrying more than one use-case mark; mark-unknown and LS5002 report a mark on a method that changes no state.

Marked checkable: the tool named here checks it.

The use case record states the facts its act leaves behind, and reactions subscribe to those facts. A marked method that raises an event the record does not list starts a consequence nobody reviewed, and a listed event that no marked method raises is a promise the code does not keep.

use-case/spending.submit-expense raises event/expense.submitted, and the Submit method marked with it raises ExpenseSubmittedEvent and nothing else.

Checked bylitespec model check reports act-event-undeclared (level S) for a marked method raising an event its use case does not list, and act-event-unimplemented (level S) for a listed event no marked method raises.

Marked checkable: the tool named here checks it.

A child that exposed mutable state would let outside code change aggregate data without passing the root's checks. The root creates, finds, and changes children through business methods, and collections surface as read-only views. A child with lifecycle states uses the same state types and no enumeration.

Reviewed forWhich child entities expose mutable state outside their root? Look at the child entities beside their root, including collection views.

Marked guidance: a reviewer answers this question.

A dedicated identity type stops one aggregate's identifier from passing where another's is expected, and with no conversion, alias, or creation path around its validation, there is no quiet route back to a bare value. The type rejects the empty value, and each factory also rejects its default. New values arrive from the caller: a factory takes its identifier as an argument, and a method that needs several identifiers takes a generator. Domain reads no clock and calls no static source of time or randomness.

Version 7 values come from the caller-supplied generator, so Domain observes no business time and decides nothing about clocks. Persistence rejects a duplicate key and the write fails, which is the same path as any other write conflict, with the violation mapped to the use case conflict refusal under litespec/backend/persistence#map-a-constraint-violation-to-its-refusal.

A post identifier wraps one version 7 UUID, rejects the empty value, and parses from text through a named method.

Reviewed forWhich aggregate identities escape the dedicated version 7 type, or which conversions, aliases, or creation paths bypass its validation? Look at each identity type and its creation paths.

Marked guidance: a reviewer answers this question.

Immutability with comparison by complete value lets two instances with the same data stand in for each other. The value exposes no mutation and no implicit conversion, because a primitive conversion hides validation and a value conversion erases the domain type. Reading uses the wrapped value or its text form, and creation through a named creation path keeps every value under the validation the type declares.

A post title accepts only non-blank text up to 200 characters: blank or longer input fails creation, and two titles with the same text compare as equal.

Reviewed forWhich value objects mutate, compare by less than their complete value, or skip validation at creation? Look at each value object and its creation paths.

Marked guidance: a reviewer answers this question.

Default structural equality compares collection references rather than contents, so two value objects holding equal lists compare as different. Content equality with a matching hash compares what the value means. Creation copies incoming mutable collections and members return read-only views, so later mutation by the caller leaves the value unchanged. The module terms state whether order is part of the value.

A post-tags value holding an ordered list compares element by element with a matching hash. If order is not part of the value, creation normalizes to the documented comparison order before storing values.

Reviewed forWhich collection values lack content equality with a matching hash under their declared ordering rule? Look at each collection value beside the module terms.

Marked guidance: a reviewer answers this question.

Money needs exact arithmetic and an explicit currency on every value, and one shared Money object gives both. The owning module record defines supported currencies, scale, rounding, sign rules, and cross-currency arithmetic, and Infrastructure maps that precision explicitly. A use case fixed to one currency accepts an amount alone and states that currency in its record.

{ "amount": "12.50", "currency": "EUR" }

The amount serializes as a string, so no reader parses it as binary floating point.

Reviewed forWhich monetary amounts escape the shared Money value with its currency and JSON shape? Look at each monetary amount in Domain.

Marked guidance: a reviewer answers this question.

Binary floating point represents most decimal fractions only approximately, so two amounts a person reads as equal compare as different, and totals drift by fractions of a cent. Exact decimal types keep equality and arithmetic exact.

A tax rate multiplied into a Money amount uses an exact decimal type. A measured latency in a diagnostic log is not a Domain quantity and is outside this rule.

Checked bydotnet build reports LS1008 for a double or float type in Domain.

Marked checkable: the tool named here checks it.

Some calculations span concepts with no natural aggregate owner; forcing them into one aggregate couples it to another's data. A stateless service holds that calculation, accepting and returning Domain values with no persistence, messaging, logging, clock, authorization, or provider call. Application loads the aggregates, calls the service, and passes its result into aggregate behavior.

A domain service is stateless and takes no port, so its tests are Domain tests. They sit beside the aggregate tests in the unit tests mirroring the module tree, with no harness, no substitute, and no fixture.

An order-pricing service takes order lines and a currency and returns their total as Money, with no domain repository, clock, logger, or provider client. Application supplies the lines and passes the returned total into aggregate behavior.

Reviewed forWhich domain services hold state, take non-Domain values, or reach persistence, messaging, logging, clock, authorization, or a provider? Look at each domain service and its calls.

Marked guidance: a reviewer answers this question.

One domain repository per aggregate keeps the write side shaped by the aggregates it loads: a required load looks the aggregate up by identity and reports a missing aggregate through the missing-resource refusal, so a handler repeats no absence check, while an optional lookup is reserved for cases where absence is normal. A flow that finds a record or creates it is two use cases that the boundary owning the flow chooses between, following litespec/backend/application#implement-one-outcome-path-per-command. A composable query, session, or generic CRUD surface would expose store mechanics to every handler.

This boundary is the write side only. Reading for a query uses a read model owned by Application and shaped by Infrastructure, and that path declares no Domain contract. A repository that gained a projection method would put query shapes in Domain, which is the coupling this layer exists to prevent.

A post repository loads a post by identity and reports a missing post through the missing-resource refusal, plus a staging call that stages the aggregate.

The Infrastructure implementation owns that refusal. The command pipeline owns the commit. The staging call stages the aggregate through the selected provider.

Reviewed forWhich domain repositories serve more than one aggregate, expose non-Domain types, or offer a composable query, session, or generic CRUD surface? Look at each repository interface.

Marked guidance: a reviewer answers this question.

A constituent serves no record of its own: it is part of its aggregate, whose record already states the states, transitions, and data the constituent holds. A mark on each would write that fact a second time, and the two copies would drift. The folder already says which aggregate a constituent belongs to, so the builder derives the link from it, and a type in a folder that holds no aggregate root and is not the product Domain/ folder is the one place the derivation fails. A domain service that holds one rule calculation is not a constituent: it carries its rule/ mark.

Claimwick's ExpenseState and IExpenseRepository sit beside the Expense root in Spending/Expenses/Domain/ and carry no mark; the builder lists them as constituents of aggregate/spending.expense. Money sits in the product Domain/ folder and belongs to no aggregate.

Checked bylitespec model check reports constituent-parent-missing (level A) for an unmarked Domain type whose folder holds no aggregate root and is not the product Domain/ folder, and the model output lists each constituent under its aggregate.

Marked checkable: the tool named here checks it.

That method is the only uniqueness code in Domain: the aggregate declares its current keys, and persistence claims and releases them in the commit that changes the aggregate, following litespec/backend/persistence#claim-a-cross-record-key-at-commit. The aggregate computes keys from its own state and validates nothing about other records, because the store arbitrates the race.

In the library product, a book holding a list of copy barcodes returns each barcode from UniquenessKeys, so adding a copy claims the new barcode at commit. In the Claimwick product, a payout carrying a reference that is unique across payouts and adjustments returns that reference, so a duplicate reference fails the commit on either record.

Reviewed forWhich aggregates with a cross-record uniqueness rule miss UniquenessKeys, or carry other uniqueness code in Domain? Look at each such aggregate.

Marked guidance: a reviewer answers this question.

A domain event records a completed fact for reactions to consume. Its name states the aggregate and the completed fact, following litespec/workspace/naming#anchor-aggregate-owned-types-on-the-aggregate-root and litespec/workspace/naming#use-architectural-suffixes, so a reader knows which aggregate raised the fact without opening the file. The event carries business data only: typed identifiers and the values its reactions need, with no aggregate, session, service, mutable collection, or thrown error, because any of those would couple reactions to the raising aggregate. Envelope identity, such as message identity and causation identity, lives on the published integration event that carries the fact outside the process. That integration event names the domain event in translates.

Reviewed forWhich domain events mutate, misname their aggregate or fact, or carry more than business data? Look at each domain event.

Marked guidance: a reviewer answers this question.

One refusal per rejected rule lets each boundary map outcomes without parsing messages: the refusal names the failed rule and the stable code travels to the caller. The name leads with the aggregate root. Domain raises no standard library, validation, transport, or provider failure for a business rejection, and carries no transport status. Refusal names follow litespec/workspace/naming#name-exceptions-by-failed-rule; this provision owns the one-refusal-per-rule shape and the code each refusal carries.

A refund allocation rule ends its use case in its own refusal, rather than sharing one refusal with a code passed at the call site.

Two rules that share a caller-visible refusal code because a boundary maps them to one response still get two refusals. The shared code lives in the two refusals, not in a value passed by the aggregate. One refusal serves more than one input only when one rule fails from more than one input and the differing values travel as creation parameters.

Application validators handle malformed caller input through validity findings. Aggregate and value-object refusals remain the last defense when direct Domain use violates a rule. Command handlers do not catch expected Domain refusals. The host maps them to transport errors through the mapping the API page documents under litespec/backend/api#defer-error-mapping-to-the-global-handler.

Reviewed forWhich rejected business rules end outside a dedicated refusal with its stable code, or leak transport status? Look at each rejection beside its refusal.

Marked guidance: a reviewer answers this question.

An object reference between aggregates loads one aggregate's data through another, which couples their consistency boundaries and their storage. A typed identifier keeps each aggregate loadable on its own: Application loads each aggregate through its domain repository when a command coordinates several, with consistency: atomic citing the rule in cites.

Reviewed forWhich aggregates store another aggregate as an object reference instead of a typed identifier? Look at the fields of each aggregate.

Marked guidance: a reviewer answers this question.

Domain behavior that read a clock or generated identifiers would return different results for the same call, which makes tests nondeterministic. Receiving time, randomness, and new identifiers as arguments keeps every Domain call a pure function of its inputs: a test supplies explicit values and stays deterministic. Application obtains each value through an owned port and passes it in. A method that needs more than one value receives a clock or a generator through its arguments, and version 7 identifiers come from the caller-supplied generator.

Checked bydotnet build reports LS1009 for a clock, randomness, or identifier read in Domain.

Marked checkable: the tool named here checks it.

A reader meeting a public Domain member needs to know the business rule behind it, not just its signature. Documentation states the business constraint, result, or refusal the member represents: a mutation method names its source states, resulting state, protected invariant, and recorded event. A summary that restates the member name adds nothing.

Reviewed forWhich public Domain types or members lack documentation of their business constraint, result, or refusal? Look at the documentation on each public member.

Marked guidance: a reviewer answers this question.