Domain Model

Records and code share one language only when each word is defined once: a term used without an entry means whatever each reader guesses. The entry fixes the meaning, the rejected synonyms, and the wider and narrower terms, so reviewers and checks read the same word the same way.

The term receipt carries the meaning "proof of payment accepted for an expense" in docs/glossary.json, so every record naming a receipt means that proof.

Each term the domain records name appears with its meaning in docs/glossary.json.

Marked guidance: a reviewer answers this question.

A module relies on the language and behavior of others, and each reliance shapes change: editing a module ripples into everything depending on it. Naming every reliance in dependsOn shows that ripple as data instead of leaving it for readers to reconstruct from prose.

Each module page names in dependsOn the modules its text and records rely on.

Marked guidance: a reviewer answers this question.

A bare state name tells a reviewer nothing: rejected without its meaning hides what rejection costs and allows. A name with a meaning makes each lifecycle step reviewable on the page, and gives the Transitions table states worth connecting.

The expense aggregate declares submitted, approved, rejected, and reimbursed, each with one sentence saying what the expense awaits or has received.

litespec consumer fails an aggregate page without states entries carrying a name and a meaning.

Marked checkable: the tool named here checks it.

States without transitions are a list of names with no path between them: a reviewer sees where an aggregate rests but never how it moves. Listing every allowed change with the use case that moves it shows the whole lifecycle as debated rows, and leaves no state reachable only by a path no record names.

The Transitions table on each aggregate page pairs every allowed change with an existing state and use case.

Marked guidance: a reviewer answers this question.

Data without a classification is handled by guess: personal facts sit beside public ones with nothing marking which is which. A meaning with a classification of public, internal, personal, or sensitive tells every later reader how each field is handled, and shows which fields the erasure and export behavior covers. A project that erases and exports in one module states which aggregates that behavior covers with a rule that governs both the aggregate and the erasure or export use case.

The Data table on each aggregate page pairs each field with a meaning and a classification.

Marked guidance: a reviewer answers this question.

The kind decides how the rule is proved: an invariant on every change, a precondition before the behavior, a calculation through its examples, a cross-aggregate rule where aggregates meet. A rule without a kind leaves each reader to prove it a different way, and the checks no place to confirm it.

rule/expense.receipt-required-above-threshold is a precondition stating "an expense above the policy threshold needs a receipt", checked before Submit expense runs.

litespec consumer fails a rule entry without kind or statement.

Marked checkable: the tool named here checks it.

A name that drops the negation reads as its own opposite: a rule named cancel-after-shipment whose statement says "never" approves what it forbids. Keeping the word keeps the name a true sentence a reviewer trusts without opening the statement.

The rule reads rule/order.cancel-never-after-shipment.

litespec model check reports rule-name-negation for a rule whose statement says not, no, never, or cannot outside its name.

Marked checkable: the tool named here checks it.

An aggregate page holds what one aggregate guarantees; a rule spanning aggregates guarantees what no single aggregate owns. Giving such rules their own page keeps each aggregate page a true account of its aggregate, and gathers the shared rules where a reviewer judges them together.

Each cross-aggregate rule sits as an entry on a rule page; other rules sit on their aggregate page.

Marked guidance: a reviewer answers this question.

A guarded rule without a named refusal leaves the ending unnamed: callers branch on a refusal the records never predicted. Naming the refusal ties the rule to the result the use case declares, so the breach and the ending stay one fact.

Each guarded rule names its refusal in refusal beside the rule entry.

Marked guidance: a reviewer answers this question.

An event without a meaning is a name every reaction interprets alone; facts without a carries list are reconstructed from code at each reaction. Stating both on the entry lets each reaction trust what happened and what arrived with it.

litespec consumer fails an event entry without meaning or carries.

Marked checkable: the tool named here checks it.

The root is the one type through which outside behavior changes the aggregate, so it sees every change worth announcing. Raising each event there keeps the fact and its announcement in one step, and leaves no event announced for a change the aggregate never made.

Each event is raised from the root of the aggregate that owns it.

Marked guidance: a reviewer answers this question.

The kind decides what the use case is allowed to touch: a command changes, a query reads, a reaction answers. A use case with no kind, or two, leaves each reader to allow it everything, and the checks no shape to confirm.

litespec consumer fails a use-case page without kind or with an unknown kind.

Marked checkable: the tool named here checks it.

A reaction without a trigger never runs or runs whenever its author remembered: reviewers see behavior with no moment attached. Naming the events, or the schedule or deadline in plain words, states when the behavior answers.

Each reaction page names its trigger events, schedule, or deadline.

Marked guidance: a reviewer answers this question.

A query without a declared output returns whatever its author fetched: readers and screens guess the shape from code. Declaring the output states what readers receive, so the shape is reviewable before anything implements it.

Each query page declares the shape its readers receive in output.

Marked guidance: a reviewer answers this question.

Callers branch on named endings: success, or one refusal with its stable code. A use case with no named success leaves readers guessing what good looks like, and a refusal without a code leaves each layer reporting the same breach another way.

The submit use case declares submitted and receipt-missing with the code spending.receipt-missing.

litespec model check reports use-case-without-success for a use case with no success result; each refusal entry on the use-case page carries its code.

Marked checkable: the tool named here checks it.

A scenario that names no result illustrates behavior without asserting an ending: it reads well and proves nothing. Naming the result ties each example to the ending it walks toward, so every test knows what to assert.

litespec consumer fails a scenario entry without result, and litespec model check reports scenario-result-unresolved for a scenario ending in another use case's result.

Marked checkable: the tool named here checks it.

The three steps separate the situation from the action and the action from the assertion: collapsing them blurs what was true, what moved, and what the test checks. Stating all three keeps each example readable by a person and provable by a test.

litespec consumer fails a scenario entry without given, when, or then.

Marked checkable: the tool named here checks it.

A calculation stated only as a sentence hides its edges: reviewers agree on the words while each pictures other numbers. An examples table shows the debated rows, and the scenario proving the rule pins them as checked facts.

A scenario proving each calculation rule carries its examples table on the use-case page.

Marked guidance: a reviewer answers this question.

The records name what carries business meaning; the design inside an aggregate changes without changing that meaning. Recording each child and value as its own record would triple the tree while adding no decision a reviewer approves. Code and the glossary carry them, where builders and readers meet them.

Order lines live as a child of the order aggregate, and money as a value with its glossary entry; neither is a record.

No record page declares a child entity or value object as a record type.

Marked guidance: a reviewer answers this question.