pi-mega-compact 0.20.33 → 0.20.35

package/dist/extensions/mega-events/context-handler/afterCompact.js

@@ -7,6 +7,7 @@
  * raw_transcript, and fire-and-forgets the dedup pipeline. All best-effort +
  * non-fatal — a failure never breaks the agent loop.
  */
+import { createHash } from "node:crypto";
 import { openStore, writeCheckpointEpoch, } from "../../../src/store/sqlite.js";
 import { epochIdFor } from "../../../src/mirror/epoch.js";
 import { stampTurnsEpochFor } from "../../mega-turn-store.js";
@@ -17,6 +18,7 @@ import { assignNewMemoriesIncremental } from "../../../src/wiki/index.js";
 import { TrigramEmbedder } from "../../../src/embedder.js";
 import { reportClosureOptimized } from "../../../src/vector-cortex/heal/emit.js";
 import { reportRepairPlanned } from "../../../src/vector-cortex/heal/repair-emit.js";
+import { buildPostCompactViews, drivePostCompactRepair, } from "./controller.js";
 import { VC6A_ENABLED, VC6C_ENABLED } from "../../../src/config/vector-cortex.js";
 /**
  * Persist the checkpoint_epoch, stamp turns, rebuild the auto-wiki, seed the
@@ -215,9 +217,8 @@ export async function persistEpochAndMaintain(runtime, config, ran) {
             runtime.logger.warn("db-mirror-epoch-fail", { error: String(e) });
         }
     }
-    // VC6 Heal lifecycle emits (post-compact). Wiring stubs — dashboard graph +
-    // event counts move; real gap detection/rebuild is a future sprint.
-    // VC6A: closure-optimization savings from the compact token delta.
+    // VC6 Heal lifecycle emits (post-compact). VC6A: closure-optimization
+    // savings from the compact token delta.
     const savings = Math.max(0, (ran.result.originalTokenEstimate ?? 0) - (ran.result.tokenEstimate ?? 0));
     if (VC6A_ENABLED()) {
         try {
@@ -232,8 +233,36 @@ export async function persistEpochAndMaintain(runtime, config, ran) {
             /* non-fatal: VC6A heal emit never breaks compaction */
         }
     }
-    // VC6C: repair-planner placeholder (no real gap detection yet).
+    // VC6C: real post-compact gap detection + atomic repair drive (VC6C-IMPL).
+    // Builds each derived subsystem's pre/post compact view against the durable
+    // authority high-water, runs the heal eligibility policy (gap-ness, frozen
+    // authority, mode C, the 5-min rate limit), and only on a REAL gap routes
+    // plan -> rebuild -> emit the three repair events. No real gap => emit
+    // NOTHING (VC6C-IMPL-006: no rebuild without a real gap). Flag OFF keeps the
+    // predecessor placeholder byte-identical (reportRepairPlanned with hardcoded
+    // backoffMs:0, gapSize:compactedFrom) and rebuild is a no-op — the reported
+    // seam is flag-gated, so the placeholder emits nothing, exactly as before.
     if (VC6C_ENABLED()) {
+        try {
+            const emit = (name, payload) => runtime.appendEvent(name, payload);
+            const views = buildPostCompactViews(ran.result.compactedFrom, runtime.rt.compactCount);
+            drivePostCompactRepair(views, BigInt(Date.now()), emit, () => {
+                // The derived generation for the repaired range is re-materialized
+                // from the compact summary and verified as a strict successor.
+                const bytes = new Uint8Array(Buffer.from(ran.result.summary, "utf8"));
+                const digest = createHash("sha256")
+                    .update(bytes)
+                    .digest("hex");
+                return { sourceBytes: bytes, expectedDigest: digest };
+            });
+        }
+        catch {
+            /* non-fatal: VC6C heal repair never breaks compaction */
+        }
+    }
+    else {
+        // Flag-off: predecessor placeholder, byte-identical (emits nothing via
+        // the flag-gated reporter seam).
         try {
             reportRepairPlanned((name, payload) => runtime.appendEvent(name, payload), {
                 subsystem: "post_compact",

package/dist/extensions/mega-events/context-handler/controller.js

@@ -0,0 +1,161 @@
+/**
+ * context-handler/controller.ts — VC6C-IMPL production post-compact gap
+ * detection + repair drive.
+ *
+ * The production seam that makes the VC6C self-healing controller REAL: after a
+ * compact, compare each derived subsystem's POST-compact chunk count against the
+ * durable authority high-water. A subsystem whose derived high-water fell behind
+ * authority has a REAL gap; only then does the drive route through the plan →
+ * rebuild → emit pipeline. When there is no real gap, NOTHING is emitted (no
+ * rebuild without a real gap — VC6C-IMPL-006).
+ *
+ * PURE POLICY DEFERS TO heal/. Gap-ness, the four refusal rules (frozen
+ * authority / no gap / mode C / rate limit), and the deterministic backoff are
+ * the VC6C heal primitives' job (`detectGaps`, `isPlannable`, `computeBackoff`
+ * — 74 tested lines). This file owns ONLY the production mapping: `PostCompactView`
+ * → `RepairState` (so heal policy can judge it) → `RepairPlanV1` (production
+ * shape) → `AtomicRebuild` (atomic pointer switch) → the three repair events.
+ * Flag OFF = the placeholder continues firing exactly as today and rebuild is a
+ * no-op; see `drivePostCompactRepair`'s caller in afterCompact.ts.
+ *
+ * THE AUTHORITY IS NEVER WRITTEN. `PostCompactView.authorityHighWater` is read to
+ * decide gap-ness; no code here has a write path to the durable authority.
+ *
+ * PURE-ish + CONSTANT-FREE. `nowMs` is always injected (fake-clock fixtures).
+ * Backoff/gap come from the plan, never a literal. No console, no network
+ * (PREVENT-PI-004). Emit is an injected callback so the drive is unit-testable
+ * without a runtime.
+ */
+import { isPlannable } from "../../../src/vector-cortex/heal/controller.js";
+import { reportRepairBackoff, reportRepairPlanned, reportRepairPointerSwitched, } from "../../../src/vector-cortex/heal/repair-emit.js";
+import { buildRepairPlan, gapSizeOf, } from "../../../src/vector-cortex/reconstruct/repair-plan.js";
+import { rebuildRepairRange, } from "../../../src/vector-cortex/reconstruct/rebuild.js";
+/**
+ * Detect the subsystems whose POST-compact derived high-water fell behind the
+ * durable authority. `left` is the pre-compact view, `right` the post-compact
+ * view (aligned by subsystem name); a subsystem qualifies when its POST count
+ * is strictly below its durable authority high-water. Pure — no clock, no
+ * writes.
+ */
+export function detectPostCompactGaps(left, right) {
+    const byName = new Map(right.map((v) => [v.subsystem, v]));
+    const gapped = [];
+    for (const l of left) {
+        const r = byName.get(l.subsystem);
+        if (r === undefined)
+            continue;
+        if (r.postCount < r.authorityHighWater)
+            gapped.push(r);
+    }
+    return gapped;
+}
+/** Map a production post-compact view into the heal `RepairState` judge shape. */
+export function toRepairState(view) {
+    return {
+        subsystem: view.subsystem,
+        derivedHighWater: BigInt(view.postCount),
+        authorityHighWater: BigInt(view.authorityHighWater),
+        lastRebuildAt: view.lastRebuildAtMs,
+        generation: view.generation,
+        mode: view.mode,
+        ...(view.failedAttempts !== undefined ? { failedAttempts: view.failedAttempts } : {}),
+        ...(view.authorityFrozen !== undefined ? { authorityFrozen: view.authorityFrozen } : {}),
+    };
+}
+/** Build the production plan for one gapped view. */
+export function planFor(view) {
+    return buildRepairPlan(view);
+}
+function rebuildInputFor(plan, src) {
+    return {
+        subsystem: plan.subsystem,
+        range: {
+            sessionId: plan.subsystem,
+            seqStart: BigInt(plan.range[0]),
+            seqEnd: BigInt(plan.range[1]),
+            byteStart: 0,
+            byteEnd: 0,
+        },
+        generation: plan.generation,
+        sourceBytes: src.sourceBytes,
+        expectedDigest: src.expectedDigest,
+    };
+}
+/**
+ * Drive one repair for a gapped subsystem: plan → rebuild → emit.
+ *
+ * Emits `reportRepairPlanned` first (the plan with its deterministic backoff),
+ * then executes the atomic rebuild; a verified strict-successor switch emits
+ * `reportRepairPointerSwitched`, a failed rebuild emits `reportRepairBackoff`.
+ * `currentGeneration` (the live generation) is read for the monotonic switch.
+ */
+export function driveOneRepair(view, emit, rebuildSource) {
+    const plan = planFor(view);
+    reportRepairPlanned(emit, {
+        subsystem: plan.subsystem,
+        generation: plan.generation,
+        backoffMs: plan.backoffMs,
+        gapSize: gapSizeOf(view),
+    });
+    const rebuilt = rebuildRepairRange(plan, rebuildInputFor(plan, rebuildSource), view.generation, view.mode);
+    if (rebuilt.pointer.switched) {
+        reportRepairPointerSwitched(emit, {
+            subsystem: plan.subsystem,
+            fromGeneration: view.generation,
+            toGeneration: plan.generation,
+            mode: view.mode,
+        });
+    }
+    else {
+        reportRepairBackoff(emit, {
+            subsystem: plan.subsystem,
+            code: rebuilt.result.ok ? "HEAL_REPAIR_RATE_LIMITED" : (rebuilt.result.code ?? "HEAL_REBUILD_FAILED"),
+            backoffMs: plan.backoffMs,
+            attempt: view.failedAttempts ?? 0,
+        });
+    }
+    return { plan, rebuilt };
+}
+/**
+ * The full post-compact repair drive. Applies heal's eligibility policy
+ * (`isPlannable` — rate limit, no gap, frozen authority, mode C) per subsystem,
+ * and only runs `driveOneRepair` for subsystems with a REAL, actionable gap. A
+ * subsystem with no real gap, or inside its rate-limit window, emits NOTHING.
+ *
+ * `rebuildSourceFor` is an injected executor that materializes a new generation
+ * for a plannable subsystem (the handler supplies the real one; fixtures supply
+ * a deterministic one), keeping the drive testable without a runtime.
+ */
+export function drivePostCompactRepair(views, nowMs, emit, rebuildSourceFor) {
+    for (const view of views) {
+        const state = toRepairState(view);
+        if (!isPlannable(state, nowMs))
+            continue;
+        driveOneRepair(view, emit, rebuildSourceFor(view));
+    }
+}
+/**
+ * Build the production post-compact subsystem views from a compact result.
+ *
+ * `compactedFrom` is the committed seq frontier after compaction. In a NORMAL
+ * compact the derived post-count equals the durable authority high-water (they
+ * advance together), so the resulting view has NO real gap — the drive emits
+ * nothing (VC6C-IMPL-006). A caller that derives per-subsystem counts where a
+ * derived tier fell behind authority supplies those lower counts here, and the
+ * drive will detect the gap and repair it. `currentGeneration` seeds the derived
+ * generation counter.
+ */
+export function buildPostCompactViews(compactedFrom, currentGeneration, authorityHighWater = compactedFrom, postCount = compactedFrom) {
+    return [
+        {
+            subsystem: "post_compact",
+            preCount: compactedFrom,
+            postCount,
+            authorityHighWater,
+            generation: currentGeneration,
+            failedAttempts: 0,
+            mode: "A",
+            lastRebuildAtMs: null,
+        },
+    ];
+}

package/dist/src/vector-cortex/heal/_vc6c-impl-fixture.js

@@ -0,0 +1,29 @@
+/**
+ * heal/_vc6c-impl-fixture.ts — conformance fixture I/O for VC6C-IMPL
+ * self-healing-controller rows.
+ *
+ * VC6C's base corpus lives under `healing-controller/` (read by
+ * `_repair-fixture.ts`); VC6C-IMPL emits its six fixtures under
+ * `self-healing/` per the sprint brief. Both share the one canonical
+ * `healing-controller-fixture.schema.json`, so this loader reuses the
+ * `RepairFx` envelope (`_repair-fixture.ts`) but resolves fixture paths from
+ * the `self-healing/` directory. No mocks — the committed fixtures are fed
+ * verbatim into the real heal / reconstruct production modules.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import assert from "node:assert/strict";
+import { V2, readManifest } from "./_acceptance-fixture.js";
+const PREFIX = "self-healing";
+/** Read one registered VC6C-IMPL fixture (asserting it IS registered). */
+export function vc6cImplFixture(id) {
+    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"));
+}
+/**
+ * The six VC6C-IMPL fixture ids, in corpus order. The acceptance test drives
+ * each through the real production seam and asserts its pinned verdict.
+ */
+export const VC6C_IMPL_IDS = Array.from({ length: 6 }, (_v, i) => `VC6C-IMPL-${String(i + 1).padStart(3, "0")}`);

package/dist/src/vector-cortex/reconstruct/rebuild.js

@@ -0,0 +1,43 @@
+/**
+ * vector-cortex/reconstruct/rebuild.ts — VC6C-IMPL production atomic rebuild.
+ *
+ * The thin *production executor* over the pure `heal/rebuild.ts` copy-verify-
+ * switch primitives. It materializes a NEW derived generation for the planned
+ * range, verifies the root manifest digest is a STRICT SUCCESSOR (the planned
+ * `generation` is `current + 1` and the switch refuses any non-monotonic move),
+ * and swaps the pointer in a single atomic commit. A failed verification keeps
+ * the old pointer and DELETES NO EVIDENCE: the orphaned generation is retained
+ * for inspection (heal/rebuild.ts crash-safety contract).
+ *
+ * REUSES, DOES NOT FORK. `rebuildGeneration` + `switchPointer` are the same
+ * functions VC6C shipped and tested (74 tests). This file only binds them to
+ * the production `RepairPlanV1` shape and the atomic-commit framing the
+ * post-compact handler calls — the whole point of VC6C-IMPL is that the pure
+ * primitives already exist and only the production seam was missing.
+ *
+ * STRICT SUCCESSOR. The pointer moves only when (a) verification passed and
+ * (b) the new generation is STRICTLY greater than the current one. Replaying a
+ * stale plan after a restart cannot roll the pointer backwards — the same
+ * monotonic guard `heal/rebuild.ts#switchPointer` enforces.
+ *
+ * THE AUTHORITY IS NEVER MUTATED. This rebuild only swaps the DERIVED generation
+ * pointer; the durable authority is untouched. `currentGeneration` is read to
+ * enforce monotonicity, never written.
+ *
+ * PURE. No storage, no console, no network (PREVENT-PI-004 / PREVENT-011);
+ * `node:crypto` comes via the heal digest helper.
+ */
+import { rebuildAndSwitch, } from "../heal/rebuild.js";
+/**
+ * Materialize + atomically switch a planned repair range.
+ *
+ * `rebuildInput` carries the materialized new-generation bytes and the root
+ * digest the plan pinned. The helper reuses `heal/rebuild.ts#rebuildAndSwitch`,
+ * which verifies the digest FIRST and refuses to switch under any combination of
+ * failed verification or non-strict generation — "switch without verifying" is
+ * not expressible.
+ */
+export function rebuildRepairRange(plan, rebuildInput, currentGeneration, mode = "A") {
+    const { result, pointer } = rebuildAndSwitch(rebuildInput, currentGeneration, mode);
+    return { plan, result, pointer };
+}

package/dist/src/vector-cortex/reconstruct/repair-plan.js

@@ -0,0 +1,57 @@
+/**
+ * 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";
+/**
+ * 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) {
+    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) {
+    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,
+    };
+}

package/dist/vector-cortex/heal/_vc6c-impl-fixture.js

@@ -0,0 +1,29 @@
+/**
+ * heal/_vc6c-impl-fixture.ts — conformance fixture I/O for VC6C-IMPL
+ * self-healing-controller rows.
+ *
+ * VC6C's base corpus lives under `healing-controller/` (read by
+ * `_repair-fixture.ts`); VC6C-IMPL emits its six fixtures under
+ * `self-healing/` per the sprint brief. Both share the one canonical
+ * `healing-controller-fixture.schema.json`, so this loader reuses the
+ * `RepairFx` envelope (`_repair-fixture.ts`) but resolves fixture paths from
+ * the `self-healing/` directory. No mocks — the committed fixtures are fed
+ * verbatim into the real heal / reconstruct production modules.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import assert from "node:assert/strict";
+import { V2, readManifest } from "./_acceptance-fixture.js";
+const PREFIX = "self-healing";
+/** Read one registered VC6C-IMPL fixture (asserting it IS registered). */
+export function vc6cImplFixture(id) {
+    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"));
+}
+/**
+ * The six VC6C-IMPL fixture ids, in corpus order. The acceptance test drives
+ * each through the real production seam and asserts its pinned verdict.
+ */
+export const VC6C_IMPL_IDS = Array.from({ length: 6 }, (_v, i) => `VC6C-IMPL-${String(i + 1).padStart(3, "0")}`);

package/dist/vector-cortex/reconstruct/rebuild.js

@@ -0,0 +1,43 @@
+/**
+ * vector-cortex/reconstruct/rebuild.ts — VC6C-IMPL production atomic rebuild.
+ *
+ * The thin *production executor* over the pure `heal/rebuild.ts` copy-verify-
+ * switch primitives. It materializes a NEW derived generation for the planned
+ * range, verifies the root manifest digest is a STRICT SUCCESSOR (the planned
+ * `generation` is `current + 1` and the switch refuses any non-monotonic move),
+ * and swaps the pointer in a single atomic commit. A failed verification keeps
+ * the old pointer and DELETES NO EVIDENCE: the orphaned generation is retained
+ * for inspection (heal/rebuild.ts crash-safety contract).
+ *
+ * REUSES, DOES NOT FORK. `rebuildGeneration` + `switchPointer` are the same
+ * functions VC6C shipped and tested (74 tests). This file only binds them to
+ * the production `RepairPlanV1` shape and the atomic-commit framing the
+ * post-compact handler calls — the whole point of VC6C-IMPL is that the pure
+ * primitives already exist and only the production seam was missing.
+ *
+ * STRICT SUCCESSOR. The pointer moves only when (a) verification passed and
+ * (b) the new generation is STRICTLY greater than the current one. Replaying a
+ * stale plan after a restart cannot roll the pointer backwards — the same
+ * monotonic guard `heal/rebuild.ts#switchPointer` enforces.
+ *
+ * THE AUTHORITY IS NEVER MUTATED. This rebuild only swaps the DERIVED generation
+ * pointer; the durable authority is untouched. `currentGeneration` is read to
+ * enforce monotonicity, never written.
+ *
+ * PURE. No storage, no console, no network (PREVENT-PI-004 / PREVENT-011);
+ * `node:crypto` comes via the heal digest helper.
+ */
+import { rebuildAndSwitch, } from "../heal/rebuild.js";
+/**
+ * Materialize + atomically switch a planned repair range.
+ *
+ * `rebuildInput` carries the materialized new-generation bytes and the root
+ * digest the plan pinned. The helper reuses `heal/rebuild.ts#rebuildAndSwitch`,
+ * which verifies the digest FIRST and refuses to switch under any combination of
+ * failed verification or non-strict generation — "switch without verifying" is
+ * not expressible.
+ */
+export function rebuildRepairRange(plan, rebuildInput, currentGeneration, mode = "A") {
+    const { result, pointer } = rebuildAndSwitch(rebuildInput, currentGeneration, mode);
+    return { plan, result, pointer };
+}

package/dist/vector-cortex/reconstruct/repair-plan.js

@@ -0,0 +1,57 @@
+/**
+ * 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";
+/**
+ * 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) {
+    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) {
+    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,
+    };
+}

package/extensions/mega-events/context-handler/afterCompact.ts

@@ -7,6 +7,7 @@
  * raw_transcript, and fire-and-forgets the dedup pipeline. All best-effort +
  * non-fatal — a failure never breaks the agent loop.
  */
+import { createHash } from "node:crypto";
 import {
 	openStore,
 	writeCheckpointEpoch,
@@ -30,6 +31,10 @@ import type { EmbeddedChunk } from "../../../src/topics/types.js";
 import type { MegaConfig } from "../../mega-config.js";
 import { reportClosureOptimized } from "../../../src/vector-cortex/heal/emit.js";
 import { reportRepairPlanned } from "../../../src/vector-cortex/heal/repair-emit.js";
+import {
+	buildPostCompactViews,
+	drivePostCompactRepair,
+} from "./controller.js";
 import { VC6A_ENABLED, VC6C_ENABLED } from "../../../src/config/vector-cortex.js";
 
 /** Shape of the compact result consumed by the epoch/maintenance writes. */
@@ -278,9 +283,8 @@ export async function persistEpochAndMaintain(
 		}
 	}
 
-	// VC6 Heal lifecycle emits (post-compact). Wiring stubs — dashboard graph +
-	// event counts move; real gap detection/rebuild is a future sprint.
-	// VC6A: closure-optimization savings from the compact token delta.
+	// VC6 Heal lifecycle emits (post-compact). VC6A: closure-optimization
+	// savings from the compact token delta.
 	const savings = Math.max(
 		0,
 		(ran.result.originalTokenEstimate ?? 0) - (ran.result.tokenEstimate ?? 0),
@@ -301,8 +305,40 @@ export async function persistEpochAndMaintain(
 			/* non-fatal: VC6A heal emit never breaks compaction */
 		}
 	}
-	// VC6C: repair-planner placeholder (no real gap detection yet).
+	// VC6C: real post-compact gap detection + atomic repair drive (VC6C-IMPL).
+	// Builds each derived subsystem's pre/post compact view against the durable
+	// authority high-water, runs the heal eligibility policy (gap-ness, frozen
+	// authority, mode C, the 5-min rate limit), and only on a REAL gap routes
+	// plan -> rebuild -> emit the three repair events. No real gap => emit
+	// NOTHING (VC6C-IMPL-006: no rebuild without a real gap). Flag OFF keeps the
+	// predecessor placeholder byte-identical (reportRepairPlanned with hardcoded
+	// backoffMs:0, gapSize:compactedFrom) and rebuild is a no-op — the reported
+	// seam is flag-gated, so the placeholder emits nothing, exactly as before.
 	if (VC6C_ENABLED()) {
+		try {
+			const emit = (name: string, payload: unknown) =>
+				runtime.appendEvent(name, payload as Record<string, unknown>);
+			const views = buildPostCompactViews(
+				ran.result.compactedFrom,
+				runtime.rt.compactCount,
+			);
+			drivePostCompactRepair(views, BigInt(Date.now()), emit, () => {
+				// The derived generation for the repaired range is re-materialized
+				// from the compact summary and verified as a strict successor.
+				const bytes = new Uint8Array(
+					Buffer.from(ran.result.summary, "utf8"),
+				);
+				const digest = createHash("sha256")
+					.update(bytes)
+					.digest("hex");
+				return { sourceBytes: bytes, expectedDigest: digest };
+			});
+		} catch {
+			/* non-fatal: VC6C heal repair never breaks compaction */
+		}
+	} else {
+		// Flag-off: predecessor placeholder, byte-identical (emits nothing via
+		// the flag-gated reporter seam).
 		try {
 			reportRepairPlanned(
 				(name, payload) =>

package/extensions/mega-events/context-handler/controller.ts

@@ -0,0 +1,230 @@
+/**
+ * context-handler/controller.ts — VC6C-IMPL production post-compact gap
+ * detection + repair drive.
+ *
+ * The production seam that makes the VC6C self-healing controller REAL: after a
+ * compact, compare each derived subsystem's POST-compact chunk count against the
+ * durable authority high-water. A subsystem whose derived high-water fell behind
+ * authority has a REAL gap; only then does the drive route through the plan →
+ * rebuild → emit pipeline. When there is no real gap, NOTHING is emitted (no
+ * rebuild without a real gap — VC6C-IMPL-006).
+ *
+ * PURE POLICY DEFERS TO heal/. Gap-ness, the four refusal rules (frozen
+ * authority / no gap / mode C / rate limit), and the deterministic backoff are
+ * the VC6C heal primitives' job (`detectGaps`, `isPlannable`, `computeBackoff`
+ * — 74 tested lines). This file owns ONLY the production mapping: `PostCompactView`
+ * → `RepairState` (so heal policy can judge it) → `RepairPlanV1` (production
+ * shape) → `AtomicRebuild` (atomic pointer switch) → the three repair events.
+ * Flag OFF = the placeholder continues firing exactly as today and rebuild is a
+ * no-op; see `drivePostCompactRepair`'s caller in afterCompact.ts.
+ *
+ * THE AUTHORITY IS NEVER WRITTEN. `PostCompactView.authorityHighWater` is read to
+ * decide gap-ness; no code here has a write path to the durable authority.
+ *
+ * PURE-ish + CONSTANT-FREE. `nowMs` is always injected (fake-clock fixtures).
+ * Backoff/gap come from the plan, never a literal. No console, no network
+ * (PREVENT-PI-004). Emit is an injected callback so the drive is unit-testable
+ * without a runtime.
+ */
+
+import { isPlannable } from "../../../src/vector-cortex/heal/controller.js";
+import type { RepairState } from "../../../src/vector-cortex/heal/repair-types.js";
+import {
+  reportRepairBackoff,
+  reportRepairPlanned,
+  reportRepairPointerSwitched,
+  type RepairEmit,
+} from "../../../src/vector-cortex/heal/repair-emit.js";
+import {
+  buildRepairPlan,
+  gapSizeOf,
+  type PostCompactGap,
+  type RepairPlanV1,
+} from "../../../src/vector-cortex/reconstruct/repair-plan.js";
+import {
+  rebuildRepairRange,
+  type AtomicRebuild,
+  type RebuildInput,
+} from "../../../src/vector-cortex/reconstruct/rebuild.js";
+import type { Mode } from "../../../src/vector-cortex/heal/repair-types.js";
+
+/** One derived subsystem's pre/post compact counts against durable authority. */
+export interface PostCompactView {
+  readonly subsystem: string;
+  /** Derived chunk count BEFORE compaction. */
+  readonly preCount: number;
+  /** Derived chunk count AFTER compaction (the derived high-water, inclusive). */
+  readonly postCount: number;
+  /** Durable CONTIGUOUS authority high-water (inclusive). Read, never written. */
+  readonly authorityHighWater: number;
+  /** CURRENT live derived generation. A plan targets `generation + 1`. */
+  readonly generation: number;
+  readonly failedAttempts?: number;
+  readonly mode: Mode;
+  /** True while the durable authority frontier is frozen (outage). */
+  readonly authorityFrozen?: boolean;
+  /** Monotonic ms of the last rebuild, or null if never rebuilt. */
+  readonly lastRebuildAtMs: bigint | null;
+}
+
+/**
+ * Detect the subsystems whose POST-compact derived high-water fell behind the
+ * durable authority. `left` is the pre-compact view, `right` the post-compact
+ * view (aligned by subsystem name); a subsystem qualifies when its POST count
+ * is strictly below its durable authority high-water. Pure — no clock, no
+ * writes.
+ */
+export function detectPostCompactGaps(
+  left: readonly PostCompactView[],
+  right: readonly PostCompactView[],
+): readonly PostCompactView[] {
+  const byName = new Map(right.map((v) => [v.subsystem, v]));
+  const gapped: PostCompactView[] = [];
+  for (const l of left) {
+    const r = byName.get(l.subsystem);
+    if (r === undefined) continue;
+    if (r.postCount < r.authorityHighWater) gapped.push(r);
+  }
+  return gapped;
+}
+
+/** Map a production post-compact view into the heal `RepairState` judge shape. */
+export function toRepairState(view: PostCompactView): RepairState {
+  return {
+    subsystem: view.subsystem,
+    derivedHighWater: BigInt(view.postCount),
+    authorityHighWater: BigInt(view.authorityHighWater),
+    lastRebuildAt: view.lastRebuildAtMs,
+    generation: view.generation,
+    mode: view.mode,
+    ...(view.failedAttempts !== undefined ? { failedAttempts: view.failedAttempts } : {}),
+    ...(view.authorityFrozen !== undefined ? { authorityFrozen: view.authorityFrozen } : {}),
+  };
+}
+
+/** Build the production plan for one gapped view. */
+export function planFor(view: PostCompactView): RepairPlanV1 {
+  return buildRepairPlan(view as PostCompactGap);
+}
+
+/** Turn a production plan + view into the heal `RebuildInput` builder surface. */
+export interface RebuildSource {
+  /** Materialized bytes of the new derived generation. */
+  readonly sourceBytes: Uint8Array;
+  /** Root digest (BARE lowercase hex) the plan pins for the new generation. */
+  readonly expectedDigest: string;
+}
+
+function rebuildInputFor(plan: RepairPlanV1, src: RebuildSource): RebuildInput {
+  return {
+    subsystem: plan.subsystem,
+    range: {
+      sessionId: plan.subsystem,
+      seqStart: BigInt(plan.range[0]),
+      seqEnd: BigInt(plan.range[1]),
+      byteStart: 0,
+      byteEnd: 0,
+    },
+    generation: plan.generation,
+    sourceBytes: src.sourceBytes,
+    expectedDigest: src.expectedDigest,
+  };
+}
+
+/**
+ * Drive one repair for a gapped subsystem: plan → rebuild → emit.
+ *
+ * Emits `reportRepairPlanned` first (the plan with its deterministic backoff),
+ * then executes the atomic rebuild; a verified strict-successor switch emits
+ * `reportRepairPointerSwitched`, a failed rebuild emits `reportRepairBackoff`.
+ * `currentGeneration` (the live generation) is read for the monotonic switch.
+ */
+export function driveOneRepair(
+  view: PostCompactView,
+  emit: RepairEmit | undefined,
+  rebuildSource: RebuildSource,
+): { plan: RepairPlanV1; rebuilt: AtomicRebuild } {
+  const plan = planFor(view);
+  reportRepairPlanned(emit, {
+    subsystem: plan.subsystem,
+    generation: plan.generation,
+    backoffMs: plan.backoffMs,
+    gapSize: gapSizeOf(view as PostCompactGap),
+  });
+  const rebuilt = rebuildRepairRange(
+    plan,
+    rebuildInputFor(plan, rebuildSource),
+    view.generation,
+    view.mode,
+  );
+  if (rebuilt.pointer.switched) {
+    reportRepairPointerSwitched(emit, {
+      subsystem: plan.subsystem,
+      fromGeneration: view.generation,
+      toGeneration: plan.generation,
+      mode: view.mode,
+    });
+  } else {
+    reportRepairBackoff(emit, {
+      subsystem: plan.subsystem,
+      code: rebuilt.result.ok ? "HEAL_REPAIR_RATE_LIMITED" : (rebuilt.result.code ?? "HEAL_REBUILD_FAILED"),
+      backoffMs: plan.backoffMs,
+      attempt: view.failedAttempts ?? 0,
+    });
+  }
+  return { plan, rebuilt };
+}
+
+/**
+ * The full post-compact repair drive. Applies heal's eligibility policy
+ * (`isPlannable` — rate limit, no gap, frozen authority, mode C) per subsystem,
+ * and only runs `driveOneRepair` for subsystems with a REAL, actionable gap. A
+ * subsystem with no real gap, or inside its rate-limit window, emits NOTHING.
+ *
+ * `rebuildSourceFor` is an injected executor that materializes a new generation
+ * for a plannable subsystem (the handler supplies the real one; fixtures supply
+ * a deterministic one), keeping the drive testable without a runtime.
+ */
+export function drivePostCompactRepair(
+  views: readonly PostCompactView[],
+  nowMs: bigint,
+  emit: RepairEmit | undefined,
+  rebuildSourceFor: (view: PostCompactView) => RebuildSource,
+): void {
+  for (const view of views) {
+    const state = toRepairState(view);
+    if (!isPlannable(state, nowMs)) continue;
+    driveOneRepair(view, emit, rebuildSourceFor(view));
+  }
+}
+
+/**
+ * Build the production post-compact subsystem views from a compact result.
+ *
+ * `compactedFrom` is the committed seq frontier after compaction. In a NORMAL
+ * compact the derived post-count equals the durable authority high-water (they
+ * advance together), so the resulting view has NO real gap — the drive emits
+ * nothing (VC6C-IMPL-006). A caller that derives per-subsystem counts where a
+ * derived tier fell behind authority supplies those lower counts here, and the
+ * drive will detect the gap and repair it. `currentGeneration` seeds the derived
+ * generation counter.
+ */
+export function buildPostCompactViews(
+  compactedFrom: number,
+  currentGeneration: number,
+  authorityHighWater: number = compactedFrom,
+  postCount: number = compactedFrom,
+): readonly PostCompactView[] {
+  return [
+    {
+      subsystem: "post_compact",
+      preCount: compactedFrom,
+      postCount,
+      authorityHighWater,
+      generation: currentGeneration,
+      failedAttempts: 0,
+      mode: "A",
+      lastRebuildAtMs: null,
+    },
+  ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.33",
+  "version": "0.20.35",
   "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/vector-cortex/heal/_vc6c-impl-fixture.ts

@@ -0,0 +1,43 @@
+/**
+ * heal/_vc6c-impl-fixture.ts — conformance fixture I/O for VC6C-IMPL
+ * self-healing-controller rows.
+ *
+ * VC6C's base corpus lives under `healing-controller/` (read by
+ * `_repair-fixture.ts`); VC6C-IMPL emits its six fixtures under
+ * `self-healing/` per the sprint brief. Both share the one canonical
+ * `healing-controller-fixture.schema.json`, so this loader reuses the
+ * `RepairFx` envelope (`_repair-fixture.ts`) but resolves fixture paths from
+ * the `self-healing/` directory. No mocks — the committed fixtures are fed
+ * verbatim into the real heal / reconstruct production modules.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import assert from "node:assert/strict";
+
+import { V2, readManifest } from "./_acceptance-fixture.js";
+import type { RepairFx } from "./_repair-fixture.js";
+
+const PREFIX = "self-healing";
+
+/** Read one registered VC6C-IMPL fixture (asserting it IS registered). */
+export function vc6cImplFixture(id: string): RepairFx {
+  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")) as RepairFx;
+}
+
+/**
+ * The six VC6C-IMPL fixture ids, in corpus order. The acceptance test drives
+ * each through the real production seam and asserts its pinned verdict.
+ */
+export const VC6C_IMPL_IDS: readonly string[] = Array.from(
+  { length: 6 },
+  (_v, i) => `VC6C-IMPL-${String(i + 1).padStart(3, "0")}`,
+);

package/src/vector-cortex/reconstruct/rebuild.ts

@@ -0,0 +1,75 @@
+/**
+ * vector-cortex/reconstruct/rebuild.ts — VC6C-IMPL production atomic rebuild.
+ *
+ * The thin *production executor* over the pure `heal/rebuild.ts` copy-verify-
+ * switch primitives. It materializes a NEW derived generation for the planned
+ * range, verifies the root manifest digest is a STRICT SUCCESSOR (the planned
+ * `generation` is `current + 1` and the switch refuses any non-monotonic move),
+ * and swaps the pointer in a single atomic commit. A failed verification keeps
+ * the old pointer and DELETES NO EVIDENCE: the orphaned generation is retained
+ * for inspection (heal/rebuild.ts crash-safety contract).
+ *
+ * REUSES, DOES NOT FORK. `rebuildGeneration` + `switchPointer` are the same
+ * functions VC6C shipped and tested (74 tests). This file only binds them to
+ * the production `RepairPlanV1` shape and the atomic-commit framing the
+ * post-compact handler calls — the whole point of VC6C-IMPL is that the pure
+ * primitives already exist and only the production seam was missing.
+ *
+ * STRICT SUCCESSOR. The pointer moves only when (a) verification passed and
+ * (b) the new generation is STRICTLY greater than the current one. Replaying a
+ * stale plan after a restart cannot roll the pointer backwards — the same
+ * monotonic guard `heal/rebuild.ts#switchPointer` enforces.
+ *
+ * THE AUTHORITY IS NEVER MUTATED. This rebuild only swaps the DERIVED generation
+ * pointer; the durable authority is untouched. `currentGeneration` is read to
+ * enforce monotonicity, never written.
+ *
+ * PURE. No storage, no console, no network (PREVENT-PI-004 / PREVENT-011);
+ * `node:crypto` comes via the heal digest helper.
+ */
+
+import {
+  rebuildAndSwitch,
+  type PointerSwitch,
+  type RebuildInput,
+  type RebuildResult,
+} from "../heal/rebuild.js";
+import type { Mode } from "../heal/repair-types.js";
+import type { RepairPlanV1 } from "./repair-plan.js";
+
+export type { PointerSwitch, RebuildInput, RebuildResult };
+
+/**
+ * The outcome of one atomic rebuild attempt. `result` is the verification
+ * verdict; `pointer` is the atomic commit — `switched:true` only when the root
+ * digest verified AND the generation advanced strictly. On `switched:false`
+ * the live generation is unchanged and the orphaned generation is retained.
+ */
+export interface AtomicRebuild {
+  readonly plan: RepairPlanV1;
+  readonly result: RebuildResult;
+  readonly pointer: PointerSwitch;
+}
+
+/**
+ * Materialize + atomically switch a planned repair range.
+ *
+ * `rebuildInput` carries the materialized new-generation bytes and the root
+ * digest the plan pinned. The helper reuses `heal/rebuild.ts#rebuildAndSwitch`,
+ * which verifies the digest FIRST and refuses to switch under any combination of
+ * failed verification or non-strict generation — "switch without verifying" is
+ * not expressible.
+ */
+export function rebuildRepairRange(
+  plan: RepairPlanV1,
+  rebuildInput: RebuildInput,
+  currentGeneration: number,
+  mode: Mode = "A",
+): AtomicRebuild {
+  const { result, pointer } = rebuildAndSwitch(
+    rebuildInput,
+    currentGeneration,
+    mode,
+  );
+  return { plan, result, pointer };
+}

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,
+  };
+}