pi-mega-compact 0.20.0 → 0.20.2

package/dist/vector-cortex/reconstruct/closure.js

@@ -0,0 +1,268 @@
+/**
+ * vector-cortex/reconstruct/closure.ts — mandatory conservative closure (VC4C).
+ *
+ * Task 2/3: a WORKLIST recursion that repeatedly adds every `depends`
+ * predecessor and every whole tool pair of an already-selected node until the
+ * selection stops growing (a FIXED POINT), tracking visited ids so a cyclic
+ * graph terminates instead of recursing forever. Task 3: contradictions are
+ * resolved by retaining the LATER exact source resolution; an explicit
+ * resolution event may name the loser directly; equal/unordered resolutions are
+ * an unresolved tie and return `CLO_CONTRADICTION_UNRESOLVED` so the candidate
+ * never goes live (CONTRACTS §plan and closure).
+ *
+ * Determinism: the worklist is drained in sorted id order and every returned
+ * array is sorted, so the closed set is identical regardless of the order seeds
+ * or edges were supplied in. Time is never read here — contradiction ordering
+ * uses the SOURCE `resolvedAtMs` fact carried on the node.
+ *
+ * OWNERSHIP: `mandatoryTokenEstimate` is CONTENT ONLY (no prompt framing) and is
+ * handed unchanged to VC5A, which owns framing + budget admission and returns
+ * `MANDATORY_CLOSURE_OVER_BUDGET` on overflow. Closure NEVER truncates a
+ * mandatory node.
+ *
+ * Pure/deterministic: no storage, no console, no network (PREVENT-PI-004 /
+ * PREVENT-011).
+ */
+/** Sorted copy (bytewise id order) — every closure output is order-stable. */
+function sortedIds(ids) {
+    return [...ids].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+/** Index the graph's nodes by id (last wins is impossible — ids are unique). */
+function indexNodes(graph) {
+    const byId = new Map();
+    for (const n of graph.nodes)
+        byId.set(n.id, n);
+    return byId;
+}
+/**
+ * Build the "requirement" adjacency: for a selected node `x`, which nodes must
+ * ALSO be selected. Edges point prerequisite `from` → dependent `to`, so:
+ *
+ *   - `depends`   — selecting `to` requires `from` (walk BACKWARD to the
+ *                   prerequisite; this is the transitive dependency closure);
+ *   - `tool-pair` — the pair is atomic, so selecting EITHER endpoint requires
+ *                   the other (walk BOTH directions — a pair is never split,
+ *                   PREVENT-PI-002).
+ *
+ * `contradicts` is deliberately absent: a contradiction never PULLS a node in,
+ * it removes one (resolved separately below).
+ */
+function buildRequirements(edges) {
+    const req = new Map();
+    const add = (key, id, rule) => {
+        const list = req.get(key);
+        if (list === undefined)
+            req.set(key, [{ id, rule }]);
+        else
+            list.push({ id, rule });
+    };
+    for (const e of edges) {
+        if (e.kind === "depends") {
+            add(e.to, e.from, "depends");
+            continue;
+        }
+        if (e.kind === "tool-pair") {
+            add(e.to, e.from, "tool-pair");
+            add(e.from, e.to, "tool-pair");
+        }
+    }
+    return req;
+}
+/**
+ * Resolve one contradiction pair. Returns the loser id, or `null` when the pair
+ * is an unresolved tie.
+ *
+ * Precedence (CONTRACTS §plan and closure):
+ *   1. An explicit resolution event naming the loser wins outright.
+ *   2. Otherwise the LATER exact source resolution supersedes the earlier claim.
+ *      "Exact" is required: a semantic node never supersedes an exact one, since
+ *      semantic vectors never claim to recover exact text (RESIDUAL_CODEC).
+ *   3. Equal timestamps, missing timestamps, or two non-exact claims are
+ *      UNORDERED — keep both and reject live use.
+ */
+function resolveContradiction(a, b, explicit) {
+    // 1. Explicit resolution event names the loser directly.
+    const aLoses = explicit.get(a.id);
+    if (aLoses === b.id)
+        return a.id;
+    const bLoses = explicit.get(b.id);
+    if (bLoses === a.id)
+        return b.id;
+    // 2. Later EXACT source resolution supersedes the earlier claim. Both sides
+    //    must be exact and both must carry a source resolution time.
+    const aExact = a.kind === "exact";
+    const bExact = b.kind === "exact";
+    const aAt = a.resolvedAtMs;
+    const bAt = b.resolvedAtMs;
+    if (aExact && bExact && aAt !== undefined && bAt !== undefined && aAt !== bAt) {
+        return aAt < bAt ? a.id : b.id;
+    }
+    // 3. Equal / unordered / non-exact — unresolved tie.
+    return null;
+}
+/**
+ * Close a selection conservatively to a fixed point (task 2 + 3).
+ *
+ * Algorithm: seed the worklist with the requested ids (plus the anchor floor,
+ * which is always mandatory), then repeatedly pop the smallest id and add every
+ * node it requires. A `visited` set makes each node expand exactly once, so a
+ * cycle (`a depends b`, `b depends a`) terminates at the fixed point rather than
+ * recursing forever. Contradictions among the CLOSED set are then resolved; an
+ * unresolved tie fails the closure.
+ */
+export function closeSelection(input) {
+    const { graph, seeds } = input;
+    const byId = indexNodes(graph);
+    const failures = [];
+    // Structural validation: every edge endpoint and every seed must exist.
+    for (const e of graph.edges) {
+        if (!byId.has(e.from) || !byId.has(e.to)) {
+            if (!failures.includes("CLO_MISSING_NODE"))
+                failures.push("CLO_MISSING_NODE");
+        }
+    }
+    for (const s of seeds) {
+        if (!byId.has(s)) {
+            if (!failures.includes("CLO_UNKNOWN_SEED"))
+                failures.push("CLO_UNKNOWN_SEED");
+        }
+    }
+    if (failures.length > 0) {
+        return {
+            ok: false,
+            selected: [],
+            addedDependencies: [],
+            removedContradictions: [],
+            unresolved: [],
+            proof: [],
+            failures,
+            mandatoryTokenEstimate: 0,
+        };
+    }
+    const requirements = buildRequirements(graph.edges);
+    const selected = new Set();
+    const proof = [];
+    const seedSet = new Set(seeds);
+    // The anchor floor is ALWAYS mandatory: an anchor is never dropped by closure
+    // (PREVENT-PI-001's anchor-floor discipline restated for the closed prompt).
+    const anchorIds = graph.nodes.filter((n) => n.anchor === true).map((n) => n.id);
+    // Seed the worklist deterministically (sorted), anchors after explicit seeds
+    // so the proof reads "what was asked for, then what the floor forced".
+    const worklist = [];
+    for (const id of sortedIds(seedSet)) {
+        if (selected.has(id))
+            continue;
+        selected.add(id);
+        proof.push({ added: id, rule: "seed" });
+        worklist.push(id);
+    }
+    for (const id of sortedIds(anchorIds)) {
+        if (selected.has(id))
+            continue;
+        selected.add(id);
+        proof.push({ added: id, rule: "anchor-floor" });
+        worklist.push(id);
+    }
+    // ── Worklist recursion to a FIXED POINT (visited = `selected`) ─────────────
+    // Each id is expanded at most once because it can only enter the worklist at
+    // the moment it is inserted into `selected`. A cyclic graph therefore
+    // terminates: the second traversal of the cycle finds every node already
+    // selected and adds nothing.
+    while (worklist.length > 0) {
+        // Drain in sorted order so the proof is deterministic across input orders.
+        worklist.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+        const current = worklist.shift();
+        if (current === undefined)
+            break;
+        const required = requirements.get(current) ?? [];
+        // Sort the requirements of one node so sibling additions are ordered too.
+        const ordered = [...required].sort((x, y) => x.id < y.id ? -1 : x.id > y.id ? 1 : x.rule < y.rule ? -1 : x.rule > y.rule ? 1 : 0);
+        for (const { id, rule } of ordered) {
+            if (selected.has(id))
+                continue; // already at the fixed point for this node
+            selected.add(id);
+            proof.push({ added: id, requiredBy: current, rule });
+            worklist.push(id);
+        }
+    }
+    // ── Contradiction resolution over the CLOSED set (task 3) ─────────────────
+    const explicit = new Map();
+    for (const r of graph.resolutions ?? [])
+        explicit.set(r.loserId, r.winnerId);
+    const removed = new Set();
+    const unresolved = new Set();
+    for (const e of graph.edges) {
+        if (e.kind !== "contradicts")
+            continue;
+        // Only contradictions BETWEEN TWO SELECTED nodes matter: an unselected claim
+        // cannot contradict the prompt that is actually being built.
+        if (!selected.has(e.from) || !selected.has(e.to))
+            continue;
+        const a = byId.get(e.from);
+        const b = byId.get(e.to);
+        if (a === undefined || b === undefined)
+            continue;
+        // A pair already decided by an earlier edge (duplicate contradiction) is
+        // skipped so one resolution is not re-litigated into a false tie.
+        if (removed.has(a.id) || removed.has(b.id))
+            continue;
+        const loser = resolveContradiction(a, b, explicit);
+        if (loser === null) {
+            unresolved.add(a.id);
+            unresolved.add(b.id);
+            continue;
+        }
+        removed.add(loser);
+    }
+    // A node that lost a contradiction leaves the selection. An unresolved tie
+    // keeps BOTH (CONTRACTS: "ties keep both and reject live use") and fails.
+    for (const id of removed)
+        selected.delete(id);
+    const selectedIds = sortedIds(selected);
+    const addedDependencies = selectedIds.filter((id) => !seedSet.has(id));
+    const mandatoryTokenEstimate = selectedIds.reduce((sum, id) => sum + (byId.get(id)?.tokenEstimate ?? 0), 0);
+    const ok = unresolved.size === 0;
+    return {
+        ok,
+        selected: selectedIds,
+        addedDependencies,
+        removedContradictions: sortedIds(removed),
+        unresolved: sortedIds(unresolved),
+        proof,
+        failures: ok ? [] : ["CLO_CONTRADICTION_UNRESOLVED"],
+        mandatoryTokenEstimate,
+    };
+}
+/**
+ * Whether a closure result is a genuine fixed point: re-running the closure over
+ * its own output adds nothing. Used by the acceptance invariant ("closure reaches
+ * a fixed point") — an independent CHECK rather than a restatement of the loop.
+ */
+export function isFixedPoint(graph, result) {
+    if (!result.ok)
+        return true; // a rejected closure is not required to be closed
+    const again = closeSelection({ graph, seeds: result.selected });
+    if (!again.ok)
+        return false;
+    return (again.selected.length === result.selected.length &&
+        again.selected.every((id, i) => id === result.selected[i]));
+}
+/**
+ * Mode B: a GREEDY EXACT-ONLY closure, forced when semantic validation fails.
+ * Independent of mode A by construction — it consults no semantic node and no
+ * semantic index, deriving purely from the exact/event source tiers
+ * (TRIAD_RESILIENCE: A/B must not share the same algorithm or index).
+ */
+export function closeExactOnly(input) {
+    const exactGraph = {
+        sessionId: input.graph.sessionId,
+        nodes: input.graph.nodes.filter((n) => n.kind !== "semantic"),
+        edges: input.graph.edges.filter((e) => {
+            const kinds = new Map(input.graph.nodes.map((n) => [n.id, n.kind]));
+            return kinds.get(e.from) !== "semantic" && kinds.get(e.to) !== "semantic";
+        }),
+        resolutions: input.graph.resolutions,
+    };
+    const seeds = input.seeds.filter((id) => exactGraph.nodes.some((n) => n.id === id));
+    return closeSelection({ graph: exactGraph, seeds });
+}

package/dist/vector-cortex/reconstruct/types.js

@@ -0,0 +1,46 @@
+/**
+ * vector-cortex/reconstruct/types.ts — conservative closure + reconstruction
+ * fidelity contract (VC4C).
+ *
+ * Owns `ClosureResult` / `ReconstructionV1` — the contract of the sprint failure
+ * triad:
+ *
+ *   A = closed semantic + exact/residual reconstruction (the normal path);
+ *   B = greedy EXACT-only closure, forced when semantic validation fails;
+ *   C = legacy prompt, forced by an unresolved contradiction (states its loss of
+ *       old semantic context — TRIAD_RESILIENCE: C is continuity, NOT semantic
+ *       completeness).
+ *
+ * Closure is MANDATORY before VC5 (CONTRACTS §plan and closure): recursively add
+ * every `depends`/tool-pair predecessor until a fixed point; for contradictions
+ * keep the LATER exact source resolution unless an explicit resolution event
+ * names the loser; ties keep both and reject live use
+ * (`CLO_CONTRADICTION_UNRESOLVED`). The anchor floor is preserved, and the closed
+ * mandatory node set is returned with its deterministic token estimate.
+ *
+ * OWNERSHIP BOUNDARY (CONTRACTS §plan and closure): `mandatoryTokenEstimate`
+ * counts CONTENT ONLY — no prompt framing, no role tags, no separators, no
+ * budget admission. VC5A exclusively owns framing/budget: it adds framing cost
+ * to this estimate and returns `MANDATORY_CLOSURE_OVER_BUDGET` if the mandatory
+ * cost exceeds its `tokenBudget`. VC4C therefore NEVER truncates a mandatory
+ * node and never reasons about a budget.
+ *
+ * Consumes only reviewer-accepted predecessor contracts (VC1A `EventV2` byte
+ * authority, VC4A `ShardRange`/`ExactShardV1`, VC4B `ParityShardV1` residual
+ * decode) and the common contracts. Pure types + registered conformance IDs: no
+ * storage, no console, no network (PREVENT-PI-004 / PREVENT-011).
+ */
+/**
+ * Registered CLO conformance ID range (CLO-001..030). The acceptance test reads
+ * these rows from the v2 manifest and asserts each returns its manifest
+ * `ok`/`code`.
+ */
+export const CLO_IDS = Array.from({ length: 30 }, (_v, i) => `CLO-${String(i + 1).padStart(3, "0")}`);
+/** Registered REC conformance ID range (REC-001..030). */
+export const REC_IDS = Array.from({ length: 30 }, (_v, i) => `REC-${String(i + 1).padStart(3, "0")}`);
+/** Named VC4C conformance assertions (the sprint's headline rows). */
+export const RECONSTRUCT_NAMED_IDS = [
+    "CLO-TRANSITIVE-001",
+    "CLO-CONTRA-002",
+    "REC-ORDER-003",
+];

package/dist/vector-cortex/reconstruct/validate.js

@@ -0,0 +1,152 @@
+/**
+ * vector-cortex/reconstruct/validate.ts — reconstruction validation (VC4C).
+ *
+ * Task 5: a validator that rejects a closed selection that would corrupt a live
+ * prompt and emits exactly two events:
+ *   - `vector_cortex_reconstruction_validated`  (the good outcome)
+ *   - `vector_cortex_closure_rejected`          (a rejected/cancelled closure)
+ *
+ * Rejection reasons (the failure codes are the ONLY externally-visible detail):
+ *   - REC_ANCHOR_MISSING          an anchor-floor node is absent from the closure
+ *   - REC_TOOL_PAIR_SPLIT         a tool-pair is not contiguous (PREVENT-PI-002)
+ *   - REC_DIGEST_MISMATCH         a decoded shard's bytes disagree with its digest
+ *   - REC_CONTRADICTION_UNRESOLVED an unresolved tie (closure already failed)
+ *   - REC_SOURCE_UNAVAILABLE      a required shard is missing/erased (failure inj.)
+ *   - REC_SPAN_OVERLAP            two spans intersect in source byte space
+ *
+ * The validator NEVER emits content; it exposes only a `ReconstructionSummary`
+ * (counts + digest + token estimate) or the failure `codes`. Assembly/closure
+ * errors are surfaced but the validator is the authoritative last gate.
+ *
+ * OWNERSHIP: this is a PURE function over its inputs — no storage, no network,
+ * no console. The dashboard/seams that consume it live in extensions/, which may
+ * emit observability; this module stays silent (structured logging contract).
+ */
+import { createHash } from "node:crypto";
+import { assembleSourceOrder } from "./assemble.js";
+/** Flag-gated reporter — mirrors the VC4B residual reporter pattern. */
+export function createReconstructReporter(emit) {
+    const fire = (event, fields) => {
+        if (!emit)
+            return;
+        try {
+            emit(event, fields);
+        }
+        catch {
+            /* non-fatal observability — never break the agent loop */
+        }
+    };
+    return {
+        reconstructionValidated: (fields) => fire("vector_cortex_reconstruction_validated", fields),
+        closureRejected: (fields) => fire("vector_cortex_closure_rejected", fields),
+    };
+}
+/** Sync SHA-256 hex (validator is sync except for assembly's concat digest). */
+function sha256HexSync(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/** Verify each decoded shard's bytes hash to its declared digest (REC_DIGEST_MISMATCH). */
+function findDigestMismatch(shards) {
+    for (const s of shards) {
+        // A pinned digest of "0" is a placeholder: the source tier did not compute a
+        // per-shard digest, so the only guarantee is the post-assembly concatenation
+        // digest. Any other digest is a real pin that must match exactly.
+        if (s.digest === "0")
+            continue;
+        const computed = sha256HexSync(s.bytes);
+        if (computed !== s.digest)
+            return "REC_DIGEST_MISMATCH";
+    }
+    return null;
+}
+/**
+ * Validate a closed selection and, on success, assemble it into source order.
+ * Returns the discriminated `ReconstructionValidation`: ok -> summary only;
+ * fail -> failure codes only. Emits exactly one of the two events.
+ */
+export async function validateAndAssemble(input) {
+    const { graph, closure, nodes, edges, shards, emit } = input;
+    const reporter = createReconstructReporter(emit);
+    // 1. A closure that failed its own contradiction resolution cannot go live.
+    if (!closure.ok) {
+        const codes = ["REC_CONTRADICTION_UNRESOLVED"];
+        reporter.closureRejected({ sessionId: graph.sessionId, codes, reason: "closure-not-ok" });
+        return {
+            validation: { ok: false, codes },
+            reconstruction: null,
+        };
+    }
+    // 2. Anchor-floor discipline (PREVENT-PI-001 restated): every anchor node must
+    //    be present in the closed set, or the closure silently dropped a floor
+    //    item and must be rejected.
+    const anchorMissing = nodes.some((n) => n.anchor === true && !closure.selected.includes(n.id));
+    if (anchorMissing) {
+        reporter.closureRejected({ sessionId: graph.sessionId, codes: ["REC_ANCHOR_MISSING"], reason: "anchor-missing" });
+        return {
+            validation: { ok: false, codes: ["REC_ANCHOR_MISSING"] },
+            reconstruction: null,
+        };
+    }
+    // 3. Unresolved contradiction present in the closed set.
+    if (closure.unresolved.length > 0) {
+        const codes = ["REC_CONTRADICTION_UNRESOLVED"];
+        reporter.closureRejected({ sessionId: graph.sessionId, codes, reason: "unresolved-contradiction" });
+        return {
+            validation: { ok: false, codes },
+            reconstruction: null,
+        };
+    }
+    // 4. Per-shard digest pre-check hook (REC_DIGEST_MISMATCH path preserved).
+    const digestCode = findDigestMismatch(shards);
+    if (digestCode !== null) {
+        reporter.closureRejected({ sessionId: graph.sessionId, codes: [digestCode], reason: "digest-mismatch" });
+        return {
+            validation: { ok: false, codes: [digestCode] },
+            reconstruction: null,
+        };
+    }
+    // 5. Assembly: missing source (REC_SOURCE_UNAVAILABLE) / split pair
+    //    (REC_TOOL_PAIR_SPLIT) / overlap (REC_SPAN_OVERLAP) all surface here.
+    const assembled = await assembleSourceOrder({
+        sessionId: graph.sessionId,
+        selected: closure.selected,
+        nodes,
+        edges,
+        shards,
+        mandatoryTokenEstimate: closure.mandatoryTokenEstimate,
+    });
+    if (assembled.code !== null || assembled.reconstruction === null) {
+        const code = assembled.code ?? "REC_DIGEST_MISMATCH";
+        reporter.closureRejected({ sessionId: graph.sessionId, codes: [code], reason: "assembly-failed" });
+        return {
+            validation: { ok: false, codes: [code] },
+            reconstruction: null,
+        };
+    }
+    const rec = assembled.reconstruction;
+    const summary = buildSummary(rec);
+    reporter.reconstructionValidated({
+        sessionId: rec.sessionId,
+        spanCount: summary.spanCount,
+        protectedSpanCount: summary.protectedSpanCount,
+        byteTotal: summary.byteTotal,
+        mandatoryTokenEstimate: summary.mandatoryTokenEstimate,
+        digest: summary.digest,
+        bySource: summary.bySource,
+    });
+    return { validation: { ok: true, summary }, reconstruction: rec };
+}
+function buildSummary(rec) {
+    const exact = rec.spans.filter((s) => s.source === "exact").length;
+    const residual = rec.spans.filter((s) => s.source === "residual").length;
+    const semantic = rec.spans.filter((s) => s.source === "semantic").length;
+    return {
+        sessionId: rec.sessionId,
+        spanCount: rec.spans.length,
+        protectedSpanCount: rec.spans.filter((s) => s.protectedSpan).length,
+        byteTotal: rec.byteTotal,
+        mandatoryTokenEstimate: rec.mandatoryTokenEstimate,
+        digest: rec.digest,
+        bySource: { exact, residual, semantic },
+    };
+}

package/dist/vector-cortex/residual/codec.js

@@ -0,0 +1,224 @@
+/**
+ * vector-cortex/residual/codec.ts — reversible residual payload codec (VC4B).
+ *
+ * Encode: split `EventV2.originalBytes` into 4096-byte blocks (zero-padding only
+ * the final block), map bytes to `x=(byte-127.5)/127.5`, take the orthonormal
+ * DCT-II, quantize to int16 with a per-block float32 scale, reconstruct, and
+ * append a block-scoped EXACT correction stream wherever the reconstruction
+ * differs. Post-decode byte error for an admitted artifact is therefore exactly
+ * ZERO — the digest is verified before admission, never assumed.
+ *
+ * Admission (RESIDUAL_CODEC §admission): residual is admitted only when the FULL
+ * encoded size — header, scales, coefficients, corrections, shard index/length
+ * metadata, all 9 shards and their digests — is `<= floor(0.95 *
+ * exactCompressedSize)` AND the complete decode + digest check succeeds.
+ * Otherwise the caller stores the exact compressed payload (mode B). Coefficient
+ * bytes alone are never compared.
+ *
+ * Emits `vector_cortex_residual_admitted` / `vector_cortex_parity_recovery_failed`
+ * through the flag-gated reporter and exposes AGGREGATE-ONLY residual metrics
+ * (counts/byte totals — never payload).
+ *
+ * Guardrails: local hashing only, no storage, no console, no network
+ * (PREVENT-PI-004 / PREVENT-011).
+ */
+import { createHash } from "node:crypto";
+import { VC4B_ENABLED } from "../../config/vector-cortex.js";
+import { bytesToSignal, forwardDct, inverseDct, signalToBytes, splitBlocks, } from "./dct.js";
+import { applyCorrections, dequantizeBlock, diffBlock, quantizeBlock, } from "./quantize.js";
+import { encodeShards, recoverStream, sha256Hex } from "./parity.js";
+import { parseStream, serializeStream } from "./stream.js";
+import { ADMISSION_DENOMINATOR, ADMISSION_NUMERATOR, RESIDUAL_BLOCK_SIZE, RESIDUAL_MAGIC, RS_DATA_SHARDS, RS_PARITY_SHARDS, } from "./types.js";
+/** Per-shard persisted metadata: u8 index + u32 LE length + 32-byte digest. */
+const SHARD_METADATA_BYTES = 1 + 4 + 32;
+/**
+ * The inclusive admission ceiling `floor(0.95 * exactCompressedSize)`, computed
+ * in integer arithmetic so the boundary is exact (a fractional 0.95 multiply
+ * would make the "one byte above rejects" case depend on float rounding).
+ */
+export function admissionCeiling(exactCompressedSize) {
+    return Math.floor((exactCompressedSize * ADMISSION_NUMERATOR) / ADMISSION_DENOMINATOR);
+}
+/** Total persisted bytes of the shard set (payload + per-shard metadata). */
+export function shardSetBytes(shards) {
+    return shards.reduce((n, s) => n + s.bytes.length + SHARD_METADATA_BYTES, 0);
+}
+/** Build the codec artifact (transform + quantize + exact corrections). */
+export function buildArtifact(payload) {
+    const digest = sha256Hex(payload);
+    const rawBlocks = splitBlocks(payload, RESIDUAL_BLOCK_SIZE);
+    const blocks = [];
+    const corrections = [];
+    for (let b = 0; b < rawBlocks.length; b++) {
+        const original = rawBlocks[b];
+        const quantized = quantizeBlock(forwardDct(bytesToSignal(original)));
+        if (!quantized.ok)
+            return { ok: false, code: "RES_QUANTIZE_RANGE" };
+        blocks.push(quantized.block);
+        // Reconstruct and diff: any residual byte error becomes an exact correction.
+        const reconstructed = signalToBytes(inverseDct(dequantizeBlock(quantized.block)));
+        const diff = diffBlock(original, reconstructed);
+        if (diff.length > 0)
+            corrections.push({ blockIndex: b, corrections: diff });
+    }
+    return {
+        ok: true,
+        codec: {
+            schema: "residual-codec-v1",
+            header: {
+                magic: RESIDUAL_MAGIC,
+                originalLength: payload.length,
+                payloadDigest: digest,
+                blockSize: RESIDUAL_BLOCK_SIZE,
+                dataShards: RS_DATA_SHARDS,
+                parityShards: RS_PARITY_SHARDS,
+            },
+            blocks,
+            corrections,
+        },
+    };
+}
+/**
+ * Encode a payload and decide admission against the competing exact compressed
+ * size. Admission requires BOTH the <=95% byte accounting AND a full decode whose
+ * digest matches the original payload.
+ */
+export function encodeResidual(payload, exactCompressedSize, emit) {
+    const built = buildArtifact(payload);
+    if (!built.ok)
+        return { ok: false, code: built.code };
+    const codec = built.codec;
+    const stream = serializeStream(codec);
+    const shards = encodeShards(stream);
+    const encodedSize = stream.length + shardSetBytes(shards);
+    const correctionCount = codec.corrections.reduce((n, b) => n + b.corrections.length, 0);
+    const accounting = {
+        encodedSize,
+        exactCompressedSize,
+        admissionCeiling: admissionCeiling(exactCompressedSize),
+        correctionCount,
+        blockCount: codec.blocks.length,
+    };
+    const reporter = createResidualReporter(emit);
+    if (encodedSize > accounting.admissionCeiling) {
+        return { ok: true, admitted: false, code: "RES_NOT_ADMITTED", accounting };
+    }
+    // Never admit without proving the full decode round-trips to the exact bytes.
+    const verified = decodeResidual(shards, emit);
+    if (!verified.ok)
+        return { ok: false, code: verified.code };
+    if (sha256Hex(verified.bytes) !== codec.header.payloadDigest) {
+        return { ok: false, code: "RES_PAYLOAD_DIGEST_MISMATCH" };
+    }
+    reporter.residualAdmitted({
+        encodedSize,
+        exactCompressedSize,
+        admissionCeiling: accounting.admissionCeiling,
+        blockCount: accounting.blockCount,
+        correctionCount,
+    });
+    return { ok: true, admitted: true, codec, shards, accounting };
+}
+/**
+ * Decode from a (possibly partial / partially corrupt) shard set: recover the
+ * protected stream, invert the transform, apply the exact corrections, truncate
+ * to the original length, and verify the payload digest.
+ */
+export function decodeResidual(shards, emit) {
+    const reporter = createResidualReporter(emit);
+    const recovered = recoverStream(shards);
+    if (!recovered.ok) {
+        reporter.parityRecoveryFailed({
+            code: recovered.code,
+            shardCount: shards.length,
+        });
+        return { ok: false, code: recovered.code };
+    }
+    const codec = parseStream(recovered.stream);
+    if (!codec) {
+        reporter.parityRecoveryFailed({
+            code: "RES_HEADER_INVALID",
+            shardCount: shards.length,
+        });
+        return { ok: false, code: "RES_HEADER_INVALID" };
+    }
+    return decodeArtifact(codec);
+}
+/** Decode a parsed artifact directly (no parity layer). */
+export function decodeArtifact(codec) {
+    const blockSize = codec.header.blockSize;
+    const out = new Uint8Array(codec.blocks.length * blockSize);
+    const byIndex = new Map();
+    for (const b of codec.corrections)
+        byIndex.set(b.blockIndex, b.corrections);
+    for (let b = 0; b < codec.blocks.length; b++) {
+        const reconstructed = signalToBytes(inverseDct(dequantizeBlock(codec.blocks[b])));
+        const applied = applyCorrections(reconstructed, byIndex.get(b) ?? []);
+        if (!applied.ok)
+            return { ok: false, code: applied.code };
+        out.set(reconstructed, b * blockSize);
+    }
+    const bytes = out.subarray(0, codec.header.originalLength);
+    if (sha256Hex(bytes) !== codec.header.payloadDigest) {
+        return { ok: false, code: "RES_PAYLOAD_DIGEST_MISMATCH" };
+    }
+    // Return an independent copy so the caller cannot alias the working buffer.
+    return { ok: true, bytes: Uint8Array.from(bytes) };
+}
+/** SHA-256 of arbitrary bytes (re-exported so callers need one import). */
+export function payloadDigest(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+// ── aggregate-only metrics + reporter ───────────────────────────────────────
+/**
+ * Accumulate AGGREGATE-ONLY residual metrics (counts/byte totals). Never
+ * payload, never prompt text: the dashboard reads this shape and nothing else.
+ */
+export function accumulateMetrics(previous, result) {
+    if (!result.ok) {
+        return { ...previous, encodeAttempts: previous.encodeAttempts + 1 };
+    }
+    const base = {
+        ...previous,
+        encodeAttempts: previous.encodeAttempts + 1,
+        encodedByteTotal: previous.encodedByteTotal + result.accounting.encodedSize,
+        exactByteTotal: previous.exactByteTotal + result.accounting.exactCompressedSize,
+    };
+    return result.admitted
+        ? { ...base, admittedCount: base.admittedCount + 1 }
+        : { ...base, rejectedCount: base.rejectedCount + 1 };
+}
+/** A zeroed metrics accumulator. */
+export function emptyMetrics() {
+    return {
+        encodeAttempts: 0,
+        admittedCount: 0,
+        rejectedCount: 0,
+        recoveryFailures: 0,
+        encodedByteTotal: 0,
+        exactByteTotal: 0,
+    };
+}
+/** Build the flag-gated typed reporter (mirrors the VC4A shard reporter). */
+export function createResidualReporter(emit) {
+    const fire = (event, fields) => {
+        if (!VC4B_ENABLED())
+            return;
+        if (!emit)
+            return;
+        try {
+            emit(event, fields);
+        }
+        catch {
+            /* non-fatal observability — never break the agent loop */
+        }
+    };
+    return {
+        residualAdmitted(fields) {
+            fire("vector_cortex_residual_admitted", fields);
+        },
+        parityRecoveryFailed(fields) {
+            fire("vector_cortex_parity_recovery_failed", fields);
+        },
+    };
+}