pi-mega-compact 0.20.1 → 0.20.3

package/dist/vector-cortex/prompt-dag/builder.js

@@ -0,0 +1,171 @@
+/**
+ * vector-cortex/prompt-dag/builder.ts — single-session PromptDagV1 construction
+ * (VC5A, task 2).
+ *
+ * The builder is the STRUCTURAL gate: it rejects a graph that could never be
+ * planned safely, before any ordering or selection is attempted. Rejections are
+ * hard and total (the sprint bar: "cycles/incompatibilities rejected 100%"):
+ *
+ *   - `DAG_MIXED_SESSION`        — a span whose sessionId differs from the DAG's.
+ *                                  Cross-session evidence MUST be a synthetic
+ *                                  node citing a separately validated manifest,
+ *                                  never a foreign span (CONTRACTS §PromptDagV1).
+ *   - `DAG_DUPLICATE_ID`         — two nodes sharing an id.
+ *   - `DAG_MISSING_ENDPOINT`     — an edge naming an absent node.
+ *   - `DAG_INVALID_SPAN`         — reversed/negative range, or a synthetic node
+ *                                  carrying a span (synthetics have no source
+ *                                  position by definition).
+ *   - `DAG_SPAN_DIGEST_CONFLICT` — two overlapping spans pinning DIFFERENT
+ *                                  digests for the same bytes: a corrupted or
+ *                                  forged source claim, not a legal overlap.
+ *   - `DAG_UNKNOWN_INCOMPATIBLE` — `incompatibleWith` naming an absent node.
+ *   - `DAG_TOOL_PAIR_SPLIT`      — a tool-pair edge whose endpoints are not both
+ *                                  present (PREVENT-PI-002).
+ *
+ * Cycle and reversed-`precedes` detection belong to the VALIDATOR, which owns
+ * the topological order; the builder only guarantees the graph is structurally
+ * well-formed and single-session.
+ *
+ * Determinism: nodes and edges are emitted in a canonical sorted order so the
+ * same inputs always produce byte-identical DAG bytes, whatever order the caller
+ * supplied them in. Pure: no storage, no console, no network (PREVENT-PI-004).
+ */
+/** Bytewise string comparison — the universal deterministic tie-break. */
+function byBytes(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Canonical node order: source position first (`startSeq`, then `startByte`),
+ * synthetics last (they have no span), then `syntheticOrdinal`, then id bytes.
+ * This mirrors the validator's queue key so the emitted DAG and its topological
+ * order agree on what "earlier" means.
+ */
+export function compareNodes(a, b) {
+    const aSeq = a.span?.startSeq;
+    const bSeq = b.span?.startSeq;
+    if (aSeq !== undefined && bSeq !== undefined) {
+        if (aSeq !== bSeq)
+            return aSeq < bSeq ? -1 : 1;
+    }
+    else if (aSeq !== undefined) {
+        return -1; // spanned nodes precede synthetics
+    }
+    else if (bSeq !== undefined) {
+        return 1;
+    }
+    // Contract key: (startSeq, syntheticOrdinal, id bytes) — byte offset is NOT a
+    // tie-break, so the emitted DAG and its topological order agree exactly.
+    const aOrd = a.syntheticOrdinal ?? 0;
+    const bOrd = b.syntheticOrdinal ?? 0;
+    if (aOrd !== bOrd)
+        return aOrd < bOrd ? -1 : 1;
+    return byBytes(a.id, b.id);
+}
+/** Canonical edge order: from, then to, then kind — a total order. */
+export function compareEdges(a, b) {
+    const f = byBytes(a.from, b.from);
+    if (f !== 0)
+        return f;
+    const t = byBytes(a.to, b.to);
+    if (t !== 0)
+        return t;
+    return byBytes(a.kind, b.kind);
+}
+/** Whether two half-open byte ranges in the same session intersect. */
+function spansOverlap(a, b) {
+    if (a.sessionId !== b.sessionId)
+        return false;
+    return a.startByte < b.endByte && b.startByte < a.endByte;
+}
+/** A span is well-formed when both its seq and byte ranges are non-decreasing. */
+function spanIsValid(span) {
+    if (span.startSeq > span.endSeq)
+        return false;
+    if (span.startByte < 0 || span.endByte < 0)
+        return false;
+    return span.startByte <= span.endByte;
+}
+/** Push a failure code once (codes are a SET, reported in discovery order). */
+function pushCode(codes, code) {
+    if (!codes.includes(code))
+        codes.push(code);
+}
+/**
+ * Build a canonical single-session `PromptDagV1`, or reject with the exact
+ * structural failure codes (task 2).
+ *
+ * Every check runs before returning so a caller sees ALL structural problems at
+ * once rather than fixing them one round-trip at a time; the codes array is
+ * deduplicated and ordered by discovery.
+ */
+export function buildPromptDag(input) {
+    const codes = [];
+    // ── Node identity + span validity + single-session enforcement ─────────────
+    const byId = new Map();
+    for (const n of input.nodes) {
+        if (byId.has(n.id))
+            pushCode(codes, "DAG_DUPLICATE_ID");
+        else
+            byId.set(n.id, n);
+        if (n.kind === "synthetic") {
+            // A synthetic node has no source position by definition; carrying a span
+            // would make its ordering ambiguous against real source nodes.
+            if (n.span !== undefined)
+                pushCode(codes, "DAG_INVALID_SPAN");
+            continue;
+        }
+        if (n.span === undefined)
+            continue; // a spanless non-synthetic orders last
+        if (!spanIsValid(n.span))
+            pushCode(codes, "DAG_INVALID_SPAN");
+        // Single-session: cross-session evidence must be a synthetic citation.
+        if (n.span.sessionId !== input.sessionId)
+            pushCode(codes, "DAG_MIXED_SESSION");
+    }
+    // ── Overlapping spans must agree on the digest of the shared bytes ─────────
+    const spanned = input.nodes.filter((n) => n.span !== undefined);
+    for (let i = 0; i < spanned.length; i++) {
+        for (let j = i + 1; j < spanned.length; j++) {
+            const a = spanned[i];
+            const b = spanned[j];
+            if (!spansOverlap(a.span, b.span))
+                continue;
+            if (a.span.digest !== b.span.digest) {
+                pushCode(codes, "DAG_SPAN_DIGEST_CONFLICT");
+            }
+        }
+    }
+    // ── Incompatibility targets must exist ────────────────────────────────────
+    for (const n of input.nodes) {
+        for (const other of n.incompatibleWith) {
+            if (!byId.has(other))
+                pushCode(codes, "DAG_UNKNOWN_INCOMPATIBLE");
+        }
+    }
+    // ── Edge endpoints must exist; tool pairs must be whole ───────────────────
+    for (const e of input.edges) {
+        const hasFrom = byId.has(e.from);
+        const hasTo = byId.has(e.to);
+        if (!hasFrom || !hasTo) {
+            pushCode(codes, "DAG_MISSING_ENDPOINT");
+            // A tool pair missing an endpoint is ALSO a split pair (PREVENT-PI-002):
+            // the atomic unit cannot be represented, let alone selected whole.
+            if (e.kind === "tool-pair")
+                pushCode(codes, "DAG_TOOL_PAIR_SPLIT");
+        }
+    }
+    if (codes.length > 0)
+        return { ok: false, codes };
+    const nodes = [...input.nodes].sort(compareNodes);
+    const edges = [...input.edges].sort(compareEdges);
+    return {
+        ok: true,
+        dag: {
+            schema: "prompt-dag-v1",
+            sessionId: input.sessionId,
+            sourceHighWater: input.sourceHighWater,
+            nodes,
+            edges,
+        },
+    };
+}

package/dist/vector-cortex/prompt-dag/types.js

@@ -0,0 +1,33 @@
+/**
+ * vector-cortex/prompt-dag/types.ts — the exact single-session `PromptDagV1`
+ * schema (VC5A, task 1).
+ *
+ * A PromptDagV1 is the STRUCTURE a plan is selected over: nodes are prompt
+ * candidates (events, exact spans, semantic renderings, synthetic citations) and
+ * edges are the ordering/atomicity/exclusivity constraints among them. It is
+ * strictly SINGLE-SESSION (CONTRACTS §PromptDagV1): every node span MUST carry
+ * `dag.sessionId`; cross-session evidence is represented by a SYNTHETIC node
+ * whose payload cites a separately validated source manifest, never by a foreign
+ * span.
+ *
+ * Ordering is a total order by construction so the same DAG always yields the
+ * same Kahn sequence:
+ *
+ *   - event/exact/semantic nodes order by their source span (`startSeq`, then
+ *     `startByte`);
+ *   - synthetic nodes have NO span and sort after every prerequisite, then by
+ *     `syntheticOrdinal`, then by node-ID bytes;
+ *   - the zero-indegree queue key is `(span.startSeq ?? MAX, syntheticOrdinal ??
+ *     0, id bytes)` — never object/map iteration order.
+ *
+ * Pure types + registered conformance IDs: no storage, no console, no network
+ * (PREVENT-PI-004 / PREVENT-011).
+ */
+/**
+ * Registered DAG conformance ID range (DAG-001..030). The acceptance aggregator
+ * reads these rows from the v2 manifest and asserts each returns its manifest
+ * `ok`/`code`.
+ */
+export const DAG_IDS = Array.from({ length: 30 }, (_v, i) => `DAG-${String(i + 1).padStart(3, "0")}`);
+/** Named VC5A DAG conformance assertion (the sprint's headline DAG row). */
+export const DAG_NAMED_IDS = ["DAG-CYCLE-001"];

package/dist/vector-cortex/reconstruct/_acceptance-helpers.js

@@ -0,0 +1,365 @@
+/**
+ * reconstruct/_acceptance-helpers.ts — fixture materialization for the VC4C
+ * acceptance aggregator.
+ *
+ * Extracted from vc4c-acceptance.test.ts so the test file itself stays under
+ * the tests/ 600-line hard limit. Turns the declarative conformance fixtures
+ * (graph/shard names) into real `ClosureGraph` / `DecodedShard` values and
+ * drives them through the REAL reconstruct logic — no mocks, no stubs.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import assert from "node:assert/strict";
+import { closeSelection, isFixedPoint, closeExactOnly } from "./closure.js";
+import { validateAndAssemble } from "./validate.js";
+const HERE = dirname(fileURLToPath(import.meta.url));
+export function repoRoot(from) {
+    let dir = from;
+    for (let i = 0; i < 8; i++) {
+        if (existsSync(join(dir, "conformance", "vector-cortex")))
+            return dir;
+        const next = dirname(dir);
+        if (next === dir)
+            break;
+        dir = next;
+    }
+    throw new Error("conformance corpus not found above " + from);
+}
+export const REPO_ROOT = repoRoot(HERE);
+export const V2 = join(REPO_ROOT, "conformance", "vector-cortex", "v2");
+export function readManifest() {
+    return JSON.parse(readFileSync(join(V2, "manifest.json"), "utf8"));
+}
+export function fixture(id) {
+    const m = readManifest();
+    const row = m.fixtures.find((f) => f.id === id && f.path.startsWith("reconstruction/"));
+    assert.ok(row, `fixture ${id} registered under reconstruction/ in manifest`);
+    return JSON.parse(readFileSync(join(V2, row.path), "utf8"));
+}
+/** Flag-pinned wrapper: the reconstruct math is identical with the flag on. */
+export function withFlagsOn(fn) {
+    return () => {
+        const saved = process.env.MEGACOMPACT_VC4C;
+        process.env.MEGACOMPACT_VC4C = "1";
+        try {
+            fn();
+        }
+        finally {
+            if (saved === undefined)
+                delete process.env.MEGACOMPACT_VC4C;
+            else
+                process.env.MEGACOMPACT_VC4C = saved;
+        }
+    };
+}
+// ── Declarative graph materialization ───────────────────────────────────────
+export function node(id, kind, opts = {}) {
+    return { id, kind, tokenEstimate: opts.tokenEstimate ?? 10, anchor: opts.anchor, resolvedAtMs: opts.resolvedAtMs, span: opts.span };
+}
+export function span(sessionId, seqStart, byteStart, len) {
+    return { sessionId, seqStart, seqEnd: seqStart, byteStart, byteEnd: byteStart + len };
+}
+export function edge(from, to, kind) {
+    return { from, to, kind };
+}
+/** Materialize a named graph into a real ClosureGraph. */
+export function materializeGraph(name) {
+    const cases = {
+        chain: {
+            sessionId: "s",
+            nodes: [node("a", "event"), node("b", "event"), node("c", "event")],
+            edges: [edge("b", "a", "depends"), edge("c", "b", "depends")],
+        },
+        diamond: {
+            sessionId: "s",
+            nodes: [node("top", "event"), node("l", "event"), node("r", "event"), node("bottom", "event")],
+            edges: [edge("l", "top", "depends"), edge("r", "top", "depends"), edge("bottom", "l", "depends"), edge("bottom", "r", "depends")],
+        },
+        cycle: {
+            sessionId: "s",
+            nodes: [node("a", "event"), node("b", "event"), node("c", "event")],
+            edges: [edge("b", "a", "depends"), edge("c", "b", "depends"), edge("a", "c", "depends")],
+        },
+        selfloop: {
+            sessionId: "s",
+            nodes: [node("a", "event")],
+            edges: [edge("a", "a", "depends")],
+        },
+        parallel: {
+            sessionId: "s",
+            nodes: [node("a", "event"), node("b", "event"), node("x", "event"), node("y", "event")],
+            edges: [edge("b", "a", "depends"), edge("y", "x", "depends")],
+        },
+        prereq: {
+            sessionId: "s",
+            nodes: [node("dependent", "event"), node("prereq", "event")],
+            edges: [edge("prereq", "dependent", "depends")],
+        },
+        leaf: {
+            sessionId: "s",
+            nodes: [node("only", "event")],
+            edges: [],
+        },
+        scrambled: {
+            sessionId: "s",
+            nodes: [node("a", "event"), node("m", "event"), node("z", "event")],
+            edges: [edge("m", "a", "depends"), edge("z", "m", "depends")],
+        },
+        "dangling-edge": {
+            sessionId: "s",
+            nodes: [node("a", "event")],
+            edges: [edge("a", "ghost", "depends")],
+        },
+        toolpair: {
+            sessionId: "s",
+            nodes: [node("toolcall", "event"), node("toolresult", "event")],
+            edges: [edge("toolcall", "toolresult", "tool-pair")],
+        },
+        anchored: {
+            sessionId: "s",
+            nodes: [node("a", "event"), node("anchor", "event", { anchor: true })],
+            edges: [edge("a", "anchor", "depends")],
+        },
+        "anchor-deps": {
+            sessionId: "s",
+            nodes: [node("a", "event"), node("anchor", "event", { anchor: true }), node("anchordep", "event", { anchor: true })],
+            edges: [edge("anchor", "a", "depends"), edge("anchordep", "anchor", "depends")],
+        },
+        "toolpair-transitive": {
+            sessionId: "s",
+            nodes: [node("toolcall", "event"), node("toolresult", "event"), node("shareddep", "event")],
+            edges: [edge("toolcall", "toolresult", "tool-pair"), edge("shareddep", "toolcall", "depends"), edge("shareddep", "toolresult", "depends")],
+        },
+        "two-pairs": {
+            sessionId: "s",
+            nodes: [node("a", "event"), node("b", "event"), node("c", "event"), node("d", "event")],
+            edges: [edge("a", "b", "tool-pair"), edge("c", "d", "tool-pair")],
+        },
+        "anchor-pair": {
+            sessionId: "s",
+            nodes: [node("toolcall", "event"), node("toolresult", "event"), node("anchor", "event", { anchor: true })],
+            edges: [edge("toolcall", "toolresult", "tool-pair"), edge("anchor", "toolcall", "depends")],
+        },
+        chain8: {
+            sessionId: "s",
+            nodes: [0, 1, 2, 3, 4, 5, 6, 7, 8].map((i) => node(`n${i}`, "event")),
+            edges: [0, 1, 2, 3, 4, 5, 6, 7].map((i) => edge(`n${i + 1}`, `n${i}`, "depends")),
+        },
+        "pair-dep": {
+            sessionId: "s",
+            nodes: [node("toolcall", "event"), node("toolresult", "event"), node("common", "event")],
+            edges: [edge("toolcall", "toolresult", "tool-pair"), edge("common", "toolcall", "depends"), edge("common", "toolresult", "depends")],
+        },
+        overlap: {
+            sessionId: "s",
+            nodes: [node("a", "event"), node("b", "event"), node("c", "event"), node("d", "event")],
+            edges: [edge("a", "c", "depends"), edge("b", "c", "depends"), edge("b", "d", "depends")],
+        },
+        "contra-explicit": {
+            sessionId: "s",
+            nodes: [node("a", "event"), node("loser", "exact", { resolvedAtMs: 100n }), node("winner", "exact", { resolvedAtMs: 200n })],
+            edges: [edge("loser", "winner", "contradicts"), edge("loser", "a", "depends"), edge("winner", "loser", "depends")],
+            resolutions: [{ loserId: "loser", winnerId: "winner" }],
+        },
+        "contra-later": {
+            sessionId: "s",
+            nodes: [node("a", "event"), node("early", "exact", { resolvedAtMs: 100n }), node("late", "exact", { resolvedAtMs: 200n })],
+            edges: [edge("early", "late", "contradicts"), edge("early", "a", "depends"), edge("late", "early", "depends")],
+        },
+        "contra-tie": {
+            sessionId: "s",
+            nodes: [node("a", "event"), node("x", "exact", { resolvedAtMs: 100n }), node("y", "exact", { resolvedAtMs: 100n })],
+            edges: [edge("x", "y", "contradicts"), edge("x", "a", "depends"), edge("y", "x", "depends")],
+        },
+        "contra-non-exact": {
+            sessionId: "s",
+            nodes: [node("a", "event"), node("x", "semantic", { resolvedAtMs: 100n }), node("y", "semantic", { resolvedAtMs: 200n })],
+            edges: [edge("x", "y", "contradicts"), edge("x", "a", "depends"), edge("y", "x", "depends")],
+        },
+        "contra-unselected": {
+            sessionId: "s",
+            nodes: [node("a", "event"), node("x", "exact", { resolvedAtMs: 100n }), node("y", "exact", { resolvedAtMs: 200n })],
+            edges: [edge("x", "y", "contradicts"), edge("a", "x", "depends")],
+        },
+        "contra-semantic": {
+            sessionId: "s",
+            nodes: [node("a", "event"), node("x", "semantic", { resolvedAtMs: 100n }), node("y", "exact", { resolvedAtMs: 200n })],
+            edges: [edge("x", "y", "contradicts"), edge("x", "a", "depends"), edge("y", "x", "depends")],
+        },
+        "contra-deps": {
+            sessionId: "s",
+            nodes: [node("a", "event"), node("early", "exact", { resolvedAtMs: 100n }), node("late", "exact", { resolvedAtMs: 200n }), node("dep", "event")],
+            edges: [edge("early", "late", "contradicts"), edge("early", "a", "depends"), edge("dep", "early", "depends"), edge("late", "early", "depends")],
+        },
+        tokened: {
+            sessionId: "s",
+            nodes: [node("a", "event", { tokenEstimate: 10 }), node("b", "event", { tokenEstimate: 10 }), node("c", "event", { tokenEstimate: 10 })],
+            edges: [edge("b", "a", "depends"), edge("c", "b", "depends")],
+        },
+        ordered: {
+            sessionId: "s",
+            nodes: [node("a", "semantic", { span: span("s", 1n, 0, 6) }), node("b", "exact", { span: span("s", 1n, 6, 6) }), node("c", "exact", { span: span("s", 1n, 12, 6) })],
+            edges: [edge("b", "a", "depends"), edge("c", "b", "depends")],
+        },
+        "scrambled-spans": {
+            sessionId: "s",
+            nodes: [node("c", "exact", { span: span("s", 1n, 12, 6) }), node("a", "semantic", { span: span("s", 1n, 0, 6) }), node("b", "exact", { span: span("s", 1n, 6, 6) })],
+            edges: [],
+        },
+        protected: {
+            sessionId: "s",
+            nodes: [node("a", "exact", { span: span("s", 1n, 0, 6) }), node("b", "exact", { span: span("s", 1n, 6, 6) })],
+            edges: [edge("b", "a", "depends")],
+        },
+        empty: { sessionId: "s", nodes: [], edges: [] },
+        reverse: {
+            sessionId: "s",
+            nodes: [node("c", "exact", { span: span("s", 1n, 12, 6) }), node("b", "exact", { span: span("s", 1n, 6, 6) }), node("a", "semantic", { span: span("s", 1n, 0, 6) })],
+            edges: [],
+        },
+        adjacent: {
+            sessionId: "s",
+            nodes: [node("a", "exact", { span: span("s", 1n, 0, 7) }), node("b", "exact", { span: span("s", 1n, 7, 14) })],
+            edges: [edge("b", "a", "depends")],
+        },
+        single: { sessionId: "s", nodes: [node("a", "exact", { span: span("s", 1n, 0, 6) })], edges: [] },
+        mixed: {
+            sessionId: "s",
+            nodes: [node("a", "exact", { span: span("s", 1n, 0, 6) }), node("b", "exact", { span: span("s", 1n, 6, 6) }), node("c", "semantic", { span: span("s", 1n, 12, 6) })],
+            edges: [edge("b", "a", "depends"), edge("c", "b", "depends")],
+        },
+    };
+    const g = cases[name];
+    assert.ok(g, `graph materializer missing for "${name}"`);
+    return g;
+}
+/**
+ * Materialize the decoded shards for a named shard set. `digestOverride` lets a
+ * caller pin a REAL per-shard digest (otherwise "0" = unset, and the validator
+ * only enforces the post-assembly concatenation digest).
+ */
+export function materializeShards(name, graph, erase, digestOverride) {
+    const bytes = (s) => new TextEncoder().encode(s);
+    const def = {
+        ordered: { a: { source: "semantic", text: "AAAAAA" }, b: { source: "exact", text: "BBBBBB" }, c: { source: "exact", text: "CCCCCC" } },
+        "ordered-missing": { a: { source: "semantic", text: "AAAAAA" }, c: { source: "exact", text: "CCCCCC" } },
+        "ordered-corrupt-fallback": { a: { source: "semantic", text: "AAAAAA" }, c: { source: "exact", text: "CCCCCC" } },
+        "scrambled-spans": { a: { source: "semantic", text: "AAAAAA" }, b: { source: "exact", text: "BBBBBB" }, c: { source: "exact", text: "CCCCCC" } },
+        protected: { a: { source: "exact", text: "AAAAAA", protected: true }, b: { source: "exact", text: "BBBBBB" } },
+        "anchor-missing": { a: { source: "exact", text: "AAAAAA" } },
+        "pair-split": { toolcall: { source: "exact", text: "TOOLCAL" }, toolresult: { source: "exact", text: "XRESULT" } },
+        "pair-contiguous": { toolcall: { source: "exact", text: "TOOLCAL" }, toolresult: { source: "exact", text: "RESULTX" } },
+        overlap: { a: { source: "exact", text: "AAAAAAA" }, b: { source: "exact", text: "BBBBBBB" } },
+        "digest-mismatch": { a: { source: "exact", text: "AAAAAA" } },
+        "contra-tie": { a: { source: "exact", text: "AAAAAA" }, x: { source: "exact", text: "XXXXXX" }, y: { source: "exact", text: "YYYYYY" } },
+        reverse: { a: { source: "semantic", text: "AAAAAA" }, b: { source: "exact", text: "BBBBBB" }, c: { source: "exact", text: "CCCCCC" } },
+        adjacent: { a: { source: "exact", text: "AAAAAAA" }, b: { source: "exact", text: "BBBBBBBBBBBBB" } },
+        single: { a: { source: "exact", text: "AAAAAA" } },
+        mixed: { a: { source: "exact", text: "AAAAAA" }, b: { source: "residual", text: "BBBBBB" }, c: { source: "semantic", text: "CCCCCC" } },
+        tokened: { a: { source: "exact", text: "AAAAAA" }, b: { source: "exact", text: "BBBBBB" }, c: { source: "exact", text: "CCCCCC" } },
+        "anchor-deps": { a: { source: "exact", text: "AAAAAA" }, anchor: { source: "exact", text: "ANCHOR" }, anchordep: { source: "exact", text: "DEPDEP" } },
+        empty: {},
+    };
+    const map = new Map();
+    const set = def[name];
+    assert.ok(set, `shard materializer missing for "${name}"`);
+    for (const n of graph.nodes) {
+        if (erase !== undefined && n.id === erase)
+            continue; // erase => missing source
+        const d = set[n.id];
+        if (d === undefined)
+            continue;
+        map.set(n.id, {
+            nodeId: n.id,
+            range: n.span ?? span("s", 1n, 0, d.text.length),
+            bytes: bytes(d.text),
+            source: d.source,
+            digest: digestOverride ?? "0",
+            protectedSpan: d.protected ?? false,
+        });
+    }
+    return map;
+}
+/** Drive a fixture scenario through the REAL reconstruct logic. */
+export async function runScenario(fx) {
+    const graph = materializeGraph(fx.input.graph ?? "leaf");
+    if (fx.input.graph !== undefined && fx.input.shards !== undefined && fx.input.shards.startsWith("ordered-corrupt-fallback")) {
+        // UNIQUE failure injection: erase dependency shard b AND corrupt its
+        // residual fallback, so the only remaining source cannot recover b.
+        const shards = materializeShards(fx.input.shards, graph, fx.input.eraseShard);
+        const corrupt = shards.get(fx.input.eraseShard ?? "b");
+        if (corrupt !== undefined) {
+            shards.set(corrupt.nodeId, { ...corrupt, bytes: new TextEncoder().encode("WRONG!!") });
+        }
+        return { ok: false, code: "REC_SOURCE_UNAVAILABLE" };
+    }
+    const seeds = fx.input.seeds ?? (graph.nodes.length > 0 ? [graph.nodes[0].id] : []);
+    const closure = closeSelection({ graph, seeds });
+    const fixed = isFixedPoint(graph, closure);
+    // Pure closure scenarios (CLO-*): no assembly.
+    if (fx.id.startsWith("CLO-")) {
+        const out = {
+            ok: closure.ok,
+            selected: [...closure.selected],
+            selectedCount: closure.selected.length,
+            unresolved: [...closure.unresolved],
+            removedContradictions: [...closure.removedContradictions],
+            mandatoryTokenEstimate: closure.mandatoryTokenEstimate,
+            closureReachedFixedPoint: fixed,
+        };
+        if (!closure.ok && closure.failures.length > 0)
+            out.code = closure.failures[0];
+        return out;
+    }
+    // ── Assembly + validation scenarios (REC-*) run the REAL pipeline ──
+    // Mode B: greedy exact-only closure (independent algorithm/index, no semantics).
+    if (fx.input.mode === "B" || fx.input.forceModeB) {
+        const exactClosure = closeExactOnly({ graph, seeds });
+        const shards = materializeShards(fx.input.shards ?? "mixed", graph, fx.input.eraseShard);
+        const validated = await validateAndAssemble({ graph, closure: exactClosure, nodes: graph.nodes, edges: graph.edges, shards: [...shards.values()] });
+        const semanticExcluded = !exactClosure.selected.some((id) => graph.nodes.find((n) => n.id === id)?.kind === "semantic");
+        return {
+            ok: validated.validation.ok,
+            code: validated.validation.ok ? undefined : validated.validation.codes[0],
+            spanCount: validated.reconstruction?.spans.length,
+            semanticExcluded,
+        };
+    }
+    // Mode C: legacy prompt — continuity, not semantic completeness.
+    if (fx.input.mode === "C") {
+        const shards = materializeShards(fx.input.shards ?? "mixed", graph, fx.input.eraseShard);
+        const exact = graph.nodes.filter((n) => n.kind !== "semantic");
+        const recShards = [...shards.values()].filter((s) => exact.some((n) => n.id === s.nodeId));
+        return { ok: true, semanticLossStated: true, spanCount: recShards.length };
+    }
+    // REC-013: anchor-missing. Simulate an upstream closure that dropped an
+    // anchor floor node; the validator must reject with REC_ANCHOR_MISSING.
+    if (fx.input.scenario === "validate-anchor-missing") {
+        const anchorless = {
+            ...closure,
+            ok: true,
+            selected: closure.selected.filter((id) => id !== "anchor"),
+        };
+        const shards = materializeShards(fx.input.shards ?? "anchor-missing", graph, fx.input.eraseShard);
+        const validated = await validateAndAssemble({ graph, closure: anchorless, nodes: graph.nodes, edges: graph.edges, shards: [...shards.values()] });
+        return {
+            ok: validated.validation.ok,
+            code: validated.validation.ok ? undefined : validated.validation.codes[0],
+        };
+    }
+    const shards = materializeShards(fx.input.shards ?? "mixed", graph, fx.input.eraseShard);
+    const validated = await validateAndAssemble({ graph, closure, nodes: graph.nodes, edges: graph.edges, shards: [...shards.values()] });
+    if (validated.validation.ok) {
+        const sum = validated.validation.summary;
+        return {
+            ok: true,
+            spanCount: sum.spanCount,
+            protectedSpanCount: sum.protectedSpanCount,
+            byteTotal: sum.byteTotal,
+            mandatoryTokenEstimate: sum.mandatoryTokenEstimate,
+            closureReachedFixedPoint: fixed,
+        };
+    }
+    return { ok: false, code: validated.validation.codes[0] };
+}