pi-mega-compact 0.20.34 → 0.20.36

package/src/vector-cortex/reconstruct/repair-plan.ts

@@ -0,0 +1,112 @@
+/**
+ * vector-cortex/reconstruct/repair-plan.ts — VC6C-IMPL production repair plan seam.
+ *
+ * Maps a compact result into the production-facing plan the handler emits. The
+ * pure `heal/repair-types.ts` contract stays the canonical design carrier; this
+ * file owns the PRODUCTION shape (`RepairPlanV1` / `RepairEventV1`) that the
+ * post-compact controller drives, plus the builder that turns a per-subsystem
+ * gap into a plan.
+ *
+ * RELATIONSHIP TO heal/. The `heal/` modules (VC6C) already ship the pure
+ * gap-detection / backoff / rebuild / switch primitives and 74 passing tests.
+ * This sprint wires them into the production compact path; it does NOT fork
+ * them. `buildRepairPlan` reuses `computeBackoff` for the deterministic
+ * exponential delay (30s * 2^attempt, 15 min cap, ±10% SHA-256-derived jitter,
+ * never `Math.random`) so a plan's `backoffMs` is byte-reproducible in a
+ * fixture. Gap arithmetic mirrors `heal/controller.ts#gapRange`: the plan's seq
+ * window is `derived post-count + 1 .. durable authority high-water`, inclusive,
+ * exactly the unbuilt range.
+ *
+ * THE AUTHORITY IS NEVER WRITTEN. A plan carries `authorityHighWater` for
+ * identity only; no code here (or anywhere in this sprint) mutates the durable
+ * authority. `generation` is the NEW derived generation the rebuild writes into
+ * (always `current + 1`), mirroring the heal copy-then-switch rule.
+ *
+ * PURE. `node:crypto` is used only transitively through `computeBackoff`; no
+ * storage, no console, no clock of its own (`nowMs` is injected), no network
+ * (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { computeBackoff } from "../heal/controller.js";
+import type { Mode, RepairSubsystem } from "../heal/repair-types.js";
+
+/**
+ * Production repair plan: the exact shape the handler emits and the acceptance
+ * fixture VC6C-IMPL-004 pins.
+ *
+ * `range` is a plain `[seqStart, seqEnd]` tuple (inclusive) — the production
+ * handler deals in seq space, not byte shards, so the plan stays the cheap
+ * operator-facing shape while `heal/repair-types.ts#RepairPlanV1.range` remains
+ * the full `ShardRange` carrier for the pure controller.
+ */
+export interface RepairPlanV1 {
+  readonly schema: "repair-plan-v1";
+  /** The derived subsystem being repaired (e.g. "topology"). */
+  readonly subsystem: RepairSubsystem;
+  /** Inclusive seq window to rebuild: derived post-count + 1 .. authority. */
+  readonly range: readonly [number, number];
+  /** The NEW derived generation the rebuild materializes into. */
+  readonly generation: number;
+  /** Deterministic delay (ms) before the plan may execute. */
+  readonly backoffMs: number;
+}
+
+/**
+ * A repair lifecycle record emitted by the handler. Identity and counters only —
+ * never a rebuilt byte, never a root digest of user content (SECURITY_PRIVACY).
+ */
+export interface RepairEventV1 {
+  readonly schema: "repair-event-v1";
+  readonly subsystem: RepairSubsystem;
+  readonly kind: "planned" | "pointer-switched" | "backoff";
+  readonly generation: number;
+  readonly backoffMs: number;
+  readonly code?: string;
+}
+
+/**
+ * One subsystem's post-compact view used to build a plan. `postCount` is the
+ * derived high-water (inclusive) AFTER compaction; `authorityHighWater` is the
+ * durable contiguous authority frontier (inclusive), read-only.
+ */
+export interface PostCompactGap {
+  readonly subsystem: RepairSubsystem;
+  readonly postCount: number;
+  readonly authorityHighWater: number;
+  /** The CURRENT live generation; a plan targets `generation + 1`. */
+  readonly generation: number;
+  /** Consecutive failed attempts, the exponent in the exponential backoff. */
+  readonly failedAttempts?: number;
+  /** Which triad arm currently serves this subsystem. */
+  readonly mode: Mode;
+}
+
+/**
+ * The size of the gap (how many seq steps the derived tier fell behind the
+ * authority), used for the `gapSize` event payload — derived from the plan
+ * inputs, never a hardcoded literal.
+ */
+export function gapSizeOf(gap: PostCompactGap): number {
+  return Math.max(0, gap.authorityHighWater - gap.postCount);
+}
+
+/**
+ * Map one subsystem's post-compact gap into a production `RepairPlanV1`.
+ *
+ * Mirrors `heal/controller.ts#planRebuild`: the seq window is
+ * `[postCount + 1, authorityHighWater]`, the generation targets `current + 1`,
+ * and the backoff is the deterministic heal `computeBackoff`. No clock is read
+ * here — the production shape carries no `scheduledAt`; the `nowMs`-injected
+ * rate-limit/backoff decisions live in the heal controller (`detectGaps`), which
+ * the handler drives with its own injected clock for reproducible fixtures.
+ */
+export function buildRepairPlan(gap: PostCompactGap): RepairPlanV1 {
+  const backoffMs = computeBackoff(gap.subsystem, gap.failedAttempts ?? 0);
+  return {
+    schema: "repair-plan-v1",
+    subsystem: gap.subsystem,
+    range: [gap.postCount + 1, gap.authorityHighWater],
+    generation: gap.generation + 1,
+    backoffMs,
+  };
+}