pi-mega-compact 0.20.0 → 0.20.1

package/dist/config/vector-cortex.js

@@ -134,6 +134,18 @@ export const VC3C_ENABLED = () => sprintFlag("MEGACOMPACT_VC3C");
  * dashboard shards aggregate view.
  */
 export const VC4A_ENABLED = () => sprintFlag("MEGACOMPACT_VC4A");
+/**
+ * VC4B — residual codec and numeric parity (ResidualCodecV1 / ParityShardV1).
+ * Default ON. `MEGACOMPACT_VC4B=0` disables and is byte-identical to the
+ * predecessor (mode C: no residual artifact is admitted, the exact compressed
+ * payload / ledger bytes remain the only representation, zero
+ * `vector_cortex_residual_admitted` / `vector_cortex_parity_recovery_failed`
+ * emissions; the VC4A shard manifest and its goldens are unchanged). The real
+ * consumers are the codec admission seam (codec.ts) and the reader-only
+ * dashboard residual aggregate view. The codec math itself is PURE — flag OFF
+ * gates the reporter/admission seam, never the arithmetic.
+ */
+export const VC4B_ENABLED = () => sprintFlag("MEGACOMPACT_VC4B");
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/dist/config.js

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

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

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

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

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

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

@@ -19,3 +19,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/dist/extensions/dashboard-server/routes.js

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

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

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

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

@@ -134,6 +134,18 @@ export const VC3C_ENABLED = () => sprintFlag("MEGACOMPACT_VC3C");
  * dashboard shards aggregate view.
  */
 export const VC4A_ENABLED = () => sprintFlag("MEGACOMPACT_VC4A");
+/**
+ * VC4B — residual codec and numeric parity (ResidualCodecV1 / ParityShardV1).
+ * Default ON. `MEGACOMPACT_VC4B=0` disables and is byte-identical to the
+ * predecessor (mode C: no residual artifact is admitted, the exact compressed
+ * payload / ledger bytes remain the only representation, zero
+ * `vector_cortex_residual_admitted` / `vector_cortex_parity_recovery_failed`
+ * emissions; the VC4A shard manifest and its goldens are unchanged). The real
+ * consumers are the codec admission seam (codec.ts) and the reader-only
+ * dashboard residual aggregate view. The codec math itself is PURE — flag OFF
+ * gates the reporter/admission seam, never the arithmetic.
+ */
+export const VC4B_ENABLED = () => sprintFlag("MEGACOMPACT_VC4B");
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/dist/src/config.js

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

package/dist/src/vector-cortex/residual/dct.js

@@ -0,0 +1,158 @@
+/**
+ * vector-cortex/residual/dct.ts — orthonormal DCT-II basis V1 (VC4B).
+ *
+ * Basis V1 is the orthonormal DCT-II matrix generated ANALYTICALLY and never
+ * learned or stored (RESIDUAL_CODEC §byte scope):
+ *
+ *   alpha(0) = sqrt(1/n),  alpha(k>0) = sqrt(2/n)
+ *   C[k][i]  = alpha(k) * cos(pi * (2i + 1) * k / (2n))
+ *
+ * Forward coefficients are the dot product with each basis row (the orthonormal
+ * least-squares solve); the inverse is the transpose applied to the coefficient
+ * vector. Byte mapping is `x = (byte - 127.5) / 127.5`; the inverse maps back
+ * with round-to-nearest-even and clamps to 0..255.
+ *
+ * The full 4096x4096 matrix is ~134 MB of float64, so it is NEVER materialized.
+ * Instead the cosine argument `pi*(2i+1)*k/(2n)` is reduced modulo `2n` against
+ * a precomputed half-period table of length `2n` — this is EXACTLY the same set
+ * of cosine values the matrix would hold (cos is sampled only at the `2n`
+ * distinct arguments `pi*j/(2n)`, j = 0..2n-1), so the transform is bit-stable
+ * and table-generation is O(n) rather than O(n^2).
+ *
+ * Pure numeric transform: no storage, no console, no network (PREVENT-PI-004 /
+ * PREVENT-011).
+ */
+import { RESIDUAL_BLOCK_SIZE } from "./types.js";
+/** Byte-to-signal mapping midpoint / half-range (RESIDUAL_CODEC §transform). */
+const BYTE_MIDPOINT = 127.5;
+/**
+ * Cosine table cache keyed by block length. `table[j] = cos(pi * j / (2n))` for
+ * j = 0..2n-1; every DCT argument `pi*(2i+1)*k/(2n)` reduces to one of these
+ * entries (with a sign) because cos has period `2*pi` = index period `4n`.
+ */
+const cosTables = new Map();
+/** Build (or fetch) the `4n`-entry cosine table for block length `n`. */
+function cosTable(n) {
+    const cached = cosTables.get(n);
+    if (cached)
+        return cached;
+    const period = 4 * n;
+    const table = new Float64Array(period);
+    for (let j = 0; j < period; j++) {
+        table[j] = Math.cos((Math.PI * j) / (2 * n));
+    }
+    cosTables.set(n, table);
+    return table;
+}
+/** Orthonormal DCT-II row scale: alpha(0)=sqrt(1/n), else sqrt(2/n). */
+export function alpha(k, n) {
+    return k === 0 ? Math.sqrt(1 / n) : Math.sqrt(2 / n);
+}
+/**
+ * Map a padded byte block to the signal domain: `x = (byte - 127.5) / 127.5`.
+ * The input must be exactly `n` bytes (the caller zero-pads the final block).
+ */
+export function bytesToSignal(block) {
+    const out = new Float64Array(block.length);
+    for (let i = 0; i < block.length; i++) {
+        out[i] = (block[i] - BYTE_MIDPOINT) / BYTE_MIDPOINT;
+    }
+    return out;
+}
+/**
+ * Map a reconstructed signal back to bytes: invert the affine map, round to
+ * nearest with ties-to-even, and clamp to 0..255 (RESIDUAL_CODEC §transform).
+ */
+export function signalToBytes(signal) {
+    const out = new Uint8Array(signal.length);
+    for (let i = 0; i < signal.length; i++) {
+        const v = signal[i] * BYTE_MIDPOINT + BYTE_MIDPOINT;
+        const r = roundHalfToEven(v);
+        out[i] = r < 0 ? 0 : r > 255 ? 255 : r;
+    }
+    return out;
+}
+/**
+ * Round to nearest, ties to even (banker's rounding). `Math.round` rounds ties
+ * toward +Infinity, which is NOT the rule RESIDUAL_CODEC mandates.
+ */
+export function roundHalfToEven(v) {
+    const floor = Math.floor(v);
+    const diff = v - floor;
+    if (diff > 0.5)
+        return floor + 1;
+    if (diff < 0.5)
+        return floor;
+    // Exact tie: pick the even neighbour.
+    return floor % 2 === 0 ? floor : floor + 1;
+}
+/**
+ * Forward orthonormal DCT-II over one block of length `n` (default 4096).
+ * `coefficients[k] = alpha(k) * sum_i x[i] * cos(pi*(2i+1)*k/(2n))`, emitted in
+ * ascending frequency order `k = 0..n-1` (the exact RESIDUAL_CODEC coefficient
+ * order).
+ */
+export function forwardDct(signal) {
+    const n = signal.length;
+    const table = cosTable(n);
+    const period = 4 * n;
+    const out = new Float64Array(n);
+    for (let k = 0; k < n; k++) {
+        let sum = 0;
+        // Argument index advances by 2k each step, starting at k (i=0 gives
+        // (2*0+1)*k = k). Reduce modulo the 4n-entry period.
+        let idx = k % period;
+        const step = (2 * k) % period;
+        for (let i = 0; i < n; i++) {
+            sum += signal[i] * table[idx];
+            idx += step;
+            if (idx >= period)
+                idx -= period;
+        }
+        out[k] = alpha(k, n) * sum;
+    }
+    return out;
+}
+/**
+ * Inverse orthonormal DCT (the transpose of the forward matrix):
+ * `x[i] = sum_k alpha(k) * c[k] * cos(pi*(2i+1)*k/(2n))`.
+ */
+export function inverseDct(coefficients) {
+    const n = coefficients.length;
+    const table = cosTable(n);
+    const period = 4 * n;
+    // Pre-scale each coefficient by its row alpha so the inner loop is a plain
+    // dot product (identical arithmetic to scaling inside the loop for k, and it
+    // keeps the per-i accumulation order stable).
+    const scaled = new Float64Array(n);
+    for (let k = 0; k < n; k++)
+        scaled[k] = alpha(k, n) * coefficients[k];
+    const out = new Float64Array(n);
+    for (let i = 0; i < n; i++) {
+        let sum = 0;
+        const step = (2 * i + 1) % period;
+        let idx = 0;
+        for (let k = 0; k < n; k++) {
+            sum += scaled[k] * table[idx];
+            idx += step;
+            if (idx >= period)
+                idx -= period;
+        }
+        out[i] = sum;
+    }
+    return out;
+}
+/**
+ * Split a payload into fixed 4096-byte blocks, zero-padding ONLY the final
+ * block. The original length is retained by the caller (the header) so the
+ * padding is dropped on decode.
+ */
+export function splitBlocks(payload, blockSize = RESIDUAL_BLOCK_SIZE) {
+    const blocks = [];
+    for (let off = 0; off < payload.length; off += blockSize) {
+        const block = new Uint8Array(blockSize);
+        block.set(payload.subarray(off, Math.min(off + blockSize, payload.length)));
+        blocks.push(block);
+    }
+    return blocks;
+}

package/dist/src/vector-cortex/residual/fixture-payload.js

@@ -0,0 +1,77 @@
+/**
+ * vector-cortex/residual/fixture-payload.ts — deterministic payload
+ * materialization for the VC4B conformance corpus.
+ *
+ * The residual fixtures describe their payloads GENERATIVELY (`kind` + `length`
+ * + `seed`) rather than embedding megabytes of base64, so this module is the
+ * single normative generator both the fixture producer and the acceptance test
+ * agree on. Every generator is pure and deterministic — the same descriptor
+ * always yields byte-identical output, which is what makes the committed
+ * fixtures meaningful.
+ *
+ * Pure byte generation: no storage, no console, no network (PREVENT-PI-004 /
+ * PREVENT-011).
+ */
+/** Linear congruential generator (numerical-recipes constants), deterministic. */
+function lcgBytes(length, seed) {
+    const out = new Uint8Array(length);
+    let state = seed >>> 0;
+    for (let i = 0; i < length; i++) {
+        state = (Math.imul(state, 1664525) + 1013904223) >>> 0;
+        out[i] = (state >>> 24) & 0xff;
+    }
+    return out;
+}
+/**
+ * Materialize a fixture payload descriptor into exact bytes.
+ *
+ *   empty        zero bytes
+ *   zeros        `length` 0x00 bytes
+ *   constant     `length` copies of `value`
+ *   sequence     `i % 256`
+ *   lcg          deterministic pseudorandom stream from `seed`
+ *   text         repeating printable ASCII (valid UTF-8)
+ *   invalid-utf8 a stream containing lone continuation/overlong bytes
+ *   dc-outlier   all 0xff except one 0x00 at `outlierOffset` (forces the exact
+ *                correction stream: a DC-dominant block whose coarse scale
+ *                cannot reproduce the outlier's neighbourhood)
+ *   alternating  0x00/0xff alternation (maximum Nyquist energy)
+ */
+export function materializePayload(d) {
+    const length = d.length ?? 0;
+    switch (d.kind) {
+        case "empty":
+            return new Uint8Array(0);
+        case "zeros":
+            return new Uint8Array(length);
+        case "constant":
+            return new Uint8Array(length).fill((d.value ?? 0) & 0xff);
+        case "sequence":
+            return Uint8Array.from({ length }, (_v, i) => i % 256);
+        case "lcg":
+            return lcgBytes(length, d.seed ?? 1);
+        case "text": {
+            const alphabet = "abcdefghijklmnopqrstuvwxyz0123456789 ";
+            return Uint8Array.from({ length }, (_v, i) => alphabet.charCodeAt(i % alphabet.length));
+        }
+        case "invalid-utf8": {
+            // Deliberately invalid: lone 0x80 continuation, 0xff (never valid), and
+            // the overlong 0xc0 0xaf encoding of "/". Never normalized by the codec.
+            const pattern = [0xff, 0x80, 0xc0, 0xaf, 0x00, 0xfe];
+            return Uint8Array.from({ length }, (_v, i) => pattern[i % pattern.length]);
+        }
+        case "dc-outlier": {
+            const out = new Uint8Array(length).fill(255);
+            const at = d.outlierOffset ?? 0;
+            if (at < length)
+                out[at] = 0;
+            return out;
+        }
+        case "alternating":
+            return Uint8Array.from({ length }, (_v, i) => (i % 2 === 0 ? 0 : 255));
+        case "literal":
+            return new Uint8Array(Buffer.from(d.bytesBase64 ?? "", "base64"));
+        default:
+            throw new Error(`unknown residual payload kind: ${d.kind}`);
+    }
+}