pi-mega-compact 0.20.8 → 0.20.10

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

@@ -0,0 +1,138 @@
+/**
+ * heal/_repair-fixture.ts — conformance fixture I/O for VC6C healing-controller rows.
+ *
+ * Sibling of `_restore-fixture.ts` (VC6B) and `_acceptance-fixture.ts` (VC6A);
+ * split out so no loader approaches the 300-line soft limit and so the
+ * BigInt/base64 decoding lives next to the contract it reconstitutes.
+ *
+ * DECODING IS THE POINT. Fixtures are canonical JSON, which cannot express
+ * bigints or bytes, so the corpus stores numeric `nowMs` / high-waters and
+ * base64 source bytes. These loaders turn those back into the REAL `RepairState`
+ * / `RebuildInput` objects the production controller consumes — no mocks, no
+ * stubs, no parallel "test shape". A lossy decode would make the digests or the
+ * planned ranges disagree and the acceptance test would fail loudly.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import assert from "node:assert/strict";
+
+import type { Mode, RepairState } from "./repair-types.js";
+import type { RebuildInput } from "./rebuild.js";
+import { V2, readManifest } from "./_acceptance-fixture.js";
+
+/** A subsystem state as it appears in JSON: high-waters are numbers, not bigints. */
+export interface RepairFxState {
+  subsystem: string;
+  derivedHighWater: number;
+  authorityHighWater: number;
+  lastRebuildAt: number | null;
+  generation: number;
+  mode: Mode;
+  failedAttempts?: number;
+  authorityFrozen?: boolean;
+}
+
+export interface RepairFxRebuild {
+  subsystem: string;
+  generation: number;
+  currentGeneration: number;
+  sourceBytesBase64: string;
+  expectedDigest: string;
+  triadMode: Mode;
+}
+
+export interface RepairFxBackoff {
+  subsystem: string;
+  attempts: number[];
+}
+
+export interface RepairFxInput {
+  scenario: string;
+  /** Which real entry point the acceptance test drives. */
+  mode: "detect" | "backoff" | "rebuild";
+  /** The INJECTED monotonic clock — VC6C never reads a real clock. */
+  nowMs: number;
+  states: RepairFxState[];
+  rebuild?: RepairFxRebuild;
+  backoff?: RepairFxBackoff;
+}
+
+export interface RepairFxExpected {
+  ok: boolean;
+  code?: string;
+  plannedCount: number;
+  /** Exact [seqStart, seqEnd] of each plan, in plan order. */
+  ranges: number[][];
+  switched?: boolean;
+  generation?: number;
+  semanticLossStated?: boolean;
+  monotonic?: boolean;
+  capped?: boolean;
+  idempotent?: boolean;
+}
+
+export interface RepairFx {
+  id: string;
+  schema: string;
+  producer: string;
+  assertion: string;
+  kind: string;
+  input: RepairFxInput;
+  expected: RepairFxExpected;
+}
+
+/** Read one registered healing-controller fixture (asserting it IS registered). */
+export function repairFixture(id: string): RepairFx {
+  const m = readManifest();
+  const row = m.fixtures.find(
+    (f) => f.id === id && f.path.startsWith("healing-controller/"),
+  );
+  assert.ok(row, `fixture ${id} registered under healing-controller/ in manifest`);
+  return JSON.parse(readFileSync(join(V2, row!.path), "utf8")) as RepairFx;
+}
+
+/** JSON numbers -> the bigint fields `RepairState` declares. */
+export function decodeState(s: RepairFxState): RepairState {
+  return {
+    subsystem: s.subsystem,
+    derivedHighWater: BigInt(s.derivedHighWater),
+    authorityHighWater: BigInt(s.authorityHighWater),
+    lastRebuildAt: s.lastRebuildAt === null ? null : BigInt(s.lastRebuildAt),
+    generation: s.generation,
+    mode: s.mode,
+    ...(s.failedAttempts !== undefined ? { failedAttempts: s.failedAttempts } : {}),
+    ...(s.authorityFrozen !== undefined ? { authorityFrozen: s.authorityFrozen } : {}),
+  };
+}
+
+/** Reconstitute a real `RebuildInput` from its fixture row. */
+export function decodeRebuild(r: RepairFxRebuild): RebuildInput {
+  return {
+    subsystem: r.subsystem,
+    range: {
+      sessionId: r.subsystem,
+      seqStart: 0n,
+      seqEnd: 0n,
+      byteStart: 0,
+      byteEnd: 0,
+    },
+    generation: r.generation,
+    sourceBytes: new Uint8Array(Buffer.from(r.sourceBytesBase64, "base64")),
+    expectedDigest: r.expectedDigest,
+  };
+}
+
+/** Flag-pinned wrapper: VC6C gated by MEGACOMPACT_VC6C (defaults ON). */
+export function withVc6cFlagsOn(fn: () => void): () => void {
+  return (): void => {
+    const saved = process.env.MEGACOMPACT_VC6C;
+    process.env.MEGACOMPACT_VC6C = "1";
+    try {
+      fn();
+    } finally {
+      if (saved === undefined) delete process.env.MEGACOMPACT_VC6C;
+      else process.env.MEGACOMPACT_VC6C = saved;
+    }
+  };
+}

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/controller.ts

@@ -0,0 +1,189 @@
+/**
+ * vector-cortex/heal/controller.ts — VC6C gap detection + rebuild planning.
+ *
+ * Compares each derived subsystem's high-water to the durable authority
+ * high-water and emits a `RepairPlanV1` for every gap that is real, actionable,
+ * and not rate-limited. The controller DECIDES; `rebuild.ts` executes.
+ *
+ * THE AUTHORITY IS NEVER WRITTEN. Every function here takes `RepairState` (whose
+ * `authorityHighWater` is readonly) and returns plans. There is no code path,
+ * guarded or otherwise, that mutates authority — derived state is rebuildable,
+ * authority is not, so repair is strictly one-directional.
+ *
+ * FOUR REASONS NOT TO PLAN, in priority order. The order is the contract: a
+ * frozen authority outranks a rate limit, because "the frontier is not real yet"
+ * is a statement about CORRECTNESS while "you rebuilt recently" is only about
+ * pacing. Reporting RATE_LIMITED during an outage would tell an operator to wait
+ * five minutes for a rebuild that must never happen at all.
+ *
+ *   1. AUTHORITY FROZEN. During an outage the durable high-water freezes while
+ *      the spool keeps accepting frames (TRIAD_RESILIENCE §frontier). A derived
+ *      subsystem behind a frozen frontier is CORRECT, so we refuse to plan rather
+ *      than chase the spool tail and materialize non-durable frames.
+ *   2. NO GAP. `derived >= authority` — nothing to do. Note `>`: a derived source
+ *      AHEAD of authority is not repaired by rebuilding a backwards range (that
+ *      would produce an inverted range); it is left alone for the breaker.
+ *   3. MODE C. Derived state is disabled for this subsystem. Re-planning a
+ *      subsystem whose derived tier is intentionally off is a rebuild loop.
+ *   4. RATE LIMITED. One rebuild per subsystem per 5 minutes.
+ *
+ * DETERMINISTIC JITTER. The ±10% spread comes from a SHA-256 of the subsystem
+ * name plus the attempt, never `Math.random`. Two subsystems desynchronize (no
+ * thundering herd) while a single subsystem's schedule is byte-reproducible — a
+ * fixture can pin `backoffMs` exactly, which a PRNG would make untestable.
+ *
+ * PURE. `node:crypto` is the only dependency beyond types: no storage, no
+ * console, no network, and no clock — `nowMs` is always injected, which is what
+ * makes the fake-clock restart fixtures possible (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { createHash } from "node:crypto";
+
+import type {
+  RepairPlanV1,
+  RepairState,
+  RepairSubsystem,
+  ShardRange,
+} from "./repair-types.js";
+import {
+  REPAIR_BACKOFF_BASE_MS,
+  REPAIR_BACKOFF_CAP_MS,
+  REPAIR_BACKOFF_JITTER,
+  REPAIR_RATE_LIMIT_MS,
+} from "./repair-types.js";
+
+/**
+ * A stable fraction in [0,1) derived from the subsystem name + attempt.
+ *
+ * Uses the first 6 hex digits (24 bits) of SHA-256 — plenty of spread for a ±10%
+ * window, and small enough to stay exact in a float64 division.
+ */
+function digestFraction(subsystem: RepairSubsystem, attempt: number): number {
+  const hex = createHash("sha256")
+    .update(`${subsystem}:${attempt}`)
+    .digest("hex")
+    .slice(0, 6);
+  return parseInt(hex, 16) / 0x1000000;
+}
+
+/**
+ * Deterministic exponential backoff: `30s * 2^attempt`, capped at 15 minutes,
+ * then spread by ±10% seeded from the subsystem digest.
+ *
+ * The cap is applied BEFORE the jitter so the jitter is a spread around the cap
+ * rather than a way to exceed it; the result is floored to an integer ms so the
+ * value is exactly representable in JSON (a fixture pins it verbatim).
+ *
+ * `attempt` is clamped at 0 and at 30: `2^attempt` for an unclamped large attempt
+ * would reach Infinity, and `Infinity * jitter` is NaN — a NaN backoff would
+ * schedule a plan that is never eligible and silently wedge the subsystem.
+ */
+export function computeBackoff(subsystem: RepairSubsystem, attempt: number): number {
+  const safe = Math.min(Math.max(Math.floor(attempt), 0), 30);
+  const raw = REPAIR_BACKOFF_BASE_MS * 2 ** safe;
+  const capped = Math.min(raw, REPAIR_BACKOFF_CAP_MS);
+  // Map [0,1) onto [-1,+1) then scale to the ±10% window.
+  const spread = (digestFraction(subsystem, safe) * 2 - 1) * REPAIR_BACKOFF_JITTER;
+  return Math.max(0, Math.floor(capped * (1 + spread)));
+}
+
+/**
+ * True when this subsystem rebuilt less than 5 minutes ago.
+ *
+ * A subsystem that has NEVER rebuilt (`lastRebuildAt === null`) is never rate
+ * limited — the first repair after a restart must not be delayed by the absence
+ * of history.
+ */
+export function isRateLimited(
+  lastRebuildAt: bigint | null,
+  nowMs: bigint,
+): boolean {
+  if (lastRebuildAt === null) return false;
+  return lastRebuildAt + BigInt(REPAIR_RATE_LIMIT_MS) > nowMs;
+}
+
+/**
+ * The seq window a rebuild must cover: the first UNBUILT seq through the
+ * authority frontier, inclusive.
+ *
+ * Byte bounds are intentionally 0..0. VC6C plans in SEQ space — the controller
+ * knows how far each derived tier has been built, but byte offsets belong to the
+ * shard/ledger layer that executes the rebuild. Inventing byte bounds here would
+ * be fabricating a fact the controller does not have.
+ */
+function gapRange(state: RepairState): ShardRange {
+  return {
+    sessionId: state.subsystem,
+    seqStart: state.derivedHighWater + 1n,
+    seqEnd: state.authorityHighWater,
+    byteStart: 0,
+    byteEnd: 0,
+  };
+}
+
+/**
+ * Build the plan for one subsystem's gap.
+ *
+ * Always targets `generation + 1`: a rebuild NEVER writes into the live
+ * generation, so a failed or half-written rebuild cannot corrupt what is
+ * currently being served (see `rebuild.ts` copy-then-switch).
+ *
+ * Exported for direct unit testing and for callers that have already decided a
+ * plan is warranted; `detectGaps` is the guarded entry point that applies the
+ * four refusal rules first.
+ */
+export function planRebuild(state: RepairState, nowMs: bigint): RepairPlanV1 {
+  const backoffMs = computeBackoff(state.subsystem, state.failedAttempts ?? 0);
+  return {
+    schema: "repair-plan-v1",
+    subsystem: state.subsystem,
+    range: gapRange(state),
+    generation: state.generation + 1,
+    backoffMs,
+    scheduledAt: nowMs + BigInt(backoffMs),
+  };
+}
+
+/**
+ * True when a subsystem is eligible for a rebuild plan (the four refusal rules).
+ * Ordering matters — see the file header.
+ */
+export function isPlannable(state: RepairState, nowMs: bigint): boolean {
+  if (state.authorityFrozen === true) return false;
+  if (state.derivedHighWater >= state.authorityHighWater) return false;
+  if (state.mode === "C") return false;
+  if (isRateLimited(state.lastRebuildAt, nowMs)) return false;
+  return true;
+}
+
+/**
+ * Detect derived gaps and plan a rebuild for each eligible subsystem.
+ *
+ * Output order follows INPUT order, not subsystem name: the caller controls
+ * priority (a topology gap may matter more than a closure gap), and re-sorting
+ * here would silently override that. Never throws — an unplannable subsystem is
+ * simply absent from the result, so a single wedged tier cannot stop the others
+ * from healing (PRACTICES: non-fatal).
+ */
+export function detectGaps(
+  states: readonly RepairState[],
+  nowMs: bigint,
+): readonly RepairPlanV1[] {
+  const plans: RepairPlanV1[] = [];
+  for (const state of states) {
+    if (!isPlannable(state, nowMs)) continue;
+    plans.push(planRebuild(state, nowMs));
+  }
+  return plans;
+}
+
+/**
+ * The bound controller surface. A plain object (not a class): there is no
+ * instance state to hold — every input, including the clock, is injected.
+ */
+export function createRepairController(): {
+  readonly detectGaps: typeof detectGaps;
+  readonly planRebuild: typeof planRebuild;
+} {
+  return { detectGaps, planRebuild };
+}