worldvm 0.0.0-stage → 0.1.0

package/dist/impact.js

@@ -0,0 +1,57 @@
+import { resolve } from "node:path";
+import { loadProject } from "./project.js";
+import { previewImpact } from "./release/impact.js";
+import { readSnapshot } from "./snapshot.js";
+export const impactDirectories = async (before, after, options) => {
+    const [a, b] = await Promise.all([loadProject(before), loadProject(after)]);
+    const base = {
+        format: "worldvm/impact-report@1",
+        command: "impact",
+        old: a.directory,
+        new: b.directory,
+        snapshot: resolve(options.world),
+    };
+    const errors = [
+        ...a.diagnostics.map((d) => ({ ...d, side: "old" })),
+        ...b.diagnostics.map((d) => ({ ...d, side: "new" })),
+    ].filter((d) => d.severity === "error");
+    if (errors.length || !a.ir || !b.ir)
+        return { ...base, ok: false, diagnostics: errors, impact: null };
+    const read = await readSnapshot(options.world, [a.ir, b.ir], "E_IMPACT_SNAPSHOT");
+    if ("diagnostic" in read)
+        return { ...base, ok: false, diagnostics: [read.diagnostic], impact: null };
+    let impact;
+    try {
+        impact = previewImpact(a.ir, b.ir, { ...read.snapshot, at: options.at });
+    }
+    catch (cause) {
+        return {
+            ...base,
+            ok: false,
+            diagnostics: [
+                {
+                    code: "E_IMPACT_AT",
+                    severity: "error",
+                    message: String(cause),
+                    at: null,
+                    help: "Pass --at as YYYY-MM-DD or YYYY-MM-DDTHH:MM and a snapshot both releases can evaluate.",
+                    fix: null,
+                },
+            ],
+            impact: null,
+        };
+    }
+    const unsound = impact.unexpected.length
+        ? [
+            {
+                code: "E_IMPACT_UNSOUND",
+                severity: "error",
+                message: `${impact.unexpected.length} changes fall outside the definitions whose dependency digests changed.`,
+                at: null,
+                help: "A dependency is missing from the node graph; report this world and edit so the digest rules can be fixed.",
+                fix: null,
+            },
+        ]
+        : [];
+    return { ...base, ok: !unsound.length, diagnostics: unsound, impact };
+};

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { type CliDiagnostic } from "./project.js";
+export { loadProject, type Project, type CliDiagnostic, type Fix } from "./project.js";
+export interface CheckReport {
+    readonly format: "worldvm/check@1";
+    readonly command: "check";
+    readonly directory: string;
+    readonly ok: boolean;
+    readonly files: readonly string[];
+    readonly diagnostics: readonly CliDiagnostic[];
+    readonly statistics: {
+        readonly accounts: number;
+        readonly components: number;
+        readonly requirements: number;
+        readonly scenarios: number;
+        readonly properties: number;
+    } | null;
+}
+export declare const checkDirectory: (directory: string, options?: {
+    readonly core?: boolean;
+}) => Promise<CheckReport>;
+export { testDirectory, type TestReport, type TestOptions, type TestFailure, type PropertyTestFailure, } from "./test.js";
+export { coverageDirectory, type CoverageReport, type CoverageDefinition, type CoverageReference, } from "./coverage.js";
+export { initWorld, STARTER, type InitResult } from "./init.js";
+export { CATALOGUE, explain, type CatalogueEntry } from "./catalogue.js";
+export { renderDirectory, type RenderReport, type RenderOptions, type RenderFormat, } from "./render.js";
+export { explainDirectory, explainReconciliation, type ExplainReport, type ExplainOptions, type ExplainedInstance, type ExplainedRequirement, type ExplainedWork, } from "./explain.js";
+export { readSnapshot, type WorldSnapshot } from "./snapshot.js";
+export { diffDirectories, type DiffReport, type SidedDiagnostic } from "./diff.js";
+export { impactDirectories, type ImpactReport, type ImpactOptions } from "./impact.js";
+export { handleMessage, serveStdio, tools as mcpTools, serverInfo, protocolVersions, } from "./mcp.js";

package/dist/index.js

@@ -0,0 +1,43 @@
+import { coreDiagnostics } from "./_internal/forma/world/index.js";
+import { loadProject } from "./project.js";
+export { loadProject } from "./project.js";
+export const checkDirectory = async (directory, options = {}) => {
+    const project = await loadProject(directory), ir = project.ir;
+    return {
+        format: "worldvm/check@1",
+        command: "check",
+        directory: project.directory,
+        ok: ir !== null && !project.diagnostics.some((d) => d.severity === "error"),
+        files: project.files.map((f) => f.id),
+        diagnostics: [
+            ...project.diagnostics,
+            ...(options.core
+                ? coreDiagnostics(project.files).map((d) => ({
+                    ...d,
+                    at: d.at ?? null,
+                    help: d.help ?? "",
+                    fix: null,
+                }))
+                : []),
+        ],
+        statistics: ir
+            ? {
+                accounts: ir.accounts.length,
+                components: ir.components.length,
+                requirements: ir.components.reduce((n, c) => n + c.requirements.length, 0),
+                scenarios: ir.scenarios?.length ?? 0,
+                properties: ir.properties?.length ?? 0,
+            }
+            : null,
+    };
+};
+export { testDirectory, } from "./test.js";
+export { coverageDirectory, } from "./coverage.js";
+export { initWorld, STARTER } from "./init.js";
+export { CATALOGUE, explain } from "./catalogue.js";
+export { renderDirectory, } from "./render.js";
+export { explainDirectory, explainReconciliation, } from "./explain.js";
+export { readSnapshot } from "./snapshot.js";
+export { diffDirectories } from "./diff.js";
+export { impactDirectories } from "./impact.js";
+export { handleMessage, serveStdio, tools as mcpTools, serverInfo, protocolVersions, } from "./mcp.js";

package/dist/init.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The starter world written by `worldvm init`. It is the smallest world that passes
+ * check, test and coverage with no warnings, and AUTHORING.md walks through it.
+ * Synthetic data; illustrative only.
+ */
+export declare const REFERENCE = "# Core world-language reference\n\nA world is a directory of `.forma` files: a library with roles and components, entities\nand an account that binds them, plus scenarios and properties. Start with `worldvm init`;\nloop `worldvm check .`, `worldvm test .`, `worldvm coverage . --mutate`.\n\nSyntax below uses `\u2026` for repetition and `[optional]` for optional syntax; those markers\nare not source. The fenced examples **together form one complete world**, in order.\nSynthetic policy and data; illustrative only. This page is compiled and tested.\nFor the deeper guide, see `AUTHORING.md` in the installed package\n(`node_modules/worldvm/AUTHORING.md`). In a scaffold, this file is `REFERENCE.md`; the examples stand alone.\n\nThe **core forms** are `source`, `entity`, `evidence`, `component`, `requirement`,\n`action`, `output`, `decision`, `scenario` and `property`. `worldvm check . --core`\nadds an `I_EXTENDED_FORM` info diagnostic at each extended declaration or child form;\nit does not reject a valid world. LSP clients can set `initializationOptions.core: true`. The surrounding declarations shown below (`library`,\n`role`, `interaction`, `layout`, `account`, plus their children) are **extended**.\nAll forms outside the ten-name core set are extended, including `attest`, `step`,\n`field`, `sign` and `for-each`; expression calls and scenario data are not declarations.\n\nFirst declare the library that owns the forms:\n\n```lisp\n(library example.training \"Annual safety training.\" :version \"1.0\" :subject training/worker)\n```\n\n| Form          | Syntax                                                                                                                            | Common mistakes                                                                                                                             |\n| ------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |\n| `source`      | `(source name \"doc\" :kind :policy :url \"url\" :as-of \"YYYY-MM-DD\")`                                                                | Cite a declared name, not a URL; use a real calendar date.                                                                                  |\n| `role`        | `(role ns/name \"doc\" {:field Type \u2026})`                                                                                            | Roles describe interfaces, not stored records; include every field components read.                                                         |\n| `entity`      | `(entity Name \"doc\" :ns :pkg.name :display field :implements {role {role-field field}} {:field Type \u2026})`                          | Namespace must start with the account package; map every role field with the same type.                                                     |\n| `evidence`    | `(evidence Name \"doc\" :of Component [:expires date-expr] {:field Type \u2026} (attest \u2026))`                                             | Declare it at top level; use `valid` for expiring evidence (`attested` ignores expiry); expiry may only read signed fields and `signed-on`. |\n| `interaction` | `(interaction Name \"doc\" :actor who :produces Evidence :layout Layout)`                                                           | Actor must resolve to a person or group; evidence fields belong in the evidence declaration.                                                |\n| `layout`      | `(layout Name \"doc\" (step id \"Label\" (field field) \u2026 (sign)))`                                                                    | Use declared evidence fields; include a signing step for attested evidence.                                                                 |\n| `component`   | `(component Name \"doc\" :key [input \u2026] :inputs {:input Type \u2026} children \u2026)`                                                        | Put an entity-reference input first in the key; requirements go inside this form; list callable actions/decisions in `:operations`.         |\n| `requirement` | `(requirement name :cites [(source \"clause\")] [:applies-when truth] :satisfied-by truth)`                                         | Child of a component, never top level; conditions use Kleene Truth with `and`, `or`, `not`; `satisfied?` is false for NotApplicable.        |\n| `action`      | `(action name :advances requirement :assignee who :via (interaction Name))`                                                       | Child of a component; match the interaction actor and signer; an action does not itself set arbitrary facts.                                |\n| `output`      | `(output name (all-of requirement-or-output \u2026))`                                                                                  | Child of a component; `all-of` accepts NotApplicable, unlike conjoining `satisfied?` checks; read locally as `self.name`.                   |\n| `decision`    | `(decision name \"doc\" :of Component :applies requirement :by who :effect :approve :reason String [:expires duration] :cites [\u2026])` | Top level, not a component child; name a requirement of that component; approval requires the declared authority.                           |\n| `account`     | `(account name \"doc\" :requires {library \"version\"} :package pkg (for-each role Component))`                                       | Require the exact library version; map roles with entities' `:implements` before running components.                                        |\n| `scenario`    | `(scenario name \"doc\" :world account (given \u2026) (at \"date\" \u2026) (do \u2026) \u2026)`                                                           | `:world` names an account; time must advance; `given` is trusted history, `do` exercises command checks.                                    |\n| `property`    | `(property name \"doc\" :world account :at \"date\" :for-all (x Entity) predicate)`                                                   | Quantify an entity, not a role; use Bool `and`/`or`/`not` and `=`/`!=` here; a reference is not an assertion.                               |\n\n## Library forms\n\n`source`, `role`, `evidence`, `interaction` and `layout`, respectively:\n\n```lisp\n(source safety-policy \"Synthetic annual safety policy.\"\n  :kind :policy :url \"https://example.invalid/safety\" :as-of \"2026-11-01\")\n```\n\n```lisp\n(role training/worker \"A worker and their reviewing group.\" {:name String :reviewers Group})\n```\n\n```lisp\n(evidence Completion \"Signed course completion.\" :of Training\n  :expires (months-after signed-on 12)\n  {:course String}\n  (attest :signer worker :covers :all :method :otp))\n```\n\nEvidence can contain `(rule name :when condition :requires fields)`. The optional\n`:when` reads signed evidence fields and uses three-valued Truth. An omitted condition\nalways applies; a false condition skips the rule, and Unknown prevents attestation.\n`:requires` accepts a single `field`, `(one-of a b \u2026)` to require at least one filled\nfield, or `(all-of a b \u2026)` to require every listed field. Groups must be nonempty\nand contain declared field names. For example,\n`(rule documents :when (= document-choice :list-b-and-c) :requires (all-of list-b list-c))`\nrequires both document fields for that signed choice. The interaction's layout must\nshow required fields whenever the rule applies; a `one-of` group needs a visible alternative.\n\nFor a signal-driven protocol, declare `(machine Protocol \u2026 :signal updated \u2026)` and\na `(connector provider \u2026 :capabilities [] :signals [updated] :owns [Protocol])`.\nAn inbound-only connector uses an empty capabilities vector. A `component-contract`\nmay omit `:capabilities`; it defaults to `[]`.\n\n```lisp\n(interaction CompletionEntry \"Record the finished course.\"\n  :actor worker :produces Completion :layout CompletionLayout)\n```\n\nAn interaction can supply signed evidence fields with `:fixes`, for example\n`:fixes {:examination :remote}` for an evidence field typed `(Union :in-person :remote)`.\nFixed values must be scalar literals matching the evidence field type. Omit these\nfields from the layout; they count as covered by the interaction. They cannot also\nuse `:binds`, `:prefill` or `:proposes`. Conflicting submissions are refused, including\nunsigned drafts. The stored evidence and signature include the fixed values, so\nevidence rules and explanations read them as signed fields. Two actions can share\none evidence type through different interactions; a remote action can use `:needs`\nto require enrollment before that interaction is eligible.\n\n```lisp\n(layout CompletionLayout \"Record and sign.\"\n  (step record \"Record\" (field course) (sign)))\n```\n\n`component` contains `requirement`, `action` and `output`. This single fence keeps the\nparentheses and child scope visible:\n\n```lisp\n(component Training \"Track one worker's training.\"\n  :key [worker] :inputs {:worker (Id training/worker)} :operations [complete waive-training]\n  (requirement completed\n    :cites [(safety-policy \"1: workers complete training every year\")]\n    :satisfied-by (valid Completion))\n  (action complete :advances completed :assignee worker :via (interaction CompletionEntry))\n  (output done (all-of completed)))\n```\n\nExplanations follow the branch that decides a condition, in source order. A passing\n`or` reports the first passing branch and that branch's evidence. A failing `and`\nreports the first failing branch. A failing `or` reports every branch's failure;\na passing `and` reports every branch's success. Combined details do not select a\nsingle evidence record. If no `or` branch passes and at least one is Unknown, the\nresult is Unknown and the explanation includes the unresolved branches and the\nfailed branches. An `and` with no failing branch and at least one Unknown likewise\nreports all branches. Every branch is evaluated, including its dependencies and\ntime cutoffs; choosing an explanation does not short-circuit evaluation.\n\n`decision` records a judgment; it affects satisfaction only when a rule reads it with\n`(decided waive-training)`. This example deliberately keeps completion evidence required:\n\n```lisp\n(decision waive-training \"Record a reviewer's approval.\"\n  :of Training :applies completed :by (members worker.reviewers)\n  :effect :approve :reason String :expires (months 6)\n  :cites [(safety-policy \"2: reviewers document exceptions\")])\n```\n\n## Account and proof\n\nA machine declared inside a component can anchor a case clock:\n`:due (business-days-after (entered-at case :referred) 10 :calendar us-federal)`.\nDeclare the calendar and the machine's protocol state. This works for plain signal-driven\nmachines, including connector-owned machines, without a resource or a separate date fact.\n`entered-at` returns the UTC Date of the first observation in the latest visit to the state.\nConsecutive duplicate states preserve it; leaving and re-entering resets it. After departure\nthe last entry date remains available; before an observed entry it is Unknown. Managed-resource\nmachines restrict history to the current acquisition generation. `resource-generation` and\n`attested-for` require a managed resource.\n\n`entity` and `account` bind stored records to the library:\n\n```lisp\n(entity Person \"A synthetic worker.\" :ns :example.person :display name\n  :implements {training/worker {:name name :reviewers reviewers}}\n  {:name String :reviewers Group})\n```\n\n```lisp\n(account example \"A synthetic training account.\"\n  :requires {example.training \"1.0\"} :package example\n  (for-each training/worker Training))\n```\n\n`scenario` tests missing, current and expired evidence through the action:\n\n```lisp\n(scenario completes-and-expires \"Training lasts twelve months.\" :world example\n  (given (entity Person ana {:name \"Ana\" :reviewers \"Safety\"}) (actor ana))\n  (at \"2026-11-02\" (expect (status (Training ana) completed) :Open))\n  (do (perform (Training ana) complete :by ana :values {:course \"Safety 101\"}))\n  (at \"2026-11-03\" (expect (status (Training ana) done) :Satisfied))\n  (at \"2027-11-03\" (expect (status (Training ana) completed) :Open)))\n```\n\n`property` explores generated worlds at a fixed instant:\n\n```lisp\n(property done-needs-evidence \"Completion requires signed evidence.\"\n  :world example :at \"2026-11-03\" :for-all (p Person)\n  (given (entity Person p {:name \"Synthetic worker\" :reviewers \"Safety\"})\n    (evidence Completion :for (Training p) :requirement completed :by p\n      :values {:course \"Safety 101\"}))\n  (implies (= (status (Training p) done) :Satisfied)\n    (attested (Training p) Completion)))\n```\n\nAn optional `given` block before the predicate uses scenario entity, evidence and\nsignal records. It must declare the quantified alias with the quantified entity type.\nEach generated case keeps those entities and explicit facts and varies unspecified\nfields. Seeded evidence and signals are retained; random history does not replace\nthe same evidence type or machine on the same occurrence. As in scenarios, `given`\nis trusted history, not an exercise of action eligibility.\nCounterexample shrinking preserves the authored seed facts and records.\n\n`test` and `coverage`, in text and JSON, count the generated cases in which each\n`implies` antecedent was true, once per case even with multiple quantified entities.\nZero produces `W_PROPERTY_VACUOUS`. This is a warning: vacuity alone does not fail\neither command. A false or Unknown property still fails. Add seed facts and evidence\nthat reach the antecedent to test the claim.\n\nUse calendar `(months N)` and `(months-after signed-on N)` for calendar periods. Comparisons use `=` and `!=` everywhere. Logic uses `and`, `or`, `not`: Kleene Truth\nin conditions and ordinary Bool in properties. Write `(and a b)` or `(or a b)`;\nTruth contexts also accept a collection as a single argument. To roll up\noptional requirements use an `all-of` output and read it with `(met? self.done)`.\n`worldvm explain W_ATTESTED_EXPIRING` explains why expiry requires `valid`.\n\n## Structured host reads\n\nThe operating protocol exposes `facts` alongside `status`, `work`, `operations` and\n`explain`. Facts include the asserting actor, valid time and retained command ID.\nWork prerequisites are structured addresses derived from IR, with canonical display\ntext; evidence prerequisites name their producing requirements. Compound conditions\nremain opaque display reasons. Status includes observed machine states and entry\ntimes. Explanations include selected evidence values. Hosts can gate subject reads\nwith `canRead`; see `docs/protocol.md` in the installed package (\"Structured subject reads\") for schemas\nand the trusted embedding boundary.\n\n## CLI: impact on a live world\n\nDeploy checked source, then serve the stored release without the source directory:\n\n```sh\nworldvm deploy deployed-world --db world.db --account example\nworldvm serve --db world.db\n# In another terminal, while serve is running (or after it stops):\nworldvm snapshot --db world.db --account example --out snapshot.json\nworldvm impact deployed-world proposed-world --world snapshot.json --at 2026-11-10\nworldvm explain deployed-world --world snapshot.json --subject hire-123 --at 2026-11-10\n```\n\n`snapshot` reads committed state in one read transaction without changing the database.\n`--account` must name the account used by the server. Deploy stores that account with the release.\nWithout `--out`, the JSON goes to stdout. The `worldvm/world@1` snapshot contains\n`accounts`, `world` and an optional `release` identifying the release that last wrote\nthe records. The evaluation instant is supplied to `impact` or `explain` with `--at`.\n\nStop `serve` before deploying another release. One process per SQLite file is required;\na busy SQLite write lock is refused with a message to stop `serve`, but an idle server\ncannot be detected. Snapshot export is a read-only exception to this rule.\n\n```sh\nworldvm deploy proposed-world --db world.db --account example --at 2026-11-10 --dry-run\nworldvm deploy proposed-world --db world.db --account example --at 2026-11-10 --json\nworldvm serve --db world.db --clock 2026-11-11 --ui\nworldvm mcp --db world.db --actor '{\"id\":\"agent:ops\",\"kind\":\"agent\"}'\n```\n\nDeploy refuses the same compile and authoring errors as `check`, before opening SQLite.\nIt reports old and new release IDs, requirement and work changes, and every changed\nsubject. `--at` controls impact evaluation and defaults to now. `--dry-run` checks and\npreviews without changing or creating the database. Deployment retains compiled IR,\naccount and deployment timestamp in the `releases` table, in deployment order. The last\nrow is active, including when an earlier release is deployed again. Records, receipts\nand proposals are preserved; statuses are recomputed under the new rules, with no data\nmigration. The SQLite format is `worldvm/sqlite-store@3`; older files are refused and\nrequire a new database.\n\n`serve <directory> --db world.db` is a development shortcut for deploy, then serve;\nit requires a world with one account. `serve --db` and `mcp --db` use stored IR.\nEmbedders can use `open({ store: sqlite(\"world.db\") })` for the deployed release.\nExplicit `open({ source, store })` still refuses records from another release unless\n`activate: true` is supplied. That embedding option recomputes status and preserves\nrecords; use CLI deploy to retain deployment history. Time passing requires a tick or\na later server clock, not another deployment.\n";
+export declare const STARTER: Readonly<Record<string, string>>;
+export interface InitResult {
+    readonly directory: string;
+    readonly files: readonly string[];
+}
+/** Write the starter world; refuses a directory that already holds files. */
+export declare const initWorld: (input: string) => Promise<InitResult>;

package/dist/init.js

@@ -0,0 +1,99 @@
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+/**
+ * The starter world written by `worldvm init`. It is the smallest world that passes
+ * check, test and coverage with no warnings, and AUTHORING.md walks through it.
+ * Synthetic data; illustrative only.
+ */
+// Kept identical to docs/reference.md by reference-doc.test.ts. Embedded so init works
+// without a checkout or a network connection.
+export const REFERENCE = '# Core world-language reference\n\nA world is a directory of `.forma` files: a library with roles and components, entities\nand an account that binds them, plus scenarios and properties. Start with `worldvm init`;\nloop `worldvm check .`, `worldvm test .`, `worldvm coverage . --mutate`.\n\nSyntax below uses `…` for repetition and `[optional]` for optional syntax; those markers\nare not source. The fenced examples **together form one complete world**, in order.\nSynthetic policy and data; illustrative only. This page is compiled and tested.\nFor the deeper guide, see `AUTHORING.md` in the installed package\n(`node_modules/worldvm/AUTHORING.md`). In a scaffold, this file is `REFERENCE.md`; the examples stand alone.\n\nThe **core forms** are `source`, `entity`, `evidence`, `component`, `requirement`,\n`action`, `output`, `decision`, `scenario` and `property`. `worldvm check . --core`\nadds an `I_EXTENDED_FORM` info diagnostic at each extended declaration or child form;\nit does not reject a valid world. LSP clients can set `initializationOptions.core: true`. The surrounding declarations shown below (`library`,\n`role`, `interaction`, `layout`, `account`, plus their children) are **extended**.\nAll forms outside the ten-name core set are extended, including `attest`, `step`,\n`field`, `sign` and `for-each`; expression calls and scenario data are not declarations.\n\nFirst declare the library that owns the forms:\n\n```lisp\n(library example.training "Annual safety training." :version "1.0" :subject training/worker)\n```\n\n| Form          | Syntax                                                                                                                            | Common mistakes                                                                                                                             |\n| ------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |\n| `source`      | `(source name "doc" :kind :policy :url "url" :as-of "YYYY-MM-DD")`                                                                | Cite a declared name, not a URL; use a real calendar date.                                                                                  |\n| `role`        | `(role ns/name "doc" {:field Type …})`                                                                                            | Roles describe interfaces, not stored records; include every field components read.                                                         |\n| `entity`      | `(entity Name "doc" :ns :pkg.name :display field :implements {role {role-field field}} {:field Type …})`                          | Namespace must start with the account package; map every role field with the same type.                                                     |\n| `evidence`    | `(evidence Name "doc" :of Component [:expires date-expr] {:field Type …} (attest …))`                                             | Declare it at top level; use `valid` for expiring evidence (`attested` ignores expiry); expiry may only read signed fields and `signed-on`. |\n| `interaction` | `(interaction Name "doc" :actor who :produces Evidence :layout Layout)`                                                           | Actor must resolve to a person or group; evidence fields belong in the evidence declaration.                                                |\n| `layout`      | `(layout Name "doc" (step id "Label" (field field) … (sign)))`                                                                    | Use declared evidence fields; include a signing step for attested evidence.                                                                 |\n| `component`   | `(component Name "doc" :key [input …] :inputs {:input Type …} children …)`                                                        | Put an entity-reference input first in the key; requirements go inside this form; list callable actions/decisions in `:operations`.         |\n| `requirement` | `(requirement name :cites [(source "clause")] [:applies-when truth] :satisfied-by truth)`                                         | Child of a component, never top level; conditions use Kleene Truth with `and`, `or`, `not`; `satisfied?` is false for NotApplicable.        |\n| `action`      | `(action name :advances requirement :assignee who :via (interaction Name))`                                                       | Child of a component; match the interaction actor and signer; an action does not itself set arbitrary facts.                                |\n| `output`      | `(output name (all-of requirement-or-output …))`                                                                                  | Child of a component; `all-of` accepts NotApplicable, unlike conjoining `satisfied?` checks; read locally as `self.name`.                   |\n| `decision`    | `(decision name "doc" :of Component :applies requirement :by who :effect :approve :reason String [:expires duration] :cites […])` | Top level, not a component child; name a requirement of that component; approval requires the declared authority.                           |\n| `account`     | `(account name "doc" :requires {library "version"} :package pkg (for-each role Component))`                                       | Require the exact library version; map roles with entities\' `:implements` before running components.                                        |\n| `scenario`    | `(scenario name "doc" :world account (given …) (at "date" …) (do …) …)`                                                           | `:world` names an account; time must advance; `given` is trusted history, `do` exercises command checks.                                    |\n| `property`    | `(property name "doc" :world account :at "date" :for-all (x Entity) predicate)`                                                   | Quantify an entity, not a role; use Bool `and`/`or`/`not` and `=`/`!=` here; a reference is not an assertion.                               |\n\n## Library forms\n\n`source`, `role`, `evidence`, `interaction` and `layout`, respectively:\n\n```lisp\n(source safety-policy "Synthetic annual safety policy."\n  :kind :policy :url "https://example.invalid/safety" :as-of "2026-11-01")\n```\n\n```lisp\n(role training/worker "A worker and their reviewing group." {:name String :reviewers Group})\n```\n\n```lisp\n(evidence Completion "Signed course completion." :of Training\n  :expires (months-after signed-on 12)\n  {:course String}\n  (attest :signer worker :covers :all :method :otp))\n```\n\nEvidence can contain `(rule name :when condition :requires fields)`. The optional\n`:when` reads signed evidence fields and uses three-valued Truth. An omitted condition\nalways applies; a false condition skips the rule, and Unknown prevents attestation.\n`:requires` accepts a single `field`, `(one-of a b …)` to require at least one filled\nfield, or `(all-of a b …)` to require every listed field. Groups must be nonempty\nand contain declared field names. For example,\n`(rule documents :when (= document-choice :list-b-and-c) :requires (all-of list-b list-c))`\nrequires both document fields for that signed choice. The interaction\'s layout must\nshow required fields whenever the rule applies; a `one-of` group needs a visible alternative.\n\nFor a signal-driven protocol, declare `(machine Protocol … :signal updated …)` and\na `(connector provider … :capabilities [] :signals [updated] :owns [Protocol])`.\nAn inbound-only connector uses an empty capabilities vector. A `component-contract`\nmay omit `:capabilities`; it defaults to `[]`.\n\n```lisp\n(interaction CompletionEntry "Record the finished course."\n  :actor worker :produces Completion :layout CompletionLayout)\n```\n\nAn interaction can supply signed evidence fields with `:fixes`, for example\n`:fixes {:examination :remote}` for an evidence field typed `(Union :in-person :remote)`.\nFixed values must be scalar literals matching the evidence field type. Omit these\nfields from the layout; they count as covered by the interaction. They cannot also\nuse `:binds`, `:prefill` or `:proposes`. Conflicting submissions are refused, including\nunsigned drafts. The stored evidence and signature include the fixed values, so\nevidence rules and explanations read them as signed fields. Two actions can share\none evidence type through different interactions; a remote action can use `:needs`\nto require enrollment before that interaction is eligible.\n\n```lisp\n(layout CompletionLayout "Record and sign."\n  (step record "Record" (field course) (sign)))\n```\n\n`component` contains `requirement`, `action` and `output`. This single fence keeps the\nparentheses and child scope visible:\n\n```lisp\n(component Training "Track one worker\'s training."\n  :key [worker] :inputs {:worker (Id training/worker)} :operations [complete waive-training]\n  (requirement completed\n    :cites [(safety-policy "1: workers complete training every year")]\n    :satisfied-by (valid Completion))\n  (action complete :advances completed :assignee worker :via (interaction CompletionEntry))\n  (output done (all-of completed)))\n```\n\nExplanations follow the branch that decides a condition, in source order. A passing\n`or` reports the first passing branch and that branch\'s evidence. A failing `and`\nreports the first failing branch. A failing `or` reports every branch\'s failure;\na passing `and` reports every branch\'s success. Combined details do not select a\nsingle evidence record. If no `or` branch passes and at least one is Unknown, the\nresult is Unknown and the explanation includes the unresolved branches and the\nfailed branches. An `and` with no failing branch and at least one Unknown likewise\nreports all branches. Every branch is evaluated, including its dependencies and\ntime cutoffs; choosing an explanation does not short-circuit evaluation.\n\n`decision` records a judgment; it affects satisfaction only when a rule reads it with\n`(decided waive-training)`. This example deliberately keeps completion evidence required:\n\n```lisp\n(decision waive-training "Record a reviewer\'s approval."\n  :of Training :applies completed :by (members worker.reviewers)\n  :effect :approve :reason String :expires (months 6)\n  :cites [(safety-policy "2: reviewers document exceptions")])\n```\n\n## Account and proof\n\nA machine declared inside a component can anchor a case clock:\n`:due (business-days-after (entered-at case :referred) 10 :calendar us-federal)`.\nDeclare the calendar and the machine\'s protocol state. This works for plain signal-driven\nmachines, including connector-owned machines, without a resource or a separate date fact.\n`entered-at` returns the UTC Date of the first observation in the latest visit to the state.\nConsecutive duplicate states preserve it; leaving and re-entering resets it. After departure\nthe last entry date remains available; before an observed entry it is Unknown. Managed-resource\nmachines restrict history to the current acquisition generation. `resource-generation` and\n`attested-for` require a managed resource.\n\n`entity` and `account` bind stored records to the library:\n\n```lisp\n(entity Person "A synthetic worker." :ns :example.person :display name\n  :implements {training/worker {:name name :reviewers reviewers}}\n  {:name String :reviewers Group})\n```\n\n```lisp\n(account example "A synthetic training account."\n  :requires {example.training "1.0"} :package example\n  (for-each training/worker Training))\n```\n\n`scenario` tests missing, current and expired evidence through the action:\n\n```lisp\n(scenario completes-and-expires "Training lasts twelve months." :world example\n  (given (entity Person ana {:name "Ana" :reviewers "Safety"}) (actor ana))\n  (at "2026-11-02" (expect (status (Training ana) completed) :Open))\n  (do (perform (Training ana) complete :by ana :values {:course "Safety 101"}))\n  (at "2026-11-03" (expect (status (Training ana) done) :Satisfied))\n  (at "2027-11-03" (expect (status (Training ana) completed) :Open)))\n```\n\n`property` explores generated worlds at a fixed instant:\n\n```lisp\n(property done-needs-evidence "Completion requires signed evidence."\n  :world example :at "2026-11-03" :for-all (p Person)\n  (given (entity Person p {:name "Synthetic worker" :reviewers "Safety"})\n    (evidence Completion :for (Training p) :requirement completed :by p\n      :values {:course "Safety 101"}))\n  (implies (= (status (Training p) done) :Satisfied)\n    (attested (Training p) Completion)))\n```\n\nAn optional `given` block before the predicate uses scenario entity, evidence and\nsignal records. It must declare the quantified alias with the quantified entity type.\nEach generated case keeps those entities and explicit facts and varies unspecified\nfields. Seeded evidence and signals are retained; random history does not replace\nthe same evidence type or machine on the same occurrence. As in scenarios, `given`\nis trusted history, not an exercise of action eligibility.\nCounterexample shrinking preserves the authored seed facts and records.\n\n`test` and `coverage`, in text and JSON, count the generated cases in which each\n`implies` antecedent was true, once per case even with multiple quantified entities.\nZero produces `W_PROPERTY_VACUOUS`. This is a warning: vacuity alone does not fail\neither command. A false or Unknown property still fails. Add seed facts and evidence\nthat reach the antecedent to test the claim.\n\nUse calendar `(months N)` and `(months-after signed-on N)` for calendar periods. Comparisons use `=` and `!=` everywhere. Logic uses `and`, `or`, `not`: Kleene Truth\nin conditions and ordinary Bool in properties. Write `(and a b)` or `(or a b)`;\nTruth contexts also accept a collection as a single argument. To roll up\noptional requirements use an `all-of` output and read it with `(met? self.done)`.\n`worldvm explain W_ATTESTED_EXPIRING` explains why expiry requires `valid`.\n\n## Structured host reads\n\nThe operating protocol exposes `facts` alongside `status`, `work`, `operations` and\n`explain`. Facts include the asserting actor, valid time and retained command ID.\nWork prerequisites are structured addresses derived from IR, with canonical display\ntext; evidence prerequisites name their producing requirements. Compound conditions\nremain opaque display reasons. Status includes observed machine states and entry\ntimes. Explanations include selected evidence values. Hosts can gate subject reads\nwith `canRead`; see `docs/protocol.md` in the installed package ("Structured subject reads") for schemas\nand the trusted embedding boundary.\n\n## CLI: impact on a live world\n\nDeploy checked source, then serve the stored release without the source directory:\n\n```sh\nworldvm deploy deployed-world --db world.db --account example\nworldvm serve --db world.db\n# In another terminal, while serve is running (or after it stops):\nworldvm snapshot --db world.db --account example --out snapshot.json\nworldvm impact deployed-world proposed-world --world snapshot.json --at 2026-11-10\nworldvm explain deployed-world --world snapshot.json --subject hire-123 --at 2026-11-10\n```\n\n`snapshot` reads committed state in one read transaction without changing the database.\n`--account` must name the account used by the server. Deploy stores that account with the release.\nWithout `--out`, the JSON goes to stdout. The `worldvm/world@1` snapshot contains\n`accounts`, `world` and an optional `release` identifying the release that last wrote\nthe records. The evaluation instant is supplied to `impact` or `explain` with `--at`.\n\nStop `serve` before deploying another release. One process per SQLite file is required;\na busy SQLite write lock is refused with a message to stop `serve`, but an idle server\ncannot be detected. Snapshot export is a read-only exception to this rule.\n\n```sh\nworldvm deploy proposed-world --db world.db --account example --at 2026-11-10 --dry-run\nworldvm deploy proposed-world --db world.db --account example --at 2026-11-10 --json\nworldvm serve --db world.db --clock 2026-11-11 --ui\nworldvm mcp --db world.db --actor \'{"id":"agent:ops","kind":"agent"}\'\n```\n\nDeploy refuses the same compile and authoring errors as `check`, before opening SQLite.\nIt reports old and new release IDs, requirement and work changes, and every changed\nsubject. `--at` controls impact evaluation and defaults to now. `--dry-run` checks and\npreviews without changing or creating the database. Deployment retains compiled IR,\naccount and deployment timestamp in the `releases` table, in deployment order. The last\nrow is active, including when an earlier release is deployed again. Records, receipts\nand proposals are preserved; statuses are recomputed under the new rules, with no data\nmigration. The SQLite format is `worldvm/sqlite-store@3`; older files are refused and\nrequire a new database.\n\n`serve <directory> --db world.db` is a development shortcut for deploy, then serve;\nit requires a world with one account. `serve --db` and `mcp --db` use stored IR.\nEmbedders can use `open({ store: sqlite("world.db") })` for the deployed release.\nExplicit `open({ source, store })` still refuses records from another release unless\n`activate: true` is supplied. That embedding option recomputes status and preserves\nrecords; use CLI deploy to retain deployment history. Time passing requires a tick or\na later server clock, not another deployment.\n';
+export const STARTER = {
+    "library/starter.forma": `;; Starter library. Synthetic and illustrative; not legal or compliance advice.
+;; A library declares roles (the shapes it needs), evidence, interactions and components.
+(library example.starter
+  "Annual policy acknowledgement for one synthetic subject."
+  :version "1.0" :subject starter/subject)
+
+(role starter/person "A person who signs on behalf of a subject." {:name String})
+(role starter/subject "The record the requirements are about."
+  {:name String :owner (Id starter/person) :opened Date})
+
+(source starter-policy "Synthetic starter policy; not legal or compliance advice."
+  :kind :policy :url "https://example.invalid/starter-policy" :as-of "2026-01-01")
+
+;; Evidence is a signed record. (valid E) is false once :expires passes; (attested E) is not.
+(evidence Acknowledgement "The owner's signed policy acknowledgement." :of Onboarding
+  :expires (months-after signed-on 12)
+  {:summary String}
+  (attest :signer subject.owner :covers :all :method :otp))
+
+(layout AcknowledgementLayout "Record and sign the acknowledgement."
+  (step record "Record" (field summary) (sign)))
+(interaction AcknowledgementEntry "Sign the policy acknowledgement."
+  :actor subject.owner :produces Acknowledgement :layout AcknowledgementLayout)
+
+;; A component is instantiated once per key. Requirements are three-valued (Truth).
+(component Onboarding "Track the requirements for one subject."
+  :key [subject] :inputs {:subject (Id starter/subject)} :operations [acknowledge]
+  (requirement acknowledged
+    :cites [(starter-policy "1: the owner acknowledges the policy every 12 months")]
+    :satisfied-by (valid Acknowledgement))
+  (action acknowledge :advances acknowledged :assignee subject.owner
+    :via (interaction AcknowledgementEntry))
+  (output complete (all-of acknowledged)))
+`,
+    "example.forma": `;; The example account: concrete entities that implement the library's roles.
+(entity Person "A synthetic person." :ns :example.person :display name
+  :implements {starter/person {:name name}} {:name String})
+(entity Subject "A synthetic subject." :ns :example.subject :display name
+  :implements {starter/subject {:name name :owner owner :opened opened}}
+  {:name String :owner (Id Person) :opened Date})
+(account example "An isolated synthetic starter account."
+  :requires {example.starter "1.0"} :package example
+  (for-each starter/subject Onboarding))
+`,
+    "scenarios/starter.forma": `;; Scenarios are worked examples; properties are claims over generated worlds.
+(scenario acknowledgement-lasts-a-year "An acknowledgement satisfies the requirement for 12 months." :world example
+  (given (entity Person owner {:name "Owner"})
+    (entity Subject s {:name "Subject" :owner owner :opened "2026-01-01"})
+    (actor owner))
+  (at "2026-01-01" (expect (status (Onboarding s) acknowledged) :Open))
+  (do (evidence Acknowledgement :for (Onboarding s) :requirement acknowledged :by owner
+        :values {:summary "Read and agreed"}))
+  (at "2026-01-02" (expect (status (Onboarding s) complete) :Satisfied))
+  (at "2027-01-02" (expect (status (Onboarding s) acknowledged) :Open)))
+
+(property complete-means-acknowledged "A complete subject has a signed acknowledgement."
+  :world example :at "2026-06-01" :for-all (s Subject)
+  (implies (= (status (Onboarding s) complete) :Satisfied)
+    (attested (Onboarding s) Acknowledgement)))
+`,
+    "REFERENCE.md": REFERENCE,
+    "README.md": `# Starter world
+
+Synthetic and illustrative; not legal or compliance advice.
+
+    worldvm check .      # compile and lint
+    worldvm test .       # run scenarios and properties
+    worldvm coverage . --mutate  # branch measurements and surviving semantic mutants
+
+Edit library/starter.forma, add scenarios under scenarios/, and rerun the loop.
+Read [REFERENCE.md](REFERENCE.md) for core syntax, examples and common mistakes.
+`,
+};
+/** Write the starter world; refuses a directory that already holds files. */
+export const initWorld = async (input) => {
+    const directory = resolve(input);
+    await mkdir(directory, { recursive: true });
+    const existing = (await readdir(directory)).filter((n) => !n.startsWith("."));
+    if (existing.length)
+        throw new Error(`${directory} is not empty; choose a new or empty directory.`);
+    const files = Object.keys(STARTER).sort();
+    for (const file of files) {
+        const path = join(directory, file);
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, STARTER[file], { flag: "wx" });
+    }
+    return { directory, files };
+};