worldvm 0.0.0-stage → 0.1.0

package/dist/release/impact.d.ts

@@ -0,0 +1,83 @@
+import type { WorldIR } from "../_internal/forma/world/index.js";
+import { type World } from "../_internal/reconciler/index.js";
+import { type IRNode } from "./nodes.js";
+/** The component a node belongs to, for component-scoped nodes and component shells. */
+export declare const nodeComponent: (node: IRNode) => string | null;
+/**
+ * Direct references of every node. Any string equal to a declaration's name counts, which
+ * over-approximates (a coincidental match only widens the preview, never narrows it). Scoped
+ * nodes depend on their component shell and on same-component siblings they name; a shell
+ * depends on the siblings it names (outputs read requirement statuses).
+ */
+export declare const nodeReferences: (nodes: ReadonlyMap<string, IRNode>) => ReadonlyMap<string, ReadonlySet<string>>;
+/** A node's digest over itself and everything it transitively depends on. */
+export declare const dependencyDigests: (ir: WorldIR) => ReadonlyMap<string, string>;
+export interface AffectedDefinitions {
+    /** Node keys whose dependency digest changed, appeared or disappeared. */
+    readonly nodes: readonly string[];
+    readonly components: readonly string[];
+    /** Accounts whose own declaration changed: every occurrence they evaluate may move. */
+    readonly accounts: readonly string[];
+}
+export declare const affectedDefinitions: (before: WorldIR, after: WorldIR) => AffectedDefinitions;
+export interface Population {
+    readonly accounts: readonly string[];
+    readonly world: World;
+    readonly at: string;
+}
+export interface OccurrenceState {
+    readonly account: string;
+    readonly instance: string;
+    readonly component: string;
+    readonly requirement: string;
+    readonly occurrence: string;
+    readonly subjects: readonly string[];
+    readonly status: string;
+    readonly due: string | null;
+}
+export interface OccurrenceChange {
+    readonly change: "gained" | "lost" | "status" | "due";
+    readonly before: OccurrenceState | null;
+    readonly after: OccurrenceState | null;
+}
+export interface WorkState {
+    readonly key: string;
+    readonly account: string;
+    readonly state: string;
+    readonly instances: readonly string[];
+    readonly subjects: readonly string[];
+}
+export interface WorkChange {
+    readonly change: "gained" | "lost" | "state";
+    readonly before: WorkState | null;
+    readonly after: WorkState | null;
+}
+export interface Impact {
+    readonly format: "worldvm/impact@1";
+    readonly at: string;
+    readonly affected: AffectedDefinitions;
+    readonly subjects: {
+        readonly total: number;
+        readonly considered: number;
+        readonly changed: number;
+    };
+    readonly occurrences: {
+        readonly total: number;
+        readonly considered: number;
+        readonly changes: readonly OccurrenceChange[];
+    };
+    readonly work: {
+        readonly before: number;
+        readonly after: number;
+        readonly changes: readonly WorkChange[];
+    };
+    /** Changes outside the dependency selection: must be empty, or the digests missed a dependency. */
+    readonly unexpected: readonly (OccurrenceChange | WorkChange)[];
+    readonly samples: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * Previews a release over a recorded population: which occurrences and work change and for
+ * whom. Dependency digests select what can change; every other occurrence is still compared,
+ * and any difference outside the selection is reported as unexpected rather than hidden.
+ */
+export declare const previewImpact: (before: WorldIR, after: WorldIR, population: Population) => Impact;

package/dist/release/impact.js

@@ -0,0 +1,214 @@
+import { basis, link, reconcile, sha256, workItems, } from "../_internal/reconciler/index.js";
+import { nodeDigest, releaseNodes, semanticJson } from "./nodes.js";
+const scoped = new Set(["requirement", "action", "invariant", "retention"]);
+/** The component a node belongs to, for component-scoped nodes and component shells. */
+export const nodeComponent = (node) => node.kind === "component" || node.kind === "retention"
+    ? node.name
+    : scoped.has(node.kind)
+        ? node.name.slice(0, node.name.indexOf("/"))
+        : null;
+const strings = (value, out) => {
+    if (typeof value === "string")
+        out.add(value);
+    else if (Array.isArray(value))
+        value.forEach((v) => strings(v, out));
+    else if (value && typeof value === "object")
+        for (const [k, v] of Object.entries(value))
+            if (k !== "at")
+                strings(v, out);
+    return out;
+};
+/**
+ * Direct references of every node. Any string equal to a declaration's name counts, which
+ * over-approximates (a coincidental match only widens the preview, never narrows it). Scoped
+ * nodes depend on their component shell and on same-component siblings they name; a shell
+ * depends on the siblings it names (outputs read requirement statuses).
+ */
+export const nodeReferences = (nodes) => {
+    const global = new Map(), local = new Map();
+    for (const node of nodes.values()) {
+        const component = nodeComponent(node);
+        if (scoped.has(node.kind) && component !== null && node.kind !== "retention") {
+            const short = `${component}\u0000${node.name.slice(component.length + 1)}`;
+            local.set(short, [...(local.get(short) ?? []), node.key]);
+        }
+        else if (node.kind !== "retention" && node.kind !== "library")
+            // A library's digest names the whole compiled unit; its meaning lives in its declarations.
+            global.set(node.name, [...(global.get(node.name) ?? []), node.key]);
+    }
+    const out = new Map();
+    for (const node of nodes.values()) {
+        const refs = new Set(), component = nodeComponent(node);
+        for (const s of strings(node.value, new Set())) {
+            for (const key of global.get(s) ?? [])
+                refs.add(key);
+            if (component !== null)
+                for (const key of local.get(`${component}\u0000${s}`) ?? [])
+                    refs.add(key);
+        }
+        if (component !== null && node.kind !== "component")
+            refs.add(`component:${component}`);
+        refs.delete(node.key);
+        out.set(node.key, refs);
+    }
+    // Components read roles; the entities implementing a role decide what those reads observe.
+    for (const node of nodes.values())
+        if (node.kind === "entity")
+            for (const ref of out.get(node.key) ?? [])
+                if (ref.startsWith("role:"))
+                    out.get(ref)?.add(node.key);
+    return out;
+};
+/** A node's digest over itself and everything it transitively depends on. */
+export const dependencyDigests = (ir) => {
+    const nodes = releaseNodes(ir), refs = nodeReferences(nodes), own = new Map([...nodes.values()].map((n) => [n.key, nodeDigest(n)]));
+    const out = new Map();
+    for (const key of nodes.keys()) {
+        const closure = new Set([key]), queue = [key];
+        while (queue.length)
+            for (const next of refs.get(queue.pop()) ?? [])
+                if (!closure.has(next)) {
+                    closure.add(next);
+                    queue.push(next);
+                }
+        out.set(key, `sha256:${sha256(semanticJson([...closure].sort().map((k) => [k, own.get(k)])))}`);
+    }
+    return out;
+};
+export const affectedDefinitions = (before, after) => {
+    const a = dependencyDigests(before), b = dependencyDigests(after), nodes = [...new Set([...a.keys(), ...b.keys()])].filter((k) => a.get(k) !== b.get(k)).sort();
+    const oldNodes = releaseNodes(before), newNodes = releaseNodes(after);
+    const components = new Set(), accounts = new Set();
+    for (const key of nodes) {
+        const was = oldNodes.get(key), now = newNodes.get(key), node = (now ?? was);
+        const component = nodeComponent(node);
+        if (component !== null)
+            components.add(component);
+        // An account's closure reaches its roots; only a change to its own declaration moves all.
+        if (node.kind === "account" && (!was || !now || nodeDigest(was) !== nodeDigest(now)))
+            accounts.add(node.name);
+    }
+    return { nodes, components: [...components].sort(), accounts: [...accounts].sort() };
+};
+const occurrences = (recon) => {
+    const out = new Map();
+    for (const [instance, result] of recon.results) {
+        const inst = recon.instances.get(instance);
+        for (const q of result.requirements)
+            out.set(JSON.stringify([inst.account, q.occurrence]), {
+                account: inst.account,
+                instance,
+                component: inst.component,
+                requirement: q.name,
+                occurrence: q.occurrence,
+                subjects: [...inst.attached].sort(),
+                status: q.status,
+                due: q.due,
+            });
+    }
+    return out;
+};
+const work = (recon) => new Map(workItems(recon).map((w) => {
+    const instances = [...new Set(w.members.map((m) => m.instance))].sort();
+    return [
+        w.key,
+        {
+            key: w.key,
+            account: w.account,
+            state: w.state,
+            instances,
+            subjects: [
+                ...new Set(instances.flatMap((i) => recon.instances.get(i)?.attached ?? [])),
+            ].sort(),
+        },
+    ];
+}));
+const run = (ir, population) => reconcile(population.accounts.map((a) => link(ir, a)), basis(population.world, population.at), population.at);
+/**
+ * Previews a release over a recorded population: which occurrences and work change and for
+ * whom. Dependency digests select what can change; every other occurrence is still compared,
+ * and any difference outside the selection is reported as unexpected rather than hidden.
+ */
+export const previewImpact = (before, after, population) => {
+    const affected = affectedDefinitions(before, after), components = new Set(affected.components), accounts = new Set(affected.accounts);
+    const old = run(before, population), next = run(after, population);
+    const inScope = (account, component) => accounts.has(account) || components.has(component);
+    const o1 = occurrences(old), o2 = occurrences(next);
+    const occurrenceChanges = [];
+    for (const key of [...new Set([...o1.keys(), ...o2.keys()])].sort()) {
+        const a = o1.get(key) ?? null, b = o2.get(key) ?? null;
+        const change = !a
+            ? "gained"
+            : !b
+                ? "lost"
+                : a.status !== b.status
+                    ? "status"
+                    : a.due !== b.due
+                        ? "due"
+                        : null;
+        if (change)
+            occurrenceChanges.push({ change, before: a, after: b });
+    }
+    const w1 = work(old), w2 = work(next), instanceComponent = (account, instance) => (next.instances.get(instance) ?? old.instances.get(instance))?.component ?? "";
+    const workChanges = [];
+    for (const key of [...new Set([...w1.keys(), ...w2.keys()])].sort()) {
+        const a = w1.get(key) ?? null, b = w2.get(key) ?? null;
+        const change = !a
+            ? "gained"
+            : !b
+                ? "lost"
+                : a.state !== b.state
+                    ? "state"
+                    : null;
+        if (change)
+            workChanges.push({ change, before: a, after: b });
+    }
+    const occurrenceScoped = (c) => {
+        const s = (c.after ?? c.before);
+        return inScope(s.account, s.component);
+    };
+    const workScoped = (c) => {
+        const s = (c.after ?? c.before);
+        return s.instances.some((i) => inScope(s.account, instanceComponent(s.account, i)));
+    };
+    const considered = [
+        ...new Set([...o1.values(), ...o2.values()]
+            .filter((s) => inScope(s.account, s.component))
+            .map((s) => JSON.stringify([s.account, s.occurrence]))),
+    ];
+    const allSubjects = new Set([...o1.values(), ...o2.values()].flatMap((s) => s.subjects));
+    const consideredSubjects = new Set([...o1.values(), ...o2.values()]
+        .filter((s) => inScope(s.account, s.component))
+        .flatMap((s) => s.subjects));
+    const changedSubjects = new Set([
+        ...occurrenceChanges.flatMap((c) => (c.after ?? c.before).subjects),
+        ...workChanges.flatMap((c) => (c.after ?? c.before).subjects),
+    ]);
+    const sample = (items) => [...new Set(items)].slice(0, 5);
+    return {
+        format: "worldvm/impact@1",
+        at: population.at,
+        affected,
+        subjects: {
+            total: allSubjects.size,
+            considered: consideredSubjects.size,
+            changed: changedSubjects.size,
+        },
+        occurrences: {
+            total: new Set([...o1.keys(), ...o2.keys()]).size,
+            considered: considered.length,
+            changes: occurrenceChanges.filter(occurrenceScoped),
+        },
+        work: { before: w1.size, after: w2.size, changes: workChanges.filter(workScoped) },
+        unexpected: [
+            ...occurrenceChanges.filter((c) => !occurrenceScoped(c)),
+            ...workChanges.filter((c) => !workScoped(c)),
+        ],
+        samples: {
+            "work gained": sample(workChanges.filter((c) => c.change === "gained").flatMap((c) => c.after.subjects)),
+            "work lost": sample(workChanges.filter((c) => c.change === "lost").flatMap((c) => c.before.subjects)),
+            "status changed": sample(occurrenceChanges.filter((c) => c.change === "status").flatMap((c) => c.after.subjects)),
+            "due changed": sample(occurrenceChanges.filter((c) => c.change === "due").flatMap((c) => c.after.subjects)),
+        },
+    };
+};

package/dist/release/nodes.d.ts

@@ -0,0 +1,20 @@
+import type { Span, WorldIR } from "../_internal/forma/world/index.js";
+/**
+ * One named declaration of a compiled world. Requirements, actions, invariants and retention are
+ * their own nodes so a diff and an impact preview can name the obligation that changed; the
+ * component node keeps the rest of the component (identity, inputs, home, slots, outputs).
+ */
+export interface IRNode {
+    readonly key: string;
+    readonly kind: string;
+    readonly name: string;
+    readonly at: Span | null;
+    readonly value: unknown;
+}
+/** Canonical JSON without source spans: moving or reformatting source never changes meaning. */
+export declare const semanticJson: (value: unknown) => string;
+export declare const nodeDigest: (node: IRNode) => string;
+export declare const behaviorDigest: (node: IRNode) => string;
+/** Every release-relevant declaration. Scenarios and properties are examples, listed separately. */
+export declare const releaseNodes: (ir: WorldIR) => ReadonlyMap<string, IRNode>;
+export declare const exampleNodes: (ir: WorldIR) => ReadonlyMap<string, IRNode>;

package/dist/release/nodes.js

@@ -0,0 +1,118 @@
+import { sha256 } from "../_internal/reconciler/index.js";
+const isSpan = (v) => !!v &&
+    typeof v === "object" &&
+    typeof v.src === "string" &&
+    typeof v.from === "number" &&
+    typeof v.line === "number";
+/** Canonical JSON without source spans: moving or reformatting source never changes meaning. */
+export const semanticJson = (value) => {
+    const visit = (v) => {
+        if (v === undefined)
+            return "null";
+        if (!v || typeof v !== "object")
+            return JSON.stringify(v);
+        if (Array.isArray(v))
+            return `[${v.map(visit).join(",")}]`;
+        const record = v;
+        return `{${Object.keys(record)
+            .filter((k) => record[k] !== undefined && !(k === "at" && isSpan(record[k])))
+            .sort()
+            .map((k) => `${JSON.stringify(k)}:${visit(record[k])}`)
+            .join(",")}}`;
+    };
+    return visit(value);
+};
+const presentation = new Set(["doc", "label", "title"]);
+/** Removes prose that never reaches evaluation, so a diff can say a change is wording only. */
+const withoutPresentation = (value) => {
+    if (Array.isArray(value))
+        return value.map(withoutPresentation);
+    if (!value || typeof value !== "object" || isSpan(value))
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([k]) => !presentation.has(k))
+        .map(([k, v]) => [k, withoutPresentation(v)]));
+};
+export const nodeDigest = (node) => `sha256:${sha256(semanticJson(node.value))}`;
+export const behaviorDigest = (node) => `sha256:${sha256(semanticJson(withoutPresentation(node.value)))}`;
+const named = (kind, items) => (items ?? []).map((item) => ({
+    key: `${kind}:${item.name}`,
+    kind,
+    name: item.name,
+    at: item.at ?? null,
+    value: item,
+}));
+/** Every release-relevant declaration. Scenarios and properties are examples, listed separately. */
+export const releaseNodes = (ir) => {
+    const nodes = [
+        ...named("library", ir.libraries),
+        ...named("type", ir.types),
+        ...named("role", ir.roles),
+        ...named("entity", ir.entities),
+        ...named("calendar", ir.calendars),
+        ...named("derive", ir.derives),
+        ...named("evidence", ir.evidence),
+        ...named("interaction", ir.interactions),
+        ...named("layout", ir.layouts),
+        ...named("connector", ir.connectors),
+        ...named("machine", ir.machines),
+        ...named("contract", ir.componentContracts),
+        ...named("import", ir.componentImports),
+        ...named("decision", ir.decisions),
+        ...named("collect", ir.collects),
+        ...named("bundle", ir.bundles),
+        ...named("document", ir.documents),
+        ...named("notice", ir.notices),
+        ...named("vault", ir.vaults),
+        ...named("agent", ir.agents),
+        ...named("source", ir.references),
+        ...named("account", ir.accounts),
+    ];
+    for (const c of ir.components) {
+        const { requirements, actions, invariants, retention, ...shell } = c;
+        nodes.push({
+            key: `component:${c.name}`,
+            kind: "component",
+            name: c.name,
+            at: c.at,
+            value: shell,
+        });
+        for (const r of requirements)
+            nodes.push({
+                key: `requirement:${c.name}/${r.name}`,
+                kind: "requirement",
+                name: `${c.name}/${r.name}`,
+                at: r.at,
+                value: r,
+            });
+        for (const a of actions)
+            nodes.push({
+                key: `action:${c.name}/${a.name}`,
+                kind: "action",
+                name: `${c.name}/${a.name}`,
+                at: a.at,
+                value: a,
+            });
+        for (const i of invariants)
+            nodes.push({
+                key: `invariant:${c.name}/${i.name}`,
+                kind: "invariant",
+                name: `${c.name}/${i.name}`,
+                at: i.at,
+                value: i,
+            });
+        if (retention)
+            nodes.push({
+                key: `retention:${c.name}`,
+                kind: "retention",
+                name: c.name,
+                at: retention.at,
+                value: retention,
+            });
+    }
+    return new Map(nodes.map((n) => [n.key, n]));
+};
+export const exampleNodes = (ir) => new Map([...named("scenario", ir.scenarios), ...named("property", ir.properties)].map((n) => [
+    n.key,
+    n,
+]));

package/dist/render.d.ts

@@ -0,0 +1,19 @@
+import { type CliDiagnostic } from "./project.js";
+import { type Manual } from "./manual/render.js";
+export type RenderFormat = "markdown" | "html";
+export interface RenderOptions {
+    readonly format?: RenderFormat;
+    readonly account?: string;
+}
+export interface RenderReport {
+    readonly format: "worldvm/render@1";
+    readonly command: "render";
+    readonly directory: string;
+    readonly ok: boolean;
+    readonly output: RenderFormat;
+    readonly account: string | null;
+    readonly diagnostics: readonly CliDiagnostic[];
+    readonly manual: Manual | null;
+    readonly document: string | null;
+}
+export declare const renderDirectory: (directory: string, options?: RenderOptions) => Promise<RenderReport>;

package/dist/render.js

@@ -0,0 +1,43 @@
+import { loadProject } from "./project.js";
+import { buildManual, ManualAccountError, renderManualHtml, renderManualMarkdown, } from "./manual/render.js";
+export const renderDirectory = async (directory, options = {}) => {
+    const project = await loadProject(directory), output = options.format ?? "markdown", base = {
+        format: "worldvm/render@1",
+        command: "render",
+        directory: project.directory,
+        output,
+        account: options.account ?? null,
+    };
+    const errors = project.diagnostics.some((d) => d.severity === "error");
+    if (!project.ir || errors)
+        return { ...base, ok: false, diagnostics: project.diagnostics, manual: null, document: null };
+    try {
+        const manual = buildManual(project.ir, project.files, options.account === undefined ? {} : { account: options.account });
+        return {
+            ...base,
+            ok: true,
+            diagnostics: project.diagnostics,
+            manual,
+            document: output === "html" ? renderManualHtml(manual) : renderManualMarkdown(manual),
+        };
+    }
+    catch (cause) {
+        if (!(cause instanceof ManualAccountError))
+            throw cause;
+        const diagnostic = {
+            code: "E_RENDER_ACCOUNT",
+            severity: "error",
+            message: cause.message,
+            at: null,
+            help: `Pass --account with one of: ${cause.available.join(", ") || "(no accounts declared)"}.`,
+            fix: null,
+        };
+        return {
+            ...base,
+            ok: false,
+            diagnostics: [...project.diagnostics, diagnostic],
+            manual: null,
+            document: null,
+        };
+    }
+};

package/dist/serve.d.ts

@@ -0,0 +1,18 @@
+import type { World } from "./handle/world.js";
+/** Schedule the next kernel wake, rescheduling after writes; no timer is owned by the handle. */
+export declare const scheduleTicks: (world: World, onError?: (cause: unknown) => void) => (() => void);
+export interface ServeOptions {
+    readonly source?: string;
+    readonly db: string;
+    readonly port?: number;
+    readonly clock?: () => string;
+    readonly ui?: boolean;
+}
+/** Optional local demo routes; deliberately separate from the protocol handler. */
+export declare const createUiHandler: (world: Pick<World, "types">, protocol: (request: Request) => Promise<Response>) => ((request: Request) => Promise<Response>);
+/** The only socket boundary; tests exercise createHandler directly. Binds loopback by default. */
+export declare const serve: (options: ServeOptions) => Promise<{
+    world: World;
+    server: import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>;
+    close: () => Promise<void>;
+}>;

package/dist/serve.js

@@ -0,0 +1,140 @@
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { readFile } from "node:fs/promises";
+import { createHandler } from "./http.js";
+import { failure } from "./handle/protocol.js";
+import { open } from "./handle/open.js";
+import { deployDirectory } from "./deploy.js";
+import { sqlite } from "./sqlite.js";
+/** Schedule the next kernel wake, rescheduling after writes; no timer is owned by the handle. */
+export const scheduleTicks = (world, onError = console.error) => {
+    let timer;
+    let stopped = false;
+    const schedule = () => {
+        if (stopped)
+            return;
+        clearTimeout(timer);
+        const wake = world.nextWake();
+        const delay = wake
+            ? Math.max(1, Math.min(60_000, Date.parse(wake) - Date.parse(world.now())))
+            : 60_000;
+        timer = setTimeout(async () => {
+            try {
+                await world.tick();
+            }
+            catch (cause) {
+                onError(cause);
+            }
+            finally {
+                schedule();
+            }
+        }, delay);
+        timer.unref();
+    };
+    const unsubscribe = world.subscribe(schedule);
+    schedule();
+    return () => {
+        stopped = true;
+        clearTimeout(timer);
+        unsubscribe();
+    };
+};
+/** Optional local demo routes; deliberately separate from the protocol handler. */
+export const createUiHandler = (world, protocol) => {
+    let page;
+    return async (request) => {
+        const path = new URL(request.url).pathname;
+        if (path !== "/" && path !== "/ui/types")
+            return protocol(request);
+        if (request.method !== "GET" && request.method !== "HEAD")
+            return new Response("Use GET or HEAD.", { status: 405, headers: { allow: "GET, HEAD" } });
+        const response = path === "/ui/types"
+            ? Response.json(world.types)
+            : new Response(await (page ??= readFile(new URL("../static/ui.html", import.meta.url), "utf8")), {
+                headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-cache" },
+            });
+        return request.method === "HEAD"
+            ? new Response(null, { status: response.status, headers: response.headers })
+            : response;
+    };
+};
+/** The only socket boundary; tests exercise createHandler directly. Binds loopback by default. */
+export const serve = async (options) => {
+    if (options.source) {
+        const report = await deployDirectory(options.source, { db: options.db });
+        if (!report.ok)
+            throw new Error(report.diagnostics.map((d) => `${d.code} ${d.message}`).join("; "));
+    }
+    const world = await open({
+        store: sqlite(options.db),
+        ...(options.clock ? { clock: options.clock } : {}),
+    });
+    const protocol = createHandler(world);
+    const handler = options.ui ? createUiHandler(world, protocol) : protocol;
+    const stopTicks = scheduleTicks(world);
+    const server = createServer(async (incoming, outgoing) => {
+        const abort = new AbortController();
+        outgoing.on("close", () => abort.abort());
+        try {
+            const chunks = [];
+            let size = 0;
+            for await (const chunk of incoming) {
+                size += chunk.length;
+                if (size > 1_048_576) {
+                    outgoing.writeHead(413).end();
+                    return;
+                }
+                chunks.push(Buffer.from(chunk));
+            }
+            const headers = new Headers();
+            for (const [key, value] of Object.entries(incoming.headers))
+                if (value !== undefined)
+                    headers.set(key, Array.isArray(value) ? value.join(", ") : value);
+            const method = incoming.method ?? "GET";
+            const response = await handler(new Request(`http://localhost${incoming.url ?? "/"}`, {
+                method,
+                headers,
+                signal: abort.signal,
+                ...(method === "GET" || method === "HEAD" ? {} : { body: Buffer.concat(chunks) }),
+            }));
+            outgoing.writeHead(response.status, Object.fromEntries(response.headers));
+            if (response.body)
+                await pipeline(Readable.fromWeb(response.body), outgoing);
+            else
+                outgoing.end();
+        }
+        catch {
+            if (!outgoing.headersSent)
+                outgoing
+                    .writeHead(500, { "content-type": "application/json" })
+                    .end(JSON.stringify(failure("internal", "HTTP request failed.")));
+            else
+                outgoing.destroy();
+        }
+    });
+    try {
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(options.port ?? 3000, "127.0.0.1", () => {
+                server.removeListener("error", reject);
+                resolve();
+            });
+        });
+    }
+    catch (cause) {
+        stopTicks();
+        await world.close();
+        throw cause;
+    }
+    return {
+        world,
+        server,
+        close: async () => {
+            stopTicks();
+            server.closeAllConnections();
+            await new Promise((resolve, reject) => server.close((e) => (e ? reject(e) : resolve())));
+            await world.close();
+        },
+    };
+};

package/dist/snapshot.d.ts

@@ -0,0 +1,19 @@
+import type { IR, World } from "./_internal/reconciler/index.js";
+import type { CliDiagnostic } from "./project.js";
+/** An in-memory host snapshot; the CLI never reads a clock, so the instant is always explicit. */
+export interface WorldSnapshot {
+    readonly format: "worldvm/world@1";
+    /** Accounts whose programs evaluate this world, in order. */
+    readonly accounts: readonly string[];
+    /** The release the exported records were last written under, when known. */
+    readonly release?: string;
+    readonly world: World;
+}
+/** Export committed records without opening a host or evaluating them under new rules. */
+export declare const snapshotDatabase: (filename: string, account: string) => Promise<WorldSnapshot>;
+/** Reads a snapshot and checks that every world it will be evaluated under declares its accounts. */
+export declare const readSnapshot: (input: string, worlds: readonly IR.WorldIR[], code: string) => Promise<{
+    readonly snapshot: WorldSnapshot;
+} | {
+    readonly diagnostic: CliDiagnostic;
+}>;