worldvm 0.0.0-stage → 0.1.0

package/dist/manual/render.d.ts

@@ -0,0 +1,76 @@
+import type { SourceFile, Span, WorldIR } from "../_internal/forma/world/index.js";
+import { type CitationView } from "./projections.js";
+/** Located prose: every rendered claim keeps the source span it was derived from. */
+export interface ManualRow {
+    readonly label: string;
+    readonly text: string;
+    readonly fallbacks: readonly {
+        readonly text: string;
+        readonly at: Span;
+    }[];
+    readonly notes: readonly string[];
+}
+export interface ManualExample {
+    readonly name: string;
+    readonly doc: string;
+    readonly at: Span;
+    readonly firstObservation: string | null;
+    readonly assertions: readonly {
+        readonly text: string;
+        readonly at: Span;
+    }[];
+    readonly referenceOnly: boolean;
+}
+export interface ManualEntry {
+    readonly id: string;
+    readonly kind: string;
+    readonly component: string;
+    readonly componentTitle: string;
+    readonly title: string;
+    readonly at: Span;
+    readonly rows: readonly ManualRow[];
+    readonly citations: readonly CitationView[];
+    readonly examples: readonly ManualExample[];
+}
+export interface ManualAccount {
+    readonly name: string;
+    readonly doc: string;
+    readonly at: Span;
+    readonly requirements: readonly ManualEntry[];
+    readonly records: readonly ManualEntry[];
+    readonly library: readonly ManualEntry[];
+}
+export interface ManualSource {
+    readonly name: string;
+    readonly title: string;
+    readonly kind: string;
+    readonly jurisdiction: string | null;
+    readonly asOf: string;
+    readonly url: string;
+    readonly doc: string;
+    readonly at: Span;
+}
+export interface Manual {
+    readonly format: "worldvm/manual@1";
+    readonly notice: string;
+    readonly accounts: readonly ManualAccount[];
+    readonly sources: readonly ManualSource[];
+}
+export interface ManualOptions {
+    /** Restrict the manual to one account; all accounts render in declaration order otherwise. */
+    readonly account?: string;
+    /** Scenario examples shown per entry; the full list stays in source. */
+    readonly examplesPerEntry?: number;
+}
+export declare const manualNotice = "Derived from the compiled world. Sources record authored authority; executable examples illustrate behavior. This manual does not certify legal completeness; reference-world data is synthetic and its rules are illustrative, not legal advice.";
+export declare class ManualAccountError extends Error {
+    readonly account: string;
+    readonly available: readonly string[];
+    constructor(account: string, available: readonly string[]);
+}
+/** Projects a compiled world into the manual model shared by the CLI and the World IDE. */
+export declare const buildManual: (ir: WorldIR, files: readonly SourceFile[], options?: ManualOptions) => Manual;
+/** Stable HTML fragment identifier for a manual entry; synthetic ids may contain any character. */
+export declare const manualAnchor: (id: string) => string;
+export declare const renderManualMarkdown: (manual: Manual) => string;
+export declare const renderManualHtml: (manual: Manual) => string;

package/dist/manual/render.js

@@ -0,0 +1,250 @@
+import { accountComponents } from "./catalog.js";
+import { projectManual, } from "./projections.js";
+import { firstLine, humanize, safeUrl, sourceTitle } from "./text.js";
+export const manualNotice = "Derived from the compiled world. Sources record authored authority; executable examples illustrate behavior. This manual does not certify legal completeness; reference-world data is synthetic and its rules are illustrative, not legal advice.";
+const row = (label, d) => ({
+    label,
+    text: d.text,
+    fallbacks: d.fallbacks.map((f) => ({ text: f.text, at: f.at })),
+    notes: [...new Set(d.notes ?? [])],
+});
+const componentTitle = (ir, name) => {
+    const doc = ir.components.find((c) => c.name === name)?.doc;
+    return doc ? firstLine(doc) : humanize(name);
+};
+const requirementEntry = (ir, r, limit) => ({
+    id: r.id,
+    kind: "Requirement",
+    component: r.component,
+    componentTitle: componentTitle(ir, r.component),
+    title: r.title,
+    at: r.at,
+    rows: r.rows.map((x) => row(x.label, x.description)),
+    citations: r.citations,
+    examples: r.exampleDetails.slice(0, limit).map((e) => {
+        const scenario = ir.scenarios?.find((s) => s.name === e.name);
+        return {
+            name: e.name,
+            doc: e.doc,
+            at: e.at,
+            firstObservation: scenario?.steps[0]?.date ?? null,
+            assertions: e.assertions.map((a) => ({ text: a.text, at: a.at })),
+            referenceOnly: e.referenceOnly,
+        };
+    }),
+});
+const recordEntry = (ir, r) => ({
+    id: r.id,
+    kind: r.kind,
+    component: r.component,
+    componentTitle: componentTitle(ir, r.component),
+    title: r.title,
+    at: r.at,
+    rows: r.rows.map((x) => row(x.label, x.description)),
+    citations: r.citations,
+    examples: [],
+});
+export class ManualAccountError extends Error {
+    account;
+    available;
+    constructor(account, available) {
+        super(`Unknown account ${account}; declared accounts: ${available.join(", ") || "none"}.`);
+        this.account = account;
+        this.available = available;
+    }
+}
+/** Projects a compiled world into the manual model shared by the CLI and the World IDE. */
+export const buildManual = (ir, files, options = {}) => {
+    const limit = options.examplesPerEntry ?? 2;
+    const names = ir.accounts.map((a) => a.name);
+    if (options.account !== undefined && !names.includes(options.account))
+        throw new ManualAccountError(options.account, names);
+    const accounts = ir.accounts
+        .filter((a) => options.account === undefined || a.name === options.account)
+        .map((account) => {
+        const data = projectManual(ir, files, account.name), used = accountComponents(ir, account.name);
+        return {
+            name: account.name,
+            doc: account.doc ?? "Declared account obligations.",
+            at: account.at,
+            requirements: data.used.map((r) => requirementEntry(ir, r, limit)),
+            records: data.people.filter((r) => used.has(r.component)).map((r) => recordEntry(ir, r)),
+            library: data.examples.map((r) => requirementEntry(ir, r, limit)),
+        };
+    });
+    return {
+        format: "worldvm/manual@1",
+        notice: manualNotice,
+        accounts,
+        sources: (ir.references ?? []).map((s) => ({
+            name: s.name,
+            title: sourceTitle(s),
+            kind: s.kind,
+            jurisdiction: s.jurisdiction ?? null,
+            asOf: s.asOf,
+            url: s.url,
+            doc: s.doc ?? "",
+            at: s.at,
+        })),
+    };
+};
+/** Stable HTML fragment identifier for a manual entry; synthetic ids may contain any character. */
+export const manualAnchor = (id) => id.replace(/[^A-Za-z0-9/_-]+/g, "-").replace(/^-+|-+$/g, "") || "entry";
+const where = (at) => `${at.src}:${at.line}:${at.col}`;
+const heading = (account) => `${humanize(account).replace(/^./, (c) => c.toUpperCase())} manual`;
+// Markdown ------------------------------------------------------------------
+/** Escapes characters that would otherwise start Markdown or HTML syntax inside prose. */
+const md = (text) => text.replace(/[\\`*_[\]<>|#]/g, (c) => `\\${c}`).replace(/\n+/g, " ");
+const code = (text) => {
+    const flat = text.replace(/\n+/g, " ");
+    const fence = flat.includes("`") ? "``" : "`";
+    return `${fence}${fence.length > 1 ? " " : ""}${flat}${fence.length > 1 ? " " : ""}${fence}`;
+};
+const citationMd = (c) => {
+    const title = c.url ? `[${md(c.title)}](${c.url})` : `**${md(c.title)}**`;
+    return `- ${title} ${md(c.clause)} (${md(c.kind)}, as of ${md(c.asOf)})${c.caveat ? ` — ${md(firstLine(c.caveat))}` : ""} · ${code(where(c.at))}`;
+};
+const entryMd = (e, level) => {
+    const h = "#".repeat(level);
+    const lines = [
+        `${h} ${md(e.title)}`,
+        "",
+        `${md(e.kind)} · ${md(e.componentTitle)} · ${code(e.id)} · ${code(where(e.at))}`,
+        "",
+    ];
+    for (const r of e.rows) {
+        lines.push(`- **${md(r.label)}:** ${md(r.text)}`);
+        for (const note of r.notes)
+            lines.push(`  - Note: ${md(note)}`);
+        for (const f of r.fallbacks)
+            lines.push(`  - Source expression ${code(f.text)} at ${code(where(f.at))}`);
+    }
+    if (e.citations.length)
+        lines.push("", "Cited sources:", "", ...e.citations.map(citationMd));
+    for (const x of e.examples) {
+        lines.push("", `Example: ${md(x.doc)} (scenario ${code(x.name)} · ${code(where(x.at))}; first observation ${x.firstObservation ?? "not declared"})`);
+        if (x.referenceOnly)
+            lines.push("", "- Reachability reference only; no direct status or due assertion.");
+        else
+            lines.push("", ...x.assertions.map((a) => `- ${code(a.text)}`));
+    }
+    lines.push("");
+    return lines;
+};
+export const renderManualMarkdown = (manual) => {
+    const lines = [];
+    for (const account of manual.accounts) {
+        lines.push(`# ${md(heading(account.name))}`, "", `> ${md(manual.notice)}`, "");
+        lines.push(md(account.doc), "", `Account ${code(account.name)} · ${code(where(account.at))}`, "");
+        lines.push("## Requirements composed by this account", "");
+        if (!account.requirements.length)
+            lines.push("No requirements are reachable from this account.", "");
+        for (const e of account.requirements)
+            lines.push(...entryMd(e, 3));
+        lines.push("## Actions, decisions and records", "");
+        if (!account.records.length)
+            lines.push("No actions, decisions or records are declared.", "");
+        for (const e of account.records)
+            lines.push(...entryMd(e, 3));
+        if (account.library.length) {
+            lines.push(`## Library requirements not used by this account (${account.library.length})`, "");
+            for (const e of account.library)
+                lines.push(...entryMd(e, 3));
+        }
+    }
+    lines.push("# Sources", "");
+    if (!manual.sources.length)
+        lines.push("No sources are declared.", "");
+    for (const s of manual.sources) {
+        lines.push(`## ${md(s.title)}`, "", `${md(s.kind)} · ${md(s.jurisdiction ?? "jurisdiction not declared")} · as of ${md(s.asOf)} · ${code(s.name)} · ${code(where(s.at))}`, "");
+        if (s.doc)
+            lines.push(md(s.doc), "");
+        lines.push(safeUrl(s.url) ? `<${s.url}>` : code(s.url), "");
+    }
+    return `${lines.join("\n").trimEnd()}\n`;
+};
+// HTML ----------------------------------------------------------------------
+const esc = (text) => text.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+const src = (at) => `<code class="src">${esc(where(at))}</code>`;
+const citationHtml = (c) => {
+    const url = c.url ? safeUrl(c.url) : null;
+    const title = url
+        ? `<a href="${esc(url)}" rel="noopener noreferrer">${esc(c.title)}</a>`
+        : `<strong>${esc(c.title)}</strong>`;
+    return `<li>${title} ${esc(c.clause)} <span class="meta">${esc(c.kind)} · as of ${esc(c.asOf)}</span>${c.caveat ? ` <span class="caveat">${esc(firstLine(c.caveat))}</span>` : ""} ${src(c.at)}</li>`;
+};
+const entryHtml = (e, level) => {
+    const parts = [
+        `<article class="entry" id="${esc(manualAnchor(e.id))}">`,
+        `<p class="eyebrow">${esc(e.kind)} · ${esc(e.componentTitle)}</p>`,
+        `<h${level}>${esc(e.title)}</h${level}>`,
+        `<p class="meta"><code>${esc(e.id)}</code> ${src(e.at)}</p>`,
+        "<dl>",
+    ];
+    for (const r of e.rows) {
+        parts.push(`<dt>${esc(r.label)}</dt><dd><p>${esc(r.text)}</p>`);
+        for (const note of r.notes)
+            parts.push(`<p class="note">${esc(note)}</p>`);
+        for (const f of r.fallbacks)
+            parts.push(`<p class="fallback">Source expression <code>${esc(f.text)}</code> ${src(f.at)}</p>`);
+        parts.push("</dd>");
+    }
+    parts.push("</dl>");
+    if (e.citations.length)
+        parts.push(`<h${level + 1}>Cited sources</h${level + 1}><ul class="citations">`, ...e.citations.map(citationHtml), "</ul>");
+    for (const x of e.examples) {
+        parts.push(`<section class="example"><p><strong>Example: ${esc(x.doc)}</strong> <code>${esc(x.name)}</code> ${src(x.at)} · first observation ${esc(x.firstObservation ?? "not declared")}</p>`);
+        if (x.referenceOnly)
+            parts.push(`<p class="note">Reachability reference only; no direct status or due assertion.</p>`);
+        else
+            parts.push("<ul>", ...x.assertions.map((a) => `<li><code>${esc(a.text)}</code></li>`), "</ul>");
+        parts.push("</section>");
+    }
+    parts.push("</article>");
+    return parts.join("\n");
+};
+const style = `body{font:16px/1.5 system-ui,sans-serif;max-width:52rem;margin:2rem auto;padding:0 1rem;color:#1b1f24;background:#fff}
+.notice{border-left:4px solid #b26b00;padding:.5rem 1rem;background:#fff7e6}
+.entry{border-top:1px solid #d0d7de;padding:1rem 0}.eyebrow,.meta,.note{color:#57606a;font-size:.875rem}
+dt{font-weight:600}dd{margin:0 0 .5rem 1rem}dd p{margin:.125rem 0}code{font-size:.875em}
+.fallback code{white-space:pre-wrap}.caveat{font-style:italic}.example{background:#f6f8fa;padding:.5rem 1rem;margin:.5rem 0}
+@media print{body{margin:0;max-width:none}.entry{break-inside:avoid}}`;
+export const renderManualHtml = (manual) => {
+    const title = manual.accounts.length === 1 ? heading(manual.accounts[0].name) : "World manual";
+    const parts = [
+        "<!doctype html>",
+        '<html lang="en">',
+        "<head>",
+        '<meta charset="utf-8">',
+        '<meta name="viewport" content="width=device-width, initial-scale=1">',
+        `<title>${esc(title)}</title>`,
+        `<style>${style}</style>`,
+        "</head>",
+        "<body>",
+        `<p class="notice">${esc(manual.notice)}</p>`,
+    ];
+    for (const account of manual.accounts) {
+        parts.push(`<section class="account" id="account-${esc(account.name)}">`, `<h1>${esc(heading(account.name))}</h1>`, `<p>${esc(account.doc)}</p>`, `<p class="meta">Account <code>${esc(account.name)}</code> ${src(account.at)}</p>`, "<h2>Requirements composed by this account</h2>");
+        if (!account.requirements.length)
+            parts.push("<p>No requirements are reachable from this account.</p>");
+        parts.push(...account.requirements.map((e) => entryHtml(e, 3)));
+        parts.push("<h2>Actions, decisions and records</h2>");
+        if (!account.records.length)
+            parts.push("<p>No actions, decisions or records are declared.</p>");
+        parts.push(...account.records.map((e) => entryHtml(e, 3)));
+        if (account.library.length)
+            parts.push(`<h2>Library requirements not used by this account (${account.library.length})</h2>`, ...account.library.map((e) => entryHtml(e, 3)));
+        parts.push("</section>");
+    }
+    parts.push('<section class="sources"><h1>Sources</h1>');
+    if (!manual.sources.length)
+        parts.push("<p>No sources are declared.</p>");
+    for (const s of manual.sources) {
+        const url = safeUrl(s.url);
+        parts.push(`<article class="entry" id="source-${esc(s.name)}"><h2>${esc(s.title)}</h2>`, `<p class="meta">${esc(s.kind)} · ${esc(s.jurisdiction ?? "jurisdiction not declared")} · as of ${esc(s.asOf)} · <code>${esc(s.name)}</code> ${src(s.at)}</p>`, s.doc ? `<p>${esc(s.doc)}</p>` : "", url
+            ? `<p><a href="${esc(url)}" rel="noopener noreferrer">${esc(url)}</a></p>`
+            : `<p><code>${esc(s.url)}</code></p>`, "</article>");
+    }
+    parts.push("</section>", "</body>", "</html>");
+    return `${parts.filter(Boolean).join("\n")}\n`;
+};

package/dist/manual/text.d.ts

@@ -0,0 +1,7 @@
+export declare const firstLine: (doc: string) => string;
+export declare const humanize: (name: string) => string;
+export declare const sourceTitle: (source: {
+    readonly name: string;
+    readonly url: string;
+}) => string;
+export declare const safeUrl: (url: string) => string | null;

package/dist/manual/text.js

@@ -0,0 +1,15 @@
+export const firstLine = (doc) => doc.split(/\r?\n/)[0] ?? doc;
+export const humanize = (name) => name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[-_]/g, " ");
+export const sourceTitle = (source) => {
+    try {
+        const url = new URL(source.url);
+        const match = /\/title-(\d+)\/section-([^/]+)/.exec(url.pathname);
+        if (/^(?:www\.)?ecfr\.gov$/.test(url.hostname) && match)
+            return `${match[1]} CFR ${match[2]}`;
+    }
+    catch {
+        /* Authored non-URLs retain their source identifier as the label. */
+    }
+    return humanize(source.name).replace(/^./, (letter) => letter.toUpperCase());
+};
+export const safeUrl = (url) => (/^https?:\/\//i.test(url) ? url : null);

package/dist/mcp.d.ts

@@ -0,0 +1,32 @@
+import type { Actor, World } from "./handle/world.js";
+/**
+ * Model Context Protocol over newline-delimited JSON-RPC 2.0. Authoring tools return
+ * the CLI reports; optional operate mode shares the library/HTTP dispatcher and actor.
+ */
+export declare const serverInfo: {
+    readonly name: "worldvm";
+    readonly version: "0.0.0";
+};
+export declare const protocolVersions: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
+type Json = null | boolean | number | string | readonly Json[] | {
+    readonly [k: string]: Json;
+};
+interface Tool {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Json;
+    readonly run: (args: Record<string, unknown>) => Promise<{
+        readonly ok: boolean;
+    }>;
+    readonly mutating?: boolean;
+}
+export declare const tools: readonly Tool[];
+/** Handles one JSON-RPC message; returns the response, or null for notifications. */
+export interface OperateOptions {
+    readonly world: World;
+    readonly actor: Actor;
+}
+export declare const handleMessage: (message: unknown, operating?: OperateOptions) => Promise<unknown>;
+/** Serves MCP over stdin/stdout until stdin closes. Logs never go to stdout. */
+export declare const serveStdio: (input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream, operating?: OperateOptions) => Promise<void>;
+export {};

package/dist/mcp.js

@@ -0,0 +1,269 @@
+import { formatForma } from "./_internal/forma-tools/index.js";
+import { createInterface } from "node:readline";
+import { checkDirectory } from "./index.js";
+import { testDirectory } from "./test.js";
+import { coverageDirectory } from "./coverage.js";
+import { renderDirectory } from "./render.js";
+import { explainDirectory } from "./explain.js";
+import { diffDirectories } from "./diff.js";
+import { impactDirectories } from "./impact.js";
+import { mutations, requestJsonSchema, verbs } from "./_internal/protocol/index.js";
+/**
+ * Model Context Protocol over newline-delimited JSON-RPC 2.0. Authoring tools return
+ * the CLI reports; optional operate mode shares the library/HTTP dispatcher and actor.
+ */
+export const serverInfo = { name: "worldvm", version: "0.0.0" };
+export const protocolVersions = ["2025-06-18", "2025-03-26", "2024-11-05"];
+const directory = {
+    type: "string",
+    description: "World source directory (contains .forma files).",
+};
+const seed = { type: "integer", minimum: 0, description: "Property seed (default 0)." };
+const cases = { type: "integer", minimum: 1, description: "Property cases (default 100)." };
+const instant = { type: "string", description: "Instant as YYYY-MM-DD or YYYY-MM-DDTHH:MM." };
+const object = (properties, required) => ({
+    type: "object",
+    properties,
+    required,
+    additionalProperties: false,
+});
+const str = (args, key) => {
+    const v = args[key];
+    if (typeof v !== "string" || !v)
+        throw new ToolInputError(`${key} must be a non-empty string.`);
+    return v;
+};
+const opt = (args, key, kind) => {
+    const v = args[key];
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== kind || (kind === "number" && !Number.isInteger(v)))
+        throw new ToolInputError(`${key} must be ${kind === "number" ? "an integer" : "a string"}.`);
+    return v;
+};
+class ToolInputError extends Error {
+}
+const pick = (value) => Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+export const tools = [
+    {
+        name: "check",
+        description: "Compile and link a world. Returns located diagnostics with help and machine-applicable fixes.",
+        inputSchema: object({
+            directory,
+            core: {
+                type: "boolean",
+                description: "Also report I_EXTENDED_FORM at declarations outside the core forms.",
+            },
+        }, ["directory"]),
+        run: (a) => checkDirectory(str(a, "directory"), { core: a["core"] === true }),
+    },
+    {
+        name: "test",
+        description: "Run authored scenarios and seeded properties; failures carry spans and counterexamples.",
+        inputSchema: object({
+            directory,
+            scenario: { type: "string", description: "Run only this scenario." },
+            seed,
+            cases,
+        }, ["directory"]),
+        run: (a) => testDirectory(str(a, "directory"), pick({
+            scenario: opt(a, "scenario", "string"),
+            seed: opt(a, "seed", "number"),
+            cases: opt(a, "cases", "number"),
+        })),
+    },
+    {
+        name: "coverage",
+        description: "Map cited sources to requirements and scenarios, with observed applicability, statuses and due branches.",
+        inputSchema: object({ directory, seed, cases }, ["directory"]),
+        run: (a) => coverageDirectory(str(a, "directory"), pick({ seed: opt(a, "seed", "number"), cases: opt(a, "cases", "number") })),
+    },
+    {
+        name: "render",
+        description: "Render the manual a person reviews: every obligation in prose with citations and scenario examples.",
+        inputSchema: object({
+            directory,
+            format: { type: "string", enum: ["markdown", "html"] },
+            account: { type: "string", description: "Render only this account." },
+        }, ["directory"]),
+        run: (a) => {
+            const format = opt(a, "format", "string");
+            if (format !== undefined && format !== "markdown" && format !== "html")
+                throw new ToolInputError("format must be markdown or html.");
+            return renderDirectory(str(a, "directory"), pick({
+                format: format,
+                account: opt(a, "account", "string"),
+            }));
+        },
+    },
+    {
+        name: "explain",
+        description: "Explain why each status, due date and work item is what it is: at a scenario step, or for a subject in a recorded world snapshot.",
+        inputSchema: object({
+            directory,
+            scenario: { type: "string" },
+            world: { type: "string", description: "Path to a worldvm/world@1 snapshot." },
+            subject: { type: "string" },
+            at: instant,
+        }, ["directory"]),
+        run: (a) => explainDirectory(str(a, "directory"), pick({
+            scenario: opt(a, "scenario", "string"),
+            world: opt(a, "world", "string"),
+            subject: opt(a, "subject", "string"),
+            at: opt(a, "at", "string"),
+        })),
+    },
+    {
+        name: "diff",
+        description: "Semantic diff of two releases: added, removed and changed declarations with spans, aspects and breaking contracts.",
+        inputSchema: object({
+            old: { ...directory, description: "Previous release source directory." },
+            new: { ...directory, description: "Candidate release source directory." },
+        }, ["old", "new"]),
+        run: (a) => diffDirectories(str(a, "old"), str(a, "new")),
+    },
+    {
+        name: "impact",
+        description: "Preview a release over a recorded population: occurrences and work gained, lost or changed, selected by dependency digests.",
+        inputSchema: object({
+            old: { ...directory, description: "Previous release source directory." },
+            new: { ...directory, description: "Candidate release source directory." },
+            world: { type: "string", description: "Path to a worldvm/world@1 snapshot." },
+            at: instant,
+        }, ["old", "new", "world", "at"]),
+        run: (a) => impactDirectories(str(a, "old"), str(a, "new"), { world: str(a, "world"), at: str(a, "at") }),
+    },
+    {
+        name: "format",
+        description: "Format Forma source text without writing files. Preserves comments; uses a 100-column style.",
+        inputSchema: object({ text: { type: "string", description: "Forma source text." } }, ["text"]),
+        run: async (a) => {
+            if (typeof a.text !== "string")
+                throw new ToolInputError("text must be a string.");
+            try {
+                return { format: "worldvm/format@1", ok: true, text: formatForma(a.text) };
+            }
+            catch (cause) {
+                return { format: "worldvm/format@1", ok: false, message: String(cause) };
+            }
+        },
+    },
+];
+const error = (id, code, message) => ({
+    jsonrpc: "2.0",
+    id: id ?? null,
+    error: { code, message },
+});
+const operatingTools = ({ world, actor }) => verbs.map((verb) => ({
+    name: verb,
+    description: `Operate the running world: ${verb}. Actor is fixed by the server.`,
+    inputSchema: requestJsonSchema(verb),
+    mutating: mutations.includes(verb),
+    run: (args) => world.request(verb, args, actor),
+}));
+export const handleMessage = async (message, operating) => {
+    const available = operating
+        ? [
+            ...tools.map((t) => (t.name === "explain" ? { ...t, name: "authoring-explain" } : t)),
+            ...operatingTools(operating),
+        ]
+        : tools;
+    const request = message;
+    if (!request ||
+        typeof request !== "object" ||
+        request.jsonrpc !== "2.0" ||
+        typeof request.method !== "string")
+        return error(null, -32600, "Invalid JSON-RPC request.");
+    const notification = !("id" in request);
+    const respond = (result) => notification ? null : { jsonrpc: "2.0", id: request.id, result };
+    switch (request.method) {
+        case "initialize": {
+            const asked = request.params?.protocolVersion;
+            return respond({
+                protocolVersion: typeof asked === "string" && protocolVersions.includes(asked)
+                    ? asked
+                    : protocolVersions[0],
+                capabilities: { tools: { listChanged: false } },
+                serverInfo,
+                instructions: operating
+                    ? "WorldVM operating protocol plus authoring tools. Identity is fixed by the server; agents propose and humans accept. authoring-explain explains source scenarios; explain explains live subjects."
+                    : "Read-only WorldVM authoring tools. Paths are resolved against the server's working directory. Each result is the command's versioned JSON report; ok=false reports carry located diagnostics with help.",
+            });
+        }
+        case "ping":
+            return respond({});
+        case "tools/list":
+            return respond({
+                tools: available
+                    .filter((t) => !(operating &&
+                    typeof operating.actor !== "string" &&
+                    operating.actor.kind === "agent" &&
+                    t.mutating &&
+                    t.name !== "propose"))
+                    .map((t) => ({
+                    name: t.name,
+                    description: t.description,
+                    inputSchema: t.inputSchema,
+                    annotations: {
+                        readOnlyHint: !t.mutating,
+                        destructiveHint: !!t.mutating,
+                        openWorldHint: false,
+                    },
+                })),
+            });
+        case "tools/call": {
+            const name = request.params?.name, args = request.params?.arguments ?? {};
+            const tool = available.find((t) => t.name === name);
+            if (!tool)
+                return notification ? null : error(request.id, -32602, `Unknown tool ${String(name)}.`);
+            if (!args || typeof args !== "object" || Array.isArray(args))
+                return notification ? null : error(request.id, -32602, "arguments must be an object.");
+            try {
+                const report = await tool.run(args);
+                return respond({
+                    content: [{ type: "text", text: JSON.stringify(report) }],
+                    structuredContent: report,
+                    isError: !report.ok,
+                });
+            }
+            catch (cause) {
+                if (cause instanceof ToolInputError)
+                    return respond({ content: [{ type: "text", text: cause.message }], isError: true });
+                throw cause;
+            }
+        }
+        default:
+            if (notification)
+                return null; // e.g. notifications/initialized, notifications/cancelled
+            return error(request.id, -32601, `Method ${request.method} is not supported.`);
+    }
+};
+/** Serves MCP over stdin/stdout until stdin closes. Logs never go to stdout. */
+export const serveStdio = async (input = process.stdin, output = process.stdout, operating) => {
+    const lines = createInterface({ input, crlfDelay: Infinity });
+    let queue = Promise.resolve();
+    for await (const line of lines) {
+        if (!line.trim())
+            continue;
+        // Responses keep request order; tools are CPU-bound and run one at a time.
+        queue = queue.then(async () => {
+            let message, response;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                output.write(`${JSON.stringify(error(null, -32700, "Parse error."))}\n`);
+                return;
+            }
+            try {
+                response = await handleMessage(message, operating);
+            }
+            catch (cause) {
+                response = error(message?.id ?? null, -32603, String(cause));
+            }
+            if (response !== null)
+                output.write(`${JSON.stringify(response)}\n`);
+        });
+    }
+    await queue;
+};