Use Cases

The kind decides what the use case is allowed to touch: a command changes, a query reads. A use case with no kind leaves each reader to allow it everything, and the checks no shape to confirm. When-X-do-Y behavior and work without a request are reaction and job records, as the Automation page states.

Checked bylitespec model check reports record-invalid for a use-case page without kind or with an unknown kind.

Marked checkable: the tool named here checks it.

One verb per meaning keeps use cases findable: read versus get and change versus update stop competing when every project starts from one closed baseline vocabulary and adds only its domain verbs. A shared first word groups related behavior in every listing, and a retired synonym points at its replacement instead of spreading silently. When the act verb is in neither list, the author first records it as a convention in the same change, and then scaffolds the use case. litespec new scaffolds a use-case page without checking its verb, so the convention lands before the scaffold rather than after a refusal from the scaffold command. A project never redefines a baseline verb. The use-case-verb-unknown check reports a use-case name starting outside the baseline vocabulary and the project verbs, and names the replacement of a retired synonym.

The project records borrow and check-in as domain verbs, so use-case/lending.borrow-copy and use-case/lending.check-in-copy pass, use-case/lending.list-loans passes on the baseline vocabulary, and use-case/lending.update-copy is told to use change.

Reviewed forWhich use-case names open outside the baseline vocabulary and the recorded project verbs? Look at the first word of each use-case name.

Marked guidance: a reviewer answers this question.

The first word is the first thing a reader trusts. A query named change-... or a command named read-... makes every listing lie about what the use case may touch, and a reader stops trusting names at all. The baseline vocabulary gives each verb a kind of query, command, or either; an either verb opens either kind. A project records which of its domain verbs read; its other domain verbs open either kind. The use-case-verb-invalid check reports a use case whose verb names the other kind.

use-case/lending.list-loans is a query and passes; use-case/lending.answer-inquiry opens either kind on an either verb and passes; use-case/lending.read-overdue-count declared as a command is reported, and so is use-case/lending.change-copy declared as a query.

Reviewed forWhich queries open with a changing verb, or which commands open with a reading verb? Look at the first word of each use-case name beside its kind.

Marked guidance: a reviewer answers this question.

The noun groups behavior by the business record it changes; a free synonym hides which record that is and breeds a second word for the concept.

use-case/lending.borrow-copy names the copy aggregate, and use-case/sales.add-line names the declared line part; use-case/lending.borrow-volume names no model word and is reported.

Reviewed forWhich use-case names carry no aggregate, declared part, or glossary term after their verb? Look at the words after the verb in each use-case name.

Marked guidance: a reviewer answers this question.

The use case is the doorway into one aggregate act. A different word at the door and at the act means two meanings have merged, or the use case is misnamed, and each reader guesses which word tells the truth. A handler calling no aggregate method answers to no act, so queries and ports stay out of this rule. A command that records a request for work an event handler finishes after the commit, as litespec/backend/application#call-external-systems-through-their-ports requires, performs the request: its method starts with Request and passes.

use-case/orders.void-order whose handler calls Abandon is reported; the project renames the use case to the domain word, or the method and its event to Void and OrderVoidedEvent.

Reviewed forWhich command handlers call aggregate methods starting with neither the use-case verb nor Request? Look at the methods each command handler calls.

Marked guidance: a reviewer answers this question.

A use case serving nothing and fulfilling nothing is behavior nobody asked for: it ships without a promise behind it and stays when the promise changes. Naming a journey step or a requirement ties each behavior to the intent it carries. The record-link-missing check reports a use case with neither field, and step-use-case-missing reports a journey step no use case serves.

The reimburse-expense command serves journey/submit-and-reimburse#s4 and fulfills requirement/approval-reminders.single-reimbursement.

Checked bylitespec model check reports record-link-missing for a use case with neither serves nor fulfills.

Marked checkable: the tool named here checks it.

Access split across prose and code is widened silently: a new caller arrives, the grant stretches, and no record shows it. Declaring the grant of permission/<name>, self(permission/<name>), anonymous, or system, and the tenant scope of own, cross, public, or none states who may act and how far the call reaches beside the behavior. The Access page states the grant forms and the tenant meanings, and the door the call arrives through states how the caller proved identity. The authorization guard enforces the grant (litespec/backend/application#enforce-target-authorization-in-the-pipeline), and LS2012 reports a handler that authorizes itself.

The reimburse-expense command declares the reimburse-expense permission with own tenant scope, reached through a session door, while the self-checkout scan declares a system grant through a device door.

Checked bylitespec model check reports record-invalid for a use-case page without access carrying grant and tenant scope.

Marked checkable: the tool named here checks it.

A use case with no named door is reachable from anywhere or nowhere: readers cannot tell a public operation from an internal one. Naming the entry points shows how callers arrive at each behavior. A use case that only a reaction, a job, or another use case runs has no door of its own, and its runs edge already shows how it is reached.

Checked bylitespec model check reports record-invalid for a live use case that names no entry point and that nothing runs, and reference-unknown for a reachedThrough entry naming no entry point.

Marked checkable: the tool named here checks it.

An input without an origin is trusted on faith: caller-asserted values pass as verified claims, and money moves on an unchecked figure. Declaring the name, the meaning, the type from text, integer, decimal, money, boolean, date, date-time, duration, email, choice, and id, the origin of caller, claim, or derived, and the classification states what arrives, what it is, and how far to trust it. An id field names the record it refers to in of, and a choice field names its choices there; other types carry no of. required states whether the caller sends the field, and a money field carries an amount with an ISO 4217 currency, as the Record Language states. A type on each field lets the builder compare the records with the generated contract and lets agents generate the right code first time. Settled by decision/0016-typed-contracts-and-privacy on the evidence in research/lower-layers-practice.

Checked bylitespec model check reports record-invalid for a use-case input without name, meaning, or type, without of on an id or choice field, or with of on another type.

Marked checkable: the tool named here checks it.

A caller-asserted figure on a money or access path is an open till: a replacement amount arrives negative, a quantity arrives absurd, and the code obliges. Citing the rule bounding it ties each such value to the guard holding it.

The replacement net amount cites the positivity rule bounding it.

Reviewed forWhich caller-supplied money or access inputs lack a cited bounding rule? Look beside each input with origin: caller on a money or access path.

Marked guidance: a reviewer answers this question.

A write no record names is invisible: the handler touches a second aggregate, the second aggregate changes, and no diff shows it. Naming every touched aggregate, including store aggregates, states the read and write footprint beside the behavior. The write-undeclared check reports a write outside changes.

Checked bylitespec model check reports write-undeclared for a write outside changes and reference-unknown for an unknown aggregate.

Marked checkable: the tool named here checks it.

Consistency left unsaid defaults to hope: a multi-aggregate write is read as atomic until it fails halfway. Declaring the mode states the promise: atomic commits every write in changes as one group, per-record commits each write on its own, and compensated names the undo of each write. An atomic write across aggregates cites its atomicity rule in cites, and changes holds exactly the aggregates the rule binds; a group above 4 aggregates is reported. Atomic consistency never spans an async edge. The Domain Model page states the atomicity rule. The consistency-cites-missing check reports an atomic multi-aggregate write with no cites, atomic-group-drift reports changes differing from the bound group, and atomic-group-invalid reports a group above 4 aggregates.

The reimburse-expense command declares atomic consistency citing the reimbursed-once rule, while the self-checkout scan declares per-record consistency across its attempts.

Checked bylitespec model check reports consistency-cites-missing for an atomic multi-aggregate write with no cites, atomic-group-drift for changes differing from the bound group, atomic-group-invalid (level A) for a group above 4 aggregates, and atomic-group-duplicate (level A) for a command saving more than one atomic write group.

Marked checkable: the tool named here checks it.

An edge no record declares is the defect: hidden calls between use cases, reactions, jobs, notifications, integration events, and external systems. Declaring each edge with exactly one verb of runs, sends, emits, or calls, with its timing of inline, after-commit, or async, and its failure handling states every coupling as data. Timing is required on every use-case effect. On a command, a sends or calls effect carries after-commit or async timing, and an event handler runs the consequence after the commit. The effect-undeclared check reports an edge the records never declared.

The reimburse-expense command emits the reimbursed integration event after commit.

Checked bylitespec model check reports effect-undeclared for an edge the records never declared and effect-timing-invalid for a command sends or calls effect with inline timing; litespec model check reports record-invalid for an effect entry without exactly one verb or its timing.

Marked checkable: the tool named here checks it.

An inline call without a stated transaction is a coin toss at failure: the caller rolls back while the issued work stands, or the reverse. Stating whether the call shares the caller transaction makes the failure shape reviewable beside the edge.

Checked bylitespec model check reports record-invalid for an inline runs effect without sharesTransaction.

Marked checkable: the tool named here checks it.

A cycle without an end condition runs until something breaks: a reaction runs a use case raising the event triggering the reaction. Forbidding cycles except through a domain event with a stated end condition keeps every loop a loop with an exit. The effect-loop-invalid check reports a cycle with no stated end.

Checked bylitespec model check reports effect-loop-invalid for a cycle with no stated end condition.

Marked checkable: the tool named here checks it.

An event raised but unnamed leaves reactions waiting: downstream behavior answers a fact no behavior admits raising. Naming the raised events ties each fact to the behavior announcing it.

Reviewed forWhich use cases raise domain events that raises does not name? Look at raises beside each use-case page.

Marked guidance: a reviewer answers this question.

A retried call without a stated idempotency runs twice: a double payout, a double loan, a double notice. Declaring the mode of key, state, or not-pending, with its key template and scope, states how repeats collapse; none carries the reason repeats cannot happen. The key templates {field} placeholders over the record's input field names, and the scope is tenant, account, login, or global. A reaction key names fields of the triggering event and a job key names fields of its run window instead, which the record does not list, so its placeholders are not checked. The self-checkout scan keys on {nonce} scoped to the login.

Checked bylitespec model check reports record-invalid for a use case without an idempotency mode or without the key, scope, or reason its mode needs; litespec model check reports record-invalid for a key with no {field} placeholder, a placeholder naming no input field, or a scope outside tenant, account, login, and global.

Marked checkable: the tool named here checks it.

An unaudited change with no exemption is a gap nobody admitted: money moves, holds lapse, and no record says who asked. Declaring the level of required, optional, or none with its target, or the exemption with its justification, states the audit beside the change. A level of none is not audited; async work audits at request time.

Checked bylitespec model check reports record-invalid for a command without an audit level and target or an exemption with its justification.

Marked checkable: the tool named here checks it.

A query without a declared output returns whatever its author fetched: readers and screens guess the shape from code. Declaring the output in named groups with fields, classifications, the aggregates each group reads, and freshness states what readers receive, so the shape is reviewable before anything implements it. The query-output-missing check reports a query with no declared output.

The list-expenses query declares open and decided groups with { "mode": "immediate" } freshness.

Checked bylitespec model check reports query-output-missing for a query with no declared output.

Marked checkable: the tool named here checks it.

A read showing more than the aggregates it reads is a quiet widening: roles see figures their own grants never allowed, and no requirement states the view. Citing the requirement in cites keeps the widening a decided choice, and visibleWhen states the condition where one narrows it. The widening-cites-missing check reports a widened group with no cited requirement.

Checked bylitespec model check reports widening-cites-missing for a widened include group with no cited requirement.

Marked checkable: the tool named here checks it.

A collection without paging is a promise the data outgrows: the first hundred rows return, the next ten thousand time out. Declaring the order, the cursor or offset, and the default and maximum limits with mode of pages states the paging beside the read, and { "mode": "none", "reason": "..." } with its reason states why a query returns one object. The paging-undeclared check reports a collection query with no paging.

Checked bylitespec model check reports paging-undeclared for a collection query with no paging.

Marked checkable: the tool named here checks it.

A read built asynchronously without a mark is trusted as fresh: screens show yesterday figures as now, and nobody warned them. Marking the query, with a { "mode": "bounded", "within": "..." } or { "mode": "advisory", "authority": "..." } freshness and one scenario covering the lag, states the staleness beside the promise.

Reviewed forWhich lagging queries lack builtAsynchronously with a bounded or advisory freshness and a lag scenario? Look at the queries beside the aggregates they read.

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 architecture layer reporting the same breach another way. The use-case-success-missing check reports a use case with no success result, and result-undeclared reports a code the records never declared.

The reimburse-expense command declares reimbursed with spending.not-approved and spending.already-reimbursed.

Checked bylitespec model check reports use-case-success-missing 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.

The code is a public contract; invalid, failed or error tell an integrator nothing to do. A code naming the state tells what holds and what to change. The prefix names the module that owns the refused state, which may differ from the module of the refusing use case; a shared kernel declares its prefix in refusals.prefixes, and a code built at run time from a key, such as the conflict for a lost uniqueness key, declares its template in refusals.composed.

spending.receipt-missing names the missing receipt; spending.receipt-invalid hides the state behind a vague word and is reported.

Reviewed forWhich refusal codes fall outside <module>.<noun>-<state> or hide their state behind a vague word? Look at the refusal codes on each use-case page.

Marked guidance: a reviewer answers this question.

The code is a public contract; clients branch on it. Renaming a code in use silently breaks them, and reusing a retired code for another state sends old clients down the new branch. Retiring the code with its replacement named keeps every past refusal readable and every new client on the new code.

The retired spending.receipt-missing result names spending.receipt-absent as its replacement, and no later refusal reuses the old code.

Reviewed forWhich refusal codes in use were renamed or reused instead of retired with a named replacement? Look at the refusal codes beside their results.

Marked guidance: a reviewer answers this question.

Two refusals matching one call need an order: without precedence, each architecture layer picks its own refusal, and callers branch on a different code per stack. The derived refusals come first, forbidden then invalid input, followed by the written refusals in the order the page lists them, so the first match is the one every architecture layer reports.

Reviewed forWhich refusal lists stand out of precedence order, or place a written refusal ahead of a derived one? Look at the refusal entries on each use-case page.

Marked guidance: a reviewer answers this question.

Some denials are forensics: a loan denial, a limit refusal, a fraud block. Storing the attempt with its reason keeps the evidence the business answers with, while a validating refusal such as a malformed code stores nothing.

The self-checkout scan records unknown, retired, and already-lent barcodes with their reasons, while a malformed scan stores nothing.

Reviewed forWhich refusals carrying recorded: true store no attempt with its reason? Look at the recorded refusals beside their use-case pages.

Marked guidance: a reviewer answers this question.

A success hiding several recorded outcomes forces callers to guess: borrow and renew both succeed, but the due date and the analytics differ. Listing the closed codes inside the success states each recorded outcome beside the ending.

The checked-out result lists borrow and renew.

Reviewed forWhich success results with recorded outcomes list no codes? Look at the success results beside their use-case pages.

Marked guidance: a reviewer answers this question.

Hand-written generic refusals multiply: hundreds of pages each declare their own forbidden, and each drifts in wording and code. Deriving them from the grant in access and the rules in input keeps one forbidden and one invalid input per use case, current with the grant: the builder derives result/<use-case>.forbidden and result/<use-case>.invalid-input. Scenarios point at the derived results without anyone writing them.

Reviewed forWhich use-case pages write a generic forbidden or invalid-input refusal as a record? Look at the results on each use-case page beside the derived names.

Marked guidance: a reviewer answers this question.

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. The scenario-result-unknown check reports a scenario ending in an unknown result.

Checked bylitespec model check reports record-invalid for a scenario entry without result, and scenario-result-unknown for a scenario ending in an unknown result.

Marked checkable: the tool named here checks it.

A written result no scenario shows is an ending nobody proved: it reads on the page and is asserted in no test, so it drifts from the code with the next change. One scenario per result pins each ending as a checked fact, including the refusals a caller can meet.

The reimburse-expense command declares the already-reimbursed refusal, and a scenario walks an approved expense claimed twice to that refusal.

Checked bylitespec model check reports result-scenario-missing, level G for a success result and level A for a refusal.

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.

Checked bylitespec model check reports record-invalid for a scenario entry without given, when, or then.

Marked checkable: the tool named here checks it.

A rule proved only through a test mark hides which example walks it: readers open the rule and find no story. Naming the shown rules in exercises ties each example to the rules it walks, so every rule meets its stories.

A scenario walking a second hold on one copy names rule/lending.one-hold-per-copy in exercises.

Reviewed forWhich scenarios show rules without naming them in exercises? Look at the scenarios beside the rules they walk.

Marked guidance: a reviewer answers this question.

Every scenario repeating the same setup buries the step that differs: readers reread one Given on each story. Holding the shared Given once in background leaves each scenario its own situation, action, and assertion.

background holds that the employee has a session and one submitted expense awaits approval, and each approval scenario starts there.

Reviewed forWhich use cases repeat shared setup across scenarios instead of holding it in background? Look at the givens beside each use-case page.

Marked guidance: a reviewer answers this question.

A use case states what it is in one paragraph, so a reader landing cold learns the act before its fields. The steps live under What Happens in the explanation file beside a command, where they stay readable without a shape a check must parse.

The submit-expense summary states that an employee files a work expense for approval, and its What Happens section walks validation, storage, and the approver notice in order.

Checked bylitespec model check reports prose-missing for a use case without summary.

Marked checkable: the tool named here checks it.

A default no requirement holds is a figure nobody stated: a price, a fee, a term, or a limit nobody decided. Declaring the value type, the range, the unit, the setter of product, operator, or tenant, and the bound behavior of refuse, truncate, or degrade states the tunable beside its promise, and a commercial, legal, or tenant-, market-, or date-varying default cites its requirement. The setting-requirement-missing check reports such a default with no cited requirement.

The receipt threshold declares money with a product-set default of EUR 25, refusing an expense above the line with no receipt, behind its requirement.

Checked bylitespec model check reports setting-requirement-missing for a commercial, legal, or varying default with no cited requirement.

Marked checkable: the tool named here checks it.

A setting read by a use case no record names is a coupling readers cannot see: the tunable moves, the reader breaks, and no diff shows the pair. Naming the settings in reads beside the use case states the coupling where the reader lives, so each change to the range or default meets its readers. The setting's readers are computed as the inverse, never written. Settled by decision/0012-use-cases-read-their-settings on the evidence in research/behavior-containment-evidence and research/field-naming-evidence.

The submit-expense use case names setting/spending.receipt-threshold in reads, so a move of the threshold meets the submission story.

Reviewed forWhich use cases read a setting that reads does not name? Look at the use cases beside the settings they read.

Marked guidance: a reviewer answers this question.

An operator setting reaches the product through configuration, so the record and the configuration meet at one path: the record states the default and the bounds, and the configuration names the value. Without the key, a renamed section silently falls back to a default nobody chose, and no reader can tell which configuration value a promise rests on. A setting a tenant or the product sets is held as data by an aggregate instead, and names no key.

Claimwick's setting/spending.approval-reminder-delay is set by the operator and carries key Spending:ApprovalReminderDelay.

Checked bylitespec model check reports setting-key-missing (level G) for a setting with setBy: operator and no key.

Marked checkable: the tool named here checks it.

The options class is where configuration becomes a typed value the code reads, so it is the code element that implements the setting. Marking it names the promise the class holds, and comparing its section name and property with the record's key finds the renamed section or the typo before the product starts with a default.

Claimwick's SpendingOptions declares SectionName = "Spending", an ApprovalReminderDelay property, and /// <implements>setting/spending.approval-reminder-delay</implements>.

Checked bylitespec model check reports setting-unimplemented (level S) for a keyed setting no options class marks, and setting-key-drift (level S) for a marked options class whose SectionName constant and property do not spell the setting's key.

Marked checkable: the tool named here checks it.

A number without a unit is a guess: minutes read as seconds, a count reads as money. Declaring the unit states the measure beside the value.

The retry backoff declares unit: seconds; a timeout with valueType: duration and no unit is reported.

Checked bylitespec model check reports setting-unit-missing (level A) for a numeric or duration setting declaring no unit.

Marked checkable: the tool named here checks it.