worldvm 0.0.0-stage → 0.1.0

package/dist/_internal/world-ir/types.generated.js

@@ -0,0 +1 @@
+export {};

package/dist/authoring.d.ts

@@ -0,0 +1,9 @@
+export * from "./manual/text.js";
+export * from "./manual/catalog.js";
+export * from "./manual/examples.js";
+export * from "./manual/prose.js";
+export * from "./manual/projections.js";
+export * from "./manual/render.js";
+export * from "./release/nodes.js";
+export * from "./release/diff.js";
+export * from "./release/impact.js";

package/dist/authoring.js

@@ -0,0 +1,10 @@
+// Filesystem-free authoring projections shared by the CLI and the browser World IDE.
+export * from "./manual/text.js";
+export * from "./manual/catalog.js";
+export * from "./manual/examples.js";
+export * from "./manual/prose.js";
+export * from "./manual/projections.js";
+export * from "./manual/render.js";
+export * from "./release/nodes.js";
+export * from "./release/diff.js";
+export * from "./release/impact.js";

package/dist/catalogue.d.ts

@@ -0,0 +1,20 @@
+export interface CatalogueEntry {
+    /** One-line summary. */
+    readonly title: string;
+    /** Why authors usually see this. */
+    readonly cause: string;
+    /** A short source fragment that triggers it (or a command line). */
+    readonly example: string;
+    /** What to change. */
+    readonly fix: string;
+}
+export declare const GENERIC_HELP = "Review this declaration and correct the reported syntax, type or reference.";
+export declare const CATALOGUE: Readonly<Record<string, CatalogueEntry>>;
+export declare const catalogueEntry: (code: string) => CatalogueEntry | undefined;
+/** Plain-text explanation used by `worldvm explain`. */
+export declare const explain: (code: string) => string | undefined;
+/** Edit distance for did-you-mean suggestions. */
+export declare const distance: (a: string, b: string) => number;
+export declare const closest: (word: string, candidates: readonly string[]) => string | undefined;
+/** The diagnostics catalogue section of AUTHORING.md, generated from the table. */
+export declare const catalogueMarkdown: () => string;

package/dist/catalogue.js

@@ -0,0 +1,531 @@
+/**
+ * The authoring diagnostics catalogue: one row per diagnostic code an author is likely to
+ * meet. It is the single source of truth for `worldvm explain <code>`, for the default help
+ * attached to compiler diagnostics that carry none, and for the catalogue in
+ * AUTHORING.md (a test checks that the document lists every row).
+ *
+ * The compiler's own messages and help strings are left untouched so compiled lab goldens
+ * stay byte-identical; the CLI layers this table and contextual refinements on top.
+ */
+import { DIAGNOSTIC_RENAMES, TOP_LEVEL_FORMS } from "./_internal/forma/world/index.js";
+const generic = "Review this declaration and correct the reported syntax, type or reference.";
+export const GENERIC_HELP = generic;
+export const CATALOGUE = {
+    ...Object.fromEntries(Object.entries(DIAGNOSTIC_RENAMES).map(([old, code]) => [
+        code,
+        {
+            title: `Compiler diagnostic (${old})`,
+            cause: `The compiler reported ${code}, formerly ${old}.`,
+            example: "",
+            fix: generic,
+        },
+    ])),
+    E_RENAMED_OPERATOR: {
+        title: "An operator was renamed",
+        cause: "The source uses all?, any?, negate or not=.",
+        example: "(negate condition)",
+        fix: "Use and, or, not and !=. Apply the diagnostic's machine fix; and/or take positional operands or a collection.",
+    },
+    I_EXTENDED_FORM: {
+        title: "This form is outside the core language",
+        cause: "check --core found an extended declaration or child form.",
+        example: "(calendar …)",
+        fix: "Use the ten core forms when possible, or keep this form and consult AUTHORING.md for its extended semantics.",
+    },
+    // ── Reader and elaboration (Forma) ──
+    E_READ_SYNTAX: {
+        title: "The file does not parse",
+        cause: "Unbalanced parentheses/brackets, an unterminated string or a stray character.",
+        example: '(library example.vendor "Doc." :version "1.0"',
+        fix: "Balance every ( [ { with its closer and close every string; the location points at the first unreadable token.",
+    },
+    E_ELABORATE_UNKNOWN_FORM: {
+        title: "A top-level form name is not a world declaration",
+        cause: "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.",
+        example: "(requirement questionnaire :satisfied-by (valid SecurityQuestionnaire))",
+        fix: `Use one of: ${TOP_LEVEL_FORMS.join(", ")}. Child forms such as requirement, action, output and invariant go inside (component ...).`,
+    },
+    E_ELABORATE_HOLE_TYPE: {
+        title: "An expression has the wrong type for its slot",
+        cause: "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.",
+        example: "(requirement dpa :applies-when (and (= vendor.tier :high) vendor.active) ...)",
+        fix: "Use and, or, not, = and != in every context; collapse Truth to Bool only with (true? x) inside if.",
+    },
+    E_ELABORATE_UNKNOWN_REFERENCE: {
+        title: "A reference names nothing declared",
+        cause: "A role, entity, component, evidence, decision or interaction name is misspelled or not declared in any file of the world.",
+        example: "(interaction Entry :produces SecurityQuestionaire ...)",
+        fix: "Declare the target or correct the spelling; names are case-sensitive and global to the world directory.",
+    },
+    E_ELABORATE_REFERENCE_TYPE: {
+        title: "A reference names the wrong kind of declaration",
+        cause: "For example :produces names a role instead of an evidence type, or :of names an entity instead of a component.",
+        example: '(evidence Review "…" :of vendor/record {...})',
+        fix: "Point the option at a declaration of the expected kind (see the message).",
+    },
+    E_ELABORATE_MISSING_SLOT: {
+        title: "A required option or part is missing",
+        cause: "The form needs a name, docstring, option or field map that was omitted.",
+        example: '(library example.vendor :version "1.0")',
+        fix: "Add the missing part named in the message; compare with the minimal world in AUTHORING.md.",
+    },
+    E_ELABORATE_INVALID_SLOT_VALUE: {
+        title: "An option has a value of the wrong shape",
+        cause: "A keyword, vector or map was expected but something else was supplied.",
+        example: ":key vendor",
+        fix: "Use the shape named in the message, for example :key [vendor].",
+    },
+    E_ELABORATE_MALFORMED_FORM: {
+        title: "A form's parts are out of order or malformed",
+        cause: "Positional parts (name, docstring, field map) are missing or in the wrong order.",
+        example: '(role {:name String} vendor/person "A person.")',
+        fix: 'Write (form name "Doc." :option value ... {fields} children...).',
+    },
+    E_ELABORATE_DUPLICATE_DECLARATION: {
+        title: "Two declarations share a name",
+        cause: "Names are global across every .forma file in the world directory.",
+        example: "(type Tier (Union :a)) … (type Tier (Union :b))",
+        fix: "Rename or delete one declaration.",
+    },
+    E_ELABORATE_FORM_CHECK: {
+        title: "A declaration failed one of its publish checks",
+        cause: "The prelude's per-form checks (key closure, unknown fields, and similar) rejected it.",
+        example: ":key [vendor] :inputs {:owner (Id vendor/person)}",
+        fix: "Follow the message; it names the field or child that failed.",
+    },
+    E_ELABORATE_MISSING_IDENTIFIER: {
+        title: "A form is missing its name",
+        cause: "The first argument after the form head must be a symbol naming the declaration.",
+        example: '(component "Track one vendor." ...)',
+        fix: 'Insert a name: (component VendorReview "Track one vendor." ...).',
+    },
+    E_ELABORATE_VALIDATION_FAILED: {
+        title: "A child form is not valid inside its parent",
+        cause: 'Usually "Expected child form X-child": a misspelt child inside component, layout, step or evidence.',
+        example: '(component C "Doc." :key [x] :inputs {:x (Id r)} (requirment r :satisfied-by …))',
+        fix: "Help lists the valid children of that parent; correct the child form's head.",
+    },
+    // ── Lowering and publish checks ──
+    E_LOWER: {
+        title: "An expression cannot be lowered to the kernel",
+        cause: "A name is not in scope, a dotted path names no field, or a call is neither a kernel function nor a derive.",
+        example: ":applies-when (or (= vendor.tier :high) (= vendor.tier :standard))",
+        fix: "Use kernel functions only: and/or/not for logic, in? for membership; declare a (derive ...) for reusable logic.",
+    },
+    E_MISSING_DOC: {
+        title: "A published declaration has no docstring",
+        cause: "Libraries, roles, entities, components, evidence, decisions, scenarios and properties need a nonempty docstring.",
+        example: "(component VendorReview :key [vendor] ...)",
+        fix: 'Add a docstring right after the name: (component VendorReview "Track one vendor." ...).',
+    },
+    E_LINK: {
+        title: "An account does not link against its library",
+        cause: "The account's :requires names a library/version that is not declared, or an entity does not :implements every role field the library needs.",
+        example: '(account example "…" :requires {example.vendor "2.0"} ...)',
+        fix: "Match :requires to the (library … :version …) declaration and map every role field in the entity's :implements.",
+    },
+    E_UNBOUND_ROLE_FIELD: {
+        title: "An entity does not map a role field",
+        cause: "The entity's :implements omits a field the role declares.",
+        example: ":implements {vendor/record {:name name}}  ; role also has :owner",
+        fix: "Map every role field: {role-field entity-field}.",
+    },
+    E_ROLE_TYPE_MISMATCH: {
+        title: "A mapped entity field has the wrong type",
+        cause: "The entity field bound to a role field has a different type.",
+        example: "role {:owner (Id vendor/person)} mapped to entity {:owner String}",
+        fix: "Make the types match, using (Id Entity) where the role has (Id role).",
+    },
+    E_UNKNOWN_REQUIREMENT: {
+        title: "A name refers to a requirement that is not declared here",
+        cause: "An action's :advances, an output or a decision's :applies names a requirement not declared in the same component.",
+        example: "(action submit :advances questionnaires ...)",
+        fix: "Name only requirements declared in the same component.",
+    },
+    E_UNKNOWN_FIELD: {
+        title: "A field name is not declared",
+        cause: "A rule, layout or binding names a field missing from the evidence or role.",
+        example: '(step record "Record" (field sumary) (sign))',
+        fix: "Use a declared evidence or role field name.",
+    },
+    E_UNKNOWN_SOURCE: {
+        title: "A citation names an undeclared source",
+        cause: ":cites refers to a source that has no (source ...) declaration.",
+        example: ':cites [(policy "1: questionnaire")]',
+        fix: "Declare the source with (source name ...), then cite its specific clause.",
+    },
+    E_CITATION: {
+        title: "A :cites value is malformed",
+        cause: ':cites must be a vector of (source "clause") pairs.',
+        example: ':cites (brief-policy "1")',
+        fix: 'Write :cites [(brief-policy "1: clause text")].',
+    },
+    E_SOURCE_KIND: {
+        title: "A source has an unsupported :kind",
+        cause: "Only a fixed set of source kinds is accepted.",
+        example: '(source p "…" :kind :memo ...)',
+        fix: "Choose :law, :regulation, :guidance, :framework, :contract or :policy.",
+    },
+    E_SOURCE_DATE: {
+        title: "A source :as-of is not a real YYYY-MM-DD date",
+        cause: "Dates are zero-padded ISO calendar dates.",
+        example: ':as-of "2026-1-2"',
+        fix: 'Pad the date ("2026-01-02"); a machine fix is offered when the date is otherwise valid.',
+    },
+    E_NO_HOME: {
+        title: "A component has no entity home",
+        cause: "The first :key input must be an entity reference (Id E), directly or through another component.",
+        example: ":key [client] :inputs {:client Keyword}",
+        fix: "Put an (Id role) input first in :key, for example :key [vendor].",
+    },
+    E_KEY_NOT_INPUT: {
+        title: "A :key name is not an input",
+        cause: "Every :key entry must also appear in :inputs.",
+        example: ":key [vendor] :inputs {:record (Id vendor/record)}",
+        fix: "Rename the key or the input so they match.",
+    },
+    E_READ_OUTSIDE_KEY: {
+        title: "An expression reads a non-key input",
+        cause: "Shared/keyed components and decisions may only read key inputs and their reference paths.",
+        example: ':key [vendor] … (= owner.name "x")',
+        fix: "Read only key inputs and their reference paths, or include this input in the component key.",
+    },
+    E_ADVANCES: {
+        title: "An action's :advances is malformed",
+        cause: ":advances must name one requirement or a vector of distinct requirement names.",
+        example: "(action submit :advances [] ...)",
+        fix: "Use one declared requirement name or a nonempty vector of distinct local names.",
+    },
+    E_OUTPUT: {
+        title: "An output expression is not supported",
+        cause: "Outputs combine statuses; they are not general expressions.",
+        example: "(output done (and a b))",
+        fix: "Write (output name (all-of a b)), (any-of a b) or (status-of a).",
+    },
+    E_EXPIRES_SCOPE: {
+        title: "An evidence :expires reads outside its signed fields",
+        cause: "Expiry may read only the evidence's own signed fields, signed-on (the signing date) and pure date logic.",
+        example: ":expires (days-after vendor.opened 365)",
+        fix: "Compute expiry from the signing date, :expires (months-after signed-on 12), or from a signed date field, :expires valid-until.",
+    },
+    E_UNBOUNDED_TIME: {
+        title: "A time expression has no finite bound",
+        cause: "Clock reads must compare against a fact-based cutoff so the reconciler can schedule wakeups.",
+        example: ":due (days-after today 3)",
+        fix: "Shift a fact-based date, not the clock: :due (days-after vendor.opened 3).",
+    },
+    E_DECISION_EFFECT: {
+        title: "Unsupported decision effect",
+        cause: "Decision :effect must be one of the kernel effects.",
+        example: ":effect :allow",
+        fix: "Choose :approve, :reject, :waive, :defer, :accept or :add.",
+    },
+    E_DECISION_REASON: {
+        title: "Unsupported decision reason type",
+        cause: ":reason must be a scalar, a keyword union, or an Option/alias of one.",
+        example: ":reason {:text String}",
+        fix: "Use :reason String (or a keyword union); structured records belong in evidence.",
+    },
+    E_DECISION_TARGET: {
+        title: "A decision applies to something its component does not own",
+        cause: ":applies names a requirement not declared in the :of component.",
+        example: "(decision approve-exception :of VendorReview :applies soc2 ...)",
+        fix: "Name a requirement declared in the :of component.",
+    },
+    E_SELF_APPROVAL: {
+        title: "The decision authority is excluded from signing",
+        cause: ":by names exactly the principal that :distinct-from excludes.",
+        example: ":by change.author :distinct-from [change.author]",
+        fix: "Choose a different principal or a reviewer group.",
+    },
+    E_TABLE_SHAPE: {
+        title: "A (table …) is malformed",
+        cause: "Tables select on a keyword parameter of a derive.",
+        example: "(table tier :high)",
+        fix: "Use (table keyword-parameter :value result ... :else fallback) inside a derive.",
+    },
+    E_TABLE_NOT_EXHAUSTIVE: {
+        title: "A table does not cover every keyword",
+        cause: "A keyword-union selector has a value with no row.",
+        example: "(table tier :high true)  ; tier is (Union :high :standard :none)",
+        fix: "Cover every value of the union, or add :else.",
+    },
+    // ── Properties ──
+    E_PROPERTY_SHAPE: {
+        title: "A property expression uses an unsupported form",
+        cause: "Properties are closed finite predicates with their own small operator set; runtime vocabulary (valid, decided, days-after …) is not available there.",
+        example: ":for-all (v Vendor) (and (= v.status :active))",
+        fix: "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_REF: {
+        title: "A property names an unknown world, binding, field or clause",
+        cause: "The :world account, :for-all entity, a field path or a status/evidence name is not declared.",
+        example: "(status (VendorReview v) reviewd)",
+        fix: "Use an entity in this account package, its declared fields, and a component requirement/output or evidence type.",
+    },
+    E_PROPERTY_TYPE: {
+        title: "A property operand has the wrong type",
+        cause: "Comparison of incompatible values, or a non-boolean under and/or/implies.",
+        example: '(= v.tier "high")',
+        fix: 'Compare like with like (keywords as :high, dates as "YYYY-MM-DD"); logic needs booleans; status predicates need (status …).',
+    },
+    E_PROPERTY_DATE: {
+        title: "A property :at is not a real date",
+        cause: "Properties never read the system clock; :at must be a fixed date or zoned instant.",
+        example: ':at "2026-11-6"',
+        fix: 'Use YYYY-MM-DD, e.g. :at "2026-11-06".',
+    },
+    E_PROPERTY_ASSERT: {
+        title: "A property was false or Unknown for a generated case",
+        cause: "The predicate failed; the report includes a shrunk counterexample scenario.",
+        example: "worldvm test my-world --seed 42",
+        fix: "Replay the counterexample source; then correct the rule, or narrow the property with implies/known?.",
+    },
+    W_PROPERTY_VACUOUS: {
+        title: "An implication was never exercised",
+        cause: "No generated case made this implies antecedent true; passing does not establish its consequent.",
+        example: "(implies false true)",
+        fix: "Add a property given block with facts and evidence that exercise the antecedent. Vacuity warns without failing test or coverage.",
+    },
+    E_FIXES_SHAPE: {
+        title: "Interaction fixed values need a map",
+        cause: ":fixes accepts evidence field names and scalar literals.",
+        example: ":fixes [:examination :remote]",
+        fix: "Use :fixes {:examination :remote}.",
+    },
+    E_FIXES_TYPE: {
+        title: "A fixed value has the wrong evidence field type",
+        cause: "The literal does not fit the declared field, including keyword union membership.",
+        example: ":fixes {:examination :unknown}",
+        fix: "Use a scalar literal of the evidence field's declared type.",
+    },
+    E_FIXES_CONFLICT: {
+        title: "A fixed field has another value source",
+        cause: "A field is fixed more than once or also uses binds, prefill or proposes.",
+        example: ":fixes {:examination :remote} :prefill {:examination person.examination}",
+        fix: "Give each fixed field exactly one literal value source.",
+    },
+    E_FIXES_LAYOUT: {
+        title: "A layout shows an interaction fixed field",
+        cause: "The interaction supplies this value, so the signer must not be prompted for it.",
+        example: ":fixes {:examination :remote} with (field examination) in its layout",
+        fix: "Remove the fixed field from the layout, including nested groups.",
+    },
+    // ── Scenarios ──
+    E_SCENARIO_SHAPE: {
+        title: "A scenario block is malformed",
+        cause: 'Scenarios are (scenario name "Doc." :world account (given …) (do …) (at "date" (expect …)) …).',
+        example: "(scenario s :world example (expect …))",
+        fix: "Use finite given entity/evidence/signal records, do commands, and dated at/expect blocks.",
+    },
+    E_SCENARIO_REF: {
+        title: "A scenario names something undeclared",
+        cause: "An entity alias, account, component, requirement or property is unknown in this scenario.",
+        example: "(expect (status (VendorReview v) questionaire) :Open)",
+        fix: "Use names declared in this world, and declare local aliases in given.",
+    },
+    E_SCENARIO_TYPE: {
+        title: "A scenario value has the wrong type",
+        cause: "A literal does not match the declared field or key type.",
+        example: '(entity Vendor v {:tier "high"})',
+        fix: 'Use a literal of the declared type (:high for a keyword union, "YYYY-MM-DD" for Date).',
+    },
+    E_SCENARIO_DATE: {
+        title: "A scenario date is invalid or goes backwards",
+        cause: "Observation dates must be real dates and nondecreasing.",
+        example: '(at "2026-11-31" …)',
+        fix: "Use YYYY-MM-DD dates in nondecreasing order.",
+    },
+    E_SCENARIO_ASSERT: {
+        title: "A scenario expectation did not hold",
+        cause: "The observed status, work, rejection or property differed from (expect …).",
+        example: "(expect (status (VendorReview v) questionnaire) :Satisfied)",
+        fix: "Inspect the expected/actual values; correct the rule if the example is right, or the example if the rule is right.",
+    },
+    E_SCENARIO_RUN: {
+        title: "A scenario command could not run",
+        cause: '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.',
+        example: "(do (decide (VendorReview v) approve-exception :by owner))  ; owner is not a CISO",
+        fix: "Assert the rejection with (expect (rejected 1) :decision-authority), or fix the command; AUTHORING.md section 9 lists the rejection codes.",
+    },
+    E_SCENARIO_NOT_FOUND: {
+        title: "--scenario names no scenario",
+        cause: "The name passed to worldvm test --scenario is not declared.",
+        example: "worldvm test my-world --scenario typo",
+        fix: "Use one of the names listed in the help.",
+    },
+    // ── CLI ──
+    E_USAGE: {
+        title: "Invalid command line",
+        cause: "Unknown subcommand, missing directory or an option the subcommand does not accept.",
+        example: "worldvm chek my-world",
+        fix: "Run worldvm --help or worldvm <command> --help.",
+    },
+    E_NO_SOURCES: {
+        title: "The directory has no .forma files",
+        cause: "check/test/coverage compile every visible .forma file under the directory.",
+        example: "worldvm check ./empty",
+        fix: "Point at the world directory, or scaffold one with worldvm init <dir>.",
+    },
+    E_PROJECT_IO: {
+        title: "The directory cannot be read",
+        cause: "The path does not exist or is not readable.",
+        example: "worldvm check ./missing",
+        fix: "Pass a readable directory containing .forma source files.",
+    },
+    E_CHECK_THROW: {
+        title: "The compiler threw",
+        cause: "An internal compiler failure, not an authoring error.",
+        example: "",
+        fix: "Reduce the failing source to the smallest example and report it.",
+    },
+    E_TEST_RUNTIME: {
+        title: "The test engine threw",
+        cause: "An internal failure while running a scenario or property.",
+        example: "",
+        fix: "Reduce the failing scenario/property to its source example and report it.",
+    },
+    // ── Warnings ──
+    W_NO_PRODUCER: {
+        title: "No action advances this requirement",
+        cause: "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.",
+        example: "(requirement active-only-if-reviewed :applies-when (= vendor.status :active) :satisfied-by (satisfied? self.review-complete))",
+        fix: "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: {
+        title: "No scenario observes this requirement",
+        cause: "No scenario expects its status, an output containing it, or work/evidence advancing it.",
+        example: "(requirement dpa …) with no (expect (status (VendorReview v) dpa) …)",
+        fix: "Add a scenario with (expect (status (Component alias) requirement) :Open) and a step that satisfies it; worldvm coverage shows branches actually taken.",
+    },
+    W_UNREACHABLE_REQUIREMENT: {
+        title: "Nothing reads this requirement's status",
+        cause: "The requirement is in no output and no expression reads it, so it never affects a result.",
+        example: "(output review-complete (all-of questionnaire soc2))  ; dpa missing",
+        fix: "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.",
+    },
+    W_UNCITED: {
+        title: "A requirement/invariant/retention has no citation",
+        cause: "Every obligation should say which source clause it implements.",
+        example: "(requirement dpa :satisfied-by …)",
+        fix: 'Add :cites [(source-name "clause")].',
+    },
+    W_NS_DEFAULTED: {
+        title: "An entity's attribute namespace was defaulted",
+        cause: "Without :ns, renaming the entity changes every stored attribute name.",
+        example: '(entity Vendor "…" :implements {…} {…})',
+        fix: "Pin it: :ns :example.vendor.",
+    },
+    W_CROSS_HOME_READ: {
+        title: "A read crosses into a home not proven equal",
+        cause: "A parent reads a child's output through a reference whose home may differ.",
+        example: "(output ready (all-of hire.i9.complete))",
+        fix: "Usually advisory; route the read through a child declared with :bind on the same home if possible.",
+    },
+    W_UNHANDLED_STATUS: {
+        title: "A custom child-output expression ignores a status",
+        cause: "The expression does not say what happens for NotApplicable or Unknown.",
+        example: "(output ok (status-of child.done))",
+        fix: "Handle NotApplicable/Unknown explicitly or use all-of/any-of.",
+    },
+    W_SHOW_COVERAGE_UNPROVEN: {
+        title: "Layout coverage of a required field cannot be proven",
+        cause: "A rule's predicate reads non-enum fields, so the checker cannot enumerate cases.",
+        example: "(rule r :when (> amount 10) :requires [note])",
+        fix: "Use keyword enums in rule predicates, or show the field unconditionally.",
+    },
+    W_ERASURE_CONFLICT: {
+        title: "Erasure may conflict with retention",
+        cause: "A vault allows on-request erasure while a cited retention obligation still applies.",
+        example: "",
+        fix: "Resolve the retention obligation before shredding.",
+    },
+    // ── Authoring lints added by the CLI ──
+    W_ATTESTED_EXPIRING: {
+        title: "attested ignores this evidence's :expires",
+        cause: "(attested E) is true once any record was signed, even after it expired. The evidence declares :expires, which suggests validity was intended.",
+        example: "(evidence Questionnaire … :expires valid-until …)\n(requirement q :satisfied-by (attested Questionnaire))",
+        fix: "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_SATISFIED_NOT_APPLICABLE: {
+        title: "satisfied? is false for NotApplicable",
+        cause: "(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.",
+        example: "(and (satisfied? questionnaire) (satisfied? dpa))  ; dpa applies only to high tier\n(satisfied? self.review-complete)  ; every member has :applies-when",
+        fix: "Use (met? r), which is true for Satisfied, Waived or NotApplicable, on the requirement or the output. The machine fix replaces satisfied? with met?.",
+    },
+    I_DETECT_ONLY: {
+        title: "This requirement detects a state it could prevent",
+        cause: "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.",
+        example: "(requirement active-only-if-reviewed :applies-when (= vendor.status :active) …)",
+        fix: "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.",
+    },
+};
+export const catalogueEntry = (code) => {
+    const renamed = Object.hasOwn(DIAGNOSTIC_RENAMES, code) ? DIAGNOSTIC_RENAMES[code] : undefined;
+    if (renamed)
+        return (CATALOGUE[renamed] ?? {
+            title: `Diagnostic renamed to ${renamed}`,
+            cause: `${code} now uses the uniform diagnostic code ${renamed}.`,
+            example: "",
+            fix: generic,
+        });
+    return Object.hasOwn(CATALOGUE, code) ? CATALOGUE[code] : undefined;
+};
+/** Plain-text explanation used by `worldvm explain`. */
+export const explain = (code) => {
+    const entry = catalogueEntry(code);
+    if (!entry)
+        return undefined;
+    return [
+        `${code}${DIAGNOSTIC_RENAMES[code] ? ` was renamed to ${DIAGNOSTIC_RENAMES[code]}` : ""}: ${entry.title}`,
+        "",
+        `Cause: ${entry.cause}`,
+        ...(entry.example ? ["", "Example:", ...entry.example.split("\n").map((l) => `  ${l}`)] : []),
+        "",
+        `Fix: ${entry.fix}`,
+    ].join("\n");
+};
+/** Edit distance for did-you-mean suggestions. */
+export const distance = (a, b) => {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let prev = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const tmp = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+            prev = tmp;
+        }
+    }
+    return row[b.length];
+};
+export const closest = (word, candidates) => {
+    let best, score = Infinity;
+    for (const c of candidates) {
+        const d = distance(word, c);
+        if (d < score)
+            [best, score] = [c, d];
+    }
+    return best !== undefined && score <= Math.max(2, Math.floor(word.length / 3)) ? best : undefined;
+};
+/** The diagnostics catalogue section of AUTHORING.md, generated from the table. */
+export const catalogueMarkdown = () => {
+    const cell = (text) => text.replace(/\|/g, "\\|").replace(/\n/g, "<br>");
+    const rows = Object.keys(CATALOGUE)
+        .sort()
+        .map((code) => {
+        const e = CATALOGUE[code];
+        return `| \`${code}\` | ${cell(e.title)} | ${cell(e.cause)} | ${cell(e.fix)} |`;
+    });
+    return [
+        "| Code | Meaning | Usual cause | Fix |",
+        "| ---- | ------- | ----------- | --- |",
+        ...rows,
+        "",
+        "### Renamed diagnostic codes",
+        "",
+        "| Old code | New code |",
+        "| --- | --- |",
+        ...Object.entries(DIAGNOSTIC_RENAMES).map(([old, next]) => `| \`${old}\` | \`${next}\` |`),
+    ].join("\n");
+};

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export declare const main: () => Promise<number>;
+export * from "./index.js";