pi-mega-compact 0.20.0 → 0.20.2

package/dist/config/vector-cortex.js

@@ -134,6 +134,31 @@ export const VC3C_ENABLED = () => sprintFlag("MEGACOMPACT_VC3C");
  * dashboard shards aggregate view.
  */
 export const VC4A_ENABLED = () => sprintFlag("MEGACOMPACT_VC4A");
+/**
+ * VC4B — residual codec and numeric parity (ResidualCodecV1 / ParityShardV1).
+ * Default ON. `MEGACOMPACT_VC4B=0` disables and is byte-identical to the
+ * predecessor (mode C: no residual artifact is admitted, the exact compressed
+ * payload / ledger bytes remain the only representation, zero
+ * `vector_cortex_residual_admitted` / `vector_cortex_parity_recovery_failed`
+ * emissions; the VC4A shard manifest and its goldens are unchanged). The real
+ * consumers are the codec admission seam (codec.ts) and the reader-only
+ * dashboard residual aggregate view. The codec math itself is PURE — flag OFF
+ * gates the reporter/admission seam, never the arithmetic.
+ */
+export const VC4B_ENABLED = () => sprintFlag("MEGACOMPACT_VC4B");
+/**
+ * VC4C — reconstruction fidelity (closure + assemble + validate). Default ON.
+ * `MEGACOMPACT_VC4C=0` disables and is byte-identical to the predecessor
+ * (VC4B): no conservative closure is computed, the reconstruction validator's
+ * `vector_cortex_reconstruction_validated` / `vector_cortex_closure_rejected`
+ * events are never emitted, and the assembled reconstruction is never produced
+ * (the prompt continues to be built by the legacy VC4B exact/residual path and
+ * the VC4A shard goldens are unchanged). The closure/assemble/validate
+ * functions are PURE — flag OFF gates the reporter seam, never the arithmetic.
+ * This flag MUST also be a dashboard SETTINGS toggle (visible in config UI,
+ * never in EXCLUDED_SETTINGS), mirroring VC4A/VC4B.
+ */
+export const VC4C_ENABLED = () => sprintFlag("MEGACOMPACT_VC4C");
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/dist/config.js

@@ -114,4 +114,4 @@ export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
 // default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
 // so root consumers share one source of truth.
 // ---------------------------------------------------------------------------
-export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";

package/dist/extensions/dashboard-server/routes-rag-settings-helpers.js

@@ -147,6 +147,8 @@ export const SETTINGS = [
             boolDirect("MEGACOMPACT_VC3B", "VC3B Deterministic Topology", "Deterministic cortical topology (TopologyV1/EdgeV1): per-(source,head) top-k=16/head calibrated-threshold edges, stable score-desc/then-target-ID sort, dependency directed + contradiction symmetric paired records, one stable generation digest. OFF = mode C, no topology graph built/emitted, predecessor-precise topology view, byte-identical predecessor.", true),
             boolDirect("MEGACOMPACT_VC3C", "VC3C Topology Query + Router Invalidation", "TopologyQueryV1/RouterKeyV2 structured keys (length-delimited, unsigned-byte order, no prefix ambiguity), exact (session,generation) invalidation, stale-generation rejection (TOP_GENERATION_STALE), and the M6 router-generation-v2 copy/validate/switch migration. OFF = mode C, no structured router key / generation invalidation, byte-identical predecessor.", true),
             boolDirect("MEGACOMPACT_VC4A", "VC4A Dual-Tier Shards", "SemanticShardV1/ExactShardV1/ShardManifestV1: partition a session ONLY at complete EventV2 boundaries; exact shards preserve every tool call/result pair, anchor and invalid UTF-8 event as original bytes (pairs never split across exact shards); manifest enforces disjoint sorted ranges + complete protected-span coverage. OFF = mode C, exact anchors/current transcript only, byte-identical predecessor.", true),
+            boolDirect("MEGACOMPACT_VC4B", "VC4B Residual Basis Parity", "Residual codec: orthonormal DCT-II basis + int16 block quantization + block-scoped exact correction stream + (9,6) Reed-Solomon parity shards with SHA-256 corruption detection; admission gates on encodedSize <= 95% of exact-compressed size. OFF = mode C, no residual artifact produced, byte-identical predecessor.", true),
+            boolDirect("MEGACOMPACT_VC4C", "VC4C Reconstruction Fidelity", "Conservative closure + source-order assembly + reconstruction validator: recursively closes dependencies and whole tool pairs to a fixed point, resolves contradictions by retaining the later exact source resolution, assembles spans solely by source range, and rejects missing anchors / split pairs / digest mismatch / unresolved contradiction. Mandatory token estimate is content-only and handed unchanged to VC5A. OFF = mode C, no closure/validator, byte-identical predecessor (VC4B).", true),
         ],
     },
     {

package/dist/extensions/dashboard-server/routes-vector-cortex-reconstruct.js

@@ -0,0 +1,33 @@
+/**
+ * Dashboard handler: GET /api/vector-cortex/reconstruct (VC4C).
+ *
+ * Reader-only reconstruction-fidelity aggregate. Mirrors the VC4B residual
+ * handler: path guard + 405 on non-GET, gated on the sprint flag, returns a
+ * zero-valued view when disabled (byte-identical predecessor contract). Never
+ * returns reconstructed spans, exact bytes, or prompt text.
+ */
+import { VC4C_ENABLED } from "../../src/config.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+export function handleVectorCortexReconstruct(req, res, _ctx) {
+    const url = req.url ?? "";
+    const path = url.split("?")[0] ?? url;
+    if (path !== "/api/vector-cortex/reconstruct")
+        return false;
+    if (req.method !== "GET") {
+        sendJson(res, 405, { error: "method_not_allowed" });
+        return true;
+    }
+    const enabled = VC4C_ENABLED();
+    const body = {
+        enabled,
+        closureAttempts: 0,
+        closureRejections: 0,
+        validatedCount: 0,
+        invalidatedCount: 0,
+        spanTotal: 0,
+        byteTotal: 0,
+        updatedAt: new Date().toISOString(),
+    };
+    sendJson(res, 200, body);
+    return true;
+}

package/dist/extensions/dashboard-server/routes-vector-cortex-residual.js

@@ -0,0 +1,51 @@
+/**
+ * dashboard-server/routes-vector-cortex-residual.ts — VC4B residual basis parity
+ * dashboard route.
+ *
+ * Reader-only GET /api/vector-cortex/residual returning a COUNT/BYTE aggregate
+ * (encode attempts, admitted/rejected counts, recovery failures, encoded/exact
+ * byte totals) — never residual payloads, correction streams, shard bytes, or
+ * original source bytes. Flag-gated on MEGACOMPACT_VC4B: `enabled:false` when off
+ * (byte-identical to the pre-VC4B predecessor).
+ *
+ * The VC4B residual codec is PURE IN-MEMORY logic in this sprint (it has no
+ * durable metrics store yet), so the aggregate reports the current status
+ * truthfully: `enabled` reflects the flag, and the count/byte fields are zero
+ * until a future sprint persists a metrics store. This route is the seam that
+ * sprint will populate. Non-fatal: a missing state dir degrades to
+ * `enabled:false`.
+ *
+ * Guardrails: PREVENT-PI-004 (local filesystem read only / in-process state),
+ * PREVENT-011 (no `any`), reader-only aggregate (counts/bytes only).
+ */
+import { VC4B_ENABLED } from "../../src/config.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+/**
+ * Reader-only GET /api/vector-cortex/residual (VC4B).
+ */
+export function handleVectorCortexResidual(req, res, _ctx) {
+    const url = req.url ?? "";
+    const path = url.split("?")[0] ?? url;
+    if (path !== "/api/vector-cortex/residual")
+        return false;
+    if (req.method !== "GET") {
+        // Reader-only path: cannot be "off" without a GET; it is genuinely read-only.
+        sendJson(res, 405, { error: "method_not_allowed" });
+        return true;
+    }
+    const enabled = VC4B_ENABLED();
+    const body = {
+        enabled,
+        // No durable residual metrics store is staged yet in this sprint (pure
+        // in-memory encode), so the aggregates are truthfully zero.
+        encodeAttempts: 0,
+        admittedCount: 0,
+        rejectedCount: 0,
+        recoveryFailures: 0,
+        encodedByteTotal: 0,
+        exactByteTotal: 0,
+        updatedAt: new Date().toISOString(),
+    };
+    sendJson(res, 200, body);
+    return true;
+}

package/dist/extensions/dashboard-server/routes-vector-cortex.js

@@ -19,3 +19,5 @@ export { handleVectorCortexLedger } from "./routes-vector-cortex-ledger.js";
 export { handleVectorCortexTopology } from "./routes-vector-cortex-topology.js";
 export { handleVectorCortexQuery } from "./routes-vector-cortex-query.js";
 export { handleVectorCortexShards } from "./routes-vector-cortex-shards.js";
+export { handleVectorCortexResidual } from "./routes-vector-cortex-residual.js";
+export { handleVectorCortexReconstruct } from "./routes-vector-cortex-reconstruct.js";

package/dist/extensions/dashboard-server/routes.js

@@ -23,4 +23,4 @@ export { handleRagSettings } from "./routes-rag-settings.js";
 export { handleRagMetrics } from "./routes-rag-metrics.js";
 export { handleModelThresholds } from "./routes-model-thresholds.js";
 export { handleWiki } from "./routes-wiki.js";
-export { handleVectorCortexEvaluation, handleVectorCortexHealth, handleVectorCortexBreakersReset, handleVectorCortexLedger, handleVectorCortexTopology, handleVectorCortexQuery, handleVectorCortexShards, } from "./routes-vector-cortex.js";
+export { handleVectorCortexEvaluation, handleVectorCortexHealth, handleVectorCortexBreakersReset, handleVectorCortexLedger, handleVectorCortexTopology, handleVectorCortexQuery, handleVectorCortexShards, handleVectorCortexResidual, handleVectorCortexReconstruct, } from "./routes-vector-cortex.js";

package/dist/extensions/dashboard-server/server.js

@@ -14,7 +14,7 @@ import { createRequire } from "node:module";
 import { NEW_UI } from "../../src/config.js";
 import { log, setLogPath, setDashboardServerVersion } from "./state.js";
 import { detectTailscaleIP } from "./tailscale.js";
-import { buildRouteContext, handleIndex, handleRepoIndex, handleEvents, handleGameState, handleGameScores, handlePerf, handlePerfSamples, handleAchievements, handleSessions, handleTopics, handleTurns, handleMaintenance, handleProviderCache, handleCacheStripes, handleMemoryStatus, handleSetupStatus, handleSetupDetect, handleSetupConfigure, handleMemoryMap, handleRaptorTree, handleRaptorBuildHistory, handleContextHealth, handleCachePoison, handleHealthSettings, handleEmbedderHealth, handleRagSettings, handleRagMetrics, handleModelThresholds, handleWiki, handleVectorCortexEvaluation, handleVectorCortexHealth, handleVectorCortexBreakersReset, handleVectorCortexLedger, handleVectorCortexTopology, handleVectorCortexQuery, handleVectorCortexShards, handleStatic, } from "./routes.js";
+import { buildRouteContext, handleIndex, handleRepoIndex, handleEvents, handleGameState, handleGameScores, handlePerf, handlePerfSamples, handleAchievements, handleSessions, handleTopics, handleTurns, handleMaintenance, handleProviderCache, handleCacheStripes, handleMemoryStatus, handleSetupStatus, handleSetupDetect, handleSetupConfigure, handleMemoryMap, handleRaptorTree, handleRaptorBuildHistory, handleContextHealth, handleCachePoison, handleHealthSettings, handleEmbedderHealth, handleRagSettings, handleRagMetrics, handleModelThresholds, handleWiki, handleVectorCortexEvaluation, handleVectorCortexHealth, handleVectorCortexBreakersReset, handleVectorCortexLedger, handleVectorCortexTopology, handleVectorCortexQuery, handleVectorCortexShards, handleVectorCortexResidual, handleVectorCortexReconstruct, handleStatic, } from "./routes.js";
 export async function launchDashboardServer(stateDir) {
     // Our own package version — exposed at /api/version so the launcher can
     // detect a stale server (started by an older build) and replace it on
@@ -269,6 +269,10 @@ export async function launchDashboardServer(stateDir) {
             return;
         if (handleVectorCortexShards(req, res, ctx))
             return;
+        if (handleVectorCortexResidual(req, res, ctx))
+            return;
+        if (handleVectorCortexReconstruct(req, res, ctx))
+            return;
         handleStatic(req, res, ctx);
     });
     // Bind base + range are env-configurable so tests can use a private,

package/dist/src/config/vector-cortex.js

@@ -134,6 +134,31 @@ export const VC3C_ENABLED = () => sprintFlag("MEGACOMPACT_VC3C");
  * dashboard shards aggregate view.
  */
 export const VC4A_ENABLED = () => sprintFlag("MEGACOMPACT_VC4A");
+/**
+ * VC4B — residual codec and numeric parity (ResidualCodecV1 / ParityShardV1).
+ * Default ON. `MEGACOMPACT_VC4B=0` disables and is byte-identical to the
+ * predecessor (mode C: no residual artifact is admitted, the exact compressed
+ * payload / ledger bytes remain the only representation, zero
+ * `vector_cortex_residual_admitted` / `vector_cortex_parity_recovery_failed`
+ * emissions; the VC4A shard manifest and its goldens are unchanged). The real
+ * consumers are the codec admission seam (codec.ts) and the reader-only
+ * dashboard residual aggregate view. The codec math itself is PURE — flag OFF
+ * gates the reporter/admission seam, never the arithmetic.
+ */
+export const VC4B_ENABLED = () => sprintFlag("MEGACOMPACT_VC4B");
+/**
+ * VC4C — reconstruction fidelity (closure + assemble + validate). Default ON.
+ * `MEGACOMPACT_VC4C=0` disables and is byte-identical to the predecessor
+ * (VC4B): no conservative closure is computed, the reconstruction validator's
+ * `vector_cortex_reconstruction_validated` / `vector_cortex_closure_rejected`
+ * events are never emitted, and the assembled reconstruction is never produced
+ * (the prompt continues to be built by the legacy VC4B exact/residual path and
+ * the VC4A shard goldens are unchanged). The closure/assemble/validate
+ * functions are PURE — flag OFF gates the reporter seam, never the arithmetic.
+ * This flag MUST also be a dashboard SETTINGS toggle (visible in config UI,
+ * never in EXCLUDED_SETTINGS), mirroring VC4A/VC4B.
+ */
+export const VC4C_ENABLED = () => sprintFlag("MEGACOMPACT_VC4C");
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/dist/src/config.js

@@ -114,4 +114,4 @@ export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
 // default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
 // so root consumers share one source of truth.
 // ---------------------------------------------------------------------------
-export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";

package/dist/src/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] };
+}