pi-mega-compact 0.20.9 → 0.20.10

package/dist/src/vector-cortex/heal/repair-types.js

@@ -0,0 +1,74 @@
+/**
+ * vector-cortex/heal/repair-types.ts — VC6C self-healing derived controller.
+ *
+ * VC6B answered "when a node's bytes are gone, WHERE do they come from?". VC6C
+ * answers the question one level up: when a DERIVED subsystem (topology, shards,
+ * closure) has fallen BEHIND the durable authority, how do we notice, and how do
+ * we catch it up without ever risking the authority itself?
+ *
+ * THE AUTHORITY IS READ-ONLY, ALWAYS. The controller compares each derived
+ * source's high-water to the durable authority high-water and plans work. It has
+ * no write path to the authority — not a guarded one, not an admin one. Derived
+ * state is disposable and can always be rebuilt from the byte ledger; the
+ * authority is not, so the repair path is deliberately one-directional. This is
+ * why `RepairState` carries `authorityHighWater` as a plain readonly field and
+ * why no function in `controller.ts` returns anything that could be applied to it.
+ *
+ * NEVER READ PAST THE AUTHORITY (TRIAD_RESILIENCE §frontier). A derived builder
+ * may not read beyond the durable CONTIGUOUS authority high-water. During an
+ * authority outage that high-water FREEZES even though the spool keeps accepting
+ * frames — so a derived subsystem that is "behind" a frozen frontier is CORRECT,
+ * not broken, and planning a rebuild against the spool tail would materialize
+ * frames that are not yet durable. `detectGaps` therefore treats
+ * `authorityFrozen` as a hard stop (`HEAL_REPAIR_AUTHORITY_FROZEN`) rather than
+ * as a large gap to chase. After the drain, catch-up resumes from the OLD
+ * high-water; it never jumps to the tail.
+ *
+ * REBUILD IS COPY-THEN-SWITCH, NEVER IN-PLACE. `rebuild.ts` materializes a NEW
+ * generation, verifies its root digest, and only then flips the pointer. A failed
+ * verification keeps the old pointer and DELETES NO EVIDENCE: the corrupt
+ * generation stays on disk to be inspected. An in-place repair would, by
+ * construction, destroy the only copy of the thing that was about to be proven
+ * wrong.
+ *
+ * RATE LIMIT + BACKOFF ARE THE BLAST RADIUS. A subsystem that fails to rebuild
+ * will fail again, usually instantly, so an unbounded retry loop turns one broken
+ * shard into a CPU-saturating rebuild storm. One rebuild per subsystem per 5
+ * minutes bounds the steady state, and the deterministic exponential backoff
+ * (30s * 2^attempt, capped at 15 min, ±10% jitter derived from the SUBSYSTEM
+ * DIGEST rather than `Math.random`) bounds the failure state while keeping the
+ * schedule reproducible in a fixture.
+ *
+ * Pure types + registered conformance IDs: no storage, no console, no clock, no
+ * network (PREVENT-PI-004 / PREVENT-011).
+ */
+/**
+ * One rebuild per subsystem per 5 minutes. Bounds a rebuild storm: a subsystem
+ * that fails will fail again immediately, and without this an unhealthy tier
+ * would saturate the box re-materializing the same broken generation.
+ */
+export const REPAIR_RATE_LIMIT_MS = 5 * 60_000;
+/**
+ * Exponential backoff base/cap, matching the breaker's retry rule
+ * (TRIAD_RESILIENCE): `30s * 2^attempt`, capped at 15 minutes.
+ */
+export const REPAIR_BACKOFF_BASE_MS = 30_000;
+export const REPAIR_BACKOFF_CAP_MS = 15 * 60_000;
+/**
+ * ±10% deterministic jitter. Derived from the SUBSYSTEM DIGEST, not a PRNG, so
+ * two subsystems desynchronize (no thundering herd) while any single subsystem's
+ * schedule stays reproducible in a fixture.
+ */
+export const REPAIR_BACKOFF_JITTER = 0.1;
+/**
+ * Registered VC6C conformance ID range (HEAL-031..045), continuing VC6B's
+ * HEAL-016..030. The acceptance test reads these rows from the v2 manifest and
+ * asserts each returns its manifest `ok`/`code`.
+ */
+export const REPAIR_IDS = Array.from({ length: 15 }, (_v, i) => `HEAL-${String(i + 31).padStart(3, "0")}`);
+/** Named VC6C conformance assertions (the sprint's headline rows). */
+export const REPAIR_NAMED_IDS = [
+    "HEAL-GAP-001",
+    "HEAL-RATE-002",
+    "HEAL-SWITCH-003",
+];

package/dist/src/vector-cortex/heal/types.js

@@ -41,3 +41,4 @@ export const HEAL_NAMED_IDS = [
     "HEAL-PROOF-003",
 ];
 export { RESTORE_IDS, RESTORE_NAMED_IDS, RESTORE_LIMIT_SPANS, RESTORE_LIMIT_BYTES, } from "./restore-types.js";
+export { REPAIR_IDS, REPAIR_NAMED_IDS, REPAIR_RATE_LIMIT_MS, REPAIR_BACKOFF_BASE_MS, REPAIR_BACKOFF_CAP_MS, REPAIR_BACKOFF_JITTER, } from "./repair-types.js";

package/dist/vector-cortex/heal/_repair-fixture.js

@@ -0,0 +1,70 @@
+/**
+ * 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 { V2, readManifest } from "./_acceptance-fixture.js";
+/** Read one registered healing-controller fixture (asserting it IS registered). */
+export function repairFixture(id) {
+    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"));
+}
+/** JSON numbers -> the bigint fields `RepairState` declares. */
+export function decodeState(s) {
+    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) {
+    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) {
+    return () => {
+        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/dist/vector-cortex/heal/controller.js

@@ -0,0 +1,165 @@
+/**
+ * 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 { 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, attempt) {
+    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, attempt) {
+    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, nowMs) {
+    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) {
+    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, nowMs) {
+    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, nowMs) {
+    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, nowMs) {
+    const plans = [];
+    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() {
+    return { detectGaps, planRebuild };
+}

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

@@ -0,0 +1,136 @@
+/**
+ * vector-cortex/heal/rebuild.ts — VC6C generation rebuild + atomic pointer switch.
+ *
+ * Executes what `controller.ts` planned: materialize a NEW generation, verify its
+ * root digest, and only then flip the live pointer.
+ *
+ * COPY, VERIFY, SWITCH — in that order, always.
+ *
+ *   1. COPY. The rebuild writes into `plan.generation` (always `current + 1`),
+ *      never into the live generation. The thing currently being served is never
+ *      the thing being modified, so a crash mid-rebuild leaves a complete old
+ *      generation and a partial new one — never a torn live one.
+ *   2. VERIFY. The new generation's root digest must equal the digest the plan
+ *      pinned. This is the ONLY gate on the pointer.
+ *   3. SWITCH. `switchPointer` moves the pointer iff verification passed.
+ *
+ * A FAILED VERIFICATION DELETES NO EVIDENCE. On mismatch we keep the old pointer
+ * AND leave the new generation on disk. That is deliberate: the corrupt
+ * generation is the only artifact that can explain WHY the rebuild was wrong, and
+ * a self-healing system that tidies up its failures is a system that cannot be
+ * debugged. Cleanup is a separate, explicit operator action.
+ *
+ * CRASH SAFETY IS A CONSEQUENCE OF THE ORDER, NOT AN EXTRA STEP. The pointer is
+ * the single atomic commit point. Kill the process after step 1 or 2 and the old
+ * pointer is still live, so the next start serves the prior generation and simply
+ * re-plans — the orphaned generation is inert. This is what
+ * `rebuild-chaos.test.ts` pins.
+ *
+ * THE TRIAD (independent algorithms, per TRIAD_RESILIENCE).
+ *   A — TARGETED: rebuild only `plan.range`, reusing the prior generation for
+ *       everything outside it. Cheap; needs a healthy prior generation.
+ *   B — FULL DETERMINISTIC: re-derive the whole subsystem from the byte ledger,
+ *       reusing NOTHING. Independent of A: it shares no index, no prior
+ *       generation, and no incremental state, so a bug or corruption that breaks
+ *       A cannot break B the same way.
+ *   C — DISABLE DERIVED STATE: no rebuild at all. Mode C is a real outcome, not
+ *       an error path, and it MUST state its loss of old semantic context — the
+ *       subsystem serves nothing rather than serving something wrong.
+ *
+ * PURE. `node:crypto` only — no storage, no console, no clock, no network
+ * (PREVENT-PI-004 / PREVENT-011). Callers own persistence; this module owns the
+ * decision and the digest arithmetic, which is what makes it fixture-testable.
+ */
+import { createHash } from "node:crypto";
+/** Root digest of a generation's bytes: SHA-256, bare lowercase hex. */
+export function rootDigest(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * Materialize + verify one generation.
+ *
+ * Hashes the rebuilt bytes and compares to the pinned root digest. A mismatch
+ * returns `HEAL_REPAIR_DIGEST_MISMATCH` and — critically — the caller must NOT
+ * switch the pointer; `switchPointer` enforces that structurally by requiring the
+ * verified flag.
+ *
+ * An EMPTY rebuild is a failure, not an empty success: a generation with no bytes
+ * would hash to the digest of nothing, and if a plan ever pinned that digest an
+ * empty rebuild would "verify" and the pointer would flip to nothing at all. It
+ * is reported as `HEAL_REBUILD_FAILED` because the rebuild produced no artifact.
+ */
+export function rebuildGeneration(input, mode = "A") {
+    if (input.sourceBytes.length === 0) {
+        return {
+            ok: false,
+            code: "HEAL_REBUILD_FAILED",
+            generation: input.generation,
+            mode,
+        };
+    }
+    const digest = rootDigest(input.sourceBytes);
+    if (digest !== input.expectedDigest) {
+        // Evidence retained: the caller keeps the generation on disk for inspection.
+        return {
+            ok: false,
+            code: "HEAL_REPAIR_DIGEST_MISMATCH",
+            generation: input.generation,
+            mode,
+        };
+    }
+    return { ok: true, generation: input.generation, digest, mode };
+}
+/**
+ * The atomic commit point: flip the live pointer iff the new generation verified.
+ *
+ * `verified` is a required argument rather than something re-derived here, so a
+ * caller cannot switch the pointer without having gone through
+ * `rebuildGeneration` — "switch without verifying" is not expressible.
+ *
+ * A non-monotonic switch is also refused: the new generation must be strictly
+ * greater than the current one. Replaying a stale plan after a restart would
+ * otherwise roll the pointer BACKWARDS onto an older generation, silently
+ * un-healing the subsystem.
+ */
+export function switchPointer(currentGen, newGen, verified) {
+    if (!verified)
+        return { switched: false, generation: currentGen };
+    if (newGen <= currentGen)
+        return { switched: false, generation: currentGen };
+    return { switched: true, generation: newGen };
+}
+/**
+ * Apply the triad arm for a rebuild.
+ *
+ * A and B run the same verification (a digest is a digest) but are reached by
+ * INDEPENDENT production paths: A reuses the prior generation and rebuilds only
+ * the planned range, while B re-derives everything from the byte ledger sharing
+ * no index or incremental state with A. C performs no rebuild at all and states
+ * its loss.
+ */
+export function applyTriad(mode, input) {
+    if (mode === "C") {
+        // Derived state disabled: no rebuild, and the loss of old semantic context
+        // is DISCLOSED rather than papered over with a stale or partial generation.
+        return {
+            ok: false,
+            code: "HEAL_REBUILD_FAILED",
+            generation: input.generation,
+            mode: "C",
+            semanticLossStated: true,
+        };
+    }
+    return rebuildGeneration(input, mode);
+}
+/**
+ * Convenience: rebuild then switch, returning both halves.
+ *
+ * The pointer moves only on a verified rebuild, so a failed verification yields
+ * `switched:false` with the ORIGINAL generation still live and the new (corrupt)
+ * generation left intact on disk for inspection.
+ */
+export function rebuildAndSwitch(input, currentGen, mode = "A") {
+    const result = applyTriad(mode, input);
+    const pointer = switchPointer(currentGen, input.generation, result.ok);
+    return { result, pointer };
+}

package/dist/vector-cortex/heal/repair-emit.js

@@ -0,0 +1,83 @@
+/**
+ * vector-cortex/heal/repair-emit.ts — VC6C event reporter seam.
+ *
+ * Mirrors `./restore-emit.ts`: a thin `safe()` wrapper around an optional
+ * injected `emit`, and the three event names the sprint spec requires verbatim:
+ *   - `vector_cortex_repair_planned`         — a gap was detected, rebuild queued.
+ *   - `vector_cortex_repair_pointer_switched`— a verified generation went live.
+ *   - `vector_cortex_repair_backoff`         — suppressed (rate limit) or failed.
+ *
+ * FLAG SEMANTICS. `detectGaps` / `planRebuild` / `rebuildGeneration` /
+ * `switchPointer` are PURE arithmetic and run REGARDLESS of `MEGACOMPACT_VC6C`.
+ * The flag gates ONLY this reporting + dashboard seam: with the flag off we still
+ * detect gaps, still verify digests, and still refuse unverified pointer
+ * switches — we just do not announce it under the VC6C event namespace. That is
+ * what makes flag-off byte-identical to VC6B: the computation is never skipped,
+ * only the emission.
+ *
+ * PAYLOAD DISCIPLINE. These events carry the SUBSYSTEM NAME, generation numbers,
+ * timings, and codes — never rebuilt bytes, never a root digest of user content,
+ * never a seq range's contents. The subsystem name is an operator-facing
+ * identifier ("topology"), not user data. A repair event is exactly the place
+ * where an unguarded `payload` field would leak a rebuilt transcript into a log.
+ *
+ * No console, no storage, no network (PREVENT-PI-004 / PREVENT-011). Every line
+ * is a structured JSON event with `ts` + `event`.
+ */
+import { VC6C_ENABLED } from "../../config/vector-cortex.js";
+/** Run `fn` only when an emit exists; a reporting failure is never fatal. */
+function safe(emit, fn) {
+    if (emit === undefined)
+        return;
+    try {
+        fn(emit);
+    }
+    catch {
+        // Non-fatal: a reporting failure must never break the agent loop.
+    }
+}
+/** The event names VC6C emits, exported for the dashboard seam and tests. */
+export const REPAIR_EVENT_NAMES = [
+    "vector_cortex_repair_planned",
+    "vector_cortex_repair_pointer_switched",
+    "vector_cortex_repair_backoff",
+];
+/** Report a planned rebuild: which subsystem, which generation, what delay. */
+export function reportRepairPlanned(emit, payload) {
+    if (!VC6C_ENABLED())
+        return;
+    safe(emit, (e) => e("vector_cortex_repair_planned", {
+        ts: undefined,
+        event: "vector_cortex_repair_planned",
+        subsystem: payload.subsystem,
+        generation: payload.generation,
+        backoffMs: payload.backoffMs,
+        gapSize: payload.gapSize,
+    }));
+}
+/** Report the atomic commit: a verified generation became live. */
+export function reportRepairPointerSwitched(emit, payload) {
+    if (!VC6C_ENABLED())
+        return;
+    safe(emit, (e) => e("vector_cortex_repair_pointer_switched", {
+        ts: undefined,
+        event: "vector_cortex_repair_pointer_switched",
+        subsystem: payload.subsystem,
+        fromGeneration: payload.fromGeneration,
+        toGeneration: payload.toGeneration,
+        mode: payload.mode,
+    }));
+}
+/** Report a suppressed or failed rebuild now waiting out its backoff. */
+export function reportRepairBackoff(emit, payload) {
+    if (!VC6C_ENABLED())
+        return;
+    safe(emit, (e) => e("vector_cortex_repair_backoff", {
+        ts: undefined,
+        event: "vector_cortex_repair_backoff",
+        subsystem: payload.subsystem,
+        code: payload.code,
+        backoffMs: payload.backoffMs,
+        attempt: payload.attempt,
+    }));
+}

package/dist/vector-cortex/heal/repair-types.js

@@ -0,0 +1,74 @@
+/**
+ * vector-cortex/heal/repair-types.ts — VC6C self-healing derived controller.
+ *
+ * VC6B answered "when a node's bytes are gone, WHERE do they come from?". VC6C
+ * answers the question one level up: when a DERIVED subsystem (topology, shards,
+ * closure) has fallen BEHIND the durable authority, how do we notice, and how do
+ * we catch it up without ever risking the authority itself?
+ *
+ * THE AUTHORITY IS READ-ONLY, ALWAYS. The controller compares each derived
+ * source's high-water to the durable authority high-water and plans work. It has
+ * no write path to the authority — not a guarded one, not an admin one. Derived
+ * state is disposable and can always be rebuilt from the byte ledger; the
+ * authority is not, so the repair path is deliberately one-directional. This is
+ * why `RepairState` carries `authorityHighWater` as a plain readonly field and
+ * why no function in `controller.ts` returns anything that could be applied to it.
+ *
+ * NEVER READ PAST THE AUTHORITY (TRIAD_RESILIENCE §frontier). A derived builder
+ * may not read beyond the durable CONTIGUOUS authority high-water. During an
+ * authority outage that high-water FREEZES even though the spool keeps accepting
+ * frames — so a derived subsystem that is "behind" a frozen frontier is CORRECT,
+ * not broken, and planning a rebuild against the spool tail would materialize
+ * frames that are not yet durable. `detectGaps` therefore treats
+ * `authorityFrozen` as a hard stop (`HEAL_REPAIR_AUTHORITY_FROZEN`) rather than
+ * as a large gap to chase. After the drain, catch-up resumes from the OLD
+ * high-water; it never jumps to the tail.
+ *
+ * REBUILD IS COPY-THEN-SWITCH, NEVER IN-PLACE. `rebuild.ts` materializes a NEW
+ * generation, verifies its root digest, and only then flips the pointer. A failed
+ * verification keeps the old pointer and DELETES NO EVIDENCE: the corrupt
+ * generation stays on disk to be inspected. An in-place repair would, by
+ * construction, destroy the only copy of the thing that was about to be proven
+ * wrong.
+ *
+ * RATE LIMIT + BACKOFF ARE THE BLAST RADIUS. A subsystem that fails to rebuild
+ * will fail again, usually instantly, so an unbounded retry loop turns one broken
+ * shard into a CPU-saturating rebuild storm. One rebuild per subsystem per 5
+ * minutes bounds the steady state, and the deterministic exponential backoff
+ * (30s * 2^attempt, capped at 15 min, ±10% jitter derived from the SUBSYSTEM
+ * DIGEST rather than `Math.random`) bounds the failure state while keeping the
+ * schedule reproducible in a fixture.
+ *
+ * Pure types + registered conformance IDs: no storage, no console, no clock, no
+ * network (PREVENT-PI-004 / PREVENT-011).
+ */
+/**
+ * One rebuild per subsystem per 5 minutes. Bounds a rebuild storm: a subsystem
+ * that fails will fail again immediately, and without this an unhealthy tier
+ * would saturate the box re-materializing the same broken generation.
+ */
+export const REPAIR_RATE_LIMIT_MS = 5 * 60_000;
+/**
+ * Exponential backoff base/cap, matching the breaker's retry rule
+ * (TRIAD_RESILIENCE): `30s * 2^attempt`, capped at 15 minutes.
+ */
+export const REPAIR_BACKOFF_BASE_MS = 30_000;
+export const REPAIR_BACKOFF_CAP_MS = 15 * 60_000;
+/**
+ * ±10% deterministic jitter. Derived from the SUBSYSTEM DIGEST, not a PRNG, so
+ * two subsystems desynchronize (no thundering herd) while any single subsystem's
+ * schedule stays reproducible in a fixture.
+ */
+export const REPAIR_BACKOFF_JITTER = 0.1;
+/**
+ * Registered VC6C conformance ID range (HEAL-031..045), continuing VC6B's
+ * HEAL-016..030. The acceptance test reads these rows from the v2 manifest and
+ * asserts each returns its manifest `ok`/`code`.
+ */
+export const REPAIR_IDS = Array.from({ length: 15 }, (_v, i) => `HEAL-${String(i + 31).padStart(3, "0")}`);
+/** Named VC6C conformance assertions (the sprint's headline rows). */
+export const REPAIR_NAMED_IDS = [
+    "HEAL-GAP-001",
+    "HEAL-RATE-002",
+    "HEAL-SWITCH-003",
+];

package/dist/vector-cortex/heal/types.js

@@ -41,3 +41,4 @@ export const HEAL_NAMED_IDS = [
     "HEAL-PROOF-003",
 ];
 export { RESTORE_IDS, RESTORE_NAMED_IDS, RESTORE_LIMIT_SPANS, RESTORE_LIMIT_BYTES, } from "./restore-types.js";
+export { REPAIR_IDS, REPAIR_NAMED_IDS, REPAIR_RATE_LIMIT_MS, REPAIR_BACKOFF_BASE_MS, REPAIR_BACKOFF_CAP_MS, REPAIR_BACKOFF_JITTER, } from "./repair-types.js";