worldvm 0.0.0-stage → 0.1.0

package/AUTHORING.md

@@ -0,0 +1,833 @@
+# Authoring worlds
+
+This guide teaches you to write a WorldVM world from a brief: the requirements, who satisfies them
+and how, where people decide, and the scenarios that prove it. Read it top to bottom once, then
+use the [forms reference](#3-forms-reference), [Truth and comparisons](#4-types-truth-and-comparisons)
+and the [diagnostics catalogue](#10-diagnostics-catalogue) while you work. You should not need to
+read the reference worlds or the compiler to start.
+
+Every example here is synthetic and illustrative, not legal, compliance or audit advice. Every
+Forma snippet in this file is compiled by a test, and the scenarios in it pass.
+
+Contents: [1 Layout and commands](#1-layout-and-commands) ·
+[2 A minimal world](#2-a-minimal-world) · [3 Forms reference](#3-forms-reference) ·
+[4 Types, Truth and comparisons](#4-types-truth-and-comparisons) · [5 Evidence](#5-evidence) ·
+[6 Decisions](#6-decisions) · [7 Outputs and NotApplicable](#7-outputs-and-notapplicable) ·
+[8 Actions, interactions and status changes](#8-actions-interactions-and-status-changes) ·
+[9 Scenarios and properties](#9-scenarios-and-properties) ·
+[10 Diagnostics catalogue](#10-diagnostics-catalogue) · [11 Units and dates](#11-units-and-dates) ·
+[12 Idioms and anti-patterns](#12-idioms-and-anti-patterns) ·
+[13 Recipes and a complete example](#13-recipes-and-a-complete-example)
+
+## 1. Layout and commands
+
+A world is a directory of `.forma` files. The CLI reads every `.forma` file under the directory
+(skipping `node_modules`, `dist`, `build`, `coverage` and dot-directories), so the split into
+files is yours. A layout that scales:
+
+```text
+my-world/
+  library/policy.forma     ; (library …), roles, sources, evidence, interactions, components, decisions
+  example.forma            ; entities that implement the roles, and the (account …) that runs the library
+  scenarios/main.forma     ; (scenario …) and (property …) examples
+```
+
+There are two halves. The **library** says what is required, of whom, and how, against abstract
+**roles** (`training/worker`). The **account package** says which stored **entities** play those
+roles and runs components for them with `(for-each role Component)`. Scenarios and properties
+run against an account.
+
+Install the package (`npm install worldvm effect@^4.1.1 @forma-language/forma@^0.6.0`), then
+point the CLI at your directory:
+
+```sh
+npx worldvm check my-world                # compile, link accounts, report diagnostics
+npx worldvm test my-world --seed 42       # run scenarios and seeded properties
+npx worldvm coverage my-world             # which requirements and cited clauses tests reach
+npx worldvm render my-world               # the human-readable manual
+npx worldvm explain my-world --scenario <name> --at 2026-11-10
+npx worldvm coverage my-world --mutate    # semantic mutants your tests fail to catch
+npx worldvm explain W_NO_SCENARIO         # cause, example and fix for a diagnostic code
+```
+
+To preview a rule change against a deployed population, export the SQLite database:
+
+```sh
+npx worldvm deploy my-world --db world.db --account example
+npx worldvm serve --db world.db
+# In another terminal, or after stopping serve:
+npx worldvm snapshot --db world.db --account example --out snapshot.json
+npx worldvm impact my-world proposed-world --world snapshot.json --at 2026-11-10
+npx worldvm explain my-world --world snapshot.json --subject hire-123 --at 2026-11-10
+```
+
+Use the account the server opened. The export reads one committed state while the server
+can keep running, and records the release that last wrote it. Omit `--out` to write JSON
+to stdout. `impact` and `explain` evaluate that population at the explicit `--at` instant.
+
+Stop `serve` before deploying changes. Use `worldvm deploy proposed-world --db world.db
+--account example --dry-run --at 2026-11-10` to preview against committed records;
+omit `--dry-run` to activate and retain the release. `serve <directory> --db` is a
+development shortcut for deploy, then serve. A later `--clock` advances evaluation
+without requiring a redeploy. See the [deployment reference](docs/reference.md#cli-impact-on-a-live-world).
+
+Start a new world with `npx worldvm init my-world`: it writes a minimal library, account,
+scenario, property and local `REFERENCE.md`. The world passes `check`, `test` and `coverage`. Every command has its own
+`--help`.
+
+Each command exits 0 when it passes and 1 when it fails; `--json` prints the machine-readable
+report, where every diagnostic carries `code`, `at` (file, line, column, offsets), `help` and
+`fix` (a mechanical edit with the exact text it replaces, or `null`). Warnings never fail `check`.
+
+### Glossary
+
+| Term           | Meaning                                                                                                                             |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| **Subject**    | The entity whose facts and work are being reconciled, such as one vendor.                                                           |
+| **Home**       | Internal code/IR term for that subject's ownership and routing boundary; diagnostic codes such as `E_NO_HOME` retain this spelling. |
+| **Instance**   | A component bound to particular key inputs, such as `(VendorReview acme)`. A subject can have several instances.                    |
+| **Occurrence** | One evaluation of an instance, including a dated recurrence when the component repeats.                                             |
+
+## 2. A minimal world
+
+One file is enough. This world requires every worker to complete safety training and proves it
+with one scenario.
+
+```forma world=minimal
+;; Synthetic example; illustrative, not legal or audit advice.
+(library example.training "Safety training for each worker." :version "1.0" :subject training/worker)
+
+(role training/worker "A person who must complete training." {:name String})
+
+(source safety-policy "A synthetic internal safety policy."
+  :kind :policy :url "https://example.invalid/safety" :as-of "2026-11-01")
+
+(evidence Completion "A signed training completion record." :of Training
+  {:course String}
+  (attest :signer worker :covers :all :method :otp))
+(layout CompletionLayout "Record and sign the completion."
+  (step record "Record" (field course) (sign)))
+(interaction CompletionEntry "The worker records the course they finished."
+  :actor worker :produces Completion :layout CompletionLayout)
+
+(component Training "Track one worker's safety training."
+  :key [worker] :inputs {:worker (Id training/worker)}
+  (requirement completed
+    :cites [(safety-policy "1: every worker completes safety training")]
+    :satisfied-by (attested Completion))
+  (action complete :advances completed :assignee worker :via (interaction CompletionEntry))
+  (output done (all-of completed)))
+
+(entity Person "A synthetic worker." :ns :example.person :display name
+  :implements {training/worker {:name name}}
+  {:name String})
+(account example "A synthetic account." :requires {example.training "1.0"} :package example
+  (for-each training/worker Training))
+
+(scenario completes "A worker completes training." :world example
+  (given (entity Person ana {:name "Ana"}) (actor ana))
+  (at "2026-11-02" (expect (status (Training ana) completed) :Open))
+  (do (perform (Training ana) complete :by ana :values {:course "Safety 101"}))
+  (at "2026-11-03" (expect (status (Training ana) done) :Satisfied)))
+```
+
+Read it in this order:
+
+1. `library` names the release (`example.training` version `"1.0"`) and the role each component's
+   subject plays (`:subject`).
+2. `role` declares the fields components may read. Roles store nothing.
+3. `source` is the authority you cite. Every requirement and decision should `:cites` a clause;
+   otherwise you get `W_UNCITED`.
+4. `evidence` is a record kept exactly as signed, owned by a component (`:of Training`). `attest`
+   says who signs it; `worker` here is the component input of that name.
+5. `layout` and `interaction` are how a person produces that evidence.
+6. `component` is one requirement scope. `:key` says when two runs are the same (one per worker),
+   `:inputs` types the key. It holds `requirement`s (what must be true), `action`s (work that
+   advances a requirement) and `output`s (named rollups).
+7. `entity` is stored data in the account package; `:implements` maps role fields to entity
+   fields. `:ns` must start with the account's `:package` name.
+8. `account` requires the library release and runs `Training` for every `training/worker`.
+9. `scenario` gives synthetic entities and actors, performs work and expects statuses.
+
+## 3. Forms reference
+
+The [core reference](docs/reference.md) lists syntax, complete examples and common mistakes
+for the fourteen forms needed to start. `worldvm init` includes it as `REFERENCE.md`.
+Options are keyword/value pairs after the docstring; field records and child forms come last.
+
+Advanced forms (`derive`, `calendar`, `agent`, `bundle`, `collect`, `connector`, `machine`,
+`document`, `notice`, `vault`, `component-contract`, `component-import`) and component children
+such as `attach`, `child`, `hold`, `invariant`, `milestone`, `resource` and `retention` are
+not fully documented yet; the [complete example](docs/authoring/vendor-risk/) uses several. `worldvm check` lists top-level forms when you misspell one.
+
+Who can act: `:assignee` and `:actor` take a component input of a person role (`worker`), a field
+path to one (`vendor.owner`), or `(members group-field)` for everyone in a `Group`. In `attest`,
+`:signer assignee` means whoever performs the action.
+
+**Assignees authorize interaction work.** Ordinary `perform` and live recorded-evidence commands
+require the assigned person or a member of the assigned group; account policy restrictions also
+apply. Attestation additionally requires the evidence's declared signer, resolved in the selected
+component occurrence. To expose actions or decisions through the embedding API, list their names in the component's
+`:operations [action-name decision-name]`. This selects callable operations; authority checks
+still apply.
+
+Unknown assignments/signers and mismatched identities fail closed
+(`:not-assignee` in scenarios). Unsigned drafts require assignment but do not claim a signature.
+Decisions separately enforce `:by` and `:distinct-from`.
+
+Hosts authenticate identities and memberships; WorldVM checks their domain authority. The pure
+in-memory `perform` API treats `by` as a trusted human ID when no `actor` is supplied (no group
+memberships); it is not a public authentication boundary. Public operations require a trusted
+actor. Scenario `(given (evidence ...))` records are trusted historical setup, not live commands.
+
+Use `worldvm check . --core` to see `I_EXTENDED_FORM` information for declarations
+outside the ten core forms in [the short reference](docs/reference.md). This mode
+keeps the usual validation and exit status. Editors can enable it with the LSP
+initialization option `core: true`; the check API takes `{ core: true }`.
+
+## 4. Types, Truth and comparisons
+
+Field types: `String`, `Int`, `Float`, `Bool`, `Date`, `Instant`, `Keyword`, `Group` (a named set
+of actors), `(Id Role-or-Entity)` (a reference), `(Option T)` (may be absent) and
+`(Union :a :b …)` (one of these keywords, usually through `(type Name (Union …))`). Read fields
+through references with dots: `contractor.sponsor.name`.
+
+**Conditions are Truth, not Bool.** A world reads facts that may be missing, so `:applies-when`,
+`:satisfied-by`, `:needs`, `:when` and `:while` are three-valued `Truth`: true, false or Unknown
+(a missing fact). Use the Truth operators there:
+
+| You mean        | Requirement, action, decision (Truth)     | Property (also accepted)     |
+| --------------- | ----------------------------------------- | ---------------------------- |
+| equal           | `(= a b)`                                 | `(= a b)`                    |
+| not equal       | `(!= a b)`                                | `(!= a b)`                   |
+| order           | `(< a b)` `(<= a b)` `(> a b)` `(>= a b)` | same                         |
+| not             | `(not x)`                                 | `(not x)`                    |
+| and             | `(and x y …)`                             | `(and x y …)`                |
+| or              | `(or x y …)`                              | `(or x y …)`                 |
+| implies         |                                           | `(implies x y)`              |
+| fact is present | `(known? x)`                              | `(known? x)`, `(unknown? x)` |
+| one of          | `(in? x [:a :b])`                         |                              |
+| dates           | `(before? a b)` `(on-or-after? a b)`      | `(< a b)` and friends        |
+
+`and`, `or` and `not` use the type of their context: Kleene Truth in conditions,
+ordinary Bool in properties and Bool tests. `=` and `!=` compare in either context.
+A Bool fact field already reads as a condition: write `contractor.escorted` or
+`(not contractor.escorted)`. `(and)` is true and `(or)` is false; in Truth
+contexts `(and collection)` and `(or collection)` also fold a collection.
+The retired spellings `all?`, `any?`, `negate` and `not=` are errors for one release,
+with machine-applicable fixes to `and`, `or`, `not` and `!=`.
+
+Unknown is not false. If `contractor.risk` is missing, `(!= contractor.risk :none)` is Unknown
+and the requirement's status is `Unknown`, so the gap stays visible instead of silently passing.
+Use `(known? x)` when you need to branch on presence.
+
+## 5. Evidence
+
+Signal-driven protocols use `(machine Protocol … :signal updated …)` and a
+`(connector provider … :capabilities [] :signals [updated] :owns [Protocol])`.
+Declare the signal and machine ownership even for an inbound-only connector.
+`component-contract` may omit `:capabilities`; it defaults to `[]`.
+
+The rest of this guide builds one world: contractors need site access. Its library starts with
+roles, a source and the evidence types.
+
+```forma world=site file=library/site.forma
+;; Synthetic site-access policy; illustrative, not legal or audit advice.
+(library example.site-access
+  "Safety and insurance requirements before a contractor's badge is active."
+  :version "1.0" :subject site/contractor)
+
+(type RiskLevel (Union :high :standard :none))
+(type BadgeState (Union :pending :active))
+(role site/person "A sponsor, site manager or badge administrator." {:name String})
+(role site/contractor "A contractor with a sponsor, approver groups and a badge."
+  {:name String :sponsor (Id site/person) :managers Group :admins Group
+   :risk RiskLevel :badge BadgeState :joined Date})
+
+(source site-policy "Synthetic site-access policy; not compliance advice."
+  :kind :policy :url "https://example.invalid/site-policy" :as-of "2026-11-01")
+
+(evidence Induction "A signed safety induction; valid for twelve months from signing."
+  :of SiteAccess
+  :expires (months-after signed-on 12)
+  {:course String}
+  (attest :signer contractor :covers :all :method :otp))
+(evidence InsuranceCertificate "Proof of liability insurance with its own end date."
+  :of SiteAccess
+  :expires valid-until
+  {:insurer String :valid-until Date}
+  (attest :signer contractor.sponsor :covers :all :method :otp))
+(evidence HazardPermit "A signed permit for hazardous work." :of SiteAccess
+  {:scope String}
+  (attest :signer contractor.sponsor :covers :all :method :otp))
+```
+
+What to know about evidence:
+
+- `:of` names the component that owns it; evidence is always recorded for one occurrence of that
+  component. Fields are typed like role fields.
+- `(rule name :when condition :requires fields)` requires filled signed fields before
+  attestation. The optional `:when` reads evidence fields and uses three-valued Truth:
+  false skips the rule, Unknown prevents attestation, and omission always applies.
+  `:requires` accepts `field`, `(one-of a b …)` for at least one filled field, or
+  `(all-of a b …)` for every listed field. Groups must be nonempty and name declared
+  fields. For example, `(rule documents :when (= document-choice :list-b-and-c)
+:requires (all-of list-b list-c))` requires both documents for that signed choice.
+  The interaction layout must show required fields when the rule applies; a `one-of`
+  group needs a visible alternative.
+- `(attest :signer who :covers :all :method :otp)` declares who signs. The signature date is the
+  date the record is made.
+- `:expires` is a Date computed from the signed record. Write a date field (`valid-until`), or
+  date arithmetic over fields and `signed-on`, the date the record was signed:
+  `(months-after signed-on 12)`. Expiry is exclusive: a record expiring on 2027-11-07 is valid
+  through 2027-11-06. It may not read live facts, other evidence or decisions (`E_EXPIRES_SCOPE`).
+- **`(attested E)` vs `(valid E)`.** `attested` is true once a record was ever signed and ignores
+  `:expires`. `valid` is true only while the latest signed record is unexpired. For anything that
+  expires you almost always want `valid`; `worldvm check` warns `W_ATTESTED_EXPIRING` and offers
+  the fix. Use `attested` for evidence without `:expires` (`HazardPermit`).
+- A requirement satisfied by `(valid E)` can add `:renew-within (days 30)` to open renewal work
+  before the record expires.
+
+## 6. Decisions
+
+A decision is a person's recorded judgment. It names the requirement it `:applies` to, who may
+make it, and its effect. `(decided name)` reads it in a condition.
+
+```forma world=site file=library/site.forma
+(decision insurance-waiver
+  "A site manager may waive insurance with a reason; the waiver lasts six months."
+  :of SiteAccess :applies insurance-or-waiver :by (members contractor.managers)
+  :effect :approve :reason String :expires (months 6)
+  :cites [(site-policy "2: insurance or a manager's time-limited waiver")])
+```
+
+- `:by` is who may decide, usually `(members group-field)`. Anyone else is rejected with
+  `:decision-authority` (a scenario can expect that, see [section 9](#9-scenarios-and-properties)).
+- `:effect` is `:approve` (read it with `(decided name)` in `:satisfied-by`), `:waive` (the
+  requirement's status becomes `Waived` directly), `:reject`, `:defer`, `:accept` or `:add`.
+- `:reason String` makes a reason mandatory. `:expires (months 6)` ends the decision six months
+  after it was made; `:until date` ends it on a date.
+- `:distinct-from [contractor.sponsor]` forbids those people from deciding (separation of
+  duties); `:approvals 2` needs two distinct deciders; `:when truth` limits when it may be made.
+- **Inside a decision's `:when`, read facts, requirement and output statuses only.**
+  `(met? self.<output>)`, `(satisfied? self.<requirement>)` and fact comparisons work there;
+  `(valid E)` and `(attested E)` currently evaluate as false with no diagnostic, so the decision
+  is always rejected with `:decision-condition`. Read the requirement that uses them instead.
+
+## 7. Outputs and NotApplicable
+
+Every requirement occurrence has one status: `Open`, `Overdue` (open past `:due`), `Satisfied`,
+`Waived`, `NotApplicable` (its `:applies-when` is false) or `Unknown` (a fact it needs is
+missing).
+
+An `output` rolls requirements and other outputs up with `(all-of …)`. **`all-of` treats
+`NotApplicable` as satisfied**, so an output is `Satisfied` when every member is `Satisfied`,
+`Waived` or `NotApplicable` and at least one applies; an output whose members are all
+NotApplicable is itself `NotApplicable`. `(satisfied? x)` is true only for `Satisfied` or `Waived`, so
+`(satisfied? requirement)` on a NotApplicable requirement is false. To ask "is everything that
+applies done?", put the requirements in an output and read it with `(met? self.<output>)`.
+`(met? x)` is true for `Satisfied`, `Waived` or `NotApplicable`, so it also counts "nothing
+applies" as met; `(satisfied? self.<output>)` would be false when every member is
+NotApplicable. `worldvm check` warns about both traps with `W_SATISFIED_NOT_APPLICABLE`.
+
+```forma world=site file=library/site.forma
+(component SiteAccess "Clear one contractor for site access and track their badge."
+  :key [contractor] :inputs {:contractor (Id site/contractor)}
+  (requirement induction
+    :cites [(site-policy "1: safety induction within the last twelve months")]
+    :applies-when (!= contractor.risk :none)
+    :satisfied-by (valid Induction)
+    :due (days-after contractor.joined 14))
+  (requirement insurance-or-waiver
+    :cites [(site-policy "2: insurance or a manager's time-limited waiver")]
+    :applies-when (!= contractor.risk :none)
+    :satisfied-by (or (valid InsuranceCertificate) (decided insurance-waiver)))
+  (requirement hazard-permit
+    :cites [(site-policy "3: high-risk work needs a hazard permit")]
+    :applies-when (= contractor.risk :high)
+    :satisfied-by (attested HazardPermit))
+  (requirement badge-activated
+    :cites [(site-policy "4: administrators activate badges after clearance")]
+    :applies-when (!= contractor.risk :none)
+    :satisfied-by (= contractor.badge :active))
+  (requirement badge-only-if-cleared
+    :cites [(site-policy "4: administrators activate badges after clearance")]
+    :applies-when (= contractor.badge :active)
+    :satisfied-by (met? self.cleared))
+  (invariant no-badge-before-clearance
+    :cites [(site-policy "4: administrators activate badges after clearance")]
+    :forbids (action-kind :activate :subject contractor)
+    :while (not (met? self.cleared)))
+  (action induct :advances induction :assignee contractor :via (interaction InductionEntry))
+  (action insure :advances insurance-or-waiver :assignee contractor.sponsor
+    :via (interaction InsuranceEntry))
+  (action permit :advances hazard-permit :assignee contractor.sponsor
+    :via (interaction PermitEntry))
+  (action activate-badge :advances badge-activated :dispatch :manual
+    :needs [(met? self.cleared)]
+    :assignee (members contractor.admins) :via (interaction BadgeActivationEntry))
+  (output cleared (all-of induction insurance-or-waiver hazard-permit))
+  (output access (all-of cleared badge-activated badge-only-if-cleared)))
+```
+
+For a standard-risk contractor `hazard-permit` is NotApplicable, so `cleared` is Satisfied once
+the induction and insurance are. `badge-only-if-cleared` is a _detection_: nothing works on it;
+it turns `Open` when someone activates a badge before clearance or when the induction expires
+(signed on 2026-11-04 in the scenario below, it stops counting on 2027-11-04).
+`worldvm check` reports `W_NO_PRODUCER` for it, which is expected for a detection.
+
+## 8. Actions, interactions and status changes
+
+An `action` is work: it `:advances` one requirement, is offered to its `:assignee`, and is done
+`:via` an interaction (or a connector). `:needs [truth …]` gates it: until every need holds, the
+work waits and performing it is rejected (`:not-eligible`). `:dispatch :manual` means the action
+is available on request rather than pushed to the assignee as soon as the requirement opens.
+
+Use `:by` with the stable assigned identity in scenario commands, not its display name. Live
+`(do (evidence ...))` records must match an eligible producing action, evidence type and current
+requirement occurrence, and pass the same assignment/signer checks as `perform`. Historical
+`given` records remain available for importing synthetic prior proof without replaying its work.
+
+An `interaction` produces one evidence type. Its `layout` decides what the form shows. Its
+`:proposes {role.field evidence-field}` writes signed values back into the subject's facts when
+the evidence is recorded; that is how a world changes a status.
+
+Use `:fixes {:examination :remote}` when an interaction supplies a signed value
+instead of asking the signer. The evidence must declare that field with a matching
+scalar type, such as `(Union :in-person :remote)`. Omit fixed fields from the layout,
+including nested groups; they count toward show coverage. A fixed field cannot also
+use `:binds`, `:prefill` or `:proposes`. Conflicting submissions are refused for both
+drafts and signatures. The stored evidence includes the fixed value, so evidence
+rules and explanations can read it. In-person and remote actions can share one
+evidence type through separate interactions fixing different values; gate the remote
+action with `:needs [employee.employer.everify-enrolled]`.
+
+**Modelling "activate".** There is no `set-fact` action. To let administrators activate a badge
+only when the contractor is cleared, record the activation as evidence whose interaction
+proposes the new status, behind an action that `:needs` the clearance (see `activate-badge`
+above):
+
+```forma world=site file=library/site.forma
+(evidence BadgeActivation "An administrator's signed badge activation." :of SiteAccess
+  {:badge BadgeState}
+  (attest :signer assignee :covers :all :method :otp))
+(layout BadgeActivationLayout "Activate the badge."
+  (step activate "Activate" (field badge :options {:active "Active"}) (sign)))
+(interaction BadgeActivationEntry "An administrator activates the contractor's badge."
+  :actor assignee :produces BadgeActivation :layout BadgeActivationLayout
+  :proposes {contractor.badge badge})
+
+(layout InductionLayout "Record the induction." (step record "Record" (field course) (sign)))
+(interaction InductionEntry "The contractor completes the safety induction."
+  :actor contractor :produces Induction :layout InductionLayout)
+(layout InsuranceLayout "Record the certificate."
+  (step record "Record" (field insurer) (field valid-until) (sign)))
+(interaction InsuranceEntry "The sponsor records the insurance certificate."
+  :actor contractor.sponsor :produces InsuranceCertificate :layout InsuranceLayout)
+(layout PermitLayout "Record the permit." (step record "Record" (field scope) (sign)))
+(interaction PermitEntry "The sponsor records the hazard permit."
+  :actor contractor.sponsor :produces HazardPermit :layout PermitLayout)
+```
+
+`:needs` controls _when_ the activation can happen, not _who_ performs it (see
+[section 3](#3-forms-reference)). When only a group may activate, record the activation as a
+decision instead: `:by` enforces who, and `:when` (over requirement statuses, see
+[section 6](#6-decisions)) enforces when. Early or unauthorised attempts are rejected with
+`:decision-condition` or `:decision-authority`.
+
+```forma world=site file=library/site.forma
+(decision approve-badge
+  "A badge administrator approves activation once the contractor is cleared."
+  :of SiteAccess :applies badge-activated :by (members contractor.admins)
+  :when (met? self.cleared)
+  :effect :approve :reason String
+  :cites [(site-policy "4: administrators activate badges after clearance")])
+```
+
+**Detect vs prevent.** `badge-only-if-cleared` _detects_ an active badge without clearance after
+the fact. To _prevent_ the write, the component also declares an `invariant`:
+`:forbids (action-kind :activate :subject contractor)` rejects any command of kind `:activate`
+against that contractor while `:while` holds. A write must be submitted as a command with that
+kind to be checked: in a scenario, `(set c :badge :active :kind :activate :subject c :by "Admin")`
+is rejected with the invariant's name (see `badge-write-blocked` below). Writes that bypass the
+command path, or carry another kind, are not checked, and an Unknown `:while` admits the write,
+so keep the detection too. `worldvm check` suggests this pair (`I_DETECT_ONLY`) for a
+detection-only requirement whose `:applies-when` compares a fact to a keyword.
+
+## 9. Scenarios and properties
+
+The account package binds entities to the roles and runs the component:
+
+```forma world=site file=example.forma
+(entity Person "A synthetic person." :ns :example.person :display name
+  :implements {site/person {:name name}} {:name String})
+(entity Contractor "A synthetic contractor." :ns :example.contractor :display name
+  :implements {site/contractor {:name name :sponsor sponsor :managers managers :admins admins
+                                :risk risk :badge badge :joined joined}}
+  {:name String :sponsor (Id Person) :managers Group :admins Group :risk RiskLevel
+   :badge BadgeState :joined Date})
+(account example "An isolated synthetic site-access account."
+  :requires {example.site-access "1.0"} :package example
+  (for-each site/contractor SiteAccess))
+```
+
+A scenario has three kinds of steps, in any order:
+
+- `(given …)` creates synthetic data: `(entity Type alias {fields})` and `(actor alias
+[:groups ["Group"]])`. A `Group` field is a string naming the group; an actor is a member when
+  its `:groups` lists that name.
+- `(do …)` performs commands. **Commands take effect at the date of the next `(at …)`**, so
+  expiry counts from that date.
+  - `(perform (Component alias) action :by actor :values {field value})` does an action's work
+    through its interaction (rejected if the action is not eligible).
+  - `(evidence Type :for (Component alias) :requirement name :by actor :values {…})` records
+    evidence directly.
+  - `(decide (Component alias) decision :by actor :reason "…")` records a decision.
+  - `(set alias :field value :by "who")` changes a fact. Add `:kind :k :subject alias` to submit
+    it as a command of kind `:k`, which invariants can reject.
+- `(at "YYYY-MM-DD" (expect selector expected) …)` checks the world on that date:
+  - `(status (Component alias) requirement-or-output)` against `:Open`, `:Overdue`,
+    `:Satisfied`, `:Waived`, `:NotApplicable` or `:Unknown`;
+  - `(work (Component alias) action)` against `{:state :eligible}` (also `:waiting`,
+    `:dispatched`, `:held`, `:absent`);
+  - `(due (Component alias) requirement)` against a date;
+  - `(rejected n)` against the reason the n-th command of the preceding `do` was refused (table
+    below). A rejection you do not assert fails the scenario with `E_SCENARIO_RUN`.
+
+Two `(at …)` steps may share a date, for example to assert a rejection and then retry.
+
+| Rejection                                                                                                          | Meaning                                                                              |
+| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| `:not-eligible`                                                                                                    | The action's `:needs` do not hold.                                                   |
+| `:decision-authority`                                                                                              | The actor is not in the decision's `:by`.                                            |
+| `:decision-distinct`                                                                                               | The actor is excluded by `:distinct-from`.                                           |
+| `:decision-reason`                                                                                                 | `:reason` is required and missing.                                                   |
+| `:decision-condition`                                                                                              | The decision's `:when` does not hold.                                                |
+| `:decision-approvals`, `:decision-duplicate`                                                                       | An approval count is not met, or the same person approved twice.                     |
+| `:decision-expiry`, `:decision-until`, `:decision-stale`, `:decision-prior`, `:decision-target`, `:decision-state` | The decision's timing, target or prior state does not allow it.                      |
+| `:evidence-invalid`, `:signature-required`                                                                         | The evidence values or signature are missing or invalid.                             |
+| `:no-occurrence`                                                                                                   | The component occurrence does not exist (check the subject and its `:applies-when`). |
+| `:command-date`                                                                                                    | The command's date is out of order.                                                  |
+| the invariant's name, e.g. `:no-badge-before-clearance`                                                            | An invariant forbids this command kind while its `:while` holds.                     |
+
+```forma world=site file=scenarios/access.forma
+;; Synthetic data only; illustrative, not compliance advice.
+(scenario standard-clearance "A standard-risk contractor is cleared, then activated."
+  :world example
+  (given (entity Person sponsor {:name "Sponsor"}) (entity Person admin {:name "Admin"})
+    (entity Contractor c {:name "Rivera Electrical" :sponsor sponsor :managers "Managers"
+                          :admins "Badge admins" :risk :standard :badge :pending
+                          :joined "2026-11-02"})
+    (actor c) (actor sponsor) (actor admin :groups ["Badge admins"]))
+  (at "2026-11-02"
+    (expect (status (SiteAccess c) induction) :Open)
+    (expect (status (SiteAccess c) hazard-permit) :NotApplicable)
+    (expect (work (SiteAccess c) activate-badge) {:state :waiting}))
+  (do (perform (SiteAccess c) activate-badge :by admin :values {:badge :active}))
+  (at "2026-11-03" (expect (rejected 1) :not-eligible))
+  (do (perform (SiteAccess c) induct :by c :values {:course "Site safety"})
+      (perform (SiteAccess c) insure :by sponsor
+        :values {:insurer "Synthetic Mutual" :valid-until "2027-12-31"}))
+  (at "2026-11-04"
+    (expect (status (SiteAccess c) cleared) :Satisfied)
+    (expect (work (SiteAccess c) activate-badge) {:state :eligible}))
+  (do (perform (SiteAccess c) activate-badge :by admin :values {:badge :active}))
+  (at "2026-11-05"
+    (expect (status (SiteAccess c) badge-activated) :Satisfied)
+    (expect (status (SiteAccess c) access) :Satisfied))
+  (at "2027-11-03" (expect (status (SiteAccess c) access) :Satisfied))
+  (at "2027-11-04"
+    (expect (status (SiteAccess c) induction) :Overdue)
+    (expect (status (SiteAccess c) badge-only-if-cleared) :Open)))
+
+(scenario manager-waiver "Only a manager waives insurance, and the waiver lasts six months."
+  :world example
+  (given (entity Person sponsor {:name "Sponsor"}) (entity Person manager {:name "Manager"})
+    (entity Contractor c {:name "Okafor Scaffolds" :sponsor sponsor :managers "Managers"
+                          :admins "Badge admins" :risk :high :badge :pending
+                          :joined "2026-11-02"})
+    (actor sponsor) (actor manager :groups ["Managers"]))
+  (do (decide (SiteAccess c) insurance-waiver :by sponsor :reason "Trust me"))
+  (at "2026-11-02"
+    (expect (rejected 1) :decision-authority)
+    (expect (status (SiteAccess c) hazard-permit) :Open))
+  (do (decide (SiteAccess c) insurance-waiver :by manager :reason "Certificate in transit"))
+  (at "2026-11-03" (expect (status (SiteAccess c) insurance-or-waiver) :Satisfied))
+  (at "2027-05-02" (expect (status (SiteAccess c) insurance-or-waiver) :Satisfied))
+  (at "2027-05-03" (expect (status (SiteAccess c) insurance-or-waiver) :Open)))
+
+(scenario no-site-work "A contractor who never comes on site has no requirements." :world example
+  (given (entity Person sponsor {:name "Sponsor"})
+    (entity Contractor c {:name "Remote Design" :sponsor sponsor :managers "Managers"
+                          :admins "Badge admins" :risk :none :badge :pending
+                          :joined "2026-11-02"}))
+  (at "2026-11-02" (expect (status (SiteAccess c) access) :NotApplicable)))
+
+(scenario badge-write-blocked "An activation submitted before clearance is rejected." :world example
+  (given (entity Person sponsor {:name "Sponsor"})
+    (entity Contractor c {:name "Rivera Electrical" :sponsor sponsor :managers "Managers"
+                          :admins "Badge admins" :risk :standard :badge :pending
+                          :joined "2026-11-02"}))
+  (do (set c :badge :active :kind :activate :subject c :by "Admin"))
+  (at "2026-11-02"
+    (expect (rejected 1) :no-badge-before-clearance)
+    (expect (status (SiteAccess c) badge-only-if-cleared) :NotApplicable)))
+```
+
+A `property` claims something for every generated entity of a type. `worldvm test` builds
+bounded synthetic worlds from a seed and checks the claim on the `:at` date; false and Unknown
+both fail, and a failure prints a replay scenario. Properties use the property operators from
+[section 4](#4-types-truth-and-comparisons), read facts through the bound name, and select
+statuses with `(status (Component x) name)` and evidence with `(attested (Component x) Type)`.
+
+Each `implies` reports how many generated cases made its antecedent true, once per
+case regardless of how many entities matched. Zero produces `W_PROPERTY_VACUOUS`
+in `test` and `coverage`, in text and JSON. Vacuity warns without failing the command;
+false and Unknown results still fail. A passing claim with zero matches has not
+tested its consequent.
+
+To reach a claim's preconditions, put an optional scenario-style `(given …)` block
+between `:for-all` and the predicate. It accepts entity, evidence and signal records
+and must declare the quantified alias with its entity type. For example, a property
+quantifying `(p Person)` can seed `(given (entity Person p {:name "Synthetic worker"})
+(evidence Completion :for (Training p) :requirement completed :by p
+:values {:course "Safety 101"}))`. Every case preserves explicit seed facts and
+records while varying unspecified fields; random history cannot replace a seeded
+evidence type or machine on the same occurrence. `given` is trusted history, as in
+scenarios. Use `do` in a scenario to test whether an action is permitted.
+Counterexample shrinking preserves the authored seed facts and records.
+
+```forma world=site file=scenarios/access.forma
+(property active-badge-means-inducted
+  "A contractor whose access is satisfied with an active badge has an induction on file."
+  :world example :at "2026-11-02" :for-all (c Contractor)
+  (implies (and (= c.badge :active) (!= c.risk :none)
+                (= (status (SiteAccess c) access) :Satisfied))
+    (attested (SiteAccess c) Induction)))
+```
+
+## 10. Diagnostics catalogue
+
+Every diagnostic has a code, a location, `help` and, when the repair is mechanical, a `fix`.
+Errors stop `check`; warnings (`W_…`) and info (`I_…`) are advice. The CLI owns the catalogue:
+
+```sh
+worldvm explain --list
+worldvm explain W_ATTESTED_EXPIRING
+worldvm explain E_NO_HOME
+```
+
+Start with the located help, repair the smallest reported declaration, then rerun `check`.
+Use `valid` for expiring evidence (`W_ATTESTED_EXPIRING`), and `met?` when NotApplicable
+should count as done (`W_SATISFIED_NOT_APPLICABLE`). `W_NO_PRODUCER` asks whether a rule
+needs work to resolve it; a detection-only rule can legitimately have no action. `W_NO_SCENARIO`
+asks for an observed status assertion. A reference alone does not demonstrate the outcome.
+
+The catalogue below quotes diagnostic messages verbatim, including internal routing terminology.
+Use `worldvm explain <code>` for details, or `worldvm explain --list` for every code.
+
+<!-- catalogue:start -->
+
+| Code                                     | Meaning                                                     | Usual cause                                                                                                                                                                                                                                                                                               | Fix                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| ---------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `E_ADVANCES`                             | An action's :advances is malformed                          | :advances must name one requirement or a vector of distinct requirement names.                                                                                                                                                                                                                            | Use one declared requirement name or a nonempty vector of distinct local names.                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `E_ARTIFACT_UNTYPED_RUNTIME_DECLARATION` | Compiler diagnostic (artifact/untyped-runtime-declaration)  | The compiler reported E_ARTIFACT_UNTYPED_RUNTIME_DECLARATION, formerly artifact/untyped-runtime-declaration.                                                                                                                                                                                              | Review this declaration and correct the reported syntax, type or reference.                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `E_CHECK_THROW`                          | The compiler threw                                          | An internal compiler failure, not an authoring error.                                                                                                                                                                                                                                                     | Reduce the failing source to the smallest example and report it.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `E_CITATION`                             | A :cites value is malformed                                 | :cites must be a vector of (source "clause") pairs.                                                                                                                                                                                                                                                       | Write :cites [(brief-policy "1: clause text")].                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `E_DECISION_EFFECT`                      | Unsupported decision effect                                 | Decision :effect must be one of the kernel effects.                                                                                                                                                                                                                                                       | Choose :approve, :reject, :waive, :defer, :accept or :add.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `E_DECISION_REASON`                      | Unsupported decision reason type                            | :reason must be a scalar, a keyword union, or an Option/alias of one.                                                                                                                                                                                                                                     | Use :reason String (or a keyword union); structured records belong in evidence.                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `E_DECISION_TARGET`                      | A decision applies to something its component does not own  | :applies names a requirement not declared in the :of component.                                                                                                                                                                                                                                           | Name a requirement declared in the :of component.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `E_ELABORATE_ACTION_DEFINITION`          | Compiler diagnostic (elaborate/action-definition)           | The compiler reported E_ELABORATE_ACTION_DEFINITION, formerly elaborate/action-definition.                                                                                                                                                                                                                | Review this declaration and correct the reported syntax, type or reference.                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `E_ELABORATE_CONSTRUCT_FAILED`           | Compiler diagnostic (elaborate/construct-failed)            | The compiler reported E_ELABORATE_CONSTRUCT_FAILED, formerly elaborate/construct-failed.                                                                                                                                                                                                                  | Review this declaration and correct the reported syntax, type or reference.                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `E_ELABORATE_DUPLICATE_DECLARATION`      | Two declarations share a name                               | Names are global across every .forma file in the world directory.                                                                                                                                                                                                                                         | Rename or delete one declaration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `E_ELABORATE_EXPANSION_FAILED`           | Compiler diagnostic (elaborate/expansion-failed)            | The compiler reported E_ELABORATE_EXPANSION_FAILED, formerly elaborate/expansion-failed.                                                                                                                                                                                                                  | Review this declaration and correct the reported syntax, type or reference.                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `E_ELABORATE_FORM_CHECK`                 | A declaration failed one of its publish checks              | The prelude's per-form checks (key closure, unknown fields, and similar) rejected it.                                                                                                                                                                                                                     | Follow the message; it names the field or child that failed.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `E_ELABORATE_FORM_DEFINITION`            | Compiler diagnostic (elaborate/form-definition)             | The compiler reported E_ELABORATE_FORM_DEFINITION, formerly elaborate/form-definition.                                                                                                                                                                                                                    | Review this declaration and correct the reported syntax, type or reference.                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `E_ELABORATE_HOLE_TYPE`                  | An expression has the wrong type for its slot               | Most often a Bool where a three-valued Truth is expected: a bare true/false or (if …) in :applies-when/:satisfied-by. Also unbound names and misspelled fields.                                                                                                                                           | Use and, or, not, = and != in every context; collapse Truth to Bool only with (true? x) inside if.                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `E_ELABORATE_INVALID_SLOT_VALUE`         | An option has a value of the wrong shape                    | A keyword, vector or map was expected but something else was supplied.                                                                                                                                                                                                                                    | Use the shape named in the message, for example :key [vendor].                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `E_ELABORATE_MALFORMED_FORM`             | A form's parts are out of order or malformed                | Positional parts (name, docstring, field map) are missing or in the wrong order.                                                                                                                                                                                                                          | Write (form name "Doc." :option value ... {fields} children...).                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `E_ELABORATE_MISSING_IDENTIFIER`         | A form is missing its name                                  | The first argument after the form head must be a symbol naming the declaration.                                                                                                                                                                                                                           | Insert a name: (component VendorReview "Track one vendor." ...).                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `E_ELABORATE_MISSING_SLOT`               | A required option or part is missing                        | The form needs a name, docstring, option or field map that was omitted.                                                                                                                                                                                                                                   | Add the missing part named in the message; compare with the minimal world in AUTHORING.md.                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `E_ELABORATE_NO_CONSTRUCT_HOOK`          | Compiler diagnostic (elaborate/no-construct-hook)           | The compiler reported E_ELABORATE_NO_CONSTRUCT_HOOK, formerly elaborate/no-construct-hook.                                                                                                                                                                                                                | Review this declaration and correct the reported syntax, type or reference.                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `E_ELABORATE_REFERENCE_TYPE`             | A reference names the wrong kind of declaration             | For example :produces names a role instead of an evidence type, or :of names an entity instead of a component.                                                                                                                                                                                            | Point the option at a declaration of the expected kind (see the message).                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `E_ELABORATE_RESULT_TYPE_FAILED`         | Compiler diagnostic (elaborate/result-type-failed)          | The compiler reported E_ELABORATE_RESULT_TYPE_FAILED, formerly elaborate/result-type-failed.                                                                                                                                                                                                              | Review this declaration and correct the reported syntax, type or reference.                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `E_ELABORATE_UNKNOWN_FORM`               | A top-level form name is not a world declaration            | The head of a top-level list is not one of the world forms, or a component/account/evidence child form was written at top level.                                                                                                                                                                          | Use one of: account, agent, bundle, calendar, collect, component, component-contract, component-import, connector, decision, derive, document, entity, evidence, interaction, layout, library, machine, notice, property, role, scenario, source, type, vault. Child forms such as requirement, action, output and invariant go inside (component ...).                                                                                                                                            |
+| `E_ELABORATE_UNKNOWN_REFERENCE`          | A reference names nothing declared                          | A role, entity, component, evidence, decision or interaction name is misspelled or not declared in any file of the world.                                                                                                                                                                                 | Declare the target or correct the spelling; names are case-sensitive and global to the world directory.                                                                                                                                                                                                                                                                                                                                                                                            |
+| `E_ELABORATE_UNSUPPORTED_FORM`           | Compiler diagnostic (elaborate/unsupported-form)            | The compiler reported E_ELABORATE_UNSUPPORTED_FORM, formerly elaborate/unsupported-form.                                                                                                                                                                                                                  | Review this declaration and correct the reported syntax, type or reference.                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `E_ELABORATE_VALIDATION_FAILED`          | A child form is not valid inside its parent                 | Usually "Expected child form X-child": a misspelt child inside component, layout, step or evidence.                                                                                                                                                                                                       | Help lists the valid children of that parent; correct the child form's head.                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `E_EXPIRES_SCOPE`                        | An evidence :expires reads outside its signed fields        | Expiry may read only the evidence's own signed fields, signed-on (the signing date) and pure date logic.                                                                                                                                                                                                  | Compute expiry from the signing date, :expires (months-after signed-on 12), or from a signed date field, :expires valid-until.                                                                                                                                                                                                                                                                                                                                                                     |
+| `E_FIXES_CONFLICT`                       | A fixed field has another value source                      | A field is fixed more than once or also uses binds, prefill or proposes.                                                                                                                                                                                                                                  | Give each fixed field exactly one literal value source.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `E_FIXES_LAYOUT`                         | A layout shows an interaction fixed field                   | The interaction supplies this value, so the signer must not be prompted for it.                                                                                                                                                                                                                           | Remove the fixed field from the layout, including nested groups.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `E_FIXES_SHAPE`                          | Interaction fixed values need a map                         | :fixes accepts evidence field names and scalar literals.                                                                                                                                                                                                                                                  | Use :fixes {:examination :remote}.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `E_FIXES_TYPE`                           | A fixed value has the wrong evidence field type             | The literal does not fit the declared field, including keyword union membership.                                                                                                                                                                                                                          | Use a scalar literal of the evidence field's declared type.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `E_KEY_NOT_INPUT`                        | A :key name is not an input                                 | Every :key entry must also appear in :inputs.                                                                                                                                                                                                                                                             | Rename the key or the input so they match.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `E_LINK`                                 | An account does not link against its library                | The account's :requires names a library/version that is not declared, or an entity does not :implements every role field the library needs.                                                                                                                                                               | Match :requires to the (library … :version …) declaration and map every role field in the entity's :implements.                                                                                                                                                                                                                                                                                                                                                                                    |
+| `E_LOWER`                                | An expression cannot be lowered to the kernel               | A name is not in scope, a dotted path names no field, or a call is neither a kernel function nor a derive.                                                                                                                                                                                                | Use kernel functions only: and/or/not for logic, in? for membership; declare a (derive ...) for reusable logic.                                                                                                                                                                                                                                                                                                                                                                                    |
+| `E_MISSING_DOC`                          | A published declaration has no docstring                    | Libraries, roles, entities, components, evidence, decisions, scenarios and properties need a nonempty docstring.                                                                                                                                                                                          | Add a docstring right after the name: (component VendorReview "Track one vendor." ...).                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `E_NO_HOME`                              | A component has no entity home                              | The first :key input must be an entity reference (Id E), directly or through another component.                                                                                                                                                                                                           | Put an (Id role) input first in :key, for example :key [vendor].                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `E_NO_SOURCES`                           | The directory has no .forma files                           | check/test/coverage compile every visible .forma file under the directory.                                                                                                                                                                                                                                | Point at the world directory, or scaffold one with worldvm init <dir>.                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `E_OUTPUT`                               | An output expression is not supported                       | Outputs combine statuses; they are not general expressions.                                                                                                                                                                                                                                               | Write (output name (all-of a b)), (any-of a b) or (status-of a).                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `E_PARSE_SYNTAX`                         | Compiler diagnostic (parse/syntax)                          | The compiler reported E_PARSE_SYNTAX, formerly parse/syntax.                                                                                                                                                                                                                                              | Review this declaration and correct the reported syntax, type or reference.                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `E_PROJECT_IO`                           | The directory cannot be read                                | The path does not exist or is not readable.                                                                                                                                                                                                                                                               | Pass a readable directory containing .forma source files.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `E_PROPERTY_ASSERT`                      | A property was false or Unknown for a generated case        | The predicate failed; the report includes a shrunk counterexample scenario.                                                                                                                                                                                                                               | Replay the counterexample source; then correct the rule, or narrow the property with implies/known?.                                                                                                                                                                                                                                                                                                                                                                                               |
+| `E_PROPERTY_DATE`                        | A property :at is not a real date                           | Properties never read the system clock; :at must be a fixed date or zoned instant.                                                                                                                                                                                                                        | Use YYYY-MM-DD, e.g. :at "2026-11-06".                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `E_PROPERTY_REF`                         | A property names an unknown world, binding, field or clause | The :world account, :for-all entity, a field path or a status/evidence name is not declared.                                                                                                                                                                                                              | Use an entity in this account package, its declared fields, and a component requirement/output or evidence type.                                                                                                                                                                                                                                                                                                                                                                                   |
+| `E_PROPERTY_SHAPE`                       | A property expression uses an unsupported form              | Properties are closed finite predicates with their own small operator set; runtime vocabulary (valid, decided, days-after …) is not available there.                                                                                                                                                      | Use :world, :at and one :for-all (alias Entity), then implies, and, or, not, =, !=, <, <=, >, >=, known?, unknown?, satisfied?, not-applicable?, (status (C alias) name), (attested (C alias) Evidence), work, due, occurrence-count.                                                                                                                                                                                                                                                              |
+| `E_PROPERTY_TYPE`                        | A property operand has the wrong type                       | Comparison of incompatible values, or a non-boolean under and/or/implies.                                                                                                                                                                                                                                 | Compare like with like (keywords as :high, dates as "YYYY-MM-DD"); logic needs booleans; status predicates need (status …).                                                                                                                                                                                                                                                                                                                                                                        |
+| `E_READ_OUTSIDE_KEY`                     | An expression reads a non-key input                         | Shared/keyed components and decisions may only read key inputs and their reference paths.                                                                                                                                                                                                                 | Read only key inputs and their reference paths, or include this input in the component key.                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `E_READ_SYNTAX`                          | The file does not parse                                     | Unbalanced parentheses/brackets, an unterminated string or a stray character.                                                                                                                                                                                                                             | Balance every ( [ { with its closer and close every string; the location points at the first unreadable token.                                                                                                                                                                                                                                                                                                                                                                                     |
+| `E_RENAMED_OPERATOR`                     | An operator was renamed                                     | The source uses all?, any?, negate or not=.                                                                                                                                                                                                                                                               | Use and, or, not and !=. Apply the diagnostic's machine fix; and/or take positional operands or a collection.                                                                                                                                                                                                                                                                                                                                                                                      |
+| `E_ROLE_TYPE_MISMATCH`                   | A mapped entity field has the wrong type                    | The entity field bound to a role field has a different type.                                                                                                                                                                                                                                              | Make the types match, using (Id Entity) where the role has (Id role).                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `E_SCENARIO_ASSERT`                      | A scenario expectation did not hold                         | The observed status, work, rejection or property differed from (expect …).                                                                                                                                                                                                                                | Inspect the expected/actual values; correct the rule if the example is right, or the example if the rule is right.                                                                                                                                                                                                                                                                                                                                                                                 |
+| `E_SCENARIO_DATE`                        | A scenario date is invalid or goes backwards                | Observation dates must be real dates and nondecreasing.                                                                                                                                                                                                                                                   | Use YYYY-MM-DD dates in nondecreasing order.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `E_SCENARIO_NOT_FOUND`                   | --scenario names no scenario                                | The name passed to worldvm test --scenario is not declared.                                                                                                                                                                                                                                               | Use one of the names listed in the help.                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `E_SCENARIO_REF`                         | A scenario names something undeclared                       | An entity alias, account, component, requirement or property is unknown in this scenario.                                                                                                                                                                                                                 | Use names declared in this world, and declare local aliases in given.                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `E_SCENARIO_RUN`                         | A scenario command could not run                            | Most often "Unasserted command rejection": a do command was rejected and no (expect (rejected n) …) follows. Also commands that reference state the scenario did not create.                                                                                                                              | Assert the rejection with (expect (rejected 1) :decision-authority), or fix the command; AUTHORING.md section 9 lists the rejection codes.                                                                                                                                                                                                                                                                                                                                                         |
+| `E_SCENARIO_SHAPE`                       | A scenario block is malformed                               | Scenarios are (scenario name "Doc." :world account (given …) (do …) (at "date" (expect …)) …).                                                                                                                                                                                                            | Use finite given entity/evidence/signal records, do commands, and dated at/expect blocks.                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `E_SCENARIO_TYPE`                        | A scenario value has the wrong type                         | A literal does not match the declared field or key type.                                                                                                                                                                                                                                                  | Use a literal of the declared type (:high for a keyword union, "YYYY-MM-DD" for Date).                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `E_SELF_APPROVAL`                        | The decision authority is excluded from signing             | :by names exactly the principal that :distinct-from excludes.                                                                                                                                                                                                                                             | Choose a different principal or a reviewer group.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `E_SOURCE_DATE`                          | A source :as-of is not a real YYYY-MM-DD date               | Dates are zero-padded ISO calendar dates.                                                                                                                                                                                                                                                                 | Pad the date ("2026-01-02"); a machine fix is offered when the date is otherwise valid.                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `E_SOURCE_KIND`                          | A source has an unsupported :kind                           | Only a fixed set of source kinds is accepted.                                                                                                                                                                                                                                                             | Choose :law, :regulation, :guidance, :framework, :contract or :policy.                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `E_SURFACE_INVALID_FORM`                 | Compiler diagnostic (surface/invalid-form)                  | The compiler reported E_SURFACE_INVALID_FORM, formerly surface/invalid-form.                                                                                                                                                                                                                              | Review this declaration and correct the reported syntax, type or reference.                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `E_TABLE_NOT_EXHAUSTIVE`                 | A table does not cover every keyword                        | A keyword-union selector has a value with no row.                                                                                                                                                                                                                                                         | Cover every value of the union, or add :else.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `E_TABLE_SHAPE`                          | A (table …) is malformed                                    | Tables select on a keyword parameter of a derive.                                                                                                                                                                                                                                                         | Use (table keyword-parameter :value result ... :else fallback) inside a derive.                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `E_TEST_RUNTIME`                         | The test engine threw                                       | An internal failure while running a scenario or property.                                                                                                                                                                                                                                                 | Reduce the failing scenario/property to its source example and report it.                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `E_UNBOUNDED_TIME`                       | A time expression has no finite bound                       | Clock reads must compare against a fact-based cutoff so the reconciler can schedule wakeups.                                                                                                                                                                                                              | Shift a fact-based date, not the clock: :due (days-after vendor.opened 3).                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `E_UNBOUND_ROLE_FIELD`                   | An entity does not map a role field                         | The entity's :implements omits a field the role declares.                                                                                                                                                                                                                                                 | Map every role field: {role-field entity-field}.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `E_UNKNOWN_FIELD`                        | A field name is not declared                                | A rule, layout or binding names a field missing from the evidence or role.                                                                                                                                                                                                                                | Use a declared evidence or role field name.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `E_UNKNOWN_REQUIREMENT`                  | A name refers to a requirement that is not declared here    | An action's :advances, an output or a decision's :applies names a requirement not declared in the same component.                                                                                                                                                                                         | Name only requirements declared in the same component.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `E_UNKNOWN_SOURCE`                       | A citation names an undeclared source                       | :cites refers to a source that has no (source ...) declaration.                                                                                                                                                                                                                                           | Declare the source with (source name ...), then cite its specific clause.                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `E_USAGE`                                | Invalid command line                                        | Unknown subcommand, missing directory or an option the subcommand does not accept.                                                                                                                                                                                                                        | Run worldvm --help or worldvm <command> --help.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `I_DETECT_ONLY`                          | This requirement detects a state it could prevent           | The requirement has no producer and applies when a fact field has a particular value, so it only flags the state after the write. Nothing blocks the write itself.                                                                                                                                        | Keep the detection, and add an invariant that rejects the labelled write while the review is incomplete: (invariant no-activation-before-review :forbids (action-kind :activate :subject vendor) :while (not (met? self.review-complete))). Scenarios exercise it with (set v :status :active :kind :activate :subject v :by buyer) and (expect (rejected 1) :no-activation-before-review). Only writes submitted as commands with that :kind are checked, and an Unknown :while admits the write. |
+| `I_EXTENDED_FORM`                        | This form is outside the core language                      | check --core found an extended declaration or child form.                                                                                                                                                                                                                                                 | Use the ten core forms when possible, or keep this form and consult AUTHORING.md for its extended semantics.                                                                                                                                                                                                                                                                                                                                                                                       |
+| `W_ATTESTED_EXPIRING`                    | attested ignores this evidence's :expires                   | (attested E) is true once any record was signed, even after it expired. The evidence declares :expires, which suggests validity was intended.                                                                                                                                                             | Use (valid E), which is false once the signed expiry passes. A machine fix replaces attested with valid. Keep attested only when historical signing is what matters.                                                                                                                                                                                                                                                                                                                               |
+| `W_CROSS_HOME_READ`                      | A read crosses into a home not proven equal                 | A parent reads a child's output through a reference whose home may differ.                                                                                                                                                                                                                                | Usually advisory; route the read through a child declared with :bind on the same home if possible.                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `W_ERASURE_CONFLICT`                     | Erasure may conflict with retention                         | A vault allows on-request erasure while a cited retention obligation still applies.                                                                                                                                                                                                                       | Resolve the retention obligation before shredding.                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `W_NO_PRODUCER`                          | No action advances this requirement                         | Nothing can be done to satisfy the requirement from inside the world: no (action … :advances r) and no machine signal. Common and fine for detection requirements that flag a state.                                                                                                                      | If people should act, add (action do-r :advances r :assignee … :via (interaction …)). If it is a detection, keep it in an output and accept this warning; to block the state instead of flagging it, add an (invariant …) (see AUTHORING.md, Detect vs prevent).                                                                                                                                                                                                                                   |
+| `W_NO_SCENARIO`                          | No scenario observes this requirement                       | No scenario expects its status, an output containing it, or work/evidence advancing it.                                                                                                                                                                                                                   | Add a scenario with (expect (status (Component alias) requirement) :Open) and a step that satisfies it; worldvm coverage shows branches actually taken.                                                                                                                                                                                                                                                                                                                                            |
+| `W_NS_DEFAULTED`                         | An entity's attribute namespace was defaulted               | Without :ns, renaming the entity changes every stored attribute name.                                                                                                                                                                                                                                     | Pin it: :ns :example.vendor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `W_PROPERTY_VACUOUS`                     | An implication was never exercised                          | No generated case made this implies antecedent true; passing does not establish its consequent.                                                                                                                                                                                                           | Add a property given block with facts and evidence that exercise the antecedent. Vacuity warns without failing test or coverage.                                                                                                                                                                                                                                                                                                                                                                   |
+| `W_SATISFIED_NOT_APPLICABLE`             | satisfied? is false for NotApplicable                       | (satisfied? r) is true only for Satisfied or Waived. Reading a requirement with :applies-when inside and or :needs means the conjunction can never hold when r does not apply. Reading an all-of output whose members can all be NotApplicable has the same effect: the output is then NotApplicable too. | Use (met? r), which is true for Satisfied, Waived or NotApplicable, on the requirement or the output. The machine fix replaces satisfied? with met?.                                                                                                                                                                                                                                                                                                                                               |
+| `W_SHOW_COVERAGE_UNPROVEN`               | Layout coverage of a required field cannot be proven        | A rule's predicate reads non-enum fields, so the checker cannot enumerate cases.                                                                                                                                                                                                                          | Use keyword enums in rule predicates, or show the field unconditionally.                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `W_UNCITED`                              | A requirement/invariant/retention has no citation           | Every obligation should say which source clause it implements.                                                                                                                                                                                                                                            | Add :cites [(source-name "clause")].                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `W_UNHANDLED_STATUS`                     | A custom child-output expression ignores a status           | The expression does not say what happens for NotApplicable or Unknown.                                                                                                                                                                                                                                    | Handle NotApplicable/Unknown explicitly or use all-of/any-of.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `W_UNREACHABLE_REQUIREMENT`              | Nothing reads this requirement's status                     | The requirement is in no output and no expression reads it, so it never affects a result.                                                                                                                                                                                                                 | Add it to an output, e.g. (output review-complete (all-of questionnaire soc2 dpa)), or remove it. A machine fix is offered when the component has exactly one all-of output.                                                                                                                                                                                                                                                                                                                       |
+
+### Renamed diagnostic codes
+
+| Old code                               | New code                                 |
+| -------------------------------------- | ---------------------------------------- |
+| `read/syntax`                          | `E_READ_SYNTAX`                          |
+| `parse/syntax`                         | `E_PARSE_SYNTAX`                         |
+| `surface/invalid-form`                 | `E_SURFACE_INVALID_FORM`                 |
+| `artifact/untyped-runtime-declaration` | `E_ARTIFACT_UNTYPED_RUNTIME_DECLARATION` |
+| `elaborate/unknown-form`               | `E_ELABORATE_UNKNOWN_FORM`               |
+| `elaborate/hole-type`                  | `E_ELABORATE_HOLE_TYPE`                  |
+| `elaborate/unknown-reference`          | `E_ELABORATE_UNKNOWN_REFERENCE`          |
+| `elaborate/reference-type`             | `E_ELABORATE_REFERENCE_TYPE`             |
+| `elaborate/missing-slot`               | `E_ELABORATE_MISSING_SLOT`               |
+| `elaborate/invalid-slot-value`         | `E_ELABORATE_INVALID_SLOT_VALUE`         |
+| `elaborate/malformed-form`             | `E_ELABORATE_MALFORMED_FORM`             |
+| `elaborate/duplicate-declaration`      | `E_ELABORATE_DUPLICATE_DECLARATION`      |
+| `elaborate/form-check`                 | `E_ELABORATE_FORM_CHECK`                 |
+| `elaborate/missing-identifier`         | `E_ELABORATE_MISSING_IDENTIFIER`         |
+| `elaborate/validation-failed`          | `E_ELABORATE_VALIDATION_FAILED`          |
+| `elaborate/action-definition`          | `E_ELABORATE_ACTION_DEFINITION`          |
+| `elaborate/construct-failed`           | `E_ELABORATE_CONSTRUCT_FAILED`           |
+| `elaborate/expansion-failed`           | `E_ELABORATE_EXPANSION_FAILED`           |
+| `elaborate/form-definition`            | `E_ELABORATE_FORM_DEFINITION`            |
+| `elaborate/no-construct-hook`          | `E_ELABORATE_NO_CONSTRUCT_HOOK`          |
+| `elaborate/result-type-failed`         | `E_ELABORATE_RESULT_TYPE_FAILED`         |
+| `elaborate/unsupported-form`           | `E_ELABORATE_UNSUPPORTED_FORM`           |
+
+<!-- catalogue:end -->
+
+```forma broken=W_ATTESTED_EXPIRING
+(library example.expiring "attested ignores expiry." :version "1.0" :subject expiring/item)
+(role expiring/item "An item with an owner." {:owner (Id expiring/item)})
+(evidence Licence "A licence with an end date." :of Expiring :expires valid-until
+  {:valid-until Date}
+  (attest :signer item.owner :covers :all :method :otp))
+(component Expiring "Warns: attested stays true after expiry." :key [item]
+  :inputs {:item (Id expiring/item)}
+  (requirement licensed :satisfied-by (attested Licence))
+  (output done (all-of licensed)))
+```
+
+```forma broken=E_ELABORATE_UNKNOWN_FORM
+(requirment stray :satisfied-by true)
+```
+
+## 11. Units and dates
+
+- Dates are strings `"YYYY-MM-DD"`; instants are zoned RFC 3339 strings such as
+  `"2026-11-02T09:00:00Z"`, or `(instant "…")` in expressions. `today` is the evaluation date and
+  `now` the evaluation instant; the CLI never reads the system clock.
+- Durations: `(days n)`, `(months n)`, `(years n)`, `(hours n)`, `(minutes n)`.
+- Date arithmetic: `(days-after d n)`, `(days-before d n)`, `(months-after d n)`,
+  `(years-after d n)`, `(business-days-after d n :calendar cal)`, `(hours-after i n)`,
+  `(minutes-after i n)`, `(earliest [d …])`, `(latest [d …])`.
+- Months keep the day of month and clamp to the end of shorter months: January 31 plus one month
+  is February 28 (29 in a leap year). Years clamp February 29 to February 28.
+- Expiry relative to signing: `:expires (months-after signed-on 12)` on evidence. Relative to a
+  decision: `:expires (months 6)` on the decision. Both are exclusive: the record or decision
+  stops counting on that date.
+- `:recur {:every …}`, `:renew-within`, `:reuse :within`, collection `:confirm-after`, escalation
+  delays and policy parameter bounds count exact days, years, hours or minutes and reject months.
+  Use `(days 30)` or `(years 1)` there.
+- `:due` is a date (or instant); a requirement open after its due date is `Overdue`.
+- A signal-driven case can use `:due (business-days-after (entered-at case :referred) 10 :calendar us-federal)`
+  with a declared calendar. `case` must be a machine declared in the current component;
+  connector ownership is allowed and no resource declaration is needed. `entered-at` returns
+  the UTC Date of the first observation in the latest visit to the state. Consecutive duplicate
+  states keep that date; leaving and re-entering resets it. After departure the last entry date
+  remains available. Before an observed entry it is Unknown. Managed-resource machines read only
+  the current acquisition generation. `resource-generation` and `attested-for` remain resource-only.
+
+## 12. Idioms and anti-patterns
+
+- Type the library against roles, never entities. Entities live only in the account package.
+- One component per subject and requirement scope; use `:key` for identity, not a name string.
+- Model flags as keyword unions; avoid comparing a Bool field with `true`.
+- Use `valid` for anything with an expiry; keep `attested` for history.
+- Combine requirements with an output and read it with `(met? self.<output>)`, never by
+  conjoining `satisfied?` of requirements that can be NotApplicable.
+- To stop a write rather than flag it, pair the detection with an `invariant` over a labelled
+  command (section 8).
+- Cite a clause on every requirement and decision; keep sources synthetic and say so.
+- Every requirement deserves a scenario that shows it Open and one that shows it closed. Run
+  `worldvm coverage` to find the ones you missed, then `worldvm coverage --mutate`: each
+  surviving mutant (for example `valid` → `attested` still passing) is behaviour no test pins
+  down.
+- Decisions are made by people. Agents may draft or recommend, never sign or
+  decide.
+
+## 13. Recipes and a complete example
+
+**Renewal.** `:renew-within (days N)` on a requirement satisfied by `(valid E)` opens replacement
+work N days before the record expires, while the requirement stays Satisfied:
+
+```forma excerpt
+  (requirement questionnaire
+    :cites [(vendor-policy "1: completed security questionnaire, renewed every 12 months")]
+    :applies-when (!= vendor.tier :none)
+    :satisfied-by (valid SecurityQuestionnaire)
+    :renew-within (days 30))
+```
+
+**Exception with expiry.** Satisfy a requirement by evidence or by a decision, and give the
+decision `:by`, `:reason` and `:expires`:
+
+```forma excerpt
+(decision approve-exception
+  "Only a CISO approves a SOC 2 exception, with a reason; it lasts six months."
+  :of VendorReview :applies soc2-or-exception :by (members vendor.cisos)
+  :effect :approve :reason String :expires (months 6)
+  :cites [(vendor-policy "5: CISO-only exceptions with a reason, expiring after six months")])
+```
+
+These excerpts come from [`docs/authoring/vendor-risk`](docs/authoring/vendor-risk/), a complete
+vendor-review world: 12-month questionnaires from `signed-on`, six-month CISO exceptions, a DPA
+for high-risk vendors, and an activation invariant next to its detection. It passes `check` and
+`test`, and `coverage --mutate` leaves no surviving mutant. `eval/` grades new cold-author worlds
+against the same brief.