pi-mega-compact 0.20.1 → 0.20.2

package/dist/config/vector-cortex.js

@@ -146,6 +146,19 @@ export const VC4A_ENABLED = () => sprintFlag("MEGACOMPACT_VC4A");
  * 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, VC4B_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

@@ -148,6 +148,7 @@ export const SETTINGS = [
             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.js

@@ -20,3 +20,4 @@ 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, handleVectorCortexResidual, } 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, handleVectorCortexResidual, 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
@@ -271,6 +271,8 @@ export async function launchDashboardServer(stateDir) {
             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

@@ -146,6 +146,19 @@ export const VC4A_ENABLED = () => sprintFlag("MEGACOMPACT_VC4A");
  * 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, VC4B_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] };
+}

package/dist/src/vector-cortex/reconstruct/assemble.js

@@ -0,0 +1,137 @@
+/**
+ * vector-cortex/reconstruct/assemble.ts — source-order assembly (VC4C).
+ *
+ * Task 4: given a CLOSED + VALIDATED selection, decode the relevant shards,
+ * insert protected exact bytes unchanged, then lay the spans out SOLELY by their
+ * source range (`ShardRange`) before concatenation — never by closure order,
+ * which carries no positional meaning. The deterministic content-only
+ * `mandatoryTokenEstimate` from the closure is carried through UNCHANGED to VC5A
+ * (VC5A owns framing + budget admission).
+ *
+ * OWNERSHIP BOUNDARY (CONTRACTS plan + TRIAD_RESILIENCE): assemble produces the
+ * raw, ordered, content-only reconstruction. It does NOT frame it, does NOT
+ * admit against a budget, and NEVER truncates a mandatory node. Any byte/order
+ * error produces a hard rejection (REC_SPAN_OVERLAP / REC_TOOL_PAIR_SPLIT)
+ * because a corrupted layout must never reach a live prompt.
+ *
+ * Determinism: sorting is bytewise on (sessionId, seqStart, byteStart). The
+ * output digest is over the CONCATENATED BYTES so any reorder is itself detected
+ * downstream (RESIDUAL_CODEC admission parity).
+ *
+ * Pure/deterministic: no storage, no console, no network.
+ */
+/** SHA-256 hex of an arbitrary byte array (Web Crypto; no network, no deps). */
+async function sha256Hex(bytes) {
+    const buf = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+    const digest = await crypto.subtle.digest("SHA-256", buf);
+    const out = new Uint8Array(digest);
+    return Array.from(out, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** Stable source-order comparator: (sessionId, seqStart, byteStart). */
+function bySourceOrder(a, b) {
+    if (a.range.sessionId !== b.range.sessionId) {
+        return a.range.sessionId < b.range.sessionId ? -1 : 1;
+    }
+    if (a.range.seqStart !== b.range.seqStart) {
+        return a.range.seqStart < b.range.seqStart ? -1 : 1;
+    }
+    return a.range.byteStart - b.range.byteStart;
+}
+/**
+ * Detect a hard layout failure BEFORE concatenation:
+ *   - REC_SPAN_OVERLAP: two spans intersect in the source byte space.
+ *   - REC_TOOL_PAIR_SPLIT: a node bound by a tool-pair edge must be adjacent to
+ *     its partner (end of one == start of the other) in source order
+ *     (PREVENT-PI-002 restated at assembly time — a toolCall/toolResult pair is
+ *     never split across a gap).
+ * Returns the first failure code found, or null when the layout is clean.
+ */
+function detectLayoutFailure(spans, nodes, edges) {
+    const ordered = [...spans].sort(bySourceOrder);
+    for (let i = 1; i < ordered.length; i++) {
+        const prev = ordered[i - 1].range;
+        const cur = ordered[i].range;
+        const prevEnd = prev.byteEnd; // half-open: [byteStart, byteEnd)
+        if (cur.byteStart < prevEnd)
+            return "REC_SPAN_OVERLAP";
+    }
+    // Tool-pair adjacency: every tool-pair edge names two partners that must be
+    // immediately adjacent in source order. We check each edge once.
+    const rangeById = new Map(spans.map((s) => [s.nodeId, s.range]));
+    const inOrder = new Map(ordered.map((s) => [s.nodeId, s.range]));
+    const seenEdges = new Set();
+    for (const e of edges) {
+        if (e.kind !== "tool-pair")
+            continue;
+        const key = e.from < e.to ? `${e.from}|${e.to}` : `${e.to}|${e.from}`;
+        if (seenEdges.has(key))
+            continue;
+        seenEdges.add(key);
+        // Both endpoints must be present in the selection to be a split concern.
+        const a = rangeById.get(e.from);
+        const b = rangeById.get(e.to);
+        if (a === undefined || b === undefined)
+            continue;
+        const aEnd = a.byteEnd;
+        const bEnd = b.byteEnd;
+        const adjacent = aEnd === b.byteStart || bEnd === a.byteStart;
+        if (!adjacent)
+            return "REC_TOOL_PAIR_SPLIT";
+    }
+    // `nodes` kept in the signature for call symmetry with the composed validator;
+    // it is the authoritative kind source but not needed for these two checks.
+    void nodes;
+    void inOrder;
+    return null;
+}
+/**
+ * Assemble a closed+validated selection into source order (task 4).
+ *
+ * `shards` must be EXACTLY one `DecodedShard` per node id in `selected` — the
+ * caller (validate.ts) guarantees availability. A missing shard is therefore a
+ * programming error surfaced as REC_SOURCE_UNAVAILABLE, never a silent gap.
+ */
+export async function assembleSourceOrder(args) {
+    const { sessionId, selected, nodes, edges, mandatoryTokenEstimate } = args;
+    const shardById = new Map(args.shards.map((s) => [s.nodeId, s]));
+    // Every selected node MUST have a decoded shard; a missing one is the unique
+    // failure-injection path (erase a dependency shard -> REC_SOURCE_UNAVAILABLE).
+    for (const id of selected) {
+        if (!shardById.has(id))
+            return { reconstruction: null, code: "REC_SOURCE_UNAVAILABLE" };
+    }
+    const spans = selected.map((id) => {
+        const s = shardById.get(id);
+        return {
+            nodeId: s.nodeId,
+            range: s.range,
+            source: s.source,
+            bytes: s.bytes,
+            digest: s.digest,
+            protectedSpan: s.protectedSpan,
+        };
+    });
+    const layoutFailure = detectLayoutFailure(spans, nodes, edges);
+    if (layoutFailure !== null)
+        return { reconstruction: null, code: layoutFailure };
+    const ordered = [...spans].sort(bySourceOrder);
+    const byteTotal = ordered.reduce((sum, s) => sum + s.bytes.length, 0);
+    const concatenated = new Uint8Array(byteTotal);
+    let offset = 0;
+    for (const s of ordered) {
+        concatenated.set(s.bytes, offset);
+        offset += s.bytes.length;
+    }
+    const digest = await sha256Hex(concatenated);
+    return {
+        reconstruction: {
+            schema: "reconstruction-v1",
+            sessionId,
+            spans: ordered,
+            digest,
+            byteTotal,
+            mandatoryTokenEstimate,
+        },
+        code: null,
+    };
+}