Automation

A reaction without a trigger never runs or runs whenever its author remembered: reviewers see behavior with no moment attached. Naming the events states when the reaction fires: the domain or integration events it answers, one id or a list. A skippedWhen clause states when it skips.

The send-due-notice reaction answers the loan-borrowed domain event and runs the send-due-notice command.

Checked bylitespec model check reports reaction-trigger-unknown (level G) for a trigger naming an unknown event, and fails a reaction without a triggeredBy list.

Marked checkable: the tool named here checks it.

A job without a kind never runs or runs whenever its author remembered: reviewers see behavior with no moment attached. Naming the kind states when the job runs: the schedule with its every duration, cron expression and timezone, or at: startup for a run once at deployment start, one-off for work that runs once, or manual for work a person starts.

The expire-lapsed-holds job runs every six hours over open holds past their window.

Checked bylitespec model check reports schedule-invalid (level G) for a schedule neither an every duration, a cron expression, nor at: startup, and fails a job without its kind or a scheduled job without schedule.

Marked checkable: the tool named here checks it.

A reaction or job with no declared edge observes and never acts, while an edge outside effects hides behavior the checks never see. Declaring each edge in effects with exactly one verb of runs, sends, emits, or calls keeps every consequence of the reaction or job beside its trigger, under one grammar for every record that has edges, as the use-cases page states.

Checked bylitespec model check reports record-invalid for a reaction or job with no effects or with a top-level effect verb.

Marked checkable: the tool named here checks it.

A reaction or job writing directly splits the write path: the same aggregate changes through a reviewed command and through an unreviewed reaction or job, each with its own guards. Running a small command keeps every write behind a use case with its access, consistency, results, and scenarios.

Reviewed forWhich reactions or jobs write an aggregate outside the use case they run? Look at the reaction and job effects beside the use cases.

Marked guidance: a reviewer answers this question.

Reactions and jobs filed by trigger scatter: one module behavior hides on a dozen trigger pages, and nobody sees the module whole. Filing each reaction and job with the module it changes keeps each module behavior in one place. Its event handler lives in that module's code in the On{Fact} folder inside the module UseCases/ folder (litespec/workspace/naming#group-event-handlers-by-the-fact-they-handle). The trigger page shows reactions answering its event as a view derived from records.

Reviewed forWhich reaction or job pages sit outside the module they change? Look at the reactions and jobs beside the modules whose records they change.

Marked guidance: a reviewer answers this question.

A reaction runs because something happened, and a name without its trigger hides why it runs: send-due-notice could fire on a borrow, a hold, or a reminder run. Naming the act and the fact lets a reader find every consequence of a fact by its name, as litespec/core/language#name-each-record-by-its-types-name-form states.

reaction/lending.send-due-notice-on-loan-borrowed answers event/loan.loan-borrowed.

Reviewed forWhich reaction names hide their act or their trigger? Look at the reaction names beside their triggering events.

Marked guidance: a reviewer answers this question.

A job selects items and runs one command for each, so naming it for that command lets a reader go from the schedule to the behavior in one step, as litespec/core/language#name-each-record-by-its-types-name-form states.

job/lending.expire-lapsed-holds runs use-case/lending.expire-holds.

Checked bylitespec model check reports job-name-invalid (level G) for a job outside <verb>-<what> with the verb of a use case it runs.

Marked checkable: the tool named here checks it.

A failed reaction or job without handling retries forever or drops silently: notices double-send, holds never clear. Declaring onFailure states the failure shape beside the trigger: mode of retry, skip-and-log, or discard; retry with maxAttempts, initialDelay, maxDelay, and backoff of exponential or fixed; then of dead-letter; deadLetter carrying after with the action a person takes; surfacesIn naming the entry point showing the failure and runbook the recovery procedure. retry and then are required with mode: retry; deadLetter, surfacesIn, and runbook are optional. Delays and after are ISO 8601 durations, and prose handling is refused. The same shape serves every record and every effect entry. The idempotency mode, usually state, states how repeats collapse.

Checked bylitespec model check fails a reaction or job with onFailure outside the one failure shape, and reports record-invalid for prose handling, a missing or malformed retry, and a malformed duration.

Marked checkable: the tool named here checks it.

A reaction or job scenario ending anywhere else proves another behavior story: it walks the trigger and asserts an ending no run use case declares. Ending in a run use case result keeps the scenario a proof of the reaction or job consequence.

Checked bylitespec model check reports scenario-result-unknown for a reaction or job scenario ending outside the run use case results.

Marked checkable: the tool named here checks it.

Run fields describe work over time: the kind, the schedule, what each run selects, how many items per batch, the lock, where resume state lives, where it runs, the guard it runs under, the promised service level, and the evidence the run leaves. A reaction answers one event and carries none of that, so a run field on it claims a schedule the trigger never states. Settled by decision/0015-automations-and-sagas on the evidence in research/lower-layers-practice.

The send-due-notice reaction answers its event with no selection and no guard.

Checked bylitespec model check fails a reaction carrying kind, schedule, runbook, runsWhere, guard, cursor, selection, lease, batchSize, serviceLevel, or evidence.

Marked checkable: the tool named here checks it.

Work a person starts without a guard runs anywhere by anyone: a rehearsal harness touches production, a manual sweep runs twice. Stating the guard keeps person-started work inside its fence, beside where it runs in runsWhere.

The rehearse-payout job runs under the platform guard on the staging deployment.

Checked bylitespec model check reports job-guard-missing (level G) for a manual job without guard.

Marked checkable: the tool named here checks it.

A runbook named by a job, a saga, a failure policy, or an alert is the answer a person opens under pressure: impact says what breaks, prerequisites say what to hold, procedure says each step, verification says how to confirm, recovery says how to undo, and escalation says who to call. A runbook missing one leaves the reader guessing at the worst moment.

The clear-stuck-reimbursements runbook states its impact on waiting expenses, its prerequisites, its procedure, its verification query, its recovery, and its escalation to the spending team.

Checked bylitespec model check fails a runbook page without impact, prerequisites, procedure, verification, recovery, or escalation.

Marked checkable: the tool named here checks it.