pi-mega-compact 0.20.0 → 0.20.2

package/dist/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/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}`);
+    }
+}

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

@@ -0,0 +1,182 @@
+/**
+ * vector-cortex/residual/gf256.ts — GF(2^8) field arithmetic and matrix algebra
+ * for the VC4B Reed–Solomon erasure parity.
+ *
+ * Field: GF(2^8) with primitive polynomial `0x11d`, elements represented as
+ * polynomial-basis bytes (RESIDUAL_CODEC §erasure parity). Log/antilog tables
+ * are built once from generator 2 and drive constant-time multiply/divide.
+ *
+ * Matrix inversion and recovery use DETERMINISTIC left-to-right pivot search and
+ * GF Gaussian elimination — no randomness, no iteration-order dependence, so
+ * every implementation reaches byte-identical results.
+ *
+ * Pure arithmetic: no storage, no console, no network (PREVENT-PI-004 /
+ * PREVENT-011).
+ */
+import { GF_PRIMITIVE_POLYNOMIAL } from "./types.js";
+const FIELD_SIZE = 256;
+/** `EXP[i] = 2^i` in GF(2^8) (doubled length so multiply needs no modulo). */
+const EXP = new Uint8Array(FIELD_SIZE * 2);
+/** `LOG[x] = i` such that `2^i = x`; `LOG[0]` is unused (0 has no logarithm). */
+const LOG = new Uint8Array(FIELD_SIZE);
+(function buildTables() {
+    let x = 1;
+    for (let i = 0; i < FIELD_SIZE - 1; i++) {
+        EXP[i] = x;
+        LOG[x] = i;
+        x <<= 1;
+        if (x & 0x100)
+            x ^= GF_PRIMITIVE_POLYNOMIAL;
+    }
+    // Mirror the cycle so `EXP[a + b]` is valid for a,b <= 254 without a modulo.
+    for (let i = FIELD_SIZE - 1; i < EXP.length; i++) {
+        EXP[i] = EXP[i - (FIELD_SIZE - 1)];
+    }
+})();
+/** GF(2^8) addition (and subtraction) is XOR. */
+export function gfAdd(a, b) {
+    return (a ^ b) & 0xff;
+}
+/** GF(2^8) multiplication via log/antilog tables. */
+export function gfMul(a, b) {
+    if (a === 0 || b === 0)
+        return 0;
+    return EXP[LOG[a] + LOG[b]];
+}
+/** GF(2^8) division; dividing by zero is a programming error and throws. */
+export function gfDiv(a, b) {
+    if (b === 0)
+        throw new RangeError("gf256: division by zero");
+    if (a === 0)
+        return 0;
+    return EXP[LOG[a] + (FIELD_SIZE - 1) - LOG[b]];
+}
+/** Multiplicative inverse of a non-zero field element. */
+export function gfInv(a) {
+    if (a === 0)
+        throw new RangeError("gf256: zero has no inverse");
+    return EXP[FIELD_SIZE - 1 - LOG[a]];
+}
+/** `base^exponent` in GF(2^8) (exponent is a non-negative integer). */
+export function gfPow(base, exponent) {
+    if (exponent === 0)
+        return 1;
+    if (base === 0)
+        return 0;
+    return EXP[(LOG[base] * exponent) % (FIELD_SIZE - 1)];
+}
+/** Allocate a zero matrix. */
+export function gfMatrix(rows, cols) {
+    return { rows, cols, data: new Uint8Array(rows * cols) };
+}
+/** Read `m[r][c]`. */
+export function gfAt(m, r, c) {
+    return m.data[r * m.cols + c];
+}
+/** Write `m[r][c] = v`. */
+export function gfSet(m, r, c, v) {
+    m.data[r * m.cols + c] = v;
+}
+/**
+ * Build the `rows x cols` Vandermonde matrix `V[r][c] = alpha_r^c` with the
+ * distinct evaluation points `alpha_r = r + 1` (RESIDUAL_CODEC: rows r=0..8,
+ * columns c=0..5).
+ */
+export function vandermonde(rows, cols) {
+    const m = gfMatrix(rows, cols);
+    for (let r = 0; r < rows; r++) {
+        for (let c = 0; c < cols; c++) {
+            gfSet(m, r, c, gfPow((r + 1) & 0xff, c));
+        }
+    }
+    return m;
+}
+/** Matrix product `a x b` over GF(2^8). */
+export function gfMatMul(a, b) {
+    const out = gfMatrix(a.rows, b.cols);
+    for (let r = 0; r < a.rows; r++) {
+        for (let c = 0; c < b.cols; c++) {
+            let acc = 0;
+            for (let i = 0; i < a.cols; i++) {
+                acc ^= gfMul(gfAt(a, r, i), gfAt(b, i, c));
+            }
+            gfSet(out, r, c, acc);
+        }
+    }
+    return out;
+}
+/** Extract the contiguous row range `[start, start+count)` of a matrix. */
+export function gfSubRows(m, start, count) {
+    const out = gfMatrix(count, m.cols);
+    out.data.set(m.data.subarray(start * m.cols, (start + count) * m.cols));
+    return out;
+}
+/** Gather the given row indices (in order) into a new matrix. */
+export function gfPickRows(m, indices) {
+    const out = gfMatrix(indices.length, m.cols);
+    indices.forEach((src, dest) => {
+        out.data.set(m.data.subarray(src * m.cols, (src + 1) * m.cols), dest * m.cols);
+    });
+    return out;
+}
+/**
+ * Invert a square GF(2^8) matrix by Gauss–Jordan elimination with a
+ * DETERMINISTIC left-to-right pivot search (the first row at or below the
+ * current column with a non-zero entry). Returns null when the matrix is
+ * singular.
+ */
+export function gfInvert(m) {
+    if (m.rows !== m.cols)
+        return null;
+    const n = m.rows;
+    const work = gfMatrix(n, n);
+    work.data.set(m.data);
+    const inv = gfMatrix(n, n);
+    for (let i = 0; i < n; i++)
+        gfSet(inv, i, i, 1);
+    const swapRows = (mat, a, b) => {
+        if (a === b)
+            return;
+        for (let c = 0; c < mat.cols; c++) {
+            const t = gfAt(mat, a, c);
+            gfSet(mat, a, c, gfAt(mat, b, c));
+            gfSet(mat, b, c, t);
+        }
+    };
+    for (let col = 0; col < n; col++) {
+        // Deterministic pivot: the lowest-index row >= col with a non-zero entry.
+        let pivot = -1;
+        for (let r = col; r < n; r++) {
+            if (gfAt(work, r, col) !== 0) {
+                pivot = r;
+                break;
+            }
+        }
+        if (pivot === -1)
+            return null; // singular
+        swapRows(work, col, pivot);
+        swapRows(inv, col, pivot);
+        // Normalize the pivot row.
+        const pivotValue = gfAt(work, col, col);
+        if (pivotValue !== 1) {
+            const scale = gfInv(pivotValue);
+            for (let c = 0; c < n; c++) {
+                gfSet(work, col, c, gfMul(gfAt(work, col, c), scale));
+                gfSet(inv, col, c, gfMul(gfAt(inv, col, c), scale));
+            }
+        }
+        // Eliminate the column from every other row.
+        for (let r = 0; r < n; r++) {
+            if (r === col)
+                continue;
+            const factor = gfAt(work, r, col);
+            if (factor === 0)
+                continue;
+            for (let c = 0; c < n; c++) {
+                gfSet(work, r, c, gfAdd(gfAt(work, r, c), gfMul(factor, gfAt(work, col, c))));
+                gfSet(inv, r, c, gfAdd(gfAt(inv, r, c), gfMul(factor, gfAt(inv, col, c))));
+            }
+        }
+    }
+    return inv;
+}

package/dist/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 };