pi-mega-compact 0.20.0 → 0.20.2

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

@@ -0,0 +1,196 @@
+/**
+ * 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(): void {
+  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: number, b: number): number {
+  return (a ^ b) & 0xff;
+}
+
+/** GF(2^8) multiplication via log/antilog tables. */
+export function gfMul(a: number, b: number): number {
+  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: number, b: number): number {
+  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: number): number {
+  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: number, exponent: number): number {
+  if (exponent === 0) return 1;
+  if (base === 0) return 0;
+  return EXP[(LOG[base]! * exponent) % (FIELD_SIZE - 1)]!;
+}
+
+/** A dense row-major GF(2^8) matrix. */
+export interface GfMatrix {
+  readonly rows: number;
+  readonly cols: number;
+  readonly data: Uint8Array;
+}
+
+/** Allocate a zero matrix. */
+export function gfMatrix(rows: number, cols: number): GfMatrix {
+  return { rows, cols, data: new Uint8Array(rows * cols) };
+}
+
+/** Read `m[r][c]`. */
+export function gfAt(m: GfMatrix, r: number, c: number): number {
+  return m.data[r * m.cols + c]!;
+}
+
+/** Write `m[r][c] = v`. */
+export function gfSet(m: GfMatrix, r: number, c: number, v: number): void {
+  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: number, cols: number): GfMatrix {
+  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: GfMatrix, b: GfMatrix): GfMatrix {
+  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: GfMatrix, start: number, count: number): GfMatrix {
+  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: GfMatrix, indices: readonly number[]): GfMatrix {
+  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: GfMatrix): GfMatrix | null {
+  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: GfMatrix, a: number, b: number): void => {
+    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/src/vector-cortex/residual/parity.ts

@@ -0,0 +1,283 @@
+/**
+ * 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,
+  type GfMatrix,
+} from "./gf256.js";
+import {
+  RS_DATA_SHARDS,
+  RS_PARITY_SHARDS,
+  RS_TOTAL_SHARDS,
+  type ParityRecoveryResult,
+  type ParityShardV1,
+  type ResidualFailureCode,
+} from "./types.js";
+
+/** SHA-256 of a byte slice, lowercase hex. */
+export function sha256Hex(bytes: Uint8Array): string {
+  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: GfMatrix | null = null;
+
+export function systematicGenerator(): GfMatrix {
+  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: number): number {
+  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: Uint8Array): ParityShardV1[] {
+  const len = shardLength(stream.length);
+  const g = systematicGenerator();
+
+  const data: Uint8Array[] = [];
+  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: ParityShardV1[] = 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: readonly ParityShardV1[],
+): number[] {
+  const corrupt: number[] = [];
+  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: readonly ParityShardV1[],
+): { ok: true; length: number; streamLength: number } | { ok: false; code: ResidualFailureCode } {
+  if (shards.length === 0) return { ok: false, code: "RES_TOO_MANY_ERASURES" };
+  const seen = new Set<number>();
+  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: readonly ParityShardV1[],
+): ParityRecoveryResult {
+  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: Uint8Array[] = [];
+  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: number[] = [];
+  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: readonly ParityShardV1[],
+  erasedIndices: readonly number[],
+): ParityRecoveryResult {
+  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: Uint8Array): ParityShardV1[] {
+  return encodeShards(stream);
+}
+
+/** Test/diagnostic helper: the systematic generator's parity rows. */
+export function parityRows(): number[][] {
+  const g = systematicGenerator();
+  const rows: number[][] = [];
+  for (let r = RS_DATA_SHARDS; r < RS_TOTAL_SHARDS; r++) {
+    const row: number[] = [];
+    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(): boolean {
+  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/src/vector-cortex/residual/quantize.ts

@@ -0,0 +1,230 @@
+/**
+ * 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,
+  type BlockCorrectionsV1,
+  type CorrectionV1,
+  type QuantizedBlockV1,
+  type ResidualFailureCode,
+} from "./types.js";
+
+/** Int16 quantization limit (symmetric; -32768 is never produced). */
+export const INT16_LIMIT = 32767;
+
+/** Quantization result: the block, or the exact rejection code. */
+export type QuantizeResult =
+  | { ok: true; block: QuantizedBlockV1 }
+  | { ok: false; code: ResidualFailureCode };
+
+/**
+ * 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: Float64Array): QuantizeResult {
+  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: QuantizedBlockV1): Float64Array {
+  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: Uint8Array,
+  reconstructed: Uint8Array,
+): CorrectionV1[] {
+  const out: CorrectionV1[] = [];
+  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: Uint8Array,
+  corrections: readonly CorrectionV1[],
+): { ok: true } | { ok: false; code: ResidualFailureCode } {
+  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: number): number[] {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new RangeError("varint requires a non-negative integer");
+  }
+  const out: number[] = [];
+  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: Uint8Array,
+  offset: number,
+): { value: number; next: number } | null {
+  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: readonly BlockCorrectionsV1[],
+): Uint8Array {
+  const present = blocks
+    .filter((b) => b.corrections.length > 0)
+    .slice()
+    .sort((a, b) => a.blockIndex - b.blockIndex);
+  const out: number[] = [];
+  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: Uint8Array,
+  offset: number,
+): { blocks: BlockCorrectionsV1[]; next: number } | null {
+  const head = decodeVarint(bytes, offset);
+  if (!head) return null;
+  let pos = head.next;
+  const blocks: BlockCorrectionsV1[] = [];
+  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: CorrectionV1[] = [];
+    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 };
+}