pi-mega-compact 0.19.3 → 0.20.1

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

@@ -0,0 +1,245 @@
+/**
+ * vector-cortex/residual/parity.ts — Reed–Solomon (9,6) erasure parity over the
+ * protected stream (VC4B).
+ *
+ * Construction (RESIDUAL_CODEC §erasure parity): the protected stream is split
+ * into `k=6` equal, zero-padded data shards (the unpadded stream length is
+ * stored on every shard). A `9x6` Vandermonde matrix `V[r][c] = alpha_r^c` with
+ * evaluation points `alpha_r = r+1` is converted to a SYSTEMATIC generator
+ * `G = V x inverse(V[0..5, 0..5])`; rows 0..5 are then the identity (data shards
+ * pass through unchanged) and rows 6..8 produce the three parity shards in that
+ * order.
+ *
+ * Recovery: any 6 of the 9 shards reconstruct the stream. Every shard carries
+ * its own SHA-256, so an UNKNOWN corruption is DETECTED and can be promoted to a
+ * known erasure — it is never blindly error-corrected. More than 3 erasures
+ * fails closed (`RES_TOO_MANY_ERASURES`) to the exact source / mode C.
+ *
+ * Guardrails: local hashing only, no storage, no console, no network
+ * (PREVENT-PI-004 / PREVENT-011).
+ */
+import { createHash } from "node:crypto";
+import { gfAdd, gfAt, gfInvert, gfMatMul, gfMatrix, gfMul, gfPickRows, gfSet, gfSubRows, vandermonde, } from "./gf256.js";
+import { RS_DATA_SHARDS, RS_PARITY_SHARDS, RS_TOTAL_SHARDS, } from "./types.js";
+/** SHA-256 of a byte slice, lowercase hex. */
+export function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * The systematic `9x6` generator `G = V x inverse(V[0..5,0..5])`. Built once:
+ * the matrix depends only on the fixed geometry and the fixed field.
+ */
+let cachedGenerator = null;
+export function systematicGenerator() {
+    if (cachedGenerator)
+        return cachedGenerator;
+    const v = vandermonde(RS_TOTAL_SHARDS, RS_DATA_SHARDS);
+    const top = gfSubRows(v, 0, RS_DATA_SHARDS);
+    const topInv = gfInvert(top);
+    if (!topInv) {
+        // The fixed Vandermonde top square over GF(2^8) with distinct points 1..6
+        // is always invertible; this guard exists so a future geometry change fails
+        // loudly rather than silently producing a broken generator.
+        throw new Error("residual parity: singular Vandermonde top square");
+    }
+    cachedGenerator = gfMatMul(v, topInv);
+    return cachedGenerator;
+}
+/** Per-shard payload length for a stream of `streamLength` bytes. */
+export function shardLength(streamLength) {
+    return Math.ceil(streamLength / RS_DATA_SHARDS);
+}
+/**
+ * Split the protected stream into 9 shards: 6 systematic data shards (equal
+ * length, final one zero-padded) followed by 3 parity shards.
+ */
+export function encodeShards(stream) {
+    const len = shardLength(stream.length);
+    const g = systematicGenerator();
+    const data = [];
+    for (let i = 0; i < RS_DATA_SHARDS; i++) {
+        const shard = new Uint8Array(len);
+        shard.set(stream.subarray(i * len, Math.min((i + 1) * len, stream.length)));
+        data.push(shard);
+    }
+    const shards = data.map((bytes, index) => ({
+        schema: "parity-shard-v1",
+        index,
+        kind: "data",
+        bytes,
+        digest: sha256Hex(bytes),
+        streamLength: stream.length,
+    }));
+    for (let p = 0; p < RS_PARITY_SHARDS; p++) {
+        const row = RS_DATA_SHARDS + p;
+        const bytes = new Uint8Array(len);
+        for (let c = 0; c < RS_DATA_SHARDS; c++) {
+            const coefficient = gfAt(g, row, c);
+            if (coefficient === 0)
+                continue;
+            const src = data[c];
+            for (let b = 0; b < len; b++) {
+                bytes[b] = gfAdd(bytes[b], gfMul(coefficient, src[b]));
+            }
+        }
+        shards.push({
+            schema: "parity-shard-v1",
+            index: row,
+            kind: "parity",
+            bytes,
+            digest: sha256Hex(bytes),
+            streamLength: stream.length,
+        });
+    }
+    return shards;
+}
+/**
+ * Verify every supplied shard's SHA-256 and return the indices whose digest
+ * does NOT match. A corrupt shard is DETECTED here; the caller promotes it to a
+ * known erasure rather than attempting unknown-error correction.
+ */
+export function detectCorruptShards(shards) {
+    const corrupt = [];
+    for (const s of shards) {
+        if (sha256Hex(s.bytes) !== s.digest)
+            corrupt.push(s.index);
+    }
+    return corrupt.sort((a, b) => a - b);
+}
+/** Structural validation shared by recovery paths. */
+function validateShards(shards) {
+    if (shards.length === 0)
+        return { ok: false, code: "RES_TOO_MANY_ERASURES" };
+    const seen = new Set();
+    const length = shards[0].bytes.length;
+    const streamLength = shards[0].streamLength;
+    for (const s of shards) {
+        if (s.index < 0 || s.index >= RS_TOTAL_SHARDS || !Number.isInteger(s.index)) {
+            return { ok: false, code: "RES_DUPLICATE_SHARD_INDEX" };
+        }
+        if (seen.has(s.index))
+            return { ok: false, code: "RES_DUPLICATE_SHARD_INDEX" };
+        seen.add(s.index);
+        if (s.bytes.length !== length) {
+            return { ok: false, code: "RES_SHARD_LENGTH_MISMATCH" };
+        }
+        if (s.streamLength !== streamLength) {
+            return { ok: false, code: "RES_SHARD_LENGTH_MISMATCH" };
+        }
+    }
+    if (shardLength(streamLength) !== length) {
+        return { ok: false, code: "RES_SHARD_LENGTH_MISMATCH" };
+    }
+    return { ok: true, length, streamLength };
+}
+/**
+ * Reconstruct the protected stream from AT LEAST 6 surviving shards.
+ *
+ * Every supplied shard is digest-checked first: a shard whose SHA-256 does not
+ * match its recorded digest is treated as a KNOWN erasure (it is dropped from
+ * the surviving set), which is exactly how a corrupt parity shard becomes the
+ * third erasure in the sprint's failure-injection case. If fewer than 6 shards
+ * survive that check, recovery fails closed with `RES_TOO_MANY_ERASURES` and
+ * never attempts unknown-error correction.
+ */
+export function recoverStream(shards) {
+    const structural = validateShards(shards);
+    if (!structural.ok)
+        return structural;
+    const { length, streamLength } = structural;
+    // Digest check: promote every detected corruption to a known erasure.
+    const corrupt = new Set(detectCorruptShards(shards));
+    const survivors = shards
+        .filter((s) => !corrupt.has(s.index))
+        .slice()
+        .sort((a, b) => a.index - b.index);
+    if (survivors.length < RS_DATA_SHARDS) {
+        return { ok: false, code: "RES_TOO_MANY_ERASURES" };
+    }
+    // Deterministic selection: the six lowest surviving indices.
+    const chosen = survivors.slice(0, RS_DATA_SHARDS);
+    const g = systematicGenerator();
+    const sub = gfPickRows(g, chosen.map((s) => s.index));
+    const subInv = gfInvert(sub);
+    if (!subInv)
+        return { ok: false, code: "RES_SINGULAR_MATRIX" };
+    // Recover the six data shards: D = inverse(G_chosen) x S_chosen.
+    const recoveredData = [];
+    for (let r = 0; r < RS_DATA_SHARDS; r++) {
+        const out = new Uint8Array(length);
+        for (let c = 0; c < RS_DATA_SHARDS; c++) {
+            const coefficient = gfAt(subInv, r, c);
+            if (coefficient === 0)
+                continue;
+            const src = chosen[c].bytes;
+            for (let b = 0; b < length; b++) {
+                out[b] = gfAdd(out[b], gfMul(coefficient, src[b]));
+            }
+        }
+        recoveredData.push(out);
+    }
+    const stream = new Uint8Array(streamLength);
+    for (let i = 0; i < RS_DATA_SHARDS; i++) {
+        const start = i * length;
+        if (start >= streamLength)
+            break;
+        const take = Math.min(length, streamLength - start);
+        stream.set(recoveredData[i].subarray(0, take), start);
+    }
+    const present = new Set(chosen.map((s) => s.index));
+    const recoveredIndices = [];
+    for (let i = 0; i < RS_TOTAL_SHARDS; i++)
+        if (!present.has(i))
+            recoveredIndices.push(i);
+    return { ok: true, stream, recoveredIndices };
+}
+/**
+ * Recover with an EXPLICIT erasure set: the named indices are treated as lost
+ * regardless of their digest. More than `m=3` marked erasures fails closed with
+ * `RES_TOO_MANY_ERASURES` before any matrix work — including the case where
+ * three data shards are marked AND a fourth (parity) shard is corrupt.
+ */
+export function recoverWithErasures(shards, erasedIndices) {
+    const erased = new Set(erasedIndices);
+    if (erased.size > RS_PARITY_SHARDS) {
+        return { ok: false, code: "RES_TOO_MANY_ERASURES" };
+    }
+    const kept = shards.filter((s) => !erased.has(s.index));
+    // A corruption among the KEPT shards is an additional known erasure; if that
+    // pushes the total past m=3 the recovery fails closed rather than attempting
+    // unknown-error correction.
+    const corrupt = detectCorruptShards(kept);
+    if (erased.size + corrupt.length > RS_PARITY_SHARDS) {
+        return { ok: false, code: "RES_TOO_MANY_ERASURES" };
+    }
+    return recoverStream(kept);
+}
+/** Rebuild the full 9-shard set from a recovered stream (repair path). */
+export function repairShards(stream) {
+    return encodeShards(stream);
+}
+/** Test/diagnostic helper: the systematic generator's parity rows. */
+export function parityRows() {
+    const g = systematicGenerator();
+    const rows = [];
+    for (let r = RS_DATA_SHARDS; r < RS_TOTAL_SHARDS; r++) {
+        const row = [];
+        for (let c = 0; c < RS_DATA_SHARDS; c++)
+            row.push(gfAt(g, r, c));
+        rows.push(row);
+    }
+    return rows;
+}
+/** Test helper: assert the generator's top square really is the identity. */
+export function generatorIsSystematic() {
+    const g = systematicGenerator();
+    for (let r = 0; r < RS_DATA_SHARDS; r++) {
+        for (let c = 0; c < RS_DATA_SHARDS; c++) {
+            const expected = r === c ? 1 : 0;
+            if (gfAt(g, r, c) !== expected)
+                return false;
+        }
+    }
+    return true;
+}
+export { gfMatrix, gfSet };

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

@@ -0,0 +1,200 @@
+/**
+ * vector-cortex/residual/quantize.ts — int16 coefficient quantization + the
+ * block-scoped exact correction stream (VC4B).
+ *
+ * Quantization (RESIDUAL_CODEC §byte scope): signed coefficients are quantized
+ * to int16 with a per-block float32 LE scale `max(abs(c))/32767` (an all-zero
+ * block has scale 0). Ties round to nearest-even; SATURATION REJECTS the
+ * encoding rather than clipping — a value that would land outside
+ * [-32767, 32767] returns `RES_QUANTIZE_RANGE`, as does any non-finite input.
+ * Dequantization multiplies back by the (float32-rounded) scale.
+ *
+ * Because quantization may not reproduce the bytes exactly, the encoder appends
+ * a block-scoped EXACT correction stream: for each block in ascending u32 LE
+ * `blockIndex`, a varint correction count followed by sorted
+ * `(u16 offsetWithinBlock, u8 original)` entries. Offsets are 0..4095, duplicate
+ * offsets are rejected, and omitted blocks have count zero. Applying the
+ * corrections makes post-quantization byte error exactly ZERO.
+ *
+ * Pure numeric/serialization logic: no storage, no console, no network
+ * (PREVENT-PI-004 / PREVENT-011).
+ */
+import { roundHalfToEven } from "./dct.js";
+import { RESIDUAL_BLOCK_SIZE, } from "./types.js";
+/** Int16 quantization limit (symmetric; -32768 is never produced). */
+export const INT16_LIMIT = 32767;
+/**
+ * Quantize one block's coefficients to int16 with a per-block float32 scale.
+ * Rejects non-finite inputs and any value that would saturate int16 with
+ * `RES_QUANTIZE_RANGE` (RESIDUAL_CODEC: saturation rejects encoding).
+ */
+export function quantizeBlock(coefficients) {
+    let peak = 0;
+    for (let i = 0; i < coefficients.length; i++) {
+        const c = coefficients[i];
+        if (!Number.isFinite(c))
+            return { ok: false, code: "RES_QUANTIZE_RANGE" };
+        const a = Math.abs(c);
+        if (a > peak)
+            peak = a;
+    }
+    const out = new Int16Array(coefficients.length);
+    if (peak === 0) {
+        // All-zero block: scale is exactly 0 and every coefficient stays 0.
+        return { ok: true, block: { scale: 0, coefficients: out } };
+    }
+    // The persisted scale is a float32 — quantize/dequantize with the SAME
+    // float32 value the artifact stores so encode and decode agree bit-for-bit.
+    const scale = Math.fround(peak / INT16_LIMIT);
+    if (!Number.isFinite(scale) || scale <= 0) {
+        return { ok: false, code: "RES_QUANTIZE_RANGE" };
+    }
+    for (let i = 0; i < coefficients.length; i++) {
+        const q = roundHalfToEven(coefficients[i] / scale);
+        if (q > INT16_LIMIT || q < -INT16_LIMIT) {
+            return { ok: false, code: "RES_QUANTIZE_RANGE" };
+        }
+        out[i] = q;
+    }
+    return { ok: true, block: { scale, coefficients: out } };
+}
+/** Dequantize a block back to float coefficients (`coefficient * scale`). */
+export function dequantizeBlock(block) {
+    const out = new Float64Array(block.coefficients.length);
+    for (let i = 0; i < block.coefficients.length; i++) {
+        out[i] = block.coefficients[i] * block.scale;
+    }
+    return out;
+}
+/**
+ * Diff a reconstructed block against the original, producing the sorted
+ * correction entries for that block (empty when the reconstruction is exact).
+ */
+export function diffBlock(original, reconstructed) {
+    const out = [];
+    for (let i = 0; i < original.length; i++) {
+        if (original[i] !== reconstructed[i]) {
+            out.push({ offset: i, original: original[i] });
+        }
+    }
+    return out;
+}
+/** Apply a block's corrections in place over a reconstructed block. */
+export function applyCorrections(reconstructed, corrections) {
+    let previous = -1;
+    for (const c of corrections) {
+        if (!Number.isInteger(c.offset) || c.offset < 0 || c.offset >= reconstructed.length) {
+            return { ok: false, code: "RES_CORRECTION_RANGE" };
+        }
+        if (!Number.isInteger(c.original) || c.original < 0 || c.original > 255) {
+            return { ok: false, code: "RES_CORRECTION_RANGE" };
+        }
+        // Entries are sorted ascending with no duplicate offset.
+        if (c.offset === previous) {
+            return { ok: false, code: "RES_CORRECTION_DUPLICATE_OFFSET" };
+        }
+        if (c.offset < previous)
+            return { ok: false, code: "RES_CORRECTION_RANGE" };
+        previous = c.offset;
+        reconstructed[c.offset] = c.original;
+    }
+    return { ok: true };
+}
+// ── varint (LEB128, unsigned) ───────────────────────────────────────────────
+/** Encode an unsigned integer as LEB128 varint bytes. */
+export function encodeVarint(value) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new RangeError("varint requires a non-negative integer");
+    }
+    const out = [];
+    let v = value;
+    do {
+        let byte = v & 0x7f;
+        v = Math.floor(v / 128);
+        if (v > 0)
+            byte |= 0x80;
+        out.push(byte);
+    } while (v > 0);
+    return out;
+}
+/** Decode an LEB128 varint at `offset`; returns the value and the next offset. */
+export function decodeVarint(bytes, offset) {
+    let value = 0;
+    let shift = 1;
+    let i = offset;
+    for (; i < bytes.length; i++) {
+        const byte = bytes[i];
+        value += (byte & 0x7f) * shift;
+        if ((byte & 0x80) === 0)
+            return { value, next: i + 1 };
+        shift *= 128;
+        if (shift > Number.MAX_SAFE_INTEGER)
+            return null;
+    }
+    return null;
+}
+// ── correction stream serialization ─────────────────────────────────────────
+/**
+ * Serialize the block-scoped correction stream: a varint block count, then for
+ * each NON-EMPTY block in ascending order a u32 LE blockIndex, a varint
+ * correction count, and the sorted `(u16 LE offset, u8 original)` entries.
+ * Omitted blocks have an implicit count of zero.
+ */
+export function serializeCorrections(blocks) {
+    const present = blocks
+        .filter((b) => b.corrections.length > 0)
+        .slice()
+        .sort((a, b) => a.blockIndex - b.blockIndex);
+    const out = [];
+    out.push(...encodeVarint(present.length));
+    for (const b of present) {
+        out.push(b.blockIndex & 0xff, (b.blockIndex >>> 8) & 0xff, (b.blockIndex >>> 16) & 0xff, (b.blockIndex >>> 24) & 0xff);
+        out.push(...encodeVarint(b.corrections.length));
+        for (const c of b.corrections) {
+            out.push(c.offset & 0xff, (c.offset >>> 8) & 0xff, c.original & 0xff);
+        }
+    }
+    return Uint8Array.from(out);
+}
+/** Parse a serialized correction stream. Returns null on any malformed input. */
+export function parseCorrections(bytes, offset) {
+    const head = decodeVarint(bytes, offset);
+    if (!head)
+        return null;
+    let pos = head.next;
+    const blocks = [];
+    let previousIndex = -1;
+    for (let b = 0; b < head.value; b++) {
+        if (pos + 4 > bytes.length)
+            return null;
+        const blockIndex = bytes[pos] |
+            (bytes[pos + 1] << 8) |
+            (bytes[pos + 2] << 16) |
+            (bytes[pos + 3] << 24);
+        pos += 4;
+        if (blockIndex < 0 || blockIndex <= previousIndex)
+            return null;
+        previousIndex = blockIndex;
+        const count = decodeVarint(bytes, pos);
+        if (!count)
+            return null;
+        pos = count.next;
+        const corrections = [];
+        let previousOffset = -1;
+        for (let i = 0; i < count.value; i++) {
+            if (pos + 3 > bytes.length)
+                return null;
+            const off = bytes[pos] | (bytes[pos + 1] << 8);
+            const original = bytes[pos + 2];
+            pos += 3;
+            if (off >= RESIDUAL_BLOCK_SIZE)
+                return null;
+            if (off <= previousOffset)
+                return null; // duplicate or unsorted
+            previousOffset = off;
+            corrections.push({ offset: off, original });
+        }
+        blocks.push({ blockIndex, corrections });
+    }
+    return { blocks, next: pos };
+}

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