worldvm 0.0.0-stage → 0.1.0

package/dist/coverage.d.ts

@@ -0,0 +1,60 @@
+import { type IR, type RequirementCoverage } from "./_internal/reconciler/index.js";
+import { type TestOptions, type TestReport } from "./test.js";
+import { type CliDiagnostic } from "./project.js";
+import { type MutationReport } from "./mutate.js";
+export interface CoverageReference {
+    readonly kind: "scenario" | "property";
+    readonly name: string;
+}
+export interface CoverageDefinition {
+    readonly key: string;
+    readonly component: string;
+    readonly name: string;
+    readonly kind: "requirement" | "invariant" | "retention";
+    readonly at: IR.Span;
+    readonly cites: readonly IR.Citation[];
+    readonly references: readonly CoverageReference[];
+}
+export interface CoverageReport {
+    readonly format: "worldvm/coverage@2";
+    readonly command: "coverage";
+    readonly mode: "branches";
+    readonly branchCoverage: {
+        readonly seed: number;
+        readonly cases: number;
+        readonly requirements: readonly RequirementCoverage[];
+        readonly clauses: readonly {
+            readonly source: string;
+            readonly clause: string;
+            readonly requirements: readonly RequirementCoverage[];
+        }[];
+        readonly tests: TestReport;
+    } | null;
+    readonly directory: string;
+    readonly ok: boolean;
+    readonly diagnostics: readonly CliDiagnostic[];
+    readonly definitions: readonly CoverageDefinition[];
+    readonly sources: readonly {
+        readonly name: string;
+        readonly kind: string;
+        readonly url: string;
+        readonly asOf: string;
+        readonly clauses: readonly {
+            readonly clause: string;
+            readonly definitions: readonly string[];
+            readonly references: readonly CoverageReference[];
+        }[];
+    }[];
+    /** Present with { mutate: true }: semantic mutants and whether any test caught them. */
+    readonly mutation?: MutationReport;
+    readonly totals: {
+        readonly requirements: number;
+        readonly requirementsReferenced: number;
+        readonly clauses: number;
+        readonly clausesReferenced: number;
+    };
+}
+/** Definition references deliberately over-approximate possible execution; branches are separate. */
+export declare const coverageDirectory: (directory: string, options?: Pick<TestOptions, "seed" | "cases"> & {
+    readonly mutate?: boolean;
+}) => Promise<CoverageReport>;

package/dist/coverage.js

@@ -0,0 +1,128 @@
+import { definitionReferences } from "./_internal/forma/world/index.js";
+import { createCoverageCollector, validatePropertyOptions, } from "./_internal/reconciler/index.js";
+import { runTests } from "./test.js";
+import { loadProject } from "./project.js";
+import { mutationTest } from "./mutate.js";
+const references = (set) => [...set].sort().map((key) => {
+    const split = key.indexOf("\0");
+    return { kind: key.slice(0, split), name: key.slice(split + 1) };
+});
+/** Definition references deliberately over-approximate possible execution; branches are separate. */
+export const coverageDirectory = async (directory, options = {}) => {
+    const budgets = { seed: options.seed ?? 0, cases: options.cases ?? 100 };
+    validatePropertyOptions(budgets);
+    const project = await loadProject(directory), ir = project.ir;
+    const empty = {
+        format: "worldvm/coverage@2",
+        command: "coverage",
+        mode: "branches",
+        branchCoverage: null,
+        directory: project.directory,
+        ok: false,
+        diagnostics: project.diagnostics,
+        definitions: [],
+        sources: [],
+        totals: { requirements: 0, requirementsReferenced: 0, clauses: 0, clausesReferenced: 0 },
+    };
+    if (!ir || project.diagnostics.some((d) => d.severity === "error"))
+        return empty;
+    const rows = new Map();
+    for (const c of ir.components) {
+        for (const r of c.requirements)
+            rows.set(`${c.name}/${r.name}`, {
+                key: `${c.name}/${r.name}`,
+                component: c.name,
+                name: r.name,
+                kind: "requirement",
+                at: r.at,
+                cites: r.cites ?? [],
+                refs: new Set(),
+            });
+        for (const r of c.invariants)
+            rows.set(`${c.name}/invariant:${r.name}`, {
+                key: `${c.name}/invariant:${r.name}`,
+                component: c.name,
+                name: r.name,
+                kind: "invariant",
+                at: r.at,
+                cites: r.cites ?? [],
+                refs: new Set(),
+            });
+        if (c.retention)
+            rows.set(`${c.name}/retention`, {
+                key: `${c.name}/retention`,
+                component: c.name,
+                name: "retention",
+                kind: "retention",
+                at: c.retention.at,
+                cites: c.retention.cites ?? [],
+                refs: new Set(),
+            });
+    }
+    for (const [key, refs] of definitionReferences(ir))
+        for (const ref of refs)
+            rows.get(key)?.refs.add(`${ref.kind}\0${ref.name}`);
+    const definitions = [...rows.values()]
+        .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+        .map(({ refs, ...row }) => ({ ...row, references: references(refs) }));
+    const sources = (ir.references ?? []).map((source) => {
+        const clauses = new Map();
+        for (const row of rows.values())
+            for (const cite of row.cites)
+                if (cite.source === source.name) {
+                    let clause = clauses.get(cite.clause);
+                    if (!clause)
+                        clauses.set(cite.clause, (clause = { definitions: new Set(), refs: new Set() }));
+                    clause.definitions.add(row.key);
+                    row.refs.forEach((r) => clause.refs.add(r));
+                }
+        return {
+            name: source.name,
+            kind: source.kind,
+            url: source.url,
+            asOf: source.asOf,
+            clauses: [...clauses]
+                .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+                .map(([clause, value]) => ({
+                clause,
+                definitions: [...value.definitions].sort(),
+                references: references(value.refs),
+            })),
+        };
+    });
+    const requirements = definitions.filter((d) => d.kind === "requirement");
+    const collector = createCoverageCollector(ir);
+    const tests = runTests(project, budgets, (recon, ref) => collector.observe(recon, ref));
+    const measured = collector.report(), byKey = new Map(measured.map((row) => [row.key, row]));
+    const diagnostics = [
+        ...tests.diagnostics,
+        ...tests.scenarios.flatMap((s) => s.failures),
+        ...tests.properties.flatMap((p) => (p.failure ? [p.failure] : [])),
+    ];
+    // Mutants only mean something against a passing baseline.
+    const mutation = options.mutate && tests.ok ? { mutation: mutationTest(project, budgets) } : {};
+    return {
+        ...empty,
+        ...mutation,
+        ok: tests.ok,
+        diagnostics,
+        branchCoverage: {
+            ...budgets,
+            requirements: measured,
+            clauses: sources.flatMap((source) => source.clauses.map((clause) => ({
+                source: source.name,
+                clause: clause.clause,
+                requirements: clause.definitions.flatMap((key) => byKey.has(key) ? [byKey.get(key)] : []),
+            }))),
+            tests,
+        },
+        definitions,
+        sources,
+        totals: {
+            requirements: requirements.length,
+            requirementsReferenced: requirements.filter((d) => d.references.length).length,
+            clauses: sources.reduce((n, s) => n + s.clauses.length, 0),
+            clausesReferenced: sources.reduce((n, s) => n + s.clauses.filter((c) => c.references.length).length, 0),
+        },
+    };
+};

package/dist/deploy.d.ts

@@ -0,0 +1,21 @@
+import { type CliDiagnostic } from "./project.js";
+import { type Impact } from "./release/impact.js";
+export interface DeployReport {
+    readonly format: "worldvm/deploy-report@1";
+    readonly ok: boolean;
+    readonly directory: string;
+    readonly old: string | null;
+    readonly new: string | null;
+    readonly at: string;
+    readonly dryRun: boolean;
+    readonly diagnostics: readonly CliDiagnostic[];
+    readonly impact: Impact | null;
+    readonly subjects: readonly string[];
+}
+/** Check, preview the committed population, then atomically retain and activate a release. */
+export declare const deployDirectory: (source: string, options: {
+    readonly db: string;
+    readonly account?: string;
+    readonly at?: string;
+    readonly dryRun?: boolean;
+}) => Promise<DeployReport>;

package/dist/deploy.js

@@ -0,0 +1,72 @@
+import { existsSync } from "node:fs";
+import { emptyWorld } from "./_internal/reconciler/index.js";
+import { loadProject } from "./project.js";
+import { host } from "./handle/world.js";
+import { sqlite } from "./sqlite.js";
+import { snapshotDatabase } from "./snapshot.js";
+import { previewImpact } from "./release/impact.js";
+/** Check, preview the committed population, then atomically retain and activate a release. */
+export const deployDirectory = async (source, options) => {
+    const project = await loadProject(source);
+    const at = options.at ?? new Date().toISOString();
+    const base = {
+        format: "worldvm/deploy-report@1",
+        directory: project.directory,
+        at,
+        dryRun: options.dryRun ?? false,
+        diagnostics: project.diagnostics,
+    };
+    if (!project.ir || project.diagnostics.some((d) => d.severity === "error"))
+        return { ...base, ok: false, old: null, new: null, impact: null, subjects: [] };
+    if (!Number.isFinite(Date.parse(at)))
+        throw new Error("--at must be an ISO instant.");
+    const checked = await host({
+        ir: project.ir,
+        ...(options.account ? { account: options.account } : {}),
+    });
+    const account = checked.account;
+    const release = checked.release;
+    await checked.close();
+    // Dry runs never create a file, schema, journal or write transaction.
+    const store = options.dryRun && !existsSync(options.db)
+        ? null
+        : sqlite(options.db, { readOnly: options.dryRun ?? false });
+    try {
+        const state = store ? await store.load() : null;
+        const previous = store?.deployed() ?? null;
+        if (previous && previous.account !== account)
+            throw new Error(`Database belongs to account ${previous.account}; cannot deploy ${account}.`);
+        if (state && !previous)
+            throw new Error("Database has records without a deployed release. Deploy into a new database.");
+        const snapshot = state ? await snapshotDatabase(options.db, account) : null;
+        const impact = previous && snapshot ? previewImpact(previous.ir, project.ir, { ...snapshot, at }) : null;
+        if (impact?.unexpected.length)
+            throw new Error("Impact contains changes outside the dependency selection; deployment refused.");
+        const subjects = [
+            ...new Set([
+                ...(impact?.occurrences.changes ?? []).flatMap((c) => [
+                    ...(c.before?.subjects ?? []),
+                    ...(c.after?.subjects ?? []),
+                ]),
+                ...(impact?.work.changes ?? []).flatMap((c) => [
+                    ...(c.before?.subjects ?? []),
+                    ...(c.after?.subjects ?? []),
+                ]),
+            ]),
+        ].sort();
+        if (!options.dryRun)
+            store.deploy({ release, account, at: new Date().toISOString(), ir: project.ir }, {
+                ...(state ?? { revision: 0, records: emptyWorld, receipts: {}, proposals: {} }),
+                release,
+            });
+        return { ...base, ok: true, old: previous?.release ?? null, new: release, impact, subjects };
+    }
+    catch (cause) {
+        if (/locked|busy/i.test(String(cause)))
+            throw new Error("Database is locked. Stop worldvm serve before deploying.");
+        throw cause;
+    }
+    finally {
+        await store?.close();
+    }
+};

package/dist/diagnostics.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Browser-safe authoring diagnostics: everything the CLI adds on top of the compiler's
+ * diagnostics (contextual help, machine fixes, catalogue defaults and lints). The CLI and
+ * the browser IDE both call this, so their reports stay identical.
+ */
+import type { CompileResult, SourceFile, WorldIR } from "./_internal/forma/world/index.js";
+import type { CliDiagnostic } from "./project.js";
+/** Compiler diagnostics with CLI help and fixes, followed by the authoring lints. */
+export declare const authoringDiagnostics: (compiled: CompileResult, files: readonly SourceFile[], ir: WorldIR | null) => CliDiagnostic[];

package/dist/diagnostics.js

@@ -0,0 +1,37 @@
+import { GENERIC_HELP, catalogueEntry } from "./catalogue.js";
+import { authoringLints } from "./lints.js";
+import { refine } from "./refine.js";
+import { authoringFix } from "./fixes.js";
+/** Padding an otherwise valid calendar date changes representation, never its meaning. */
+const dateFix = (d, files) => {
+    if (!d.at || !["E_SOURCE_DATE", "E_SCENARIO_DATE", "E_PROPERTY_DATE"].includes(d.code))
+        return null;
+    const text = files.find((f) => f.id === d.at.src)?.text.slice(d.at.from, d.at.to);
+    if (!text)
+        return null;
+    const match = /^"(\d{4})-(\d{1,2})-(\d{1,2})"$/.exec(text);
+    if (!match)
+        return null;
+    const padded = `${match[1]}-${match[2].padStart(2, "0")}-${match[3].padStart(2, "0")}`;
+    const replacement = JSON.stringify(padded), time = Date.parse(`${padded}T00:00:00Z`);
+    if (replacement === text ||
+        !Number.isFinite(time) ||
+        new Date(time).toISOString().slice(0, 10) !== padded)
+        return null;
+    return { src: d.at.src, from: d.at.from, to: d.at.to, text: replacement, expected: text };
+};
+/** Compiler diagnostics with CLI help and fixes, followed by the authoring lints. */
+export const authoringDiagnostics = (compiled, files, ir) => {
+    const diagnostics = compiled.diagnostics.map((d) => {
+        const at = d.at ?? null, refined = refine({ code: d.code, message: d.message, at }, files, ir);
+        return {
+            ...d,
+            at,
+            help: refined?.help ?? d.help ?? catalogueEntry(d.code)?.fix ?? GENERIC_HELP,
+            fix: d.fix ?? refined?.fix ?? dateFix(d, files) ?? authoringFix(d, files),
+        };
+    });
+    if (ir)
+        diagnostics.push(...authoringLints(ir, files));
+    return diagnostics;
+};

package/dist/diff.d.ts

@@ -0,0 +1,17 @@
+import { type CliDiagnostic } from "./project.js";
+import { type WorldDiff } from "./release/diff.js";
+export interface SidedDiagnostic extends CliDiagnostic {
+    /** Which release the diagnostic belongs to; spans are relative to that directory. */
+    readonly side: "old" | "new";
+}
+export interface DiffReport {
+    readonly format: "worldvm/diff-report@1";
+    readonly command: "diff";
+    readonly old: string;
+    readonly new: string;
+    readonly ok: boolean;
+    readonly diagnostics: readonly SidedDiagnostic[];
+    readonly diff: WorldDiff | null;
+}
+/** Compiles both releases and compares declarations; either side failing to compile fails the diff. */
+export declare const diffDirectories: (before: string, after: string) => Promise<DiffReport>;

package/dist/diff.js

@@ -0,0 +1,19 @@
+import { loadProject } from "./project.js";
+import { diffWorlds } from "./release/diff.js";
+/** Compiles both releases and compares declarations; either side failing to compile fails the diff. */
+export const diffDirectories = async (before, after) => {
+    const [a, b] = await Promise.all([loadProject(before), loadProject(after)]);
+    const errors = [
+        ...a.diagnostics.map((d) => ({ ...d, side: "old" })),
+        ...b.diagnostics.map((d) => ({ ...d, side: "new" })),
+    ].filter((d) => d.severity === "error");
+    const base = {
+        format: "worldvm/diff-report@1",
+        command: "diff",
+        old: a.directory,
+        new: b.directory,
+    };
+    if (errors.length || !a.ir || !b.ir)
+        return { ...base, ok: false, diagnostics: errors, diff: null };
+    return { ...base, ok: true, diagnostics: [], diff: diffWorlds(a.ir, b.ir) };
+};

package/dist/durable-object.d.ts

@@ -0,0 +1,14 @@
+import type { Store } from "./world.js";
+/** The synchronous SQLite subset of Cloudflare DurableObjectStorage. */
+export interface DurableObjectSqliteStorage {
+    readonly sql: {
+        readonly exec: (query: string, ...bindings: string[]) => Iterable<Record<string, unknown>>;
+    };
+    readonly transactionSync: <A>(callback: () => A) => A;
+}
+/**
+ * One world account per SQLite-backed Durable Object. The platform owns the database
+ * lifetime. Serialize handle operations with blockConcurrencyWhile in the host; this
+ * adapter supplies atomic persistence, not coordination between concurrent handles.
+ */
+export declare const durableObject: (storage: DurableObjectSqliteStorage) => Store;

package/dist/durable-object.js

@@ -0,0 +1,30 @@
+const format = "worldvm/durable-object-store@1";
+/**
+ * One world account per SQLite-backed Durable Object. The platform owns the database
+ * lifetime. Serialize handle operations with blockConcurrencyWhile in the host; this
+ * adapter supplies atomic persistence, not coordination between concurrent handles.
+ */
+export const durableObject = (storage) => {
+    storage.sql.exec(`CREATE TABLE IF NOT EXISTS worldvm_handle_state (
+    id INTEGER PRIMARY KEY CHECK (id = 1), body TEXT NOT NULL
+  )`);
+    return {
+        load: () => {
+            const row = [...storage.sql.exec("SELECT body FROM worldvm_handle_state WHERE id = 1")][0];
+            if (!row)
+                return null;
+            const saved = JSON.parse(row["body"]);
+            if (saved.format !== format)
+                throw new Error("Unsupported WorldVM Durable Object store format.");
+            return saved.state;
+        },
+        commit: (state) => {
+            const body = JSON.stringify({ format, state });
+            storage.transactionSync(() => {
+                storage.sql.exec(`INSERT INTO worldvm_handle_state (id, body) VALUES (1, ?)
+          ON CONFLICT(id) DO UPDATE SET body = excluded.body`, body);
+            });
+        },
+        close: () => { },
+    };
+};

package/dist/explain.d.ts

@@ -0,0 +1,113 @@
+import { type IR, type WorldReconciliation } from "./_internal/reconciler/index.js";
+import { type CliDiagnostic, type Project } from "./project.js";
+export interface ExplainOptions {
+    /** Authored scenario to replay; its steps are the observable instants. */
+    readonly scenario?: string;
+    /** Recorded in-memory world snapshot (`worldvm/world@1`) holding a live subject. */
+    readonly world?: string;
+    /** Restricts the explanation to occurrences attached to (or homed at) this subject. */
+    readonly subject?: string;
+    /** Scenario: latest authored step at or before this instant. Snapshot: required evaluation instant. */
+    readonly at?: string;
+}
+export interface ExplainedStep {
+    readonly at: IR.Span;
+    readonly value: unknown;
+    readonly branch: "true" | "false" | "Unknown" | null;
+    readonly note: string | null;
+}
+export interface ExplainedRequirement {
+    readonly name: string;
+    readonly label: string;
+    readonly occurrence: string;
+    readonly status: string;
+    readonly due: string | null;
+    readonly dueUnknown: string | null;
+    readonly dueSteps: readonly ExplainedStep[];
+    readonly remindAt: string | null;
+    readonly reasons: readonly {
+        readonly label: string;
+        readonly outcome: string;
+        readonly detail: string;
+        readonly at: IR.Span | null;
+    }[];
+    readonly evidence: {
+        readonly values: Readonly<Record<string, string>>;
+        readonly id: string;
+        readonly type: string;
+        readonly status: string;
+        readonly by: string;
+        readonly at: string;
+    } | null;
+    readonly via: string;
+    readonly awaits: string | null;
+    readonly blocked: string | null;
+    /** Reproducible decision digest over release, occurrence, status, reasons, evidence and due. */
+    readonly proof: string;
+    /** The rule as authored: located definition, manual prose and cited clauses. */
+    readonly rule: {
+        readonly at: IR.Span;
+        readonly prose: readonly {
+            readonly label: string;
+            readonly text: string;
+        }[];
+        readonly cites: readonly {
+            readonly source: string;
+            readonly clause: string;
+            readonly title: string;
+            readonly at: IR.Span;
+        }[];
+    };
+}
+export interface ExplainedWork {
+    readonly key: string;
+    readonly state: string;
+    readonly assignee: {
+        readonly id: string | null;
+        readonly kind: string;
+    };
+    readonly members: readonly {
+        readonly instance: string;
+        readonly action: string;
+        readonly occurrences: readonly string[];
+    }[];
+    readonly reason: string | null;
+}
+export interface ExplainedInstance {
+    readonly instance: string;
+    readonly component: string;
+    readonly account: string;
+    readonly attached: readonly string[];
+    readonly requirements: readonly ExplainedRequirement[];
+    readonly wakeAt: string | null;
+    readonly wakeReason: string;
+}
+export interface ExplainReport {
+    readonly format: "worldvm/explain@1";
+    readonly command: "explain";
+    readonly directory: string;
+    readonly ok: boolean;
+    readonly source: {
+        readonly kind: "scenario";
+        readonly name: string;
+        readonly step: number;
+    } | {
+        readonly kind: "snapshot";
+        readonly path: string;
+        readonly accounts: readonly string[];
+    } | null;
+    readonly subject: string | null;
+    readonly requestedAt: string | null;
+    /** The instant actually evaluated. */
+    readonly now: string | null;
+    readonly releases: readonly string[];
+    readonly instances: readonly ExplainedInstance[];
+    readonly work: readonly ExplainedWork[];
+    readonly diagnostics: readonly CliDiagnostic[];
+}
+/** Shapes one reconciliation into located answers: why each status, due date and work item. */
+export declare const explainReconciliation: (ir: IR.WorldIR, files: Project["files"], recon: WorldReconciliation, subject: string | null) => {
+    readonly instances: readonly ExplainedInstance[];
+    readonly work: readonly ExplainedWork[];
+};
+export declare const explainDirectory: (directory: string, options: ExplainOptions) => Promise<ExplainReport>;