pi-mega-compact 0.20.7 → 0.20.9

package/dist/src/vector-cortex/heal/restore-readers.js

@@ -0,0 +1,114 @@
+/**
+ * vector-cortex/heal/restore-readers.ts — the two EXACT source readers (VC6B).
+ *
+ * Split out of `restore.ts` so the orchestrator stays a short, readable policy
+ * file and each reader can be reasoned about on its own (PRACTICES: split at the
+ * 300-line soft limit, delegate-shell + impl).
+ *
+ * Both readers share one discipline: they return bytes ONLY after recomputing
+ * SHA-256 over the bytes they actually hold and comparing it to the digest the
+ * REQUEST pinned. Neither reader trusts the digest recorded alongside its own
+ * source — an `ExactShardV1.digest` is metadata that lives in the same file as
+ * the bytes, so a swapped file carries a matching (wrong) pair. Only the
+ * caller-supplied digest is authoritative, and only a fresh hash of the fetched
+ * bytes can be checked against it.
+ *
+ * Pure/deterministic/local: `node:crypto` only (a Node built-in, not a network
+ * call), no storage, no console (PREVENT-PI-004 / PREVENT-011).
+ */
+import { createHash } from "node:crypto";
+/**
+ * SHA-256 over bytes as LOWERCASE HEX with NO `sha256:` prefix — the
+ * `ExactShardV1.digest` / `ReconstructionSpan.digest` / `RestoreSpanRequest`
+ * convention. `EventV2.bytesDigest` prefixes this same value with `sha256:`.
+ */
+export function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * Strip the `sha256:` prefix from an `EventV2.bytesDigest` so it can be compared
+ * against a bare hex digest. A value that does not carry the prefix is returned
+ * unchanged rather than mangled — the comparison then simply fails, which is the
+ * correct outcome for a malformed record.
+ */
+export function bareHex(digest) {
+    return digest.startsWith("sha256:") ? digest.slice("sha256:".length) : digest;
+}
+/**
+ * Structural range equality. All five components must match: two spans over the
+ * same seq window but different byte offsets are DIFFERENT spans (a re-encoded
+ * or re-offset stream is not the stream that was requested).
+ */
+export function rangeEquals(a, b) {
+    return (a.sessionId === b.sessionId &&
+        a.seqStart === b.seqStart &&
+        a.seqEnd === b.seqEnd &&
+        a.byteStart === b.byteStart &&
+        a.byteEnd === b.byteEnd);
+}
+/**
+ * Mode A — indexed exact-shard read.
+ *
+ * Selection is by RANGE identity plus the shard's own recorded digest, which
+ * narrows the candidate set the way a real index lookup would. The accepted
+ * candidate is then re-hashed from its `originalBytes`: this second check is
+ * what catches a shard whose bytes were swapped AFTER the index lookup resolved
+ * (the sprint's unique failure injection). A candidate that matches by range but
+ * fails either digest check reports `digest-mismatch` — it does NOT silently fall
+ * through to the ledger, because a corrupt exact shard is a fact worth surfacing.
+ */
+export function readExactShard(shards, range, digest) {
+    const byRange = shards.filter((s) => rangeEquals(s.range, range));
+    if (byRange.length === 0)
+        return { kind: "absent" };
+    const candidate = byRange.find((s) => s.digest === digest);
+    if (candidate === undefined)
+        return { kind: "digest-mismatch" };
+    // Defense in depth: the shard's recorded digest is metadata, the bytes are the
+    // authority. Re-hash what we actually hold.
+    const bytes = candidate.originalBytes;
+    if (sha256Hex(bytes) !== digest)
+        return { kind: "digest-mismatch" };
+    return { kind: "bytes", bytes };
+}
+/**
+ * Mode B — ledger range scan.
+ *
+ * An INDEPENDENT path from mode A: no shard index is consulted. The occurrence
+ * records covering `[seqStart..seqEnd]` are selected, sorted ascending by seq
+ * (the caller's array order is untrusted — a scan that concatenated records in
+ * arrival order would produce plausible-looking but wrong bytes), each record's
+ * own `bytesDigest` is verified, and the concatenation is hashed against the
+ * span digest.
+ *
+ * Both checks matter. Per-record verification localizes corruption to a single
+ * occurrence; the span-level hash catches a scan that is individually valid but
+ * collectively wrong — a missing record in the middle of the range, or a range
+ * that covers different content than the requester believed.
+ */
+export function readLedgerSpan(events, range, digest) {
+    const covering = events
+        .filter((e) => e.sessionId === range.sessionId &&
+        e.seq >= range.seqStart &&
+        e.seq <= range.seqEnd)
+        .sort((a, b) => (a.seq < b.seq ? -1 : a.seq > b.seq ? 1 : 0));
+    if (covering.length === 0)
+        return { kind: "absent" };
+    // Per-record byte authority (VC1A): a record whose own digest disagrees with
+    // its bytes is corrupt, and a corrupt record can never contribute to a restore.
+    for (const e of covering) {
+        if (sha256Hex(e.originalBytes) !== bareHex(e.bytesDigest)) {
+            return { kind: "digest-mismatch" };
+        }
+    }
+    const total = covering.reduce((sum, e) => sum + e.originalBytes.length, 0);
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const e of covering) {
+        bytes.set(e.originalBytes, offset);
+        offset += e.originalBytes.length;
+    }
+    if (sha256Hex(bytes) !== digest)
+        return { kind: "digest-mismatch" };
+    return { kind: "bytes", bytes };
+}

package/dist/src/vector-cortex/heal/restore-types.js

@@ -0,0 +1,66 @@
+/**
+ * vector-cortex/heal/restore-types.ts — VC6B exact source restoration contract.
+ *
+ * VC6A optimized WHICH EDGES the closure plan walks. VC6B answers the next
+ * question: when the plan needs a node whose bytes are no longer in the live
+ * window, WHERE do those bytes come from? The answer is deliberately narrow —
+ * an EXACT source, or nothing.
+ *
+ * THE CARDINAL RULE. Restored bytes are ONLY ever read from an exact source:
+ *   1. an `ExactShardV1` whose range and digest both match the request, or
+ *   2. a scan of the `EventV2` occurrence ledger over the requested seq range.
+ * Bytes are NEVER inferred from an embedding, a semantic shard, a RAPTOR
+ * summary, or any other derived/lossy representation. A semantic tier can tell
+ * you what a span was ABOUT; it cannot tell you what the span WAS. Attempting to
+ * "restore" from a derived source would silently fabricate transcript history,
+ * so VC6B has no code path that can do it: `RestoreReader` exposes exactly the
+ * two exact sources and nothing else.
+ *
+ * THE VERIFICATION RULE. Every restored span must hash to the SHA-256 digest the
+ * REQUEST pinned, checked immediately before insertion. A source that matches by
+ * range but not by hash is rejected (`HEAL_RESTORE_DIGEST_MISMATCH`) — never
+ * "close enough". This is what makes a swapped shard file, a truncated read, or a
+ * corrupted ledger record fail loudly instead of poisoning the reconstruction.
+ *
+ * DIGEST PINNING (three fields exist; do not confuse them).
+ *   - `ReconstructionSpan.digest` and `ExactShardV1.digest` are SHA-256 in
+ *     LOWERCASE HEX with NO prefix.
+ *   - `EventV2.bytesDigest` is `sha256:<hex>`, WITH the prefix.
+ * `RestoreSpanRequest.digest` works at SPAN level and uses the FORMER: bare
+ * lowercase hex, matching `ExactShardV1.digest` / `ReconstructionSpan.digest`.
+ * The prefixed `EventV2.bytesDigest` is used ONLY for per-event verification
+ * inside the ledger-scan path and is never the request-level digest. Mixing the
+ * two would make every ledger restoration fail (or, worse, make a prefix-stripped
+ * comparison accidentally succeed against the wrong granularity).
+ *
+ * BOUNDS. A restore request is attacker-shaped input: it names spans and byte
+ * ranges. `RESTORE_LIMIT_SPANS` / `RESTORE_LIMIT_BYTES` bound it BEFORE any
+ * reader is consulted, so an oversized request cannot be used to make the
+ * restorer walk the whole ledger (HEAL-LIMIT-002).
+ *
+ * Pure types + registered conformance IDs: no storage, no console, no network
+ * (PREVENT-PI-004 / PREVENT-011).
+ */
+/**
+ * Maximum spans in one request. A request naming more spans than this is
+ * rejected outright — the bound exists so a single call cannot be turned into an
+ * unbounded traversal of the ledger.
+ */
+export const RESTORE_LIMIT_SPANS = 64;
+/**
+ * Maximum aggregate requested bytes (4 MiB), summed from the REQUEST's ranges
+ * (`byteEnd - byteStart`) so the bound is enforceable without reading anything.
+ */
+export const RESTORE_LIMIT_BYTES = 4 * 1024 * 1024;
+/**
+ * Registered VC6B conformance ID range (HEAL-016..030), continuing VC6A's
+ * HEAL-001..015. The acceptance test reads these rows from the v2 manifest and
+ * asserts each returns its manifest `ok`/`code`.
+ */
+export const RESTORE_IDS = Array.from({ length: 15 }, (_v, i) => `HEAL-${String(i + 16).padStart(3, "0")}`);
+/** Named VC6B conformance assertions (the sprint's headline rows). */
+export const RESTORE_NAMED_IDS = [
+    "HEAL-SPAN-001",
+    "HEAL-LIMIT-002",
+    "HEAL-DIGEST-003",
+];

package/dist/src/vector-cortex/heal/restore.js

@@ -0,0 +1,140 @@
+/**
+ * vector-cortex/heal/restore.ts — VC6B exact source restoration orchestrator.
+ *
+ * Turns a `RestoreRequestV1` into a `RestoreResultV1` by consulting, per span,
+ * the two EXACT sources in `restore-readers.ts` — an indexed exact shard first,
+ * then a ledger range scan — and inserting bytes only after they hash to the
+ * digest the request pinned.
+ *
+ * ORDER OF OPERATIONS IS THE CONTRACT.
+ *
+ *   1. BOUNDS, BEFORE ANY READER TOUCH. The span count and the aggregate
+ *      requested byte span are computed PURELY FROM THE REQUEST (`byteEnd -
+ *      byteStart`, which needs no source at all) and checked first. On breach we
+ *      return immediately, having never read `reader.exactShards` or
+ *      `reader.ledgerEvents`. This is HEAL-LIMIT-002: an oversized request must
+ *      not be able to make the restorer walk the ledger even once, so the check
+ *      cannot be "inside the loop, before the read" — it must be before the loop
+ *      exists. The acceptance corpus proves it by passing EMPTY readers with an
+ *      over-limit request: a reader-touching implementation would still return
+ *      "missing" rather than "limit".
+ *
+ *   2. EXACT SHARD, then LEDGER, then MISSING. Sources are tried strongest-first.
+ *      A digest mismatch anywhere is recorded and the span is NOT restored — the
+ *      restorer never downgrades to "closest available bytes".
+ *
+ *   3. MODE from what actually happened, not from what was attempted. A = every
+ *      span came from a shard; B = all restored, at least one via ledger scan;
+ *      C = something is missing, and mode C STATES its semantic loss rather than
+ *      hiding an incomplete restoration behind a successful-looking result.
+ *
+ * PURE. No storage, no console, no clock, no network — `node:crypto` (a Node
+ * built-in) is the only dependency beyond types (PREVENT-PI-004 / PREVENT-011).
+ * The reporter seam in `restore-emit.ts` is flag-gated; THIS arithmetic is not,
+ * so flag-off is byte-identical.
+ */
+import { RESTORE_LIMIT_BYTES, RESTORE_LIMIT_SPANS } from "./restore-types.js";
+import { readExactShard, readLedgerSpan } from "./restore-readers.js";
+/**
+ * Fixed code ordering so a result's `codes` array is deterministic regardless of
+ * which span failed first. Deterministic output is what lets the conformance
+ * corpus pin an exact expected value.
+ */
+const CODE_ORDER = [
+    "HEAL_RESTORE_LIMIT",
+    "HEAL_RESTORE_DIGEST_MISMATCH",
+    "HEAL_RESTORE_SOURCE_MISSING",
+    "HEAL_RESTORE_RANGE_MISMATCH",
+];
+/** Deduplicate + sort codes into the fixed priority order. */
+export function orderCodes(codes) {
+    const seen = new Set(codes);
+    return CODE_ORDER.filter((c) => seen.has(c));
+}
+/**
+ * Total bytes the request ASKS for, derived from the ranges alone. Negative or
+ * inverted ranges contribute 0 rather than reducing the total — an inverted span
+ * must never be usable to smuggle a large request under the bound.
+ */
+function requestedBytes(spans) {
+    let total = 0;
+    for (const s of spans) {
+        const len = s.range.byteEnd - s.range.byteStart;
+        total += len > 0 ? len : 0;
+    }
+    return total;
+}
+/** The immediate over-limit result: nothing read, everything missing. */
+function limitExceeded(request) {
+    return {
+        schema: "restore-result-v1",
+        sessionId: request.sessionId,
+        mode: "C",
+        restored: [],
+        missing: request.spans.map((s) => s.nodeId),
+        semanticLossStated: true,
+        codes: ["HEAL_RESTORE_LIMIT"],
+    };
+}
+/**
+ * Restore the exact original bytes for every requested span.
+ *
+ * Never throws: a request naming spans no source covers yields a mode-C result
+ * that discloses the loss, not an exception (PRACTICES: non-fatal — a failed
+ * restoration must degrade the prompt, never break the agent loop).
+ */
+export function restoreSources(request, reader) {
+    // (1) Bounds first — computed from the request only. `reader` is not touched
+    // on this path, which is exactly what HEAL-LIMIT-002 asserts.
+    if (request.spans.length > RESTORE_LIMIT_SPANS ||
+        requestedBytes(request.spans) > RESTORE_LIMIT_BYTES) {
+        return limitExceeded(request);
+    }
+    const restored = [];
+    const missing = [];
+    const codes = [];
+    let usedLedger = false;
+    // (2) Per span, strongest source first, in request order.
+    for (const span of request.spans) {
+        const exact = readExactShard(reader.exactShards, span.range, span.digest);
+        if (exact.kind === "bytes") {
+            restored.push({
+                nodeId: span.nodeId,
+                source: "exact-shard",
+                bytes: exact.bytes,
+                digest: span.digest,
+            });
+            continue;
+        }
+        if (exact.kind === "digest-mismatch")
+            codes.push("HEAL_RESTORE_DIGEST_MISMATCH");
+        const ledger = readLedgerSpan(reader.ledgerEvents, span.range, span.digest);
+        if (ledger.kind === "bytes") {
+            usedLedger = true;
+            restored.push({
+                nodeId: span.nodeId,
+                source: "ledger-scan",
+                bytes: ledger.bytes,
+                digest: span.digest,
+            });
+            continue;
+        }
+        if (ledger.kind === "digest-mismatch")
+            codes.push("HEAL_RESTORE_DIGEST_MISMATCH");
+        // (3) Neither exact source answered. Identity only — never bytes.
+        missing.push(span.nodeId);
+        codes.push("HEAL_RESTORE_SOURCE_MISSING");
+    }
+    const complete = missing.length === 0 && restored.length === request.spans.length;
+    const mode = !complete ? "C" : usedLedger ? "B" : "A";
+    return {
+        schema: "restore-result-v1",
+        sessionId: request.sessionId,
+        mode,
+        restored,
+        missing,
+        // Mode C omits spans, so it MUST disclose that the old context is gone.
+        semanticLossStated: mode === "C",
+        codes: orderCodes(codes),
+    };
+}

package/dist/src/vector-cortex/heal/types.js

@@ -0,0 +1,43 @@
+/**
+ * vector-cortex/heal/types.ts — VC6A closure-optimization contract.
+ *
+ * Owns `ClosureProofV2` and `RestoreHintV1`.
+ *
+ * VC4C already performs the MANDATORY conservative closure (CONTRACTS §plan and
+ * closure): it recursively adds every `depends`/tool-pair predecessor to a fixed
+ * point, resolves contradictions, and preserves the anchor floor. VC6A does NOT
+ * re-close and does NOT change WHICH NODES ARE SELECTED — "VC6 only optimizes
+ * restoration/self-healing". It optimizes the PROOF EDGES of that already-closed
+ * graph by transitive reduction: an edge `a -> c` whose requirement is already
+ * carried by a path `a -> b -> c` is redundant and can be dropped from the
+ * traversal plan without changing the closed set.
+ *
+ * The optimization is therefore a claim, and a claim needs a receipt:
+ * `ClosureProofV2` records EVERY considered edge — retained or removed — with
+ * the reason. `proof.ts` replays those rows against the conservative VC4C oracle
+ * and rejects the optimization if the selected set diverges
+ * (`HEAL_PROOF_SET_MISMATCH`) or if a considered edge has no proof row
+ * (`HEAL_PROOF_INCOMPLETE`).
+ *
+ * PROTECTED EDGES ARE NEVER REMOVED. A tool-pair edge (PREVENT-PI-002), an edge
+ * touching an anchor node (PREVENT-PI-001's anchor floor), a
+ * contradiction-resolution edge, and a SOLE dependency edge (the only edge that
+ * pulls its prerequisite in) are all retained unconditionally, even when an
+ * alternate path exists. Only a redundant `depends` edge may go.
+ *
+ * Pure types + registered conformance IDs: no storage, no console, no network
+ * (PREVENT-PI-004 / PREVENT-011).
+ */
+/**
+ * Registered HEAL conformance ID range (HEAL-001..015). The acceptance test
+ * reads these rows from the v2 manifest and asserts each returns its manifest
+ * `ok`/`code`.
+ */
+export const HEAL_IDS = Array.from({ length: 15 }, (_v, i) => `HEAL-${String(i + 1).padStart(3, "0")}`);
+/** Named VC6A conformance assertions (the sprint's headline rows). */
+export const HEAL_NAMED_IDS = [
+    "HEAL-REDUCE-001",
+    "HEAL-PROTECT-002",
+    "HEAL-PROOF-003",
+];
+export { RESTORE_IDS, RESTORE_NAMED_IDS, RESTORE_LIMIT_SPANS, RESTORE_LIMIT_BYTES, } from "./restore-types.js";

package/dist/src/vector-cortex/heal/verify.js

@@ -0,0 +1,75 @@
+/**
+ * vector-cortex/heal/verify.ts — VC6B pre-insertion verification (task 3).
+ *
+ * `restoreSources` already hashes every span before it puts it in the result, so
+ * why hash again here?
+ *
+ * Because the result is a VALUE that travels. Between restoration and insertion
+ * it is passed across module boundaries, possibly cached, possibly assembled from
+ * more than one restore call, possibly reordered. `verifyRestored` is the gate
+ * immediately before bytes enter the reconstruction, and it re-derives its facts
+ * from scratch: it hashes the bytes the result ACTUALLY CARRIES and cross-checks
+ * them against the digest THE REQUEST asked for. A result object mutated after
+ * `restoreSources` returned — the classic "verified then swapped" injection —
+ * fails here.
+ *
+ * TWO DISTINCT INVARIANTS, TWO DISTINCT CODES.
+ *   - `HEAL_RESTORE_DIGEST_MISMATCH` — the bytes do not hash to their OWN stated
+ *     digest. The span is internally inconsistent (tampering or truncation).
+ *   - `HEAL_RESTORE_RANGE_MISMATCH` — the bytes are internally consistent but do
+ *     not answer the question that was asked: the nodeId was never requested, or
+ *     the digest disagrees with the digest the request pinned for that nodeId.
+ *     This is the "right bytes, wrong span" failure — substituting one real,
+ *     correctly-hashed span for another would otherwise pass a naive check.
+ *
+ * WHOLESALE, NOT PER-SPAN. `insertable` returns the restored spans only when the
+ * entire result verifies. Inserting the good half of a result whose other half
+ * failed verification would splice a partially-corrupt transcript into the
+ * reconstruction without the caller ever seeing a mode-C disclosure.
+ *
+ * Pure: `node:crypto` only, no storage/console/network (PREVENT-PI-004 /
+ * PREVENT-011).
+ */
+import { sha256Hex } from "./restore-readers.js";
+import { orderCodes } from "./restore.js";
+/**
+ * Re-verify every restored span against the request that asked for it.
+ *
+ * Returns `{ok:true}` only when EVERY restored span hashes to its own digest AND
+ * that digest is the one the request pinned for that node.
+ */
+export function verifyRestored(result, request) {
+    const requestedDigests = new Map();
+    for (const span of request.spans)
+        requestedDigests.set(span.nodeId, span.digest);
+    const codes = [];
+    for (const span of result.restored) {
+        // (1) Internal consistency: do these bytes hash to the digest they claim?
+        if (sha256Hex(span.bytes) !== span.digest) {
+            codes.push("HEAL_RESTORE_DIGEST_MISMATCH");
+            // A span that fails its own digest cannot meaningfully be checked against
+            // the request's digest as well; one code per real defect keeps the verdict
+            // readable.
+            continue;
+        }
+        // (2) Provenance: was this node requested, and with THIS digest? An
+        // unrequested node or a digest swap is a range mismatch, not a hash failure.
+        const wanted = requestedDigests.get(span.nodeId);
+        if (wanted === undefined || wanted !== span.digest) {
+            codes.push("HEAL_RESTORE_RANGE_MISMATCH");
+        }
+    }
+    if (codes.length === 0)
+        return { ok: true };
+    return { ok: false, codes: orderCodes(codes) };
+}
+/**
+ * The spans that may be inserted: all of them, or none.
+ *
+ * A caller should never need to decide which half of a partially-verified result
+ * is safe — that decision is the whole point of the digest contract, so it is
+ * made here, once, in the strict direction.
+ */
+export function insertable(result, request) {
+    return verifyRestored(result, request).ok ? result.restored : [];
+}

package/dist/vector-cortex/heal/_acceptance-fixture.js

@@ -0,0 +1,56 @@
+/**
+ * heal/_acceptance-fixture.ts — conformance fixture I/O for VC6A closure
+ * optimization acceptance rows.
+ *
+ * Reads the v2 conformance manifest + the per-sprint closure-optimization
+ * fixture files, and exposes the `HealFx` shape the acceptance aggregator
+ * drives. No mocks/stubs: the fixtures are the committed canonical corpus, fed
+ * verbatim into `closeSelection` → `optimizeClosure` → `verifyProof`.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import assert from "node:assert/strict";
+const HERE = dirname(fileURLToPath(import.meta.url));
+function repoRoot(from) {
+    let dir = from;
+    for (let i = 0; i < 8; i++) {
+        if (existsSync(join(dir, "conformance", "vector-cortex")))
+            return dir;
+        const next = dirname(dir);
+        if (next === dir)
+            break;
+        dir = next;
+    }
+    throw new Error("conformance corpus not found above " + from);
+}
+export const REPO_ROOT = repoRoot(HERE);
+export const V2 = join(REPO_ROOT, "conformance", "vector-cortex", "v2");
+export function readManifest() {
+    return JSON.parse(readFileSync(join(V2, "manifest.json"), "utf8"));
+}
+function readFixture(id, prefix) {
+    const m = readManifest();
+    const row = m.fixtures.find((f) => f.id === id && f.path.startsWith(`${prefix}/`));
+    assert.ok(row, `fixture ${id} registered under ${prefix}/ in manifest`);
+    return JSON.parse(readFileSync(join(V2, row.path), "utf8"));
+}
+export function healFixture(id) {
+    return readFixture(id, "closure-optimization");
+}
+/** Flag-pinned wrapper: VC6A gated by MEGACOMPACT_VC6A (defaults ON). */
+export function withFlagsOn(fn) {
+    return () => {
+        const saved = process.env.MEGACOMPACT_VC6A;
+        process.env.MEGACOMPACT_VC6A = "1";
+        try {
+            fn();
+        }
+        finally {
+            if (saved === undefined)
+                delete process.env.MEGACOMPACT_VC6A;
+            else
+                process.env.MEGACOMPACT_VC6A = saved;
+        }
+    };
+}

package/dist/vector-cortex/heal/_restore-fixture.js

@@ -0,0 +1,96 @@
+/**
+ * heal/_restore-fixture.ts — conformance fixture I/O for VC6B restoration rows.
+ *
+ * Sibling of `_acceptance-fixture.ts` (which owns the VC6A closure-optimization
+ * rows); split out so neither file approaches the 300-line soft limit and so the
+ * base64/BigInt decoding lives next to the contract it reconstitutes.
+ *
+ * DECODING IS THE POINT. Fixtures are canonical JSON, which cannot express bytes
+ * or bigints, so the corpus stores `originalBytesBase64` + numeric `seq`. These
+ * loaders turn those back into the REAL `ExactShardV1` / `EventV2` objects the
+ * production readers consume — no mocks, no stubs, no parallel "test shape". If
+ * the decode were lossy the digests would not match and the acceptance test would
+ * fail loudly, which is exactly the guarantee we want from a byte-identity sprint.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import assert from "node:assert/strict";
+import { V2, readManifest } from "./_acceptance-fixture.js";
+/** Read one registered restoration fixture (asserting it IS registered). */
+export function restorationFixture(id) {
+    const m = readManifest();
+    const row = m.fixtures.find((f) => f.id === id && f.path.startsWith("restoration/"));
+    assert.ok(row, `fixture ${id} registered under restoration/ in manifest`);
+    return JSON.parse(readFileSync(join(V2, row.path), "utf8"));
+}
+/** base64 -> exact bytes, byte-for-byte (invalid UTF-8 included). */
+export function decodeBytes(base64) {
+    return new Uint8Array(Buffer.from(base64, "base64"));
+}
+/** JSON number seq bounds -> the bigint bounds `ShardRange` declares. */
+export function decodeRange(r) {
+    return {
+        sessionId: r.sessionId,
+        seqStart: BigInt(r.seqStart),
+        seqEnd: BigInt(r.seqEnd),
+        byteStart: r.byteStart,
+        byteEnd: r.byteEnd,
+    };
+}
+/** Reconstitute a real `ExactShardV1` from its fixture row. */
+export function decodeShard(s) {
+    return {
+        schema: "exact-shard-v1",
+        sessionId: s.sessionId,
+        range: decodeRange(s.range),
+        kind: "exact",
+        originalBytes: decodeBytes(s.originalBytesBase64),
+        digest: s.digest,
+        byteCount: s.byteCount,
+        case: s.case,
+    };
+}
+/**
+ * Reconstitute a real `EventV2`. `utf8` is re-derived by strict classification
+ * (never lossy replacement) so an invalid-UTF-8 fixture produces the
+ * `{valid:false, base64}` discriminant the VC1A contract requires.
+ */
+export function decodeEvent(e) {
+    const bytes = decodeBytes(e.originalBytesBase64);
+    let utf8;
+    try {
+        utf8 = { valid: true, text: new TextDecoder("utf-8", { fatal: true }).decode(bytes) };
+    }
+    catch {
+        utf8 = { valid: false, base64: e.originalBytesBase64 };
+    }
+    return {
+        schema: "event-v2",
+        sessionId: e.sessionId,
+        seq: BigInt(e.seq),
+        eventId: e.eventId,
+        role: e.role,
+        kind: e.kind,
+        originalBytes: bytes,
+        bytesDigest: e.bytesDigest,
+        utf8,
+        ...(e.toolCallId !== undefined ? { toolCallId: e.toolCallId } : {}),
+        occurredAtMs: BigInt(e.occurredAtMs),
+    };
+}
+/** Flag-pinned wrapper: VC6B gated by MEGACOMPACT_VC6B (defaults ON). */
+export function withVc6bFlagsOn(fn) {
+    return () => {
+        const saved = process.env.MEGACOMPACT_VC6B;
+        process.env.MEGACOMPACT_VC6B = "1";
+        try {
+            fn();
+        }
+        finally {
+            if (saved === undefined)
+                delete process.env.MEGACOMPACT_VC6B;
+            else
+                process.env.MEGACOMPACT_VC6B = saved;
+        }
+    };
+}

package/dist/vector-cortex/heal/_vc6b-helpers.js

@@ -0,0 +1,35 @@
+/**
+ * heal/_vc6b-helpers.ts — shared decode/run helpers for VC6B acceptance tests.
+ *
+ * Extracted from vc6b-acceptance.test.ts so no single test file crosses the
+ * 300-line soft limit (soft-as-hard gate). Each sibling test file imports from
+ * here rather than duplicating the decode/runReal logic.
+ */
+import { createHash } from "node:crypto";
+import { restoreSources } from "./restore.js";
+import { verifyRestored } from "./verify.js";
+import { decodeRange, decodeShard, decodeEvent } from "./_restore-fixture.js";
+export const enc = (s) => new Uint8Array(Buffer.from(s));
+export const hex = (b) => createHash("sha256").update(b).digest("hex");
+export function decodeFx(fx) {
+    return {
+        request: {
+            schema: "restore-request-v1",
+            sessionId: fx.input.sessionId,
+            spans: fx.input.request.spans.map((s) => ({
+                nodeId: s.nodeId,
+                range: decodeRange(s.range),
+                digest: s.digest,
+            })),
+        },
+        reader: {
+            exactShards: fx.input.exactShards.map(decodeShard),
+            ledgerEvents: fx.input.ledgerEvents.map(decodeEvent),
+        },
+    };
+}
+export function runReal(fx) {
+    const { request, reader } = decodeFx(fx);
+    const result = restoreSources(request, reader);
+    return { request, reader, result, verification: verifyRestored(result, request) };
+}