pi-mega-compact 0.20.34 → 0.20.36

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.34",
+  "version": "0.20.36",
   "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-ml5a.ts

@@ -0,0 +1,30 @@
+/**
+ * config/vector-cortex-ml5a.ts — ML5-A five-head training + calibration flag.
+ *
+ * Extracted from vector-cortex.ts so that file stays under the 300-line soft
+ * limit (soft-as-hard gate), exactly as vector-cortex-vc9a.ts..vector-cortex-vc9d.ts
+ * were. This is the ML5 training sprint flag. vector-cortex.ts re-exports the
+ * ENUM below and root src/config.ts re-exports it, so no consumer import path
+ * changes.
+ *
+ * The split is purely mechanical: ML5A_ENABLED is byte-identical in name,
+ * semantics, and default to the definition it replaces, and vector-cortex.ts
+ * re-exports it so every existing `from "./config/vector-cortex.js"` import
+ * keeps resolving unchanged.
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { sprintFlag } from "./vector-cortex-flag.js";
+
+/**
+ * ML5-A — five-head training + calibrated onnx asset. Default ON.
+ * `MEGACOMPACT_ML5_A=0` disables and is byte-identical to the placeholder
+ * predecessor (VC2C-era): `calibrate.ts`/`heads.ts` keep serving the LCG fake
+ * projections and the placeholder `fitTemperature`/`fitThreshold`, mode B
+ * trigram continues serving, and no trained artifact is loaded (a fresh/no
+ * corpus also no-ops gracefully — asset_emitted:false, placeholder behavior,
+ * byte-identical). This flag MUST also be a dashboard SETTINGS toggle (visible
+ * in config UI, never in EXCLUDED_SETTINGS), mirroring VC4A..VC9D.
+ */
+export const ML5A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_ML5_A");

package/src/config/vector-cortex.ts

@@ -269,18 +269,17 @@ export const VC8A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC8A");
  */
 export const VC8B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC8B");
 
-// VC8C (canary selection + external Rust parity) extracted to
-// vector-cortex-vc8c.ts to keep this file under the 300-line soft limit.
-// Re-exported here so every existing `from "./config/vector-cortex.js"`
-// import keeps resolving unchanged.
+// VC8C (canary selection + Rust parity) extracted to vector-cortex-vc8c.ts;
+// re-exported so existing `./config/vector-cortex.js` imports keep resolving.
 export { VC8C_ENABLED } from "./vector-cortex-vc8c.js";
 
-// VC9A/VC9B/VC9C/VC9D split to vector-cortex-vc9{a,b,c,d}.ts to stay under the 300-line soft limit.
+// VC9A/VC9B/VC9C/VC9D/PCC/ML5A split to sibling files to stay under the 300-line soft limit.
 export { VC9A_ENABLED } from "./vector-cortex-vc9a.js";
 export { VC9B_ENABLED } from "./vector-cortex-vc9b.js";
 export { VC9C_ENABLED } from "./vector-cortex-vc9c.js";
 export { VC9D_ENABLED } from "./vector-cortex-vc9d.js";
 export { PCC_ENABLED } from "./vector-cortex-pcc.js";
+export { ML5A_ENABLED } from "./vector-cortex-ml5a.js";
 
 // Breaker constants (TRIAD_RESILIENCE.md §breaker) extracted to vector-cortex-breakers.ts.
 export {

package/src/config.ts

@@ -183,6 +183,7 @@ export {
   VC9C_ENABLED,
   VC9D_ENABLED,
   PCC_ENABLED,
+  ML5A_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

package/src/vector-cortex/encoder/calibrate.ts

@@ -23,6 +23,8 @@
  */
 
 import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { ML5A_ENABLED } from "../../config/vector-cortex.js";
 import {
   ENCODER_HEAD_ORDER,
   ENCODER_SEED,
@@ -223,3 +225,50 @@ export function fitCalibration(
   };
   return { ok: true, calibration };
 }
+
+/**
+ * Load a persisted `CalibrationV1` artifact (schema "calibration-v1") from disk.
+ * ML5-A: gated on MEGACOMPACT_ML5_A; flag-off, absent file, malformed JSON,
+ * wrong schema, non-canonical five-head order, or non-finite temp/threshold each
+ * return null (non-fatal, never throws). Deterministic, local (PREVENT-PI-004).
+ */
+export function loadCalibrationV1(path: string): CalibrationV1 | null {
+  if (!ML5A_ENABLED()) return null;
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const r = parsed as Record<string, unknown> | null;
+  if (!r || r["schema"] !== "calibration-v1") return null;
+  const order = r["headOrder"];
+  if (!Array.isArray(order)) return null;
+  if (order.length !== ENCODER_HEAD_ORDER.length || !ENCODER_HEAD_ORDER.every((h, i) => order[i] === h)) {
+    return null;
+  }
+  const temperatures = r["temperatures"] as Record<string, unknown> | undefined;
+  const thresholds = r["thresholds"] as Record<string, unknown> | undefined;
+  const splitDigest = r["calibrationSplitDigest"];
+  if (!temperatures || !thresholds || typeof splitDigest !== "string" || splitDigest.length !== 64) return null;
+  for (const h of ENCODER_HEAD_ORDER) {
+    const t = Number(temperatures[h]);
+    const th = Number(thresholds[h]);
+    if (!Number.isFinite(t) || !Number.isFinite(th)) return null;
+  }
+  return {
+    schema: "calibration-v1",
+    headOrder: [...ENCODER_HEAD_ORDER],
+    calibrationSplitDigest: splitDigest,
+    fittedOnCalibrationOnly: true,
+    temperatures: { ...(temperatures as Record<EncoderHeadName, number>) },
+    thresholds: { ...(thresholds as Record<EncoderHeadName, number>) },
+    seed: Number(r["seed"] ?? ENCODER_SEED),
+  };
+}

package/src/vector-cortex/encoder/heads.ts

@@ -20,6 +20,8 @@
  * Pi-agnostic, zero network (PREVENT-PI-004), no `any` (PREVENT-011).
  */
 
+import { readFileSync } from "node:fs";
+import { ML5A_ENABLED } from "../../config/vector-cortex.js";
 import {
   ENCODER_HEAD_DIMS,
   ENCODER_HEAD_ORDER,
@@ -139,4 +141,108 @@ export function headLossWeights(): Readonly<Record<EncoderHeadName, number>> {
   return { ...ENCODER_HEAD_LOSS_WEIGHTS };
 }
 
+// ---------------------------------------------------------------------------
+// ML5-A real trained-head loading. Produces the projection matrices that the
+// deterministic placeholder `projectHead` approximates: row-major
+// `weights[h]` of length `headDim * trunkDim`, applied `W[i*t+j]*trunk[j]`,
+// L2-normalized. Loaded from the `trained-heads-v1` JSON that
+// `training/vector-cortex/train.py` emits, under the MEGACOMPACT_ML5_A gate.
+// Non-fatal: any violation (flag off, absent, malformed, wrong seed, wrong
+// shape) yields null, never a throw (all loaders return null on violation).
+// ---------------------------------------------------------------------------
+
+/** The real loadable form of the trained five-head projection table. */
+export interface HeadProjectionTable {
+  readonly schema: "trained-heads-v1";
+  readonly seed: number;
+  /** Input/trunk embedding dimension every head projects from (uniform 384). */
+  readonly trunkDim: number;
+  /** Per-head OUTPUT dimension (semantic 384 / ... / payloadRouting 32). */
+  readonly dims: Readonly<Record<EncoderHeadName, number>>;
+  /** Row-major `[headDim * trunkDim]` projection matrix per head. */
+  readonly weights: Readonly<Record<EncoderHeadName, Float32Array>>;
+  readonly temperatures: Readonly<Record<EncoderHeadName, number>>;
+}
+
+/** True when every head's output dim + weight length matches the contract. */
+export function headsShapeValid(t: HeadProjectionTable): boolean {
+  return ENCODER_HEAD_ORDER.every(
+    (h) => t.dims[h] === ENCODER_HEAD_DIMS[h] && t.weights[h].length === ENCODER_HEAD_DIMS[h] * t.trunkDim,
+  );
+}
+
+/**
+ * Load a `trained-heads-v1` artifact into a `HeadProjectionTable`. Gated on
+ * MEGACOMPACT_ML5_A: flag-off, absent file, malformed JSON, wrong schema,
+ * wrong seed, or a shape mismatch each return null (non-fatal). Deterministic
+ * and local (PREVENT-PI-004).
+ */
+export function loadHeadProjections(path: string): HeadProjectionTable | null {
+  if (!ML5A_ENABLED()) return null;
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const r = parsed as Record<string, unknown> | null;
+  if (!r || r["schema"] !== "trained-heads-v1") return null;
+  if (r["seed"] !== ENCODER_SEED) return null;
+  const dims = r["dims"] as Record<string, unknown> | undefined;
+  const heads = r["heads"] as Record<string, unknown> | undefined;
+  if (!dims || !heads) return null;
+  const trunkDim = Number(r["trunkDim"] ?? 0);
+  if (!Number.isFinite(trunkDim) || trunkDim <= 0) return null;
+  const weights: Record<string, Float32Array> = {};
+  const temperatures: Record<string, number> = {};
+  for (const h of ENCODER_HEAD_ORDER) {
+    const hd = heads[h] as Record<string, unknown> | undefined;
+    if (!hd || typeof hd !== "object") return null;
+    const w = hd["weights"];
+    if (!Array.isArray(w)) return null;
+    weights[h] = Float32Array.from(w as number[]);
+    if (Number(hd["dim"] ?? 0) !== ENCODER_HEAD_DIMS[h]) return null;
+    temperatures[h] = Number(hd["temperature"] ?? 1);
+    if (!Number.isFinite(dims[h])) return null;
+  }
+  const table: HeadProjectionTable = {
+    schema: "trained-heads-v1",
+    seed: Number(r["seed"]),
+    trunkDim,
+    dims: { semantic: 384, dependency: 128, contradiction: 128, cacheStability: 64, payloadRouting: 32 } as unknown as Record<EncoderHeadName, number>,
+    weights: weights as unknown as Record<EncoderHeadName, Float32Array>,
+    temperatures: temperatures as unknown as Record<EncoderHeadName, number>,
+  };
+  if (!headsShapeValid(table)) return null;
+  return table;
+}
+
+/**
+ * Project a trunk embedding through a trained head's real weights, applying the
+ * row-major matrix then L2-normalizing (all-zero on zero norm). Returns a
+ * `HeadVector` of the head's normative dimension.
+ */
+export function projectHeadFromTrunk(
+  head: EncoderHeadName,
+  trunk: Float32Array,
+  table: HeadProjectionTable,
+): HeadVector {
+  const dim = ENCODER_HEAD_DIMS[head];
+  const W = table.weights[head];
+  const t = table.trunkDim;
+  const out = new Float32Array(dim);
+  for (let i = 0; i < dim; i++) {
+    let acc = 0;
+    for (let j = 0; j < t; j++) acc += W[i * t + j]! * (trunk[j] ?? 0);
+    out[i] = acc;
+  }
+  return { head, dim, values: l2Normalize(out) };
+}
+
 export { ENCODER_HEAD_ORDER, ENCODER_HEAD_DIMS, ENCODER_HEAD_LOSS_SUM, ENCODER_SEED, NOOP_VC2B_REPORTER };

package/src/vector-cortex/encoder/select.ts

@@ -34,6 +34,8 @@
  */
 
 import { createHash } from "node:crypto";
+import { ML5A_ENABLED } from "../../config/vector-cortex.js";
+import { loadHeadProjections } from "./heads.js";
 import {
   ENC_QUALIFICATION_FAIL,
   EVALUATION_THRESHOLDS,
@@ -83,6 +85,13 @@ export interface QualificationCandidate {
    * corrupt-qualification-manifest injection (ENC_QUALIFICATION_DIGEST_MISMATCH).
    */
   readonly expectedQualificationManifestDigest?: string;
+  /**
+   * ML5-A: path to the `trained-heads-v1` artifact. When supplied AND the
+   * MEGACOMPACT_ML5_A gate is on, the candidate qualifies to mode A only if the
+   * real trained head weights load; a load failure atomically demotes all of A
+   * to B (non-fatal, reported as THRESHOLD_FAILED / head.weights.trainedHeadsPath).
+   */
+  readonly trainedHeadsPath?: string;
 }
 
 /**
@@ -183,6 +192,14 @@ export function selectQualifiedEncoder(
 
   // Atomic: collect EVERY failed field across asset + all heads + reconstruction.
   const failed: string[] = [];
+  // ML5-A: real trained-head weights must load for mode A. When the gate is on
+  // and a trained-heads path is pinned, an unloadable/wrong-seed/malformed
+  // artifact is a qualification failure (any failed field demotes ALL of A).
+  if (ML5A_ENABLED() && candidate.trainedHeadsPath !== undefined) {
+    if (loadHeadProjections(candidate.trainedHeadsPath) === null) {
+      failed.push("head.weights.trainedHeadsPath");
+    }
+  }
   assetPasses(candidate.asset, failed);
   const heads: EncoderHeadName[] = ["semantic", "dependency", "contradiction", "cacheStability", "payloadRouting"];
   for (const h of heads) {

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