worldvm 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,553 @@
+import { DIAGNOSTIC_RENAMES } from "./_internal/forma/world/index.js";
+import { writeFile } from "node:fs/promises";
+import { codegenDirectory } from "./codegen.js";
+import { formatPaths } from "./fmt.js";
+import { serveLsp } from "./lsp.js";
+import { parseArgs } from "node:util";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { checkDirectory, testDirectory, coverageDirectory, renderDirectory, explainDirectory, diffDirectories, impactDirectories, serveStdio, } from "./index.js";
+import { existsSync } from "node:fs";
+import { CATALOGUE, catalogueEntry, explain } from "./catalogue.js";
+import { initWorld } from "./init.js";
+import { decodeActor } from "./_internal/protocol/index.js";
+import { open } from "./handle/open.js";
+import { sqlite } from "./sqlite.js";
+import { serve, scheduleTicks } from "./serve.js";
+import { deployDirectory } from "./deploy.js";
+import { snapshotDatabase } from "./snapshot.js";
+const guide = fileURLToPath(new URL("../AUTHORING.md", import.meta.url));
+const usage = `Usage:\n  worldvm init <directory>   (scaffold a minimal passing world)\n  worldvm codegen <directory> [--out file]\n  worldvm check <directory> [--json] [--core]\n  worldvm test <directory> [--json] [--scenario name] [--seed n] [--cases n]\n  worldvm coverage <directory> [--json] [--seed n] [--cases n] [--mutate]\n  worldvm render <directory> [--json] [--format markdown|html] [--account name]\n  worldvm explain <directory> --scenario name [--at instant] [--subject id] [--json]\n  worldvm explain <directory> --world snapshot.json --subject id --at instant [--json]\n  worldvm explain <diagnostic-code> | --list [--json]\n  worldvm diff <old-directory> <new-directory> [--json]\n  worldvm impact <old-directory> <new-directory> --world snapshot.json --at instant [--json]\n  worldvm snapshot --db file.db --account id [--out snapshot.json]\n  worldvm fmt [--check] <directory|files> [--json]\n  worldvm lsp   (Language Server Protocol on stdio)\n  worldvm deploy <directory> --db file.db --account id [--at instant] [--dry-run] [--json]\n  worldvm serve [directory] --db file.db [--port n] [--clock instant] [--ui]   (runs the deployed release; directory is the deploy-then-serve shortcut)\n  worldvm mcp [--world <directory>] [--db file.db --actor json]   (Model Context Protocol server on stdio)\n\nA world is a directory of .forma files. To write one, read the authoring guide shipped\nwith this package: layout, a minimal world, every form, Truth and comparisons, scenarios\nand the diagnostics catalogue.\n  ${guide}\n\nThe authoring loop: worldvm check → worldvm test → worldvm coverage.\nRun worldvm <command> --help for that command's options.`;
+/** Per-subcommand help; `worldvm <command> --help` prints the matching entry. */
+const HELP = {
+    deploy: `Usage: worldvm deploy <directory> --db file.db --account id [--at instant] [--dry-run] [--json]
+
+Check, report live population impact, retain the compiled release and activate it.
+--at defaults to now. --dry-run leaves the database unchanged.
+Stop serve before deploying; one process per SQLite file.`,
+    snapshot: `Usage: worldvm snapshot --db file.db --account id [--out snapshot.json]
+
+Export a committed SQLite world as worldvm/world@1 JSON. Defaults to stdout.
+--account names the account whose committed records are exported.
+The export includes its recorded release and is safe while serve is running.`,
+    codegen: "Usage: worldvm codegen <directory> [--out file]\n\nEmit entity, evidence and operation types. Defaults to stdout.",
+    init: `Usage: worldvm init <directory>
+
+Write a minimal passing world: a library with one role, evidence, interaction and
+component, an example account with entities, one scenario and one property.
+The directory must be new or empty. Then run the authoring loop:
+  worldvm check <directory> && worldvm test <directory> && worldvm coverage <directory>`,
+    check: `Usage: worldvm check <directory> [--json] [--core]
+
+Compile every visible .forma file under <directory>, link each account and run the
+authoring lints. Diagnostics include a location, specific help and, where the edit
+is mechanical, a fix with the expected old text. Exit 0 when there are no errors
+(warnings and info are allowed), 1 when there are errors, 2 for invalid usage.
+--core adds I_EXTENDED_FORM information at declarations outside the ten core forms.
+Explain any code with: worldvm explain <code>`,
+    test: `Usage: worldvm test <directory> [--json] [--scenario name] [--seed n] [--cases n]
+
+Run every scenario and seeded property (defaults: seed 0, 100 cases). A property
+failure prints a shrunk counterexample scenario you can paste and replay.
+  --scenario name   run only that scenario (properties are skipped)
+  --seed n          property generation seed
+  --cases n         property cases per property
+Exit 0 when everything passes, 1 on any failure, 2 for invalid usage.`,
+    coverage: `Usage: worldvm coverage <directory> [--json] [--seed n] [--cases n] [--mutate]
+
+Run the same scenarios and properties as test, then report per requirement which
+scenarios/properties reference it and which applicability, status and due branches
+were actually observed. References are not proof of behaviour: a requirement can be
+"covered" by a scenario that never checks the branch that matters.
+  --mutate   also apply semantic mutants one at a time (valid->attested,
+             attested->valid, drop a conjunct/disjunct, flip = and !=, remove
+             :applies-when), rerun every test, and report each mutant that no
+             scenario or property catches as a gap
+Exit 0 when tests pass, 1 when they fail, 2 for invalid usage.`,
+    render: `Usage: worldvm render <directory> [--json] [--format markdown|html] [--account name]
+
+Render the world as a manual a person can review and sign off.`,
+    explain: `Usage: worldvm explain <directory> --scenario name [--at instant] [--subject id] [--json]
+       worldvm explain <directory> --world snapshot.json --subject id --at instant [--json]
+       worldvm explain <diagnostic-code> [--json]
+       worldvm explain --list [--json]
+
+With a directory, explain each requirement's status, due date and proof at a scenario
+step or snapshot instant. With a diagnostic code (e.g. W_ATTESTED_EXPIRING,
+elaborate/unknown-form), print its cause, an example and the fix. --list lists codes.`,
+    diff: `Usage: worldvm diff <old-directory> <new-directory> [--json]
+
+Semantic diff of two releases: added, removed and changed declarations, breaking changes
+and example changes.`,
+    impact: `Usage: worldvm impact <old-directory> <new-directory> --world snapshot.json --at instant [--json]
+
+Preview which subjects, occurrences and work a release change would affect.`,
+    fmt: `Usage: worldvm fmt [--check] <directory|files> [--json]
+
+Format visible .forma sources. --check reports changes without writing (exit 1).`,
+    lsp: `Usage: worldvm lsp
+
+Serve the Forma Language Server Protocol on stdio.`,
+    serve: `Usage: worldvm serve [directory] --db file.db [--port 3000] [--clock fixed-instant] [--ui]
+
+Runs the deployed release. A directory is a development shortcut: deploy, then serve.
+
+Serve the operating protocol on loopback HTTP. x-worldvm-actor is trusted, dev-only identity.
+See docs/protocol.md.`,
+    mcp: `Usage: worldvm mcp [--world directory] [--db file.db --actor '{"id":"agent:x","kind":"agent"}']
+
+Serve authoring tools over stdio. With --db and --actor, also expose operating
+tools for the deployed release. --world supplies source for development. See docs/protocol.md.`,
+};
+/** A diagnostic code rather than a directory: catalogued, or code-shaped and not on disk. */
+const isCode = (arg) => !!catalogueEntry(arg) || (/^(?:[EWI]_[A-Z0-9_]+|[a-z]+\/[a-z-]+)$/.test(arg) && !existsSync(arg));
+const display = (directory, d) => {
+    const location = d.at ? `${resolve(directory, d.at.src)}:${d.at.line}:${d.at.col}: ` : "";
+    console.error(`${location}${d.severity} ${d.code}: ${d.message}\n  help: ${d.help}${d.fix ? `\n  fix: replace [${d.fix.from}, ${d.fix.to}) with ${d.fix.text}` : ""}${catalogueEntry(d.code) ? `\n  explain: worldvm explain ${d.code}` : ""}`);
+};
+const printExplanation = (report) => {
+    const at = (s) => `${s.src}:${s.line}:${s.col}`;
+    console.log(`explain ${report.source?.kind === "scenario" ? `scenario ${report.source.name} step ${report.source.step}` : `snapshot ${report.source?.kind === "snapshot" ? report.source.path : ""}`} at ${report.now}${report.subject ? ` for ${report.subject}` : ""}`);
+    for (const inst of report.instances) {
+        console.log(`\n${inst.component} ${inst.instance}`);
+        for (const q of inst.requirements) {
+            console.log(`  ${q.name}: ${q.status}; due ${q.due ?? `unknown${q.dueUnknown ? ` (${q.dueUnknown})` : ""}`} · ${at(q.rule.at)}`);
+            for (const r of q.reasons)
+                console.log(`    ${r.outcome} ${r.label}: ${r.detail}${r.at ? ` · ${at(r.at)}` : ""}`);
+            for (const s of q.dueSteps)
+                console.log(`    due step ${JSON.stringify(s.value)}${s.branch ? ` [${s.branch}]` : ""}${s.note ? ` ${s.note}` : ""} · ${at(s.at)}`);
+            if (q.evidence)
+                console.log(`    evidence ${q.evidence.id} (${q.evidence.status}, ${q.evidence.by})`);
+            if (q.blocked)
+                console.log(`    blocked: ${q.blocked}`);
+            for (const c of q.rule.cites)
+                console.log(`    cites ${c.title} ${c.clause}`);
+            console.log(`    proof ${q.proof}`);
+        }
+    }
+    for (const w of report.work)
+        console.log(`work ${w.key}: ${w.state}; ${w.assignee.kind} ${w.assignee.id ?? "unresolved"}${w.reason ? `; ${w.reason}` : ""}`);
+};
+const printDiff = (report) => {
+    if (!report.diff)
+        return;
+    const at = (s) => (s ? `${s.src}:${s.line}` : "-");
+    for (const c of report.diff.changes)
+        console.log(`${c.change} ${c.kind} ${c.name}${c.fields.length ? `: ${c.fields.map((f) => (f.aspect === "other" ? f.field : f.aspect)).join(", ")}` : ""}${c.presentationOnly ? " (wording only)" : ""}${c.breaking ? " BREAKING" : ""} · ${at(c.old)} → ${at(c.new)}`);
+    const s = report.diff.summary;
+    console.log(`diff: ${s.added} added, ${s.removed} removed, ${s.changed} changed (${s.presentationOnly} wording only, ${s.breaking} breaking); requirements ${s.requirements.added}/${s.requirements.removed}/${s.requirements.changed}; ${report.diff.examples.length} example changes`);
+};
+const printImpact = (report) => {
+    const impact = report.impact;
+    if (!impact)
+        return;
+    console.log(`impact at ${impact.at}: ${impact.affected.components.length} affected components (${impact.affected.components.join(", ") || "none"})${impact.affected.accounts.length ? `; accounts ${impact.affected.accounts.join(", ")}` : ""}`);
+    for (const c of impact.occurrences.changes) {
+        const s = (c.after ?? c.before);
+        console.log(`${c.change} ${s.component}/${s.requirement} ${s.occurrence}: ${c.before ? `${c.before.status} due ${c.before.due ?? "unknown"}` : "absent"} → ${c.after ? `${c.after.status} due ${c.after.due ?? "unknown"}` : "absent"}`);
+    }
+    for (const c of impact.work.changes)
+        console.log(`work ${c.change} ${(c.after ?? c.before).key}: ${c.before?.state ?? "absent"} → ${c.after?.state ?? "absent"}`);
+    console.log(`subjects: ${impact.subjects.changed} changed of ${impact.subjects.considered} considered (${impact.subjects.total} total); occurrences ${impact.occurrences.changes.length} changed of ${impact.occurrences.considered} considered (${impact.occurrences.total} total); work ${impact.work.before} → ${impact.work.after}`);
+    for (const [label, subjects] of Object.entries(impact.samples))
+        if (subjects.length)
+            console.log(`  ${label}: ${subjects.join(", ")}`);
+};
+export const main = async () => {
+    let json = process.argv.includes("--json");
+    let help = usage;
+    try {
+        const { values, positionals } = parseArgs({
+            options: {
+                out: { type: "string" },
+                db: { type: "string" },
+                "dry-run": { type: "boolean" },
+                port: { type: "string" },
+                ui: { type: "boolean" },
+                clock: { type: "string" },
+                actor: { type: "string" },
+                check: { type: "boolean" },
+                core: { type: "boolean" },
+                json: { type: "boolean" },
+                help: { type: "boolean", short: "h" },
+                scenario: { type: "string" },
+                seed: { type: "string" },
+                cases: { type: "string" },
+                format: { type: "string" },
+                account: { type: "string" },
+                world: { type: "string" },
+                subject: { type: "string" },
+                at: { type: "string" },
+                list: { type: "boolean" },
+                mutate: { type: "boolean" },
+            },
+            allowPositionals: true,
+            strict: true,
+        });
+        json = values.json ?? false;
+        const command = positionals[0];
+        if (command !== undefined && Object.hasOwn(HELP, command))
+            help = HELP[command];
+        if (values.help) {
+            console.log(help);
+            return 0;
+        }
+        if (command === "deploy") {
+            if (positionals.length !== 2 ||
+                !values.db ||
+                !values.account ||
+                Object.keys(values).some((k) => !["db", "account", "at", "dry-run", "json"].includes(k)))
+                throw new Error(HELP.deploy);
+            const report = await deployDirectory(positionals[1], {
+                db: values.db,
+                account: values.account,
+                ...(values.at ? { at: values.at } : {}),
+                ...(values["dry-run"] ? { dryRun: true } : {}),
+            });
+            if (json)
+                console.log(JSON.stringify(report, null, 2));
+            else {
+                report.diagnostics.forEach((d) => display(report.directory, d));
+                if (report.ok) {
+                    console.log(`${report.dryRun ? "preview" : "deployed"}: ${report.old ?? "none"} → ${report.new}`);
+                    printImpact(report);
+                    console.log(`subjects changed: ${report.subjects.join(", ") || "none"}`);
+                }
+            }
+            return report.ok ? 0 : 1;
+        }
+        if (values["dry-run"] !== undefined)
+            throw new Error("--dry-run requires deploy.");
+        if (command === "snapshot") {
+            if (positionals.length !== 1 ||
+                !values.db ||
+                !values.account ||
+                Object.keys(values).some((k) => !["db", "account", "out"].includes(k)))
+                throw new Error(HELP.snapshot);
+            if (values.out && resolve(values.out) === resolve(values.db))
+                throw new Error("--out must differ from --db.");
+            const snapshot = await snapshotDatabase(values.db, values.account);
+            const output = `${JSON.stringify(snapshot, null, 2)}\n`;
+            if (values.out)
+                await writeFile(values.out, output);
+            else
+                process.stdout.write(output);
+            return 0;
+        }
+        if (command === "serve") {
+            if ((positionals.length !== 1 && positionals.length !== 2) ||
+                !values.db ||
+                Object.keys(values).some((k) => !["db", "port", "clock", "ui"].includes(k)))
+                throw new Error(HELP.serve);
+            const port = values.port === undefined ? 3000 : Number(values.port);
+            if (!Number.isInteger(port) || port < 0 || port > 65535)
+                throw new Error("--port must be an integer from 0 to 65535.");
+            if (values.clock && !Number.isFinite(Date.parse(values.clock)))
+                throw new Error("--clock must be an ISO instant.");
+            const fixed = values.clock;
+            const running = await serve({
+                ...(positionals[1] ? { source: positionals[1] } : {}),
+                db: values.db,
+                port,
+                ...(values.ui ? { ui: true } : {}),
+                ...(fixed ? { clock: () => fixed } : {}),
+            });
+            console.error(`WorldVM listening on http://127.0.0.1:${running.server.address().port}; trusted identity header is dev-only.`);
+            await new Promise((resolve) => {
+                const stop = () => {
+                    process.removeListener("SIGINT", stop);
+                    process.removeListener("SIGTERM", stop);
+                    resolve();
+                };
+                process.once("SIGINT", stop);
+                process.once("SIGTERM", stop);
+            });
+            await running.close();
+            return 0;
+        }
+        if (command === "mcp") {
+            if (positionals.length !== 1 ||
+                Object.keys(values).some((k) => !["world", "db", "actor"].includes(k)))
+                throw new Error(HELP.mcp);
+            if (!Object.keys(values).length) {
+                await serveStdio();
+                return 0;
+            }
+            if (!values.db || !values.actor)
+                throw new Error(HELP.mcp);
+            const actor = decodeActor(JSON.parse(values.actor));
+            const world = await open({
+                ...(values.world ? { source: values.world } : {}),
+                store: sqlite(values.db),
+            });
+            const stopTicks = scheduleTicks(world);
+            try {
+                await serveStdio(process.stdin, process.stdout, { world, actor });
+            }
+            finally {
+                stopTicks();
+                await world.close();
+            }
+            return 0;
+        }
+        if (values.ui !== undefined)
+            throw new Error("--ui requires serve.");
+        if (values.db !== undefined ||
+            values.port !== undefined ||
+            values.clock !== undefined ||
+            values.actor !== undefined)
+            throw new Error("--db requires deploy, serve, snapshot or mcp; --port/--clock/--actor require serve or mcp.");
+        if (values.core !== undefined && command !== "check")
+            throw new Error("--core requires check.");
+        if (values.check !== undefined && command !== "fmt")
+            throw new Error("--check requires fmt.");
+        if (command === "fmt") {
+            if (positionals.length < 2 || Object.keys(values).some((k) => !["json", "check"].includes(k)))
+                throw new Error(HELP.fmt);
+            const report = await formatPaths(positionals.slice(1), values.check ?? false);
+            if (json)
+                console.log(JSON.stringify(report, null, 2));
+            else
+                for (const file of report.files)
+                    if (file.changed)
+                        console.log(`${values.check ? "unformatted" : "formatted"} ${file.path}`);
+            return report.ok ? 0 : 1;
+        }
+        if (command === "lsp") {
+            if (positionals.length !== 1 || Object.keys(values).length)
+                throw new Error("lsp takes no arguments.");
+            await serveLsp();
+            return 0;
+        }
+        if (values.list !== undefined && command !== "explain")
+            throw new Error("--list requires the explain command.");
+        if (values.mutate !== undefined && command !== "coverage")
+            throw new Error("--mutate requires the coverage command.");
+        if (command === "explain" && (values.list || (positionals[1] && isCode(positionals[1])))) {
+            if (values.list) {
+                if (json)
+                    console.log(JSON.stringify({ format: "worldvm/explain-code@1", codes: CATALOGUE }, null, 2));
+                else
+                    for (const code of Object.keys(CATALOGUE).sort())
+                        console.log(`${code}  ${CATALOGUE[code].title}`);
+                return 0;
+            }
+            if (positionals.length !== 2)
+                throw new Error("Expected one diagnostic code.");
+            const code = positionals[1], entry = catalogueEntry(code);
+            if (!entry) {
+                const message = `No catalogue entry for ${code}; its diagnostic help is the best guide. List codes with worldvm explain --list.`;
+                if (json)
+                    console.log(JSON.stringify({ format: "worldvm/explain-code@1", code, ok: false, message }, null, 2));
+                else
+                    console.error(message);
+                return 1;
+            }
+            if (json)
+                console.log(JSON.stringify({
+                    format: "worldvm/explain-code@1",
+                    code,
+                    ok: true,
+                    ...(DIAGNOSTIC_RENAMES[code] ? { renamedTo: DIAGNOSTIC_RENAMES[code] } : {}),
+                    ...entry,
+                }, null, 2));
+            else
+                console.log(explain(code));
+            return 0;
+        }
+        if (values.out !== undefined && command !== "codegen")
+            throw new Error("--out requires codegen.");
+        if (command === "codegen") {
+            if (positionals.length !== 2 || Object.keys(values).some((k) => k !== "out"))
+                throw new Error("Expected worldvm codegen <directory> [--out file].");
+            const module = await codegenDirectory(positionals[1]);
+            if (values.out)
+                await writeFile(values.out, module);
+            else
+                process.stdout.write(module);
+            return 0;
+        }
+        if (command === "init") {
+            if (positionals.length !== 2)
+                throw new Error("Expected worldvm init <directory>.");
+            const directory = positionals[1];
+            const result = await initWorld(directory);
+            if (json)
+                console.log(JSON.stringify({ format: "worldvm/init@1", ok: true, ...result }, null, 2));
+            else {
+                for (const file of result.files)
+                    console.log(`created ${file}`);
+                console.log(`\nNext: worldvm check ${directory} && worldvm test ${directory} && worldvm coverage ${directory}`);
+            }
+            return 0;
+        }
+        if (positionals[0] === "impact") {
+            if (positionals.length !== 3)
+                throw new Error("impact needs an old and a new source directory.");
+            if (Object.keys(values).some((k) => !["json", "world", "at"].includes(k)))
+                throw new Error("impact accepts --world, --at and --json.");
+            if (values.world === undefined || values.at === undefined)
+                throw new Error("impact needs --world snapshot.json and --at instant.");
+            const report = await impactDirectories(positionals[1], positionals[2], {
+                world: values.world,
+                at: values.at,
+            });
+            if (json)
+                console.log(JSON.stringify(report, null, 2));
+            else {
+                report.diagnostics.forEach((d) => display("side" in d && d.side === "new" ? report.new : report.old, d));
+                printImpact(report);
+            }
+            return report.ok ? 0 : 1;
+        }
+        if (positionals[0] === "diff") {
+            if (positionals.length !== 3)
+                throw new Error("diff needs an old and a new source directory.");
+            if (Object.keys(values).some((k) => k !== "json"))
+                throw new Error("diff accepts only --json.");
+            const report = await diffDirectories(positionals[1], positionals[2]);
+            if (json)
+                console.log(JSON.stringify(report, null, 2));
+            else {
+                report.diagnostics.forEach((d) => display(d.side === "old" ? report.old : report.new, d));
+                printDiff(report);
+            }
+            return report.ok ? 0 : 1;
+        }
+        if (positionals.length !== 2 ||
+            !["check", "test", "coverage", "render", "explain"].includes(positionals[0]))
+            throw new Error("Expected init/check/test/coverage/render/explain/diff/impact/mcp and a source directory.");
+        if (positionals[0] !== "explain" &&
+            positionals[0] !== "impact" &&
+            (values.world !== undefined || values.subject !== undefined || values.at !== undefined))
+            throw new Error("--world, --subject and --at require the explain command.");
+        if (positionals[0] === "explain") {
+            if (values.seed !== undefined ||
+                values.cases !== undefined ||
+                values.format !== undefined ||
+                values.account !== undefined)
+                throw new Error("explain accepts --scenario, --world, --subject and --at.");
+            const report = await explainDirectory(positionals[1], {
+                ...(values.scenario === undefined ? {} : { scenario: values.scenario }),
+                ...(values.world === undefined ? {} : { world: values.world }),
+                ...(values.subject === undefined ? {} : { subject: values.subject }),
+                ...(values.at === undefined ? {} : { at: values.at }),
+            });
+            if (json)
+                console.log(JSON.stringify(report, null, 2));
+            else {
+                report.diagnostics
+                    .filter((d) => d.severity === "error")
+                    .forEach((d) => display(report.directory, d));
+                if (report.ok)
+                    printExplanation(report);
+            }
+            return report.ok ? 0 : 1;
+        }
+        if (positionals[0] !== "render" &&
+            (values.format !== undefined || values.account !== undefined))
+            throw new Error("--format and --account require the render command.");
+        if (positionals[0] === "render") {
+            if (values.scenario !== undefined || values.seed !== undefined || values.cases !== undefined)
+                throw new Error("Test options require the test command.");
+            const format = values.format ?? "markdown";
+            if (format !== "markdown" && format !== "html")
+                throw new Error("--format must be markdown or html.");
+            const report = await renderDirectory(positionals[1], {
+                format,
+                ...(values.account === undefined ? {} : { account: values.account }),
+            });
+            if (json)
+                console.log(JSON.stringify(report, null, 2));
+            else {
+                report.diagnostics
+                    .filter((d) => d.severity === "error")
+                    .forEach((d) => display(report.directory, d));
+                if (report.document !== null)
+                    process.stdout.write(report.document);
+            }
+            return report.ok ? 0 : 1;
+        }
+        if (positionals[0] === "coverage") {
+            if (values.scenario !== undefined)
+                throw new Error("--scenario requires the test command.");
+            const report = await coverageDirectory(positionals[1], {
+                seed: values.seed === undefined ? 0 : Number(values.seed),
+                cases: values.cases === undefined ? 100 : Number(values.cases),
+                mutate: values.mutate ?? false,
+            });
+            if (json)
+                console.log(JSON.stringify(report, null, 2));
+            else {
+                report.diagnostics.forEach((d) => display(report.directory, d));
+                for (const row of report.definitions)
+                    console.log(`${row.key}: ${row.references.length ? row.references.map((r) => `${r.kind} ${r.name}`).join(", ") : "unreferenced"}`);
+                for (const row of report.branchCoverage?.requirements ?? [])
+                    console.log(`${row.key}: ${row.observations} observed; applicability ${row.applicability.seen.join(", ") || "none"}; statuses ${row.statuses.seen.join(", ") || "none"}; due branches ${row.due?.branches.map((b) => `${b.seen.length}/${b.expected.length}`).join(", ") || "none"}`);
+                for (const property of report.branchCoverage?.tests.properties ?? [])
+                    for (const [index, antecedent] of property.antecedents.entries())
+                        console.log(`${property.name} implies ${index + 1}: antecedent true in ${antecedent.cases}/${property.cases} cases`);
+                for (const m of report.mutation?.mutants ?? [])
+                    if (m.outcome === "survived")
+                        console.log(`gap: mutant ${m.id} survived (${m.operator}, ${m.requirement}) at ${m.at.src}:${m.at.line}:${m.at.col}: ${m.description}`);
+                if (report.mutation)
+                    console.log(`mutation: ${report.mutation.killed} killed, ${report.mutation.survived} survived, ${report.mutation.invalid} invalid`);
+                console.log(`coverage references: ${report.totals.requirementsReferenced}/${report.totals.requirements} requirements, ${report.totals.clausesReferenced}/${report.totals.clauses} cited clauses; ${report.ok ? "tests passed" : "tests failed"}`);
+            }
+            return report.ok ? 0 : 1;
+        }
+        if (positionals[0] === "check") {
+            if (values.scenario !== undefined || values.seed !== undefined || values.cases !== undefined)
+                throw new Error("Test options require the test command.");
+            const report = await checkDirectory(positionals[1], { core: values.core ?? false });
+            if (json)
+                console.log(JSON.stringify(report, null, 2));
+            else {
+                report.diagnostics.forEach((d) => display(report.directory, d));
+                console.log(`check: ${report.ok ? "passed" : "failed"}; ${report.files.length} source files${report.statistics ? `, ${report.statistics.requirements} requirements` : ""}`);
+            }
+            return report.ok ? 0 : 1;
+        }
+        const report = await testDirectory(positionals[1], {
+            seed: values.seed === undefined ? 0 : Number(values.seed),
+            cases: values.cases === undefined ? 100 : Number(values.cases),
+            ...(values.scenario === undefined ? {} : { scenario: values.scenario }),
+        });
+        if (json)
+            console.log(JSON.stringify(report, null, 2));
+        else {
+            report.diagnostics.forEach((d) => display(report.directory, d));
+            for (const scenario of report.scenarios) {
+                console.log(`${scenario.passed ? "PASS" : "FAIL"} scenario ${scenario.name} (${scenario.assertions} assertions)`);
+                scenario.failures.forEach((f) => display(report.directory, f));
+            }
+            for (const property of report.properties) {
+                console.log(`${property.passed ? "PASS" : "FAIL"} property ${property.name} (seed ${property.seed}, ${property.cases} cases, ${property.checks} checks)`);
+                for (const [index, antecedent] of property.antecedents.entries())
+                    console.log(`  implies ${index + 1}: antecedent true in ${antecedent.cases}/${property.cases} cases`);
+                if (property.failure) {
+                    display(report.directory, property.failure);
+                    console.error(property.failure.counterexample.source);
+                }
+            }
+            console.log(`test: ${report.ok ? "passed" : "failed"}; ${report.scenarios.length} scenarios, ${report.properties.length} properties`);
+        }
+        return report.ok ? 0 : 1;
+    }
+    catch (cause) {
+        const d = {
+            code: "E_USAGE",
+            severity: "error",
+            message: String(cause),
+            at: null,
+            help,
+            fix: null,
+        };
+        if (json)
+            console.log(JSON.stringify({ format: "worldvm/error@1", ok: false, diagnostics: [d] }, null, 2));
+        else
+            console.error(`${d.message}\n${help}`);
+        return 2;
+    }
+};
+export * from "./index.js";

package/dist/codegen.d.ts

@@ -0,0 +1,6 @@
+import type { IR } from "./_internal/reconciler/index.js";
+/** Translate IR types to the values accepted by the embedding API. */
+export declare const typescriptType: (type: IR.TypeRef, aliases: readonly IR.TypeAlias[], seen?: ReadonlySet<string>) => string;
+/** A declaration-only module: safe as either .ts or .d.ts, without runtime imports. */
+export declare const generateTypes: (ir: IR.WorldIR) => string;
+export declare const codegenDirectory: (directory: string) => Promise<string>;

package/dist/codegen.js

@@ -0,0 +1,89 @@
+import { loadProject } from "./project.js";
+import { WorldError } from "./handle/world.js";
+/** Translate IR types to the values accepted by the embedding API. */
+export const typescriptType = (type, aliases, seen = new Set()) => {
+    const next = (t) => typescriptType(t, aliases, seen);
+    if (typeof type === "string") {
+        if (type.startsWith(":"))
+            return JSON.stringify(type.slice(1));
+        const alias = aliases.find((a) => a.name === type);
+        if (alias) {
+            if (seen.has(type))
+                throw new WorldError("E_CODEGEN_TYPE", `Recursive type alias ${type}.`);
+            return typescriptType(alias.type, aliases, new Set([...seen, type]));
+        }
+        if (["String", "Keyword", "Group", "Date", "Instant", "File"].includes(type))
+            return "string";
+        if (["Int", "Float"].includes(type))
+            return "number";
+        if (type === "Bool")
+            return "boolean";
+    }
+    else {
+        const [head, ...args] = type;
+        if (head === "Id")
+            return "string";
+        if (head === "Union")
+            return args.map(next).join(" | ") || "never";
+        if (head === "Option")
+            return `(${next(args[0])}) | null`;
+        if (head === "Brand")
+            return next(args[0]);
+        if (head === "Sensitive")
+            return next(args[1]);
+        if (head === "List" || head === "Set" || head === "Vec")
+            return `ReadonlyArray<${next(args[0])}>`;
+    }
+    // Never silently widen a new IR form to any/string; that would hide misspellings.
+    throw new WorldError("E_CODEGEN_TYPE", `Unsupported TypeRef ${JSON.stringify(type)}.`);
+};
+/** A declaration-only module: safe as either .ts or .d.ts, without runtime imports. */
+export const generateTypes = (ir) => {
+    const field = (f) => `readonly ${JSON.stringify(f.name)}: ${typescriptType(f.type, ir.types)};`;
+    const shape = (fields) => `{ ${fields.map(field).join(" ")} }`;
+    const operations = new Map();
+    const add = (name, input) => {
+        if (!operations.has(name))
+            operations.set(name, new Set());
+        operations.get(name).add(input);
+    };
+    for (const component of ir.components) {
+        const contracts = (ir.componentContracts ?? []).filter((c) => c.component === component.name);
+        const publicNames = component.operations ??
+            (contracts.length
+                ? contracts.flatMap((c) => c.operations.map((o) => o.name))
+                : [
+                    ...component.actions.map((a) => a.name),
+                    ...(ir.decisions ?? []).filter((d) => d.of === component.name).map((d) => d.name),
+                ]);
+        for (const action of component.actions) {
+            if (!publicNames.includes(action.name))
+                continue;
+            const via = action.via;
+            const evidence = via.kind === "interaction"
+                ? ir.evidence.find((e) => e.name === ir.interactions.find((i) => i.name === via.name)?.produces)
+                : undefined;
+            add(action.name, evidence?.fields.length
+                ? `{ readonly unsigned?: false; readonly values: ${shape(evidence.fields)}; readonly reason?: never } | { readonly unsigned: true; readonly values?: Partial<${shape(evidence.fields)}>; readonly reason?: never }`
+                : "{ readonly values?: never; readonly reason?: never }");
+        }
+        for (const decision of (ir.decisions ?? []).filter((d) => d.of === component.name))
+            if (publicNames.includes(decision.name)) {
+                const reason = typescriptType(decision.reason, ir.types);
+                add(decision.name, `{ readonly reason${reason.includes(" | null") ? "?" : ""}: ${reason}; readonly values?: never }`);
+            }
+    }
+    const entries = (rows) => rows.map(([name, value]) => `  readonly ${JSON.stringify(name)}: ${value};`).join("\n");
+    return (`// Generated by worldvm codegen. Regenerate after changing the world.\n` +
+        `export interface Entities {\n${entries(ir.entities.map((e) => [e.name, shape(e.fields)]))}\n}\n` +
+        `export interface Evidence {\n${entries(ir.evidence.map((e) => [e.name, shape(e.fields)]))}\n}\n` +
+        `export interface Operations {\n${entries([...operations].sort(([a], [b]) => a.localeCompare(b)).map(([name, inputs]) => [name, [...inputs].join(" | ")]))}\n}\n` +
+        `export interface WorldTypes { readonly entities: Entities; readonly operations: Operations }\n`);
+};
+export const codegenDirectory = async (directory) => {
+    const project = await loadProject(directory);
+    const errors = project.diagnostics.filter((d) => d.severity === "error");
+    if (!project.ir || errors.length)
+        throw new WorldError("E_CHECK", "Cannot generate types for an invalid world.", errors);
+    return generateTypes(project.ir);
+};