pi-mega-compact 0.20.8 → 0.20.9

package/extensions/dashboard-server/api-contracts/vector-cortex.ts

@@ -374,4 +374,7 @@ export interface VectorCortexLedgerView {
   readonly updatedAt: string;
 }
 
-export type { VectorCortexClosureProofView } from "./vector-cortex-heal.js";
+export type {
+  VectorCortexClosureProofView,
+  VectorCortexRestoreView,
+} from "./vector-cortex-heal.js";

package/extensions/dashboard-server/route-dispatch.ts

@@ -55,6 +55,7 @@ import {
 	handleVectorCortexRender,
 	handleVectorCortexRollout,
 	handleVectorCortexClosureProof,
+	handleVectorCortexRestore,
 } from "./routes.js";
 
 /**
@@ -108,5 +109,6 @@ export function dispatchRoutes(
 	if (handleVectorCortexRender(req, res, ctx)) return true;
 	if (handleVectorCortexRollout(req, res, ctx)) return true;
 	if (handleVectorCortexClosureProof(req, res, ctx)) return true;
+	if (handleVectorCortexRestore(req, res, ctx)) return true;
 	return false;
 }

package/extensions/dashboard-server/routes-rag-settings-vector-cortex.ts

@@ -144,5 +144,11 @@ export const VECTOR_CORTEX_SETTINGS: SettingGroup = {
 			"Advanced closure optimization: deterministically reduces the already-mandatory VC4C closure by transitive reduction over depends edges, emitting a ClosureProofV2 receipt per closure and a verifier that replays reductions against the conservative oracle (HEAL_PROOF_SET_MISMATCH on selected-set divergence). Protected edges (tool-pair / anchor / contradiction / sole-dependency) are never removed. The optimized selected set is byte-identical to the conservative closure. OFF = byte-identical predecessor (VC5C); arithmetic runs, only the reporter + dashboard seam is suppressed.",
 			true,
 		),
+		boolDirect(
+			"MEGACOMPACT_VC6B",
+			"VC6B Exact Source Restoration",
+			"Exact source restoration: restores the original bytes of closure spans ONLY from an exact shard (mode A) or a verified ledger range scan (mode B) — never inferred, reconstructed, or paraphrased from embeddings or semantic text. Requests are hard-bounded at 64 spans / 4MiB (HEAL_RESTORE_LIMIT); every span's SHA-256 is recomputed and bytes are inserted only after all requested span metadata validates, so a single bad span fails the whole request closed (HEAL_RESTORE_DIGEST_MISMATCH, HEAL_RESTORE_RANGE_MISMATCH). When no exact source exists (HEAL_RESTORE_SOURCE_MISSING) the old context is omitted and the loss is disclosed (mode C) rather than filled in. OFF = byte-identical predecessor (VC6A).",
+			true,
+		),
 	],
 };

package/extensions/dashboard-server/routes-vector-cortex-heal.ts

@@ -1,6 +1,6 @@
 /**
- * dashboard-server/routes-vector-cortex-heal.ts — VC6A closure-optimization
- * dashboard route.
+ * dashboard-server/routes-vector-cortex-heal.ts — VC6A closure-optimization and
+ * VC6B exact-source-restoration dashboard routes.
  *
  * Reader-only GET /api/vector-cortex/closure-proof returning aggregate-only
  * closure diagnostics: whether the flag is enabled, the runtime triad mode, and
@@ -12,15 +12,22 @@
  * (the conservative VC4C closure, no reduction) — that is exactly the spec's
  * fallback rule — so `mode:"B"` + `enabled:false` is the byte-stable OFF view.
  *
+ * Reader-only GET /api/vector-cortex/restore (VC6B) returns restore COUNTS and
+ * HEAL_RESTORE_* error codes only. There is NO payload endpoint for restoration,
+ * ever — no restored bytes, span ids, node ids, byte ranges, or ledger text.
+ *
  * Guardrails: PREVENT-PI-004 (local in-process state only), PREVENT-011 (no
  * `any`), reader-only aggregate (counts + mode only).
  */
 
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteContext } from "./routes-core.js";
-import { VC6A_ENABLED } from "../../src/config.js";
+import { VC6A_ENABLED, VC6B_ENABLED } from "../../src/config.js";
 import { sendJson } from "./routes-vector-cortex-shared.js";
-import type { VectorCortexClosureProofView } from "./api-contracts/vector-cortex.js";
+import type {
+  VectorCortexClosureProofView,
+  VectorCortexRestoreView,
+} from "./api-contracts/vector-cortex.js";
 
 /** Reader-only GET /api/vector-cortex/closure-proof (VC6A). */
 export function handleVectorCortexClosureProof(
@@ -54,3 +61,43 @@ export function handleVectorCortexClosureProof(
   sendJson(res, 200, body);
   return true;
 }
+
+/**
+ * Reader-only GET /api/vector-cortex/restore (VC6B).
+ *
+ * Counts and HEAL_RESTORE_* codes only — this is a static reader-only aggregate
+ * seam (same shape as the VC6A handler): there is no payload endpoint and never
+ * will be, so no restored bytes/span ids/node ids/ledger text can leak here.
+ */
+export function handleVectorCortexRestore(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  const path = url.split("?")[0] ?? url;
+  if (path !== "/api/vector-cortex/restore") return false;
+  if (req.method !== "GET") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  const enabled = VC6B_ENABLED();
+  // Flag-off routes to mode C: with VC6B off there is no exact-restoration path
+  // at all, so the honest OFF view is the disclose-loss mode (old context is
+  // omitted rather than inferred) — mirroring how VC6A's OFF view reports the
+  // conservative fallback it actually takes.
+  const mode: "A" | "B" | "C" = enabled ? "A" : "C";
+  const body: VectorCortexRestoreView = {
+    enabled,
+    mode,
+    restoreAttempts: 0,
+    restoredCount: 0,
+    missingCount: 0,
+    digestRejections: 0,
+    lastRejection: null,
+    updatedAt: new Date().toISOString(),
+  };
+  sendJson(res, 200, body);
+  return true;
+}

package/extensions/dashboard-server/routes-vector-cortex.ts

@@ -9,6 +9,8 @@
  *   VC0C health/reset-> routes-vector-cortex-health.ts(GET  /health, POST /breakers/reset)
  *   VC1B ledger      -> routes-vector-cortex-ledger.ts (GET  /ledger)
  *   VC3A topology    -> routes-vector-cortex-topology.ts(GET /topology)
+ *   VC6A closure     -> routes-vector-cortex-heal.ts   (GET  /closure-proof)
+ *   VC6B restore     -> routes-vector-cortex-heal.ts   (GET  /restore)
  *
  * Guardrails: PREVENT-PI-004 (local filesystem read only), PREVENT-011 (no
  * `any`), reader-only aggregates (never payloads/prompts/ledger text).
@@ -25,4 +27,7 @@ export { handleVectorCortexReconstruct } from "./routes-vector-cortex-reconstruc
 export { handleVectorCortexPlans } from "./routes-vector-cortex-plans.js";
 export { handleVectorCortexRender } from "./routes-vector-cortex-render.js";
 export { handleVectorCortexRollout } from "./routes-vector-cortex-rollout.js";
-export { handleVectorCortexClosureProof } from "./routes-vector-cortex-heal.js";
+export {
+	handleVectorCortexClosureProof,
+	handleVectorCortexRestore,
+} from "./routes-vector-cortex-heal.js";

package/extensions/dashboard-server/routes.ts

@@ -54,4 +54,5 @@ export {
 	handleVectorCortexRender,
 	handleVectorCortexRollout,
 	handleVectorCortexClosureProof,
+	handleVectorCortexRestore,
 } from "./routes-vector-cortex.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.8",
+  "version": "0.20.9",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",

package/src/config/vector-cortex.ts

@@ -227,6 +227,20 @@ export const VC5C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC5C");
  */
 export const VC6A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC6A");
 
+/**
+ * VC6B — exact source restoration. Default ON. `MEGACOMPACT_VC6B=0` disables and
+ * is byte-identical to the predecessor (VC6A): the `restoreSources` /
+ * `verifyRestored` arithmetic STILL RUNS (it is PURE — an exact-source read plus
+ * a SHA-256 comparison, with no clock, storage, or network), but the
+ * `vector_cortex_source_restored` / `vector_cortex_restore_digest_rejected`
+ * events are never emitted and the dashboard restoration diagnostics seam is
+ * suppressed. Flag OFF gates the reporter + dashboard seam, never the
+ * restore/verify arithmetic, so flag-off outbound/predecessor golden bytes match
+ * exactly. This flag MUST also be a dashboard SETTINGS toggle (visible in config
+ * UI, never in EXCLUDED_SETTINGS), mirroring VC4A/VC4B/VC4C/VC5A/VC5B/VC5C/VC6A.
+ */
+export const VC6B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC6B");
+
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/src/config.ts

@@ -170,6 +170,7 @@ export {
   VC5B_ENABLED,
   VC5C_ENABLED,
   VC6A_ENABLED,
+  VC6B_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

package/src/vector-cortex/heal/_restore-fixture.ts

@@ -0,0 +1,163 @@
+/**
+ * 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 type { EventV2, ExactShardV1, ShardRange } from "./restore-types.js";
+import { V2, readManifest } from "./_acceptance-fixture.js";
+
+/** A `ShardRange` as it appears in JSON: `seq` bounds are numbers, not bigints. */
+export interface RestoreFxRange {
+  sessionId: string;
+  seqStart: number;
+  seqEnd: number;
+  byteStart: number;
+  byteEnd: number;
+}
+
+export interface RestoreFxSpan {
+  nodeId: string;
+  range: RestoreFxRange;
+  digest: string;
+}
+
+export interface RestoreFxShard {
+  sessionId: string;
+  range: RestoreFxRange;
+  originalBytesBase64: string;
+  digest: string;
+  byteCount: number;
+  case: "tool-pair" | "anchor" | "invalid-utf8" | "anchor+invalid";
+}
+
+export interface RestoreFxEvent {
+  sessionId: string;
+  seq: number;
+  eventId: string;
+  role: "policy" | "user" | "assistant" | "tool";
+  kind: string;
+  originalBytesBase64: string;
+  bytesDigest: string;
+  occurredAtMs: number;
+  toolCallId?: string;
+}
+
+export interface RestoreFxInput {
+  scenario: string;
+  sessionId: string;
+  request: { spans: RestoreFxSpan[] };
+  exactShards: RestoreFxShard[];
+  ledgerEvents: RestoreFxEvent[];
+}
+
+export interface RestoreFxExpected {
+  ok: boolean;
+  code?: string;
+  restoredCount: number;
+  missingCount: number;
+  mode: "A" | "B" | "C";
+}
+
+export interface RestoreFx {
+  id: string;
+  schema: string;
+  producer: string;
+  assertion: string;
+  kind: string;
+  input: RestoreFxInput;
+  expected: RestoreFxExpected;
+}
+
+/** Read one registered restoration fixture (asserting it IS registered). */
+export function restorationFixture(id: string): RestoreFx {
+  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")) as RestoreFx;
+}
+
+/** base64 -> exact bytes, byte-for-byte (invalid UTF-8 included). */
+export function decodeBytes(base64: string): Uint8Array {
+  return new Uint8Array(Buffer.from(base64, "base64"));
+}
+
+/** JSON number seq bounds -> the bigint bounds `ShardRange` declares. */
+export function decodeRange(r: RestoreFxRange): ShardRange {
+  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: RestoreFxShard): ExactShardV1 {
+  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: RestoreFxEvent): EventV2 {
+  const bytes = decodeBytes(e.originalBytesBase64);
+  let utf8: EventV2["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 as EventV2["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: () => void): () => void {
+  return (): void => {
+    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/src/vector-cortex/heal/_vc6b-helpers.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 type {
+  RestoreReader,
+  RestoreRequestV1,
+  RestoreResultV1,
+} from "./restore-types.js";
+import { restoreSources } from "./restore.js";
+import { verifyRestored } from "./verify.js";
+import type { RestoreFx } from "./_restore-fixture.js";
+import { decodeRange, decodeShard, decodeEvent } from "./_restore-fixture.js";
+
+export const enc = (s: string): Uint8Array => new Uint8Array(Buffer.from(s));
+export const hex = (b: Uint8Array): string =>
+  createHash("sha256").update(b).digest("hex");
+
+export function decodeFx(fx: RestoreFx): {
+  request: RestoreRequestV1;
+  reader: RestoreReader;
+} {
+  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: RestoreFx): {
+  request: RestoreRequestV1;
+  reader: RestoreReader;
+  result: RestoreResultV1;
+  verification: ReturnType<typeof verifyRestored>;
+} {
+  const { request, reader } = decodeFx(fx);
+  const result = restoreSources(request, reader);
+  return { request, reader, result, verification: verifyRestored(result, request) };
+}

package/src/vector-cortex/heal/restore-emit.ts

@@ -0,0 +1,94 @@
+/**
+ * vector-cortex/heal/restore-emit.ts — VC6B event reporter seam.
+ *
+ * Mirrors `./emit.ts`: a thin `safe()` wrapper around an optional injected
+ * `emit` (unit tests pass `undefined` and stay pure), and the two event names the
+ * sprint spec requires verbatim:
+ *   - `vector_cortex_source_restored`         — a restore batch completed.
+ *   - `vector_cortex_restore_digest_rejected` — a source failed its digest check.
+ *
+ * FLAG SEMANTICS. `restoreSources` / `verifyRestored` are PURE arithmetic and run
+ * REGARDLESS of `MEGACOMPACT_VC6B`. The flag gates ONLY this reporting +
+ * dashboard seam: with the flag off we still restore and still verify, we just do
+ * not announce it under the VC6B event namespace. That is what makes flag-off
+ * byte-identical to VC6A — the computation is never skipped, only the emission.
+ *
+ * PAYLOAD DISCIPLINE. These events carry COUNTS and MODES only — never restored
+ * bytes, never node text, never a digest of user content. The exact ledger is not
+ * diagnostic data (SECURITY_PRIVACY), and a restoration event is exactly the
+ * place where an unguarded `payload` field would leak the entire transcript into
+ * a log file.
+ *
+ * No console, no storage, no network (PREVENT-PI-004 / PREVENT-011). Every line
+ * is a structured JSON event with `ts` + `event`.
+ */
+
+import { VC6B_ENABLED } from "../../config/vector-cortex.js";
+import type { RestoreEventName, RestoreFailureCode } from "./restore-types.js";
+
+/** Optional emit fn injected by the runtime; tests pass `undefined`. */
+export type RestoreEmit = (name: string, payload: unknown) => void;
+
+/** Run `fn` only when an emit exists; a reporting failure is never fatal. */
+function safe(emit: RestoreEmit | undefined, fn: (emit: RestoreEmit) => void): void {
+  if (emit === undefined) return;
+  try {
+    fn(emit);
+  } catch {
+    // Non-fatal: a reporting failure must never break the agent loop.
+  }
+}
+
+/** The event names VC6B emits, exported for the dashboard seam and tests. */
+export const RESTORE_EVENT_NAMES: readonly RestoreEventName[] = [
+  "vector_cortex_source_restored",
+  "vector_cortex_restore_digest_rejected",
+] as const;
+
+/**
+ * Report a completed restoration. Counts and mode only — enough to see whether
+ * the shard index is serving reads (mode A) or every span is falling through to
+ * a ledger scan (mode B), without disclosing what was restored.
+ */
+export function reportSourceRestored(
+  emit: RestoreEmit | undefined,
+  payload: {
+    readonly sessionId: string;
+    readonly restoredCount: number;
+    readonly missingCount: number;
+    readonly mode: "A" | "B" | "C";
+  },
+): void {
+  if (!VC6B_ENABLED()) return;
+  safe(emit, (e) =>
+    e("vector_cortex_source_restored", {
+      ts: undefined,
+      event: "vector_cortex_source_restored",
+      sessionId: payload.sessionId,
+      restoredCount: payload.restoredCount,
+      missingCount: payload.missingCount,
+      mode: payload.mode,
+    }),
+  );
+}
+
+/** Report a rejected source (digest/limit/range). Suppressed under flag-off. */
+export function reportRestoreDigestRejected(
+  emit: RestoreEmit | undefined,
+  payload: {
+    readonly sessionId: string;
+    readonly code: RestoreFailureCode;
+    readonly mode: "A" | "B" | "C";
+  },
+): void {
+  if (!VC6B_ENABLED()) return;
+  safe(emit, (e) =>
+    e("vector_cortex_restore_digest_rejected", {
+      ts: undefined,
+      event: "vector_cortex_restore_digest_rejected",
+      sessionId: payload.sessionId,
+      code: payload.code,
+      mode: payload.mode,
+    }),
+  );
+}

package/src/vector-cortex/heal/restore-readers.ts

@@ -0,0 +1,145 @@
+/**
+ * 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";
+
+import type { EventV2, ExactShardV1, ShardRange } from "./restore-types.js";
+
+/**
+ * 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: Uint8Array): string {
+  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: string): string {
+  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: ShardRange, b: ShardRange): boolean {
+  return (
+    a.sessionId === b.sessionId &&
+    a.seqStart === b.seqStart &&
+    a.seqEnd === b.seqEnd &&
+    a.byteStart === b.byteStart &&
+    a.byteEnd === b.byteEnd
+  );
+}
+
+/** What a reader attempt produced: bytes, a stated failure, or simply nothing. */
+export type ReadOutcome =
+  /** Bytes fetched AND verified against the request digest. */
+  | { readonly kind: "bytes"; readonly bytes: Uint8Array }
+  /** A source existed but its bytes did not hash to the pinned digest. */
+  | { readonly kind: "digest-mismatch" }
+  /** No source of this tier covers the span; try the next tier. */
+  | { readonly kind: "absent" };
+
+/**
+ * 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: readonly ExactShardV1[],
+  range: ShardRange,
+  digest: string,
+): ReadOutcome {
+  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: readonly EventV2[],
+  range: ShardRange,
+  digest: string,
+): ReadOutcome {
+  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 };
+}