worldvm 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,155 @@
-# Temporary Holding Version
+# WorldVM
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+WorldVM is a requirement runtime. You declare what must be true in a _world_ (a directory of
+`.forma` files: requirements, evidence, deadlines and who may act), and WorldVM computes, for
+every subject, what is satisfied, what is missing, who must act next, and why.
+
+## Status
+
+`worldvm` 0.1.0 is a **preview**. Read this before depending on it.
+
+- **The package is published for evaluation, all rights reserved, with no licence granted yet.**
+- **Breaking changes are expected** in every 0.x release: the world language, the protocol
+  and the storage format.
+- **SQLite only, one process per database file.** Stop `serve` before you `deploy` to the
+  same file. Multi-process storage and Postgres are not available.
+- **`serve` has no authentication.** The `x-worldvm-actor` header is a trusted, development-only
+  identity. Put your own authentication in front of it, or embed WorldVM instead.
+- **`/v1/changes` is live only.** There is no replay cursor; after a disconnect, read the
+  current status and work again.
+- Node prints an `ExperimentalWarning` for `node:sqlite` when you embed the SQLite store.
+- Example worlds and data are synthetic, and their rules are illustrative, not legal or
+  compliance advice.
+
+## Install
+
+Requires Node 22.5 or later. Effect and Forma are peer dependencies:
+
+```sh
+npm install worldvm effect@^4.1.1 @forma-language/forma@^0.6.0
+```
+
+## A first world
+
+Run these in an empty project after installing:
+
+```sh
+npx worldvm init my-world        # writes a minimal passing world and REFERENCE.md
+npx worldvm check my-world       # compile, link accounts, report diagnostics
+npx worldvm test my-world        # run scenarios and seeded properties
+npx worldvm coverage my-world    # which requirements and cited clauses the tests reach
+```
+
+`check` prints `check: passed; 3 source files, 1 requirements`, and `test` passes one scenario
+and one property. Edit `my-world/library/starter.forma`, add scenarios under
+`my-world/scenarios/`, and rerun the loop.
+
+Serve it over HTTP on a SQLite file:
+
+```sh
+npx worldvm serve my-world --db my-world.db --port 3000 --clock 2026-03-01
+```
+
+In another terminal:
+
+```sh
+curl http://127.0.0.1:3000/v1/assert -H 'content-type: application/json' \
+  -H 'x-worldvm-actor: {"id":"system:hr","kind":"service"}' \
+  -d '{"type":"Person","subject":"olu","id":"hr-1","values":{"name":"Olu"}}'
+curl http://127.0.0.1:3000/v1/assert -H 'content-type: application/json' \
+  -H 'x-worldvm-actor: {"id":"system:hr","kind":"service"}' \
+  -d '{"type":"Subject","subject":"s1","id":"hr-2","values":{"name":"Synthetic subject","owner":"olu","opened":"2026-01-01"}}'
+curl http://127.0.0.1:3000/v1/work -H 'content-type: application/json' \
+  -H 'x-worldvm-actor: {"id":"olu","kind":"human"}' \
+  -d '{"type":"Subject","subject":"s1"}'
+```
+
+The last call lists one eligible action, `acknowledge`, assigned to `olu`.
+
+## Run a world inside your application
+
+The same world, embedded with a SQLite store. Save this as `embed.mjs` next to `my-world`
+and run `node embed.mjs`:
+
+```js
+import { open } from "worldvm";
+import { sqlite } from "worldvm/sqlite";
+
+const world = await open({
+  source: "./my-world",
+  store: sqlite("embedded.db"),
+  clock: () => "2026-03-01", // a fixed clock for the example; omit it to use the real clock
+});
+try {
+  await world.subject("Person", "olu").assert({ name: "Olu" }, { by: "system:hr" });
+  const subject = world.subject("Subject", "s1");
+  await subject.assert(
+    { name: "Synthetic subject", owner: "olu", opened: "2026-01-01" },
+    { by: "system:hr" },
+  );
+  console.log(subject.work()); // one eligible action: acknowledge, assigned to olu
+  const result = await subject.perform("acknowledge", {
+    by: "olu",
+    values: { summary: "Read and agreed" },
+  });
+  if (!result.accepted) throw new Error(result.codes.join(", "));
+  console.log(subject.status().instances[0].requirements); // acknowledged: Satisfied
+  console.log(JSON.stringify(subject.explain("acknowledged"), null, 2)); // cites starter-policy
+  console.log(subject.status("2027-03-02").instances[0].requirements); // a year later: Open
+} finally {
+  await world.close();
+}
+```
+
+## Documentation
+
+These files ship in the package, so they match the version you installed:
+
+- `node_modules/worldvm/docs/reference.md`: the core language on one page. `worldvm init`
+  also writes it into each new world as `REFERENCE.md`.
+- `node_modules/worldvm/AUTHORING.md`: the full authoring guide, including every form, Truth
+  and comparisons, scenarios, properties and the diagnostics catalogue.
+- `node_modules/worldvm/docs/protocol.md`: the operating protocol (library, HTTP and MCP).
+- `node_modules/worldvm/docs/authoring/vendor-risk/`: a complete synthetic example world.
+
+`worldvm explain <code>` prints the cause, an example and the fix for any diagnostic code;
+`worldvm explain --list` lists them.
+
+## Commands
+
+Every command has its own `--help`. JSON mode (`--json`) writes one versioned result to
+stdout; human diagnostics go to stderr. Exit 0 means success, 1 a failed check or test, and 2
+invalid usage.
+
+| Command                                                   | What it does                                                                                   |
+| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `init <dir>`                                              | Scaffold a minimal passing world                                                               |
+| `check <dir> [--core]`                                    | Compile, link accounts and lint; diagnostics carry locations, help and fixes                   |
+| `test <dir> [--scenario name] [--seed n] [--cases n]`     | Run scenarios and seeded properties; failures include a shrunk counterexample                  |
+| `coverage <dir> [--mutate]`                               | Measure which requirements and cited clauses tests reach; `--mutate` reports surviving mutants |
+| `render <dir> [--format markdown\|html] [--account name]` | Write the human-readable manual, with citations and examples                                   |
+| `explain <dir> --scenario name [--at instant]`            | Explain each status, due date and work item at a scenario instant                              |
+| `explain <dir> --world snapshot.json --subject id --at t` | Explain a live subject from a snapshot                                                         |
+| `diff <old> <new>`                                        | Semantic diff of two releases; formatting and moves are not changes                            |
+| `impact <old> <new> --world snapshot.json --at t`         | Preview a release over a recorded population                                                   |
+| `deploy <dir> --db file.db --account id [--dry-run]`      | Check a world, preview its impact and record it as the active release                          |
+| `serve [dir] --db file.db [--port n] [--clock t] [--ui]`  | Serve the deployed release over HTTP; with a directory, deploy then serve                      |
+| `snapshot --db file.db --account id [--out file]`         | Export committed state as a `worldvm/world@1` snapshot                                         |
+| `fmt [--check] <dir\|files>`                              | Format `.forma` files                                                                          |
+| `lsp`                                                     | Language Server Protocol on stdio                                                              |
+| `mcp [--world dir] [--db file.db --actor json]`           | Model Context Protocol server on stdio                                                         |
+| `codegen <dir> [--out file]`                              | Emit TypeScript entity, evidence and operation types                                           |
+
+## Exports
+
+| Import                   | Contents                                                                |
+| ------------------------ | ----------------------------------------------------------------------- |
+| `worldvm`                | `open()`, `memory()`, `operate()` and the subject handle API            |
+| `worldvm/sqlite`         | `sqlite(file)`, the single-file store                                   |
+| `worldvm/http`           | `createHandler(world)`, a `(Request) => Promise<Response>` HTTP handler |
+| `worldvm/serve`          | `serve()`, the Node HTTP server behind `worldvm serve`                  |
+| `worldvm/cli`            | Node-only command APIs and result types                                 |
+| `worldvm/authoring`      | Filesystem-free projections and manual renderers                        |
+| `worldvm/diagnostics`    | The diagnostics catalogue                                               |
+| `worldvm/durable-object` | `durableObject(storage)`, a Cloudflare Durable Object SQLite store      |
+| `worldvm/ir-schema.json` | JSON Schema for compiled world IR                                       |

package/bin/worldvm.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "../dist/cli.js";
+process.exitCode = await main();

package/dist/_internal/forma/index.d.ts

@@ -0,0 +1 @@
+export * from "./world/index.js";

package/dist/_internal/forma/index.js

@@ -0,0 +1 @@
+export * from "./world/index.js";

package/dist/_internal/forma/world/authoring-help.d.ts

@@ -0,0 +1,25 @@
+import type * as IR from "../../world-ir/types.generated.js";
+export declare const CORE_FORMS: Set<string>;
+export type FormMetadata = {
+    readonly name: string;
+    readonly tier: "core" | "extended";
+};
+export declare const formMetadata: (name: string) => FormMetadata;
+/** Top-level forms an author may write in a .forma file, sorted. */
+export declare const TOP_LEVEL_FORMS: string[] & {
+    metadata: FormMetadata[];
+};
+/** Child forms by parent form, e.g. component → requirement, action, output. */
+export declare const CHILD_FORMS: ReadonlyMap<string, readonly string[]> & {
+    metadata: Map<string, FormMetadata[]>;
+};
+/** The single closest form name within two edits, if any. */
+export declare const suggestForm: (name: string, candidates?: readonly string[]) => string | undefined;
+export declare const TRUTH_HELP = "Conditions use three-valued Truth (true, false or Unknown). Use and, or, not, = and != in requirements and properties. A Bool field is already a condition: write record.flag or (not record.flag). Collapse Truth with true?, false? or unknown? when a Bool is needed.";
+/** Help for a diagnostic whose code alone says too little; undefined keeps the existing help. */
+export declare const authoringHelp: (d: {
+    readonly code: string;
+    readonly message: string;
+}) => string | undefined;
+/** `attested` ignores :expires; an expiring record almost always wants `valid`. */
+export declare const attestedExpiryDiagnostics: (ir: IR.WorldIR) => IR.Diagnostic[];

package/dist/_internal/forma/world/authoring-help.js

@@ -0,0 +1,130 @@
+import { worldPrelude } from "./prelude.generated.js";
+// Authoring help for diagnostics Forma's elaborator reports without WorldVM context. Form names
+// come from the prelude itself so the lists cannot drift from what actually elaborates.
+const declared = [...worldPrelude.matchAll(/\(form\s*\(\s*([a-z][\w?/-]*)/g)].map((m) => m[1]);
+export const CORE_FORMS = new Set([
+    "source",
+    "entity",
+    "evidence",
+    "component",
+    "requirement",
+    "action",
+    "output",
+    "decision",
+    "scenario",
+    "property",
+]);
+export const formMetadata = (name) => ({
+    name,
+    tier: CORE_FORMS.has(name) ? "core" : "extended",
+});
+/** Top-level forms an author may write in a .forma file, sorted. */
+export const TOP_LEVEL_FORMS = Object.assign([...new Set([...declared.filter((n) => !n.includes("/")), "type"])].sort(), {
+    metadata: declared
+        .filter((n) => !n.includes("/"))
+        .concat("type")
+        .sort()
+        .map(formMetadata),
+});
+const children = new Map();
+for (const name of declared) {
+    const [group, child] = name.split("/");
+    if (!child || !group?.endsWith("-child"))
+        continue;
+    const parent = group.slice(0, -"-child".length);
+    children.set(parent, [...(children.get(parent) ?? []), child].sort());
+}
+/** Child forms by parent form, e.g. component → requirement, action, output. */
+export const CHILD_FORMS = Object.assign(children, {
+    metadata: new Map([...children].map(([parent, names]) => [parent, names.map(formMetadata)])),
+});
+const distance = (a, b) => {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let previous = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const current = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+            previous = current;
+        }
+    }
+    return row[b.length];
+};
+/** The single closest form name within two edits, if any. */
+export const suggestForm = (name, candidates = TOP_LEVEL_FORMS) => {
+    const ranked = candidates
+        .map((c) => [c, distance(name, c)])
+        .filter(([, d]) => d <= 2)
+        .sort((a, b) => a[1] - b[1]);
+    return ranked.length && (ranked.length === 1 || ranked[0][1] < ranked[1][1])
+        ? ranked[0][0]
+        : undefined;
+};
+const parentsOf = (child) => [...CHILD_FORMS].filter(([, names]) => names.includes(child)).map(([parent]) => parent);
+export const TRUTH_HELP = "Conditions use three-valued Truth (true, false or Unknown). Use and, or, not, = and != in requirements and properties. A Bool field is already a condition: write record.flag or (not record.flag). Collapse Truth with true?, false? or unknown? when a Bool is needed.";
+/** Help for a diagnostic whose code alone says too little; undefined keeps the existing help. */
+export const authoringHelp = (d) => {
+    if (d.code === "E_ELABORATE_MALFORMED_FORM" &&
+        d.message.includes("Missing required option :signal"))
+        return "Give the machine :signal a signal name. Declare that name in a (connector … :capabilities [] :signals [signal-name] :owns [MachineName]); the connector must own the machine even when it only receives signals.";
+    if (d.code === "E_ELABORATE_UNKNOWN_FORM") {
+        const name = /Unknown form '([^']+)'/.exec(d.message)?.[1] ?? "";
+        const parents = parentsOf(name);
+        const forms = `Top-level forms: ${TOP_LEVEL_FORMS.join(", ")}.`;
+        if (parents.length)
+            return `${name} is only valid inside ${parents.map((p) => `(${p} …)`).join(" or ")}. ${forms}`;
+        const suggestion = suggestForm(name);
+        return `${suggestion ? `Did you mean ${suggestion}? ` : ""}${forms} See AUTHORING.md, Forms reference.`;
+    }
+    if (d.code === "E_ELABORATE_VALIDATION_FAILED") {
+        const parent = /Expected child form ([a-z][\w-]*)-child/.exec(d.message)?.[1];
+        const names = parent ? CHILD_FORMS.get(parent) : undefined;
+        if (names)
+            return `Inside (${parent} …) each child form is one of: ${names.join(", ")}. Check the spelling of the child form's head.`;
+    }
+    if (d.code === "E_ELABORATE_HOLE_TYPE") {
+        if (d.message.startsWith("Unknown reference "))
+            return "Declare the referenced name with the required form. For a component's (machine local Protocol), declare (machine Protocol … :signal signal-name …). Declare signal-name in a (connector … :capabilities [] :signals [signal-name] :owns [Protocol]); signal-only connectors still declare ownership.";
+        if (/\bTruth\b/.test(d.message) && /\bBool\b/.test(d.message))
+            return TRUTH_HELP;
+        const unknown = /Unknown type (\S+)/.exec(d.message)?.[1];
+        if (unknown)
+            return `Declare ${unknown} with (type ${unknown} …), (role …) or (entity …) before using it, or use a built-in type: String, Int, Float, Bool, Date, Instant, Keyword, Group, (Id Role-or-Entity), (Option T), (Union :a :b). See AUTHORING.md, Forms reference.`;
+        return "This expression's type does not fit the field it is written in. Requirement conditions are Truth, :due is a Date or Instant, durations are (days n), (months n) or (years n). See AUTHORING.md.";
+    }
+    if (d.code === "W_NO_PRODUCER")
+        return "Nothing assigns work for this requirement, so when it is open no one is asked to act. Add (action <name> :advances <requirement> :assignee <who> :via (interaction <Interaction>)) to give it a producer. If the requirement only detects a condition (for example an active record whose review lapsed), keep it in an output and accept this warning.";
+    return undefined;
+};
+const ref = (e) => e && typeof e === "object" && e.k === "ref"
+    ? e.name
+    : undefined;
+/** `attested` ignores :expires; an expiring record almost always wants `valid`. */
+export const attestedExpiryDiagnostics = (ir) => {
+    const expiring = new Set(ir.evidence.filter((e) => e.expires).map((e) => e.name));
+    const diagnostics = [];
+    const walk = (value) => {
+        if (Array.isArray(value))
+            return value.forEach(walk);
+        if (!value || typeof value !== "object")
+            return;
+        const node = value;
+        const evidence = node.k === "call" && node.fn === "attested"
+            ? ref(node.args && node.args[0])
+            : undefined;
+        if (typeof evidence === "string" && expiring.has(evidence))
+            diagnostics.push({
+                code: "W_ATTESTED_EXPIRING",
+                severity: "warning",
+                message: `(attested ${evidence}) stays true after ${evidence} expires; ${evidence} declares :expires.`,
+                help: `attested means "was ever signed" and ignores :expires. Use (valid ${evidence}) to require an unexpired record; keep attested only if history is what you mean.`,
+                ...(node.at ? { at: node.at } : {}),
+            });
+        for (const [key, child] of Object.entries(node))
+            if (key !== "at")
+                walk(child);
+    };
+    walk(ir.components);
+    return diagnostics;
+};

package/dist/_internal/forma/world/citations.d.ts

@@ -0,0 +1,3 @@
+import type * as IR from "../../world-ir/types.generated.js";
+/** Citation absence is visible without certifying an author's interpretation of the source. */
+export declare const citationDiagnostics: (ir: IR.WorldIR) => readonly IR.Diagnostic[];

package/dist/_internal/forma/world/citations.js

@@ -0,0 +1,26 @@
+/** Citation absence is visible without certifying an author's interpretation of the source. */
+export const citationDiagnostics = (ir) => {
+    const diagnostics = [];
+    const check = (name, node) => {
+        if (node.cites?.length)
+            return;
+        diagnostics.push({
+            code: "W_UNCITED",
+            severity: "warning",
+            message: `Missing citation for ${name}.`,
+            at: node.at,
+            help: 'Declare the authority with (source name ...), then add :cites [(name "specific clause")] to this clause. Reference worlds are illustrative, not legal or audit advice.',
+        });
+    };
+    for (const component of ir.components) {
+        for (const requirement of component.requirements)
+            check(`${component.name}/${requirement.name}`, requirement);
+        for (const invariant of component.invariants)
+            check(`${component.name}/${invariant.name}`, invariant);
+        if (component.retention)
+            check(`${component.name}/retention`, component.retention);
+    }
+    for (const decision of ir.decisions ?? [])
+        check(decision.name, decision);
+    return diagnostics;
+};

package/dist/_internal/forma/world/clock-bindings.d.ts

@@ -0,0 +1,4 @@
+import type * as IR from "../../world-ir/types.generated.js";
+import type { SourceFile } from "./compile.js";
+/** Keep binder tokens in source diagnostics; the canonical field IR omits their spans. */
+export declare const clockBindingDiagnostics: (files: readonly SourceFile[]) => IR.Diagnostic[];

package/dist/_internal/forma/world/clock-bindings.js

@@ -0,0 +1,45 @@
+import { sourceSyntax } from "./source-syntax.js";
+import {} from "@forma-language/forma/reader";
+import { headOf, items, mapPairs, option, spanOf, symName } from "./lowering/syntax.js";
+/** Keep binder tokens in source diagnostics; the canonical field IR omits their spans. */
+export const clockBindingDiagnostics = (files) => {
+    const out = [];
+    for (const file of files) {
+        const parsed = sourceSyntax(file);
+        if (parsed.errors.length)
+            continue;
+        const binding = (node) => {
+            if (!["today", "now"].includes(symName(node)?.replace(/^:/, "") ?? ""))
+                return;
+            out.push({
+                code: "E_CLOCK_BINDING",
+                severity: "error",
+                message: "Clock names cannot be shadowed by runtime bindings.",
+                help: "Rename the binding; today and now are reserved clock expressions. Access role/entity fields through their paths.",
+                at: spanOf(file.id, node),
+            });
+        };
+        const walk = (node) => {
+            const head = headOf(node);
+            if (head === "type" || head === "quote")
+                return;
+            if (["component", "derive", "account"].includes(head ?? ""))
+                for (const key of ["inputs", "params"])
+                    for (const [name] of mapPairs(option(node, key)))
+                        binding(name);
+            if (head === "evidence")
+                for (const [name] of mapPairs(items(node).find((n) => n._tag === "Map")))
+                    binding(name);
+            if (head === "fn")
+                for (const param of items(items(node)[1]))
+                    binding(param);
+            if (node._tag === "List" || node._tag === "Vector" || node._tag === "Set")
+                node.items.forEach(walk);
+            if (node._tag === "Map")
+                for (const [, value] of node.pairs)
+                    walk(value);
+        };
+        parsed.forms.forEach(walk);
+    }
+    return out;
+};

package/dist/_internal/forma/world/compile.d.ts

@@ -0,0 +1,13 @@
+import { type SurfaceDiagnostic } from "./surface.js";
+import type * as IR from "../../world-ir/types.generated.js";
+export interface SourceFile {
+    readonly id: string;
+    readonly text: string;
+}
+export interface CompileResult {
+    readonly ok: boolean;
+    readonly ir: IR.WorldIR | null;
+    readonly diagnostics: readonly SurfaceDiagnostic[];
+}
+export declare const compileWorld: (files: readonly SourceFile[]) => CompileResult;
+export { KERNEL_FUNCTIONS, type ListNode } from "./lowering/syntax.js";

package/dist/_internal/forma/world/compile.js

@@ -0,0 +1,190 @@
+import { diagnosticCode, elaborationSource, operatorDiagnostics, } from "./surface.js";
+import { agentSourceDiagnostics } from "./lowering/agents.js";
+import { agentReadDiagnostics } from "../../ir-checks/index.js";
+import { sensitivitySourceDiagnostics } from "./sensitivity.js";
+import { vaultSourceDiagnostics } from "./lowering/vaults.js";
+import { vaultDiagnostics } from "../../ir-checks/index.js";
+import { sensitivityDiagnostics } from "../../ir-checks/index.js";
+import { resourceProofDiagnostics } from "../../ir-checks/index.js";
+import { amendmentDiagnostics } from "../../ir-checks/index.js";
+import { resourceDiagnostics } from "../../ir-checks/index.js";
+import { signatureDiagnostics } from "../../ir-checks/index.js";
+import { noticeDiagnostics } from "../../ir-checks/index.js";
+import { documentDiagnostics } from "../../ir-checks/index.js";
+import { fileFieldDiagnostics } from "../../ir-checks/index.js";
+import { statusHandlingDiagnostics } from "./status-handling.js";
+import { childParameterDiagnostics } from "../../ir-checks/index.js";
+import { componentContractDiagnostics } from "../../ir-checks/index.js";
+import { clockBindingDiagnostics } from "./clock-bindings.js";
+import { layoutSourceDiagnostics } from "./lowering/interactions.js";
+// Forma elaborates against the byte-stable virtual world.lisp prelude. Construct-family
+// lowering modules preserve reader spans and emit canonical JSON; this boundary orders
+// compilation and publish diagnostics for both Node and browser callers.
+import { bootstrapFromSources, elaborateSources, } from "@forma-language/forma/descriptor";
+import { preludeSource } from "@forma-language/forma/preludes";
+import { evidenceScopeDiagnostics, finiteTimeDiagnostics, instantLiteralDiagnostics, } from "../../ir-checks/index.js";
+import { attestedExpiryDiagnostics, authoringHelp } from "./authoring-help.js";
+import { citationDiagnostics } from "./citations.js";
+import { requirementDiagnostics } from "./coverage.js";
+import { documentationDiagnostics } from "./documentation.js";
+import { homeDiagnostics } from "./homes.js";
+import { recurrenceDiagnostics } from "./lowering/recurrences.js";
+import { lower } from "./lowering/index.js";
+import { LowerError } from "./lowering/syntax.js";
+import { worldPrelude } from "./prelude.generated.js";
+import { compileProperties } from "./properties.js";
+import { compileScenarios } from "./scenarios.js";
+import { tableEnvironment } from "./table-expressions.js";
+let bootstrapped;
+// UPSTREAM: derives.lisp expands :type signatures until Forma transports prelude aliases there.
+const prelude = () => (bootstrapped ??= bootstrapFromSources(preludeSource("compiler.lisp"), worldPrelude));
+export const compileWorld = (files) => {
+    const operators = operatorDiagnostics(files);
+    if (operators.length)
+        return { ok: false, ir: null, diagnostics: operators };
+    const adapted = new Map(files.map((f) => [f.id, elaborationSource(f)]));
+    const sensitivity = sensitivitySourceDiagnostics(files);
+    if (sensitivity.length)
+        return { ok: false, ir: null, diagnostics: sensitivity };
+    const vaults = vaultSourceDiagnostics(files);
+    if (vaults.length)
+        return { ok: false, ir: null, diagnostics: vaults };
+    const bindings = clockBindingDiagnostics(files);
+    if (bindings.length)
+        return { ok: false, ir: null, diagnostics: bindings };
+    const recurrenceErrors = recurrenceDiagnostics(files);
+    if (recurrenceErrors.length)
+        return { ok: false, ir: null, diagnostics: recurrenceErrors };
+    const layoutErrors = layoutSourceDiagnostics(files);
+    if (layoutErrors.length)
+        return { ok: false, ir: null, diagnostics: layoutErrors };
+    const agentErrors = agentSourceDiagnostics(files);
+    if (agentErrors.length)
+        return { ok: false, ir: null, diagnostics: agentErrors };
+    const elaborated = elaborateSources(files.map((f) => ({ sourceId: f.id, source: adapted.get(f.id).source })), { prelude: prelude(), semanticEnv: tableEnvironment() });
+    const diagnostics = elaborated.diagnostics.map((raw) => {
+        const d = {
+            ...raw,
+            code: diagnosticCode(raw.code, raw.severity),
+            ...(raw.span ? { span: adapted.get(raw.span.sourceId)?.span(raw.span) ?? raw.span } : {}),
+        };
+        return {
+            code: d.code,
+            severity: d.severity,
+            message: d.message,
+            ...(authoringHelp(d) ? { help: authoringHelp(d) } : {}),
+            ...(["E_COLLECT_FROM", "E_COLLECT_FACTS", "E_COLLECT_READONLY"].includes(d.code)
+                ? {
+                    help: "Use :from Role with a nonempty vector of unique declared :facts. Collect directly writable fields; for reference paths, collect the referenced record's own role fields instead.",
+                }
+                : {}),
+            ...(["E_BINDS_SHAPE", "E_BINDS_TARGET", "E_BINDS_TYPE", "E_BINDS_CONFLICT"].includes(d.code)
+                ? {
+                    help: "Use :binds {:evidence-field input.role-field} with compatible types. Bind each field once; use the legacy options only for other fields. Reference-path facts are read-only.",
+                }
+                : {}),
+            ...(d.code === "E_BUNDLE_ROLE"
+                ? {
+                    help: "Use :for with a declared role, such as :for compliance/principal. A bundle projects assigned work; it grants no authority.",
+                }
+                : {}),
+            ...(d.code === "E_UNKNOWN_REQUIREMENT"
+                ? { help: "Name only requirements declared in the same component." }
+                : {}),
+            ...(d.code === "E_UNKNOWN_FIELD"
+                ? { help: "Use a declared evidence or role field name." }
+                : {}),
+            ...(d.code === "E_TABLE_SHAPE"
+                ? {
+                    help: "Use (table keyword-parameter :value result ... :else fallback), with unique declared keyword rows and :else last; select a named derive parameter.",
+                }
+                : {}),
+            ...(d.code === "E_TABLE_NOT_EXHAUSTIVE"
+                ? {
+                    help: "Cover every value of the parameter's keyword union, or add an explicit :else fallback; open Keyword parameters always need :else.",
+                }
+                : {}),
+            ...(d.code === "E_NO_HOME"
+                ? {
+                    help: "The first key input must be an entity reference (Id E), directly or through another component's home. Put the reference first, for example [employee client] instead of [client].",
+                }
+                : {}),
+            ...(d.code === "E_SOURCE_KIND"
+                ? { help: "Choose :law, :regulation, :guidance, :framework, :contract or :policy." }
+                : {}),
+            ...(d.span
+                ? {
+                    at: {
+                        src: d.span.sourceId,
+                        from: d.span.startOffset,
+                        to: d.span.endOffset,
+                        line: d.span.startLine ?? 1,
+                        col: d.span.startColumn ?? 1,
+                    },
+                }
+                : {}),
+        };
+    });
+    if (!elaborated.ok)
+        return { ok: false, ir: null, diagnostics };
+    try {
+        const model = lower(files, elaborated.declarations.map((d) => ({ ...d, span: adapted.get(d.sourceId).span(d.span) })));
+        const claims = compileProperties(model, files);
+        const withClaims = {
+            ...model,
+            ...(claims.properties.length ? { properties: claims.properties } : {}),
+        };
+        const examples = compileScenarios(withClaims, files);
+        const ir = {
+            ...withClaims,
+            ...(examples.scenarios.length ? { scenarios: examples.scenarios } : {}),
+        };
+        const checked = [
+            ...vaultDiagnostics(ir),
+            ...agentReadDiagnostics(ir),
+            ...sensitivityDiagnostics(ir),
+            ...documentDiagnostics(ir),
+            ...noticeDiagnostics(ir),
+            ...signatureDiagnostics(ir),
+            ...amendmentDiagnostics(ir),
+            ...resourceDiagnostics(ir),
+            ...resourceProofDiagnostics(ir),
+            ...fileFieldDiagnostics(ir),
+            ...childParameterDiagnostics(ir),
+            ...componentContractDiagnostics(ir),
+            ...statusHandlingDiagnostics(ir),
+            ...examples.diagnostics,
+            ...claims.diagnostics,
+            ...diagnostics,
+            ...homeDiagnostics(ir),
+            ...finiteTimeDiagnostics(ir),
+            ...instantLiteralDiagnostics(ir),
+            ...evidenceScopeDiagnostics(ir),
+            ...citationDiagnostics(ir),
+            ...documentationDiagnostics(ir),
+            ...requirementDiagnostics(ir),
+            ...attestedExpiryDiagnostics(ir),
+        ];
+        const ok = !checked.some((d) => d.severity === "error");
+        return { ok, ir: ok ? ir : null, diagnostics: checked };
+    }
+    catch (error) {
+        if (!(error instanceof LowerError))
+            throw error;
+        return {
+            ok: false,
+            ir: null,
+            diagnostics: [
+                ...diagnostics,
+                {
+                    code: error.code,
+                    severity: "error",
+                    message: error.message,
+                    at: error.at,
+                    ...(error.help ? { help: error.help } : {}),
+                },
+            ],
+        };
+    }
+};
+export { KERNEL_FUNCTIONS } from "./lowering/syntax.js";

package/dist/_internal/forma/world/coverage.d.ts

@@ -0,0 +1,10 @@
+import type * as IR from "../../world-ir/types.generated.js";
+export interface DefinitionReference {
+    readonly kind: "scenario" | "property";
+    readonly name: string;
+}
+export declare const definitionReferences: (ir: Pick<IR.WorldIR, "scenarios" | "properties" | "decisions"> & {
+    readonly components: readonly Omit<IR.Component, "home">[];
+}) => ReadonlyMap<string, readonly DefinitionReference[]>;
+/** Advisory reference analysis deliberately over-approximates reads; it proves no reachability. */
+export declare const requirementDiagnostics: (ir: IR.WorldIR) => readonly IR.Diagnostic[];