pi-mega-compact 0.20.0 → 0.20.1

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

@@ -0,0 +1,124 @@
+/**
+ * vector-cortex/residual/stream.ts — canonical PROTECTED STREAM serialization
+ * for the VC4B residual codec.
+ *
+ * The protected stream is `header + all block scales/coefficient arrays +
+ * corrections` (RESIDUAL_CODEC §erasure parity), serialized in exactly this
+ * canonical order so encode and decode are byte-symmetric:
+ *
+ *   header (46 bytes)  magic `VCR1` | u32 LE originalLength | 32-byte SHA-256
+ *                      | u16 LE blockSize | u16 LE k | u16 LE m
+ *   blocks             for each block in ascending index:
+ *                        float32 LE scale | 4096 * int16 LE coefficient
+ *   corrections        varint blockCount, then per non-empty block
+ *                        u32 LE blockIndex | varint count
+ *                        | count * (u16 LE offset, u8 original)
+ *
+ * Pure serialization: no storage, no console, no network (PREVENT-PI-004 /
+ * PREVENT-011).
+ */
+import { parseCorrections, serializeCorrections, } from "./quantize.js";
+import { RESIDUAL_BLOCK_SIZE, RESIDUAL_HEADER_BYTES, RESIDUAL_MAGIC, RS_DATA_SHARDS, RS_PARITY_SHARDS, } from "./types.js";
+/** Per-block serialized size: float32 scale + n int16 coefficients. */
+export function blockBytes(blockSize = RESIDUAL_BLOCK_SIZE) {
+    return 4 + blockSize * 2;
+}
+/** Serialize the canonical 46-byte header. */
+export function serializeHeader(header) {
+    const out = new Uint8Array(RESIDUAL_HEADER_BYTES);
+    const view = new DataView(out.buffer);
+    for (let i = 0; i < 4; i++)
+        out[i] = RESIDUAL_MAGIC.charCodeAt(i);
+    view.setUint32(4, header.originalLength, true);
+    const digest = Buffer.from(header.payloadDigest, "hex");
+    out.set(digest.subarray(0, 32), 8);
+    view.setUint16(40, header.blockSize, true);
+    view.setUint16(42, header.dataShards, true);
+    view.setUint16(44, header.parityShards, true);
+    return out;
+}
+/** Parse the canonical header. Returns null on magic/geometry mismatch. */
+export function parseHeader(bytes) {
+    if (bytes.length < RESIDUAL_HEADER_BYTES)
+        return null;
+    for (let i = 0; i < 4; i++) {
+        if (bytes[i] !== RESIDUAL_MAGIC.charCodeAt(i))
+            return null;
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const originalLength = view.getUint32(4, true);
+    const payloadDigest = Buffer.from(bytes.subarray(8, 40)).toString("hex");
+    const blockSize = view.getUint16(40, true);
+    const dataShards = view.getUint16(42, true);
+    const parityShards = view.getUint16(44, true);
+    if (blockSize !== RESIDUAL_BLOCK_SIZE)
+        return null;
+    if (dataShards !== RS_DATA_SHARDS || parityShards !== RS_PARITY_SHARDS)
+        return null;
+    return {
+        magic: RESIDUAL_MAGIC,
+        originalLength,
+        payloadDigest,
+        blockSize: RESIDUAL_BLOCK_SIZE,
+        dataShards: RS_DATA_SHARDS,
+        parityShards: RS_PARITY_SHARDS,
+    };
+}
+/** Serialize the full protected stream for one encoded artifact. */
+export function serializeStream(codec) {
+    const head = serializeHeader(codec.header);
+    const perBlock = blockBytes(codec.header.blockSize);
+    const corrections = serializeCorrections(codec.corrections);
+    const out = new Uint8Array(head.length + codec.blocks.length * perBlock + corrections.length);
+    out.set(head, 0);
+    const view = new DataView(out.buffer);
+    let pos = head.length;
+    for (const block of codec.blocks) {
+        view.setFloat32(pos, block.scale, true);
+        pos += 4;
+        for (let i = 0; i < block.coefficients.length; i++) {
+            view.setInt16(pos, block.coefficients[i], true);
+            pos += 2;
+        }
+    }
+    out.set(corrections, pos);
+    return out;
+}
+/** Parse a protected stream back into the codec artifact. Null on malformed. */
+export function parseStream(stream) {
+    const header = parseHeader(stream);
+    if (!header)
+        return null;
+    const perBlock = blockBytes(header.blockSize);
+    const blockCount = Math.ceil(header.originalLength / header.blockSize);
+    const bodyEnd = RESIDUAL_HEADER_BYTES + blockCount * perBlock;
+    if (stream.length < bodyEnd)
+        return null;
+    const view = new DataView(stream.buffer, stream.byteOffset, stream.byteLength);
+    const blocks = [];
+    let pos = RESIDUAL_HEADER_BYTES;
+    for (let b = 0; b < blockCount; b++) {
+        const scale = view.getFloat32(pos, true);
+        pos += 4;
+        const coefficients = new Int16Array(header.blockSize);
+        for (let i = 0; i < header.blockSize; i++) {
+            coefficients[i] = view.getInt16(pos, true);
+            pos += 2;
+        }
+        blocks.push({ scale, coefficients });
+    }
+    const parsed = parseCorrections(stream, pos);
+    if (!parsed)
+        return null;
+    // Every correction must name a block that exists.
+    for (const block of parsed.blocks) {
+        if (block.blockIndex >= blockCount)
+            return null;
+    }
+    return {
+        schema: "residual-codec-v1",
+        header,
+        blocks,
+        corrections: parsed.blocks,
+    };
+}

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

@@ -0,0 +1,55 @@
+/**
+ * vector-cortex/residual/types.ts — reversible residual payload codec (VC4B).
+ *
+ * Owns `ResidualCodecV1` / `ParityShardV1` — the contract of the sprint failure
+ * triad:
+ *
+ *   A = admitted residual (DCT + int16 + exact corrections) + RS(9,6) parity;
+ *   B = exact compressed bytes (forced when the >95% accounting rejects A);
+ *   C = ledger bytes (forced when A/B decode fails).
+ *
+ * Semantic vectors NEVER claim to recover exact text. Exact bytes come only from
+ * exact payload shards (VC4A `ExactShardV1`) or this REVERSIBLE codec: a block
+ * DCT-II analysis, int16 quantization, and a block-scoped exact correction
+ * stream that makes post-decode byte error exactly zero for admitted artifacts.
+ * Numeric erasure parity protects the codec bytes; it is not a substitute for
+ * the exact payload (RESIDUAL_CODEC.md).
+ *
+ * Consumes only reviewer-accepted predecessor contracts (VC1A EventV2 bytes via
+ * VC4A shard ranges) and the common contracts. Pure types + registered
+ * conformance IDs: no storage, no console, no network (PREVENT-PI-004 /
+ * PREVENT-011).
+ */
+/** Fixed transform block length (RESIDUAL_CODEC §byte scope: 4096). */
+export const RESIDUAL_BLOCK_SIZE = 4096;
+/** Reed–Solomon shard geometry: k=6 data shards, m=3 parity shards. */
+export const RS_DATA_SHARDS = 6;
+export const RS_PARITY_SHARDS = 3;
+export const RS_TOTAL_SHARDS = RS_DATA_SHARDS + RS_PARITY_SHARDS;
+/** GF(2^8) primitive polynomial for the parity field (0x11d). */
+export const GF_PRIMITIVE_POLYNOMIAL = 0x11d;
+/** Header magic bytes `VCR1`. */
+export const RESIDUAL_MAGIC = "VCR1";
+/**
+ * Admission ratio: residual is admitted only when its FULL encoded size is at
+ * most `floor(0.95 * exactCompressedSize)` (RESIDUAL_CODEC §admission). The
+ * accounting counts every persisted byte — header, scales, coefficients,
+ * corrections, shard metadata, all 9 shards, and digests.
+ */
+export const ADMISSION_NUMERATOR = 95;
+export const ADMISSION_DENOMINATOR = 100;
+/** Serialized header byte length: 4 + 4 + 32 + 2 + 2 + 2. */
+export const RESIDUAL_HEADER_BYTES = 46;
+/**
+ * Registered RES conformance ID range (RES-001..050). The acceptance test reads
+ * these rows from the v2 manifest and asserts each returns its manifest
+ * `ok`/`code`. The three named assertions (RES-DCT-001 / RES-RS-002 /
+ * RES-ADMIT-003) live alongside them.
+ */
+export const RES_IDS = Array.from({ length: 50 }, (_v, i) => `RES-${String(i + 1).padStart(3, "0")}`);
+/** Named RES conformance assertions (the sprint's headline rows). */
+export const RES_NAMED_IDS = [
+    "RES-DCT-001",
+    "RES-RS-002",
+    "RES-ADMIT-003",
+];

package/extensions/dashboard-server/api-contracts/vector-cortex.ts

@@ -201,6 +201,35 @@ export interface VectorCortexShardsView {
   readonly updatedAt: string;
 }
 
+/**
+ * Reader-only residual-basis-parity aggregate for GET /api/vector-cortex/residual
+ * (VC4B). Purely an enabled-flag + COUNT/BYTE aggregate — encode attempts,
+ * admitted/rejected counts, recovery failures, and encoded/exact byte totals.
+ * Reader-only: NEVER exposes residual payloads, correction streams, shard bytes,
+ * or original source bytes (SECURITY_PRIVACY). The residual codec is pure
+ * in-memory logic in this sprint (no durable metrics store), so when no encode has
+ * been staged the aggregates are truthfully zero. Non-fatal: a missing state dir
+ * degrades to `enabled:false`.
+ */
+export interface VectorCortexResidualView {
+  /** Whether the VC4B residual basis parity flag is enabled in this process. */
+  readonly enabled: boolean;
+  /** Number of residual encode attempts observed by the process emitter. */
+  readonly encodeAttempts: number;
+  /** Number of payloads admitted under the 95% admission ceiling. */
+  readonly admittedCount: number;
+  /** Number of payloads rejected (failed encode or above ceiling). */
+  readonly rejectedCount: number;
+  /** Number of parity recoveries that failed closed (RES_TOO_MANY_ERASURES). */
+  readonly recoveryFailures: number;
+  /** Total encoded artifact bytes across admitted payloads. */
+  readonly encodedByteTotal: number;
+  /** Total exact-compressed bytes across admitted payloads (denominator). */
+  readonly exactByteTotal: number;
+  /** ISO timestamp of the snapshot. */
+  readonly updatedAt: string;
+}
+
 /**
  * Reader-only occurrence-ledger view for GET /api/vector-cortex/ledger (VC1B).
  * Built on the LedgerReader capability surface. Exposes occurrence IDENTITY

package/extensions/dashboard-server/routes-rag-settings-helpers.ts

@@ -355,6 +355,12 @@ export const SETTINGS: ReadonlyArray<{
 				"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,
+			),
 		],
 	},
 	{

package/extensions/dashboard-server/routes-vector-cortex-residual.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteContext } from "./routes-core.js";
+import { VC4B_ENABLED } from "../../src/config.js";
+import { sendJson } from "./routes-vector-cortex-shared.js";
+import type { VectorCortexResidualView } from "./api-contracts/vector-cortex.js";
+
+/**
+ * Reader-only GET /api/vector-cortex/residual (VC4B).
+ */
+export function handleVectorCortexResidual(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  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: VectorCortexResidualView = {
+    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/extensions/dashboard-server/routes-vector-cortex.ts

@@ -20,3 +20,4 @@ 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";

package/extensions/dashboard-server/routes.ts

@@ -48,4 +48,5 @@ export {
 	handleVectorCortexTopology,
 	handleVectorCortexQuery,
 	handleVectorCortexShards,
+	handleVectorCortexResidual,
 } from "./routes-vector-cortex.js";

package/extensions/dashboard-server/server.ts

@@ -64,6 +64,7 @@ import {
 	handleVectorCortexTopology,
 	handleVectorCortexQuery,
 	handleVectorCortexShards,
+	handleVectorCortexResidual,
 	handleStatic,
 } from "./routes.js";
 
@@ -306,6 +307,7 @@ export async function launchDashboardServer(
 		if (handleVectorCortexTopology(req, res, ctx)) return;
 		if (handleVectorCortexQuery(req, res, ctx)) return;
 		if (handleVectorCortexShards(req, res, ctx)) return;
+		if (handleVectorCortexResidual(req, res, ctx)) return;
 		handleStatic(req, res, ctx);
 	});
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.0",
+  "version": "0.20.1",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",

package/src/config/vector-cortex.ts

@@ -147,6 +147,19 @@ export const VC3C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC3C");
  */
 export const VC4A_ENABLED = (): boolean => 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 = (): boolean => sprintFlag("MEGACOMPACT_VC4B");
+
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/src/config.ts

@@ -164,6 +164,7 @@ export {
   VC3B_ENABLED,
   VC3C_ENABLED,
   VC4A_ENABLED,
+  VC4B_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

package/src/vector-cortex/residual/codec.ts

@@ -0,0 +1,292 @@
+/**
+ * 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,
+  type BlockCorrectionsV1,
+  type ParityShardV1,
+  type QuantizedBlockV1,
+  type ResidualAccountingV1,
+  type ResidualCodecV1,
+  type ResidualDecodeResult,
+  type ResidualEmitter,
+  type ResidualEncodeResult,
+  type ResidualMetricsV1,
+  type ResidualReporter,
+} 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: number): number {
+  return Math.floor(
+    (exactCompressedSize * ADMISSION_NUMERATOR) / ADMISSION_DENOMINATOR,
+  );
+}
+
+/** Total persisted bytes of the shard set (payload + per-shard metadata). */
+export function shardSetBytes(shards: readonly ParityShardV1[]): number {
+  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: Uint8Array,
+): { ok: true; codec: ResidualCodecV1 } | { ok: false; code: "RES_QUANTIZE_RANGE" } {
+  const digest = sha256Hex(payload);
+  const rawBlocks = splitBlocks(payload, RESIDUAL_BLOCK_SIZE);
+  const blocks: QuantizedBlockV1[] = [];
+  const corrections: BlockCorrectionsV1[] = [];
+
+  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: Uint8Array,
+  exactCompressedSize: number,
+  emit?: ResidualEmitter,
+): ResidualEncodeResult {
+  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: ResidualAccountingV1 = {
+    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: readonly ParityShardV1[],
+  emit?: ResidualEmitter,
+): ResidualDecodeResult {
+  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: ResidualCodecV1): ResidualDecodeResult {
+  const blockSize = codec.header.blockSize;
+  const out = new Uint8Array(codec.blocks.length * blockSize);
+  const byIndex = new Map<number, readonly { offset: number; original: number }[]>();
+  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: Uint8Array): string {
+  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: ResidualMetricsV1,
+  result: ResidualEncodeResult,
+): ResidualMetricsV1 {
+  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(): ResidualMetricsV1 {
+  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?: ResidualEmitter): ResidualReporter {
+  const fire = (
+    event: Parameters<ResidualEmitter>[0],
+    fields: Record<string, unknown>,
+  ): void => {
+    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);
+    },
+  };
+}