worldvm 0.0.0-stage → 0.1.0

package/dist/mutate.d.ts

@@ -0,0 +1,36 @@
+import type { Span } from "./_internal/forma/world/index.js";
+import { type Project } from "./project.js";
+import { type TestOptions } from "./test.js";
+/** One semantic edit to the source, and what the tests made of it. */
+export interface Mutant {
+    readonly id: number;
+    readonly operator: "valid->attested" | "attested->valid" | "drop-conjunct" | "drop-disjunct" | "flip-equality" | "remove-applies-when";
+    readonly requirement: string;
+    readonly description: string;
+    readonly at: Span;
+    /** killed: some scenario/property failed. survived: every test still passed (a gap). */
+    readonly outcome: "killed" | "survived" | "invalid";
+    readonly killedBy?: readonly string[];
+}
+export interface MutationReport {
+    readonly mutants: readonly Mutant[];
+    readonly killed: number;
+    readonly survived: number;
+    readonly invalid: number;
+}
+interface Edit {
+    readonly src: string;
+    readonly from: number;
+    readonly to: number;
+    readonly text: string;
+}
+/** Candidate mutants for every requirement's :applies-when and :satisfied-by. */
+export declare const mutants: (project: Project) => (Omit<Mutant, "id" | "outcome" | "killedBy"> & {
+    edit: Edit;
+})[];
+/**
+ * Apply each mutant alone, recompile and rerun every scenario and property. A mutant that
+ * compiles and still passes every test is a behavioural gap the tests do not pin down.
+ */
+export declare const mutationTest: (project: Project, options?: Pick<TestOptions, "seed" | "cases">) => MutationReport;
+export {};

package/dist/mutate.js

@@ -0,0 +1,123 @@
+import { compileProject } from "./project.js";
+import { runTests } from "./test.js";
+const calls = (e, f) => {
+    if (!e || typeof e !== "object")
+        return;
+    if (Array.isArray(e))
+        return e.forEach((x) => calls(x, f));
+    const node = e;
+    if (node.k === "call")
+        f(node);
+    for (const [key, child] of Object.entries(node))
+        if (key !== "at")
+            calls(child, f);
+};
+/** The head token of the list at `at`, located in the source text. */
+const head = (text, at) => {
+    const m = /^\(\s*([^\s()[\]{}]+)/.exec(text.slice(at.from, at.to));
+    return m ? { name: m[1], from: at.from + m[0].length - m[1].length } : undefined;
+};
+/** Remove one element of a vector, with the whitespace that separated it. */
+const removeItem = (text, items, index) => {
+    const item = items[index].at;
+    if (index < items.length - 1)
+        return { from: item.from, to: items[index + 1].at.from, text: "" };
+    return { from: items[index - 1].at.to, to: item.to, text: "" };
+};
+/** Candidate mutants for every requirement's :applies-when and :satisfied-by. */
+export const mutants = (project) => {
+    const ir = project.ir;
+    const out = [];
+    const evidenceByName = new Map((ir.evidence ?? []).map((e) => [e.name, e]));
+    const source = (src) => project.files.find((f) => f.id === src)?.text ?? "";
+    for (const c of ir.components)
+        for (const r of c.requirements) {
+            const requirement = `${c.name}/${r.name}`;
+            for (const [slot, expr] of [
+                ["applies-when", r.appliesWhen],
+                ["satisfied-by", r.satisfiedBy],
+            ]) {
+                if (!expr)
+                    continue;
+                calls(expr, (call) => {
+                    const text = source(call.at.src), h = head(text, call.at);
+                    if (!h)
+                        return;
+                    const swap = (operator, to) => out.push({
+                        operator,
+                        requirement,
+                        description: `${slot}: ${h.name} -> ${to} in ${text.slice(call.at.from, call.at.to)}`,
+                        at: call.at,
+                        edit: { src: call.at.src, from: h.from, to: h.from + h.name.length, text: to },
+                    });
+                    // Without :expires, valid and attested agree: that mutant would be equivalent.
+                    const arg = call.args[0];
+                    const expiring = arg?.k === "ref" && arg.kind === "evidence" && !!evidenceByName.get(arg.name)?.expires;
+                    if (h.name === "valid" && expiring)
+                        swap("valid->attested", "attested");
+                    if (h.name === "attested" && expiring)
+                        swap("attested->valid", "valid");
+                    if (h.name === "=")
+                        swap("flip-equality", "!=");
+                    if (h.name === "not=" || h.name === "!=")
+                        swap("flip-equality", "=");
+                    const list = call.args[0];
+                    if ((h.name === "and" || h.name === "or") && list?.k === "list" && list.items.length > 1)
+                        list.items.forEach((item, index) => {
+                            const edit = removeItem(text, list.items, index);
+                            out.push({
+                                operator: h.name === "and" ? "drop-conjunct" : "drop-disjunct",
+                                requirement,
+                                description: `${slot}: drop ${text.slice(item.at.from, item.at.to)} from ${h.name}`,
+                                at: item.at,
+                                edit: { src: call.at.src, ...edit },
+                            });
+                        });
+                });
+            }
+            if (r.appliesWhen) {
+                const at = r.appliesWhen.at, text = source(at.src);
+                const keyword = text.lastIndexOf(":applies-when", at.from);
+                if (keyword >= r.at.from && /^\s*$/.test(text.slice(keyword + 13, at.from)))
+                    out.push({
+                        operator: "remove-applies-when",
+                        requirement,
+                        description: `remove :applies-when ${text.slice(at.from, at.to)}`,
+                        at,
+                        edit: { src: at.src, from: keyword, to: at.to, text: "" },
+                    });
+            }
+        }
+    return out;
+};
+/**
+ * Apply each mutant alone, recompile and rerun every scenario and property. A mutant that
+ * compiles and still passes every test is a behavioural gap the tests do not pin down.
+ */
+export const mutationTest = (project, options = {}) => {
+    const results = [];
+    mutants(project).forEach(({ edit, ...m }, index) => {
+        const files = project.files.map((f) => f.id === edit.src
+            ? { id: f.id, text: f.text.slice(0, edit.from) + edit.text + f.text.slice(edit.to) }
+            : f);
+        const mutated = compileProject(project.directory, files);
+        const base = { id: index + 1, ...m };
+        if (!mutated.ir || mutated.diagnostics.some((d) => d.severity === "error")) {
+            results.push({ ...base, outcome: "invalid" });
+            return;
+        }
+        const tests = runTests(mutated, options);
+        const killedBy = [
+            ...tests.scenarios.filter((s) => !s.passed).map((s) => `scenario ${s.name}`),
+            ...tests.properties.filter((p) => !p.passed).map((p) => `property ${p.name}`),
+            ...(tests.diagnostics.some((d) => d.severity === "error") ? ["test runtime error"] : []),
+        ];
+        results.push(killedBy.length ? { ...base, outcome: "killed", killedBy } : { ...base, outcome: "survived" });
+    });
+    return {
+        mutants: results,
+        killed: results.filter((m) => m.outcome === "killed").length,
+        survived: results.filter((m) => m.outcome === "survived").length,
+        invalid: results.filter((m) => m.outcome === "invalid").length,
+    };
+};

package/dist/project.d.ts

@@ -0,0 +1,26 @@
+import { type SourceFile, type Span } from "./_internal/forma/world/index.js";
+import { type IR } from "./_internal/reconciler/index.js";
+export interface Fix {
+    readonly src: string;
+    readonly from: number;
+    readonly to: number;
+    readonly text: string;
+    readonly expected: string;
+}
+export interface CliDiagnostic {
+    readonly code: string;
+    readonly severity: "error" | "warning" | "info";
+    readonly message: string;
+    readonly at: Span | null;
+    readonly help: string;
+    readonly fix: Fix | null;
+}
+export interface Project {
+    readonly directory: string;
+    readonly files: readonly SourceFile[];
+    readonly ir: IR.WorldIR | null;
+    readonly diagnostics: readonly CliDiagnostic[];
+}
+export declare const loadProject: (input: string) => Promise<Project>;
+/** Compile in-memory sources as a project rooted at `directory` (used by mutation runs). */
+export declare const compileProject: (directory: string, files: readonly SourceFile[]) => Project;

package/dist/project.js

@@ -0,0 +1,80 @@
+import { readdir, readFile } from "node:fs/promises";
+import { resolve, relative, sep } from "node:path";
+import { compileWorld } from "./_internal/forma/world/index.js";
+import { decodeCompiled, link } from "./_internal/reconciler/index.js";
+import { authoringDiagnostics } from "./diagnostics.js";
+const ignored = new Set(["node_modules", "dist", "build", "coverage"]);
+const discover = async (directory) => {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const lists = await Promise.all(entries
+        .filter((e) => !e.name.startsWith(".") && !ignored.has(e.name))
+        .map(async (e) => {
+        const path = resolve(directory, e.name);
+        return e.isDirectory()
+            ? discover(path)
+            : e.isFile() && e.name.endsWith(".forma")
+                ? [path]
+                : [];
+    }));
+    return lists.flat().sort();
+};
+const error = (code, message, help, at = null) => ({ code, message, help, at, severity: "error", fix: null });
+export const loadProject = async (input) => {
+    const directory = resolve(input);
+    let files;
+    try {
+        const paths = await discover(directory);
+        files = await Promise.all(paths.map(async (path) => ({
+            id: relative(directory, path).split(sep).join("/"),
+            text: await readFile(path, "utf8"),
+        })));
+    }
+    catch (cause) {
+        return {
+            directory,
+            files: [],
+            ir: null,
+            diagnostics: [
+                error("E_PROJECT_IO", String(cause), "Pass a readable directory containing .forma source files."),
+            ],
+        };
+    }
+    if (!files.length)
+        return {
+            directory,
+            files,
+            ir: null,
+            diagnostics: [
+                error("E_NO_SOURCES", "No .forma source files found.", "Point at the directory containing the world's library, account and examples."),
+            ],
+        };
+    return compileProject(directory, files);
+};
+/** Compile in-memory sources as a project rooted at `directory` (used by mutation runs). */
+export const compileProject = (directory, files) => {
+    try {
+        const compiled = compileWorld(files);
+        const ir = compiled.ok ? decodeCompiled(compiled).ir : null;
+        const diagnostics = authoringDiagnostics(compiled, files, ir);
+        if (ir)
+            for (const account of ir.accounts) {
+                try {
+                    link(ir, account.name);
+                }
+                catch (cause) {
+                    diagnostics.push(error("E_LINK", String(cause), "Bind the roles and library release required by this account, then rerun check.", account.at));
+                }
+            }
+        return { directory, files, ir, diagnostics };
+    }
+    catch (cause) {
+        return {
+            directory,
+            files,
+            ir: null,
+            diagnostics: [
+                error("E_CHECK_THROW", String(cause), "Reduce this compiler failure to the smallest source example and report it."),
+            ],
+        };
+    }
+};

package/dist/refine.d.ts

@@ -0,0 +1,18 @@
+import { type Span, type WorldIR } from "./_internal/forma/world/index.js";
+import type { Fix } from "./project.js";
+export interface SourceText {
+    readonly id: string;
+    readonly text: string;
+}
+export interface Refinement {
+    readonly help?: string;
+    readonly fix?: Fix;
+}
+interface Input {
+    readonly code: string;
+    readonly message: string;
+    readonly at: Span | null;
+}
+/** Contextual help and mechanical fixes for diagnostics whose compiler help is generic. */
+export declare const refine: (d: Input, files: readonly SourceText[], ir: WorldIR | null) => Refinement | undefined;
+export {};

package/dist/refine.js

@@ -0,0 +1,197 @@
+import { KERNEL_FUNCTIONS, OLD_OPERATORS } from "./_internal/forma/world/index.js";
+import { closest } from "./catalogue.js";
+const textAt = (files, at) => at ? files.find((f) => f.id === at.src)?.text.slice(at.from, at.to) : undefined;
+/** Replace `expected` at an absolute offset in `src`. */
+const edit = (src, from, expected, text) => ({
+    src,
+    from,
+    to: from + expected.length,
+    text,
+    expected,
+});
+/** The head symbol of a list span and its absolute offset. */
+const headOf = (text, at) => {
+    if (!text || !at)
+        return undefined;
+    const m = /^\(\s*([^\s()[\]{}]+)/.exec(text);
+    return m ? { name: m[1], from: at.from + m[0].length - m[1].length } : undefined;
+};
+/** Index just past the list that opens at `open` (text[open] === "("). */
+const closeOf = (text, open) => {
+    let depth = 0, inString = false;
+    for (let i = open; i < text.length; i++) {
+        const c = text[i];
+        if (inString) {
+            if (c === "\\")
+                i++;
+            else if (c === '"')
+                inString = false;
+        }
+        else if (c === '"')
+            inString = true;
+        else if (c === ";")
+            while (i < text.length && text[i] !== "\n")
+                i++;
+        else if (c === "(" || c === "[" || c === "{")
+            depth++;
+        else if (c === ")" || c === "]" || c === "}") {
+            depth--;
+            if (depth === 0)
+                return i + 1;
+        }
+    }
+    return undefined;
+};
+/** The list whose head is the symbol at `at`, when a diagnostic points at an operator. */
+const enclosing = (files, at) => {
+    const file = at && files.find((f) => f.id === at.src);
+    if (!file || !at)
+        return undefined;
+    let open = at.from - 1;
+    while (open >= 0 && /\s/.test(file.text[open]))
+        open--;
+    if (file.text[open] !== "(")
+        return undefined;
+    const close = closeOf(file.text, open);
+    return close === undefined ? undefined : { ...at, from: open, to: close };
+};
+/** Names declared at top level, for did-you-mean on references. */
+const declaredNames = (files) => {
+    const names = new Set();
+    for (const f of files)
+        for (const m of f.text.matchAll(/^\(\s*[a-z][\w-]*\s+([^\s()[\]{}"]+)/gm))
+            names.add(m[1]);
+    return [...names];
+};
+const fieldNames = (files) => {
+    const names = new Set();
+    for (const f of files)
+        for (const m of f.text.matchAll(/:([a-z][\w?-]*)\s+(?=[A-Z(])/g))
+            names.add(m[1]);
+    return [...names];
+};
+const functions = [...KERNEL_FUNCTIONS].map((name) => OLD_OPERATORS[name] ?? name);
+const vocabulary = () => [...functions, "self", "today", "now"];
+const holeType = (d, files) => {
+    const text = textAt(files, d.at);
+    // Truth/Bool mismatches get help from Forma (authoring-help.ts) and a fix from fixes.ts.
+    const unbound = /Unbound variable: (\S+)/.exec(d.message)?.[1];
+    if (unbound) {
+        const guess = closest(unbound, [...vocabulary(), ...declaredNames(files)]);
+        const fix = d.at && text === unbound && guess ? edit(d.at.src, d.at.from, unbound, guess) : undefined;
+        return {
+            help: `${unbound} is not in scope here.${guess ? ` Did you mean ${guess}?` : ""} Expressions may use the kernel vocabulary, this component's inputs, self, requirement names, and declared evidence/decision names.`,
+            ...(fix ? { fix } : {}),
+        };
+    }
+    const missingField = /^\S+ has no field (\S+)(?: |$)/.exec(d.message)?.[1];
+    if (missingField && text) {
+        const last = missingField;
+        const guess = closest(last, fieldNames(files));
+        return {
+            help: `${text} names a field that the role/entity does not declare.${guess && guess !== last ? ` Did you mean .${guess}?` : ""} Fields come from the role declaration's field map.`,
+            ...(guess && guess !== last && d.at
+                ? { fix: edit(d.at.src, d.at.from + text.length - last.length, last, guess) }
+                : {}),
+        };
+    }
+    const reference = /Unknown reference (\S+)/.exec(d.message)?.[1];
+    if (reference) {
+        const guess = closest(reference, declaredNames(files).filter((n) => n !== reference));
+        return {
+            help: `${reference} is not declared in any .forma file of this world.${guess ? ` Did you mean ${guess}?` : ""} Names are case-sensitive and shared across the directory; if the declaration itself failed to compile, fix that error first.`,
+            ...(guess && d.at && text === reference
+                ? { fix: edit(d.at.src, d.at.from, reference, guess) }
+                : {}),
+        };
+    }
+    if (/Too many arguments|Too few arguments/.test(d.message))
+        return {
+            help: "The call has the wrong number of arguments. Comparisons take two (= a b); combine several with (and (= a b) (= c d)).",
+        };
+    return undefined;
+};
+const lower = (d, files) => {
+    const name = /^(\S+) is not a kernel function or a derive\./.exec(d.message)?.[1];
+    if (!name)
+        return undefined;
+    const text = textAt(files, d.at);
+    const guess = closest(name, functions);
+    const head = headOf(text, d.at);
+    return {
+        help: `${name} is not a kernel function.${guess ? ` Did you mean ${guess}?` : ""} Declare reusable logic with (derive name "Doc." :params {…} :returns Truth expr).`,
+        ...(guess && head?.name === name ? { fix: edit(d.at.src, head.from, name, guess) } : {}),
+    };
+};
+const propertyShape = (input, files) => {
+    const bare = textAt(files, input.at);
+    const list = bare && !bare.startsWith("(") ? enclosing(files, input.at) : undefined;
+    const d = list ? { ...input, at: list } : input;
+    const text = textAt(files, d.at);
+    const head = headOf(text, d.at);
+    const operators = "Property operators: implies, and, or, not, =, !=, <, <=, >, >=, known?, unknown?, satisfied?, not-applicable?, (status (Component alias) name), (attested (Component alias) Evidence), work, due, occurrence-count.";
+    const op = head?.name ?? text?.trim();
+    if (op && ["valid", "decided", "met?"].includes(op))
+        return {
+            help: `${op} is not available in properties. Read the requirement that uses it instead, e.g. (= (status (Component alias) requirement) :Satisfied). ${operators}`,
+        };
+    return {
+        help: `Unsupported or malformed property expression${op ? ` at ${op}` : ""}. A property is (property name "Doc." :world account :at "YYYY-MM-DD" :for-all (alias Entity) predicate). ${operators}`,
+    };
+};
+const noScenario = (d, ir) => {
+    const key = /^(\S+)\/(\S+) has no authored scenario reference/.exec(d.message);
+    if (!key || !ir)
+        return undefined;
+    const [, componentName, requirement] = key;
+    const component = ir.components.find((c) => c.name === componentName);
+    const input = component?.inputs.find((i) => i.name === component.key[0]);
+    const role = Array.isArray(input?.type) && input.type[0] === "Id" ? input.type[1] : undefined;
+    const entity = ir.entities.find((e) => e.implements.some((b) => b.role === role));
+    const account = ir.accounts.find((a) => a.forEach.some((f) => f.component === componentName)) ?? ir.accounts[0];
+    const keys = component?.key.map((_, i) => (i === 0 ? "x" : `k${i}`)).join(" ") ?? "x";
+    const skeleton = `(scenario ${requirement}-opens "${requirement} opens for a new subject." :world ${account?.name ?? "<account>"}\n  (given (entity ${entity?.name ?? "<Entity>"} x {…}))\n  (at "2026-01-01" (expect (status (${componentName} ${keys}) ${requirement}) :Open)))`;
+    return {
+        help: `Add a scenario that observes ${componentName}/${requirement} (then a step that satisfies it and a second expectation), for example:\n${skeleton}\nworldvm coverage shows which applicability and status branches the scenarios actually take.`,
+    };
+};
+const unreachable = (d, files, ir) => {
+    const key = /^(\S+)\/(\S+) has no status consumer/.exec(d.message);
+    if (!key || !ir)
+        return undefined;
+    const [, componentName, requirement] = key;
+    const component = ir.components.find((c) => c.name === componentName);
+    const outputs = component?.outputs.filter((o) => o.op === "all-of") ?? [];
+    const help = `Add ${requirement} to an output so its status counts, e.g. (output complete (all-of … ${requirement})), read it from another expression, or delete it if unintended. This advisory check is not a reachability proof.`;
+    if (outputs.length !== 1)
+        return { help };
+    const output = outputs[0], file = files.find((f) => f.id === output.at.src), text = file?.text.slice(output.at.from, output.at.to);
+    const open = text?.search(/\(all-of\b/);
+    if (!file || !text || open === undefined || open < 0)
+        return { help };
+    const close = closeOf(text, open);
+    if (close === undefined)
+        return { help };
+    const at = output.at.from + close - 1;
+    return {
+        help: `${help} The fix appends it to output ${output.name}.`,
+        fix: { src: file.id, from: at, to: at, text: ` ${requirement}`, expected: "" },
+    };
+};
+/** Contextual help and mechanical fixes for diagnostics whose compiler help is generic. */
+export const refine = (d, files, ir) => {
+    switch (d.code) {
+        case "E_ELABORATE_HOLE_TYPE":
+            return holeType(d, files);
+        case "E_LOWER":
+            return lower(d, files);
+        case "E_PROPERTY_SHAPE":
+            return propertyShape(d, files);
+        case "W_NO_SCENARIO":
+            return noScenario(d, ir);
+        case "W_UNREACHABLE_REQUIREMENT":
+            return unreachable(d, files, ir);
+        default:
+            return undefined;
+    }
+};

package/dist/release/diff.d.ts

@@ -0,0 +1,45 @@
+import type { Span, WorldIR } from "../_internal/forma/world/index.js";
+export type ChangeKind = "added" | "removed" | "changed";
+/** What a requirement change means for the people it governs. */
+export type Aspect = "applicability" | "satisfaction" | "due" | "timing" | "assignment" | "citations" | "presentation"
+/** A release or contract digest: identity of the compiled unit, not an obligation. */
+ | "identity" | "other";
+export interface FieldChange {
+    readonly field: string;
+    readonly aspect: Aspect;
+    readonly old: Span | null;
+    readonly new: Span | null;
+}
+export interface DeclarationChange {
+    readonly key: string;
+    readonly kind: string;
+    readonly name: string;
+    readonly change: ChangeKind;
+    /** Only documentation, labels or titles changed; evaluation is identical. */
+    readonly presentationOnly: boolean;
+    /** A public component contract was removed or its digest changed. */
+    readonly breaking: boolean;
+    readonly old: Span | null;
+    readonly new: Span | null;
+    readonly fields: readonly FieldChange[];
+}
+export interface WorldDiff {
+    readonly format: "worldvm/diff@1";
+    readonly changes: readonly DeclarationChange[];
+    readonly examples: readonly DeclarationChange[];
+    readonly summary: {
+        readonly added: number;
+        readonly removed: number;
+        readonly changed: number;
+        readonly presentationOnly: number;
+        readonly breaking: number;
+        readonly requirements: {
+            readonly added: number;
+            readonly removed: number;
+            readonly changed: number;
+        };
+        readonly aspects: Readonly<Record<Aspect, number>>;
+    };
+}
+/** Semantic diff of two compiled releases: declarations, not text. Spans never count as change. */
+export declare const diffWorlds: (before: WorldIR, after: WorldIR) => WorldDiff;

package/dist/release/diff.js

@@ -0,0 +1,103 @@
+import { behaviorDigest, exampleNodes, nodeDigest, releaseNodes, semanticJson, } from "./nodes.js";
+const aspects = {
+    appliesWhen: "applicability",
+    presentWhen: "applicability",
+    effective: "applicability",
+    satisfiedBy: "satisfaction",
+    accepts: "satisfaction",
+    reuse: "satisfaction",
+    due: "due",
+    remind: "timing",
+    recur: "timing",
+    renewWithin: "timing",
+    escalate: "timing",
+    assignee: "assignment",
+    assigneeKind: "assignment",
+    by: "assignment",
+    approvals: "assignment",
+    distinctFrom: "assignment",
+    cites: "citations",
+    doc: "presentation",
+    label: "presentation",
+    title: "presentation",
+    digest: "identity",
+};
+const spanOf = (value) => {
+    const at = value?.at;
+    return at && typeof at === "object" && typeof at.src === "string" ? at : null;
+};
+const fieldChanges = (before, after) => {
+    const a = before.value, b = after.value;
+    return [...new Set([...Object.keys(a), ...Object.keys(b)])]
+        .filter((k) => k !== "at" && semanticJson(a[k]) !== semanticJson(b[k]))
+        .sort()
+        .map((field) => ({
+        field,
+        aspect: aspects[field] ?? "other",
+        old: spanOf(a[field]),
+        new: spanOf(b[field]),
+    }));
+};
+const compare = (before, after) => {
+    const out = [];
+    for (const key of [...new Set([...before.keys(), ...after.keys()])].sort()) {
+        const a = before.get(key), b = after.get(key);
+        const node = (b ?? a);
+        if (a && b && nodeDigest(a) === nodeDigest(b))
+            continue;
+        const change = !a ? "added" : !b ? "removed" : "changed";
+        const presentationOnly = !!a && !!b && behaviorDigest(a) === behaviorDigest(b);
+        const breaking = node.kind === "contract" &&
+            (change === "removed" ||
+                (change === "changed" &&
+                    a.value.digest !== b.value.digest));
+        out.push({
+            key,
+            kind: node.kind,
+            name: node.name,
+            change,
+            presentationOnly,
+            breaking,
+            old: a?.at ?? null,
+            new: b?.at ?? null,
+            fields: a && b ? fieldChanges(a, b) : [],
+        });
+    }
+    return out;
+};
+/** Semantic diff of two compiled releases: declarations, not text. Spans never count as change. */
+export const diffWorlds = (before, after) => {
+    const changes = compare(releaseNodes(before), releaseNodes(after));
+    const examples = compare(exampleNodes(before), exampleNodes(after));
+    const count = (kind, list = changes) => list.filter((c) => c.change === kind).length;
+    const requirements = changes.filter((c) => c.kind === "requirement");
+    const tally = Object.fromEntries([
+        "applicability",
+        "satisfaction",
+        "due",
+        "timing",
+        "assignment",
+        "citations",
+        "presentation",
+        "identity",
+        "other",
+    ].map((a) => [a, requirements.filter((c) => c.fields.some((f) => f.aspect === a)).length]));
+    return {
+        format: "worldvm/diff@1",
+        changes,
+        examples,
+        summary: {
+            added: count("added"),
+            removed: count("removed"),
+            changed: count("changed"),
+            presentationOnly: changes.filter((c) => c.presentationOnly).length,
+            breaking: changes.filter((c) => c.breaking).length,
+            requirements: {
+                added: count("added", requirements),
+                removed: count("removed", requirements),
+                changed: count("changed", requirements),
+            },
+            aspects: tally,
+        },
+    };
+};