pi-mega-compact 0.20.8 → 0.20.10

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

@@ -0,0 +1,140 @@
+/**
+ * vector-cortex/heal/restore.ts — VC6B exact source restoration orchestrator.
+ *
+ * Turns a `RestoreRequestV1` into a `RestoreResultV1` by consulting, per span,
+ * the two EXACT sources in `restore-readers.ts` — an indexed exact shard first,
+ * then a ledger range scan — and inserting bytes only after they hash to the
+ * digest the request pinned.
+ *
+ * ORDER OF OPERATIONS IS THE CONTRACT.
+ *
+ *   1. BOUNDS, BEFORE ANY READER TOUCH. The span count and the aggregate
+ *      requested byte span are computed PURELY FROM THE REQUEST (`byteEnd -
+ *      byteStart`, which needs no source at all) and checked first. On breach we
+ *      return immediately, having never read `reader.exactShards` or
+ *      `reader.ledgerEvents`. This is HEAL-LIMIT-002: an oversized request must
+ *      not be able to make the restorer walk the ledger even once, so the check
+ *      cannot be "inside the loop, before the read" — it must be before the loop
+ *      exists. The acceptance corpus proves it by passing EMPTY readers with an
+ *      over-limit request: a reader-touching implementation would still return
+ *      "missing" rather than "limit".
+ *
+ *   2. EXACT SHARD, then LEDGER, then MISSING. Sources are tried strongest-first.
+ *      A digest mismatch anywhere is recorded and the span is NOT restored — the
+ *      restorer never downgrades to "closest available bytes".
+ *
+ *   3. MODE from what actually happened, not from what was attempted. A = every
+ *      span came from a shard; B = all restored, at least one via ledger scan;
+ *      C = something is missing, and mode C STATES its semantic loss rather than
+ *      hiding an incomplete restoration behind a successful-looking result.
+ *
+ * PURE. No storage, no console, no clock, no network — `node:crypto` (a Node
+ * built-in) is the only dependency beyond types (PREVENT-PI-004 / PREVENT-011).
+ * The reporter seam in `restore-emit.ts` is flag-gated; THIS arithmetic is not,
+ * so flag-off is byte-identical.
+ */
+import { RESTORE_LIMIT_BYTES, RESTORE_LIMIT_SPANS } from "./restore-types.js";
+import { readExactShard, readLedgerSpan } from "./restore-readers.js";
+/**
+ * Fixed code ordering so a result's `codes` array is deterministic regardless of
+ * which span failed first. Deterministic output is what lets the conformance
+ * corpus pin an exact expected value.
+ */
+const CODE_ORDER = [
+    "HEAL_RESTORE_LIMIT",
+    "HEAL_RESTORE_DIGEST_MISMATCH",
+    "HEAL_RESTORE_SOURCE_MISSING",
+    "HEAL_RESTORE_RANGE_MISMATCH",
+];
+/** Deduplicate + sort codes into the fixed priority order. */
+export function orderCodes(codes) {
+    const seen = new Set(codes);
+    return CODE_ORDER.filter((c) => seen.has(c));
+}
+/**
+ * Total bytes the request ASKS for, derived from the ranges alone. Negative or
+ * inverted ranges contribute 0 rather than reducing the total — an inverted span
+ * must never be usable to smuggle a large request under the bound.
+ */
+function requestedBytes(spans) {
+    let total = 0;
+    for (const s of spans) {
+        const len = s.range.byteEnd - s.range.byteStart;
+        total += len > 0 ? len : 0;
+    }
+    return total;
+}
+/** The immediate over-limit result: nothing read, everything missing. */
+function limitExceeded(request) {
+    return {
+        schema: "restore-result-v1",
+        sessionId: request.sessionId,
+        mode: "C",
+        restored: [],
+        missing: request.spans.map((s) => s.nodeId),
+        semanticLossStated: true,
+        codes: ["HEAL_RESTORE_LIMIT"],
+    };
+}
+/**
+ * Restore the exact original bytes for every requested span.
+ *
+ * Never throws: a request naming spans no source covers yields a mode-C result
+ * that discloses the loss, not an exception (PRACTICES: non-fatal — a failed
+ * restoration must degrade the prompt, never break the agent loop).
+ */
+export function restoreSources(request, reader) {
+    // (1) Bounds first — computed from the request only. `reader` is not touched
+    // on this path, which is exactly what HEAL-LIMIT-002 asserts.
+    if (request.spans.length > RESTORE_LIMIT_SPANS ||
+        requestedBytes(request.spans) > RESTORE_LIMIT_BYTES) {
+        return limitExceeded(request);
+    }
+    const restored = [];
+    const missing = [];
+    const codes = [];
+    let usedLedger = false;
+    // (2) Per span, strongest source first, in request order.
+    for (const span of request.spans) {
+        const exact = readExactShard(reader.exactShards, span.range, span.digest);
+        if (exact.kind === "bytes") {
+            restored.push({
+                nodeId: span.nodeId,
+                source: "exact-shard",
+                bytes: exact.bytes,
+                digest: span.digest,
+            });
+            continue;
+        }
+        if (exact.kind === "digest-mismatch")
+            codes.push("HEAL_RESTORE_DIGEST_MISMATCH");
+        const ledger = readLedgerSpan(reader.ledgerEvents, span.range, span.digest);
+        if (ledger.kind === "bytes") {
+            usedLedger = true;
+            restored.push({
+                nodeId: span.nodeId,
+                source: "ledger-scan",
+                bytes: ledger.bytes,
+                digest: span.digest,
+            });
+            continue;
+        }
+        if (ledger.kind === "digest-mismatch")
+            codes.push("HEAL_RESTORE_DIGEST_MISMATCH");
+        // (3) Neither exact source answered. Identity only — never bytes.
+        missing.push(span.nodeId);
+        codes.push("HEAL_RESTORE_SOURCE_MISSING");
+    }
+    const complete = missing.length === 0 && restored.length === request.spans.length;
+    const mode = !complete ? "C" : usedLedger ? "B" : "A";
+    return {
+        schema: "restore-result-v1",
+        sessionId: request.sessionId,
+        mode,
+        restored,
+        missing,
+        // Mode C omits spans, so it MUST disclose that the old context is gone.
+        semanticLossStated: mode === "C",
+        codes: orderCodes(codes),
+    };
+}

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

@@ -40,3 +40,5 @@ export const HEAL_NAMED_IDS = [
     "HEAL-PROTECT-002",
     "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/src/vector-cortex/heal/verify.js

@@ -0,0 +1,75 @@
+/**
+ * vector-cortex/heal/verify.ts — VC6B pre-insertion verification (task 3).
+ *
+ * `restoreSources` already hashes every span before it puts it in the result, so
+ * why hash again here?
+ *
+ * Because the result is a VALUE that travels. Between restoration and insertion
+ * it is passed across module boundaries, possibly cached, possibly assembled from
+ * more than one restore call, possibly reordered. `verifyRestored` is the gate
+ * immediately before bytes enter the reconstruction, and it re-derives its facts
+ * from scratch: it hashes the bytes the result ACTUALLY CARRIES and cross-checks
+ * them against the digest THE REQUEST asked for. A result object mutated after
+ * `restoreSources` returned — the classic "verified then swapped" injection —
+ * fails here.
+ *
+ * TWO DISTINCT INVARIANTS, TWO DISTINCT CODES.
+ *   - `HEAL_RESTORE_DIGEST_MISMATCH` — the bytes do not hash to their OWN stated
+ *     digest. The span is internally inconsistent (tampering or truncation).
+ *   - `HEAL_RESTORE_RANGE_MISMATCH` — the bytes are internally consistent but do
+ *     not answer the question that was asked: the nodeId was never requested, or
+ *     the digest disagrees with the digest the request pinned for that nodeId.
+ *     This is the "right bytes, wrong span" failure — substituting one real,
+ *     correctly-hashed span for another would otherwise pass a naive check.
+ *
+ * WHOLESALE, NOT PER-SPAN. `insertable` returns the restored spans only when the
+ * entire result verifies. Inserting the good half of a result whose other half
+ * failed verification would splice a partially-corrupt transcript into the
+ * reconstruction without the caller ever seeing a mode-C disclosure.
+ *
+ * Pure: `node:crypto` only, no storage/console/network (PREVENT-PI-004 /
+ * PREVENT-011).
+ */
+import { sha256Hex } from "./restore-readers.js";
+import { orderCodes } from "./restore.js";
+/**
+ * Re-verify every restored span against the request that asked for it.
+ *
+ * Returns `{ok:true}` only when EVERY restored span hashes to its own digest AND
+ * that digest is the one the request pinned for that node.
+ */
+export function verifyRestored(result, request) {
+    const requestedDigests = new Map();
+    for (const span of request.spans)
+        requestedDigests.set(span.nodeId, span.digest);
+    const codes = [];
+    for (const span of result.restored) {
+        // (1) Internal consistency: do these bytes hash to the digest they claim?
+        if (sha256Hex(span.bytes) !== span.digest) {
+            codes.push("HEAL_RESTORE_DIGEST_MISMATCH");
+            // A span that fails its own digest cannot meaningfully be checked against
+            // the request's digest as well; one code per real defect keeps the verdict
+            // readable.
+            continue;
+        }
+        // (2) Provenance: was this node requested, and with THIS digest? An
+        // unrequested node or a digest swap is a range mismatch, not a hash failure.
+        const wanted = requestedDigests.get(span.nodeId);
+        if (wanted === undefined || wanted !== span.digest) {
+            codes.push("HEAL_RESTORE_RANGE_MISMATCH");
+        }
+    }
+    if (codes.length === 0)
+        return { ok: true };
+    return { ok: false, codes: orderCodes(codes) };
+}
+/**
+ * The spans that may be inserted: all of them, or none.
+ *
+ * A caller should never need to decide which half of a partially-verified result
+ * is safe — that decision is the whole point of the digest contract, so it is
+ * made here, once, in the strict direction.
+ */
+export function insertable(result, request) {
+    return verifyRestored(result, request).ok ? result.restored : [];
+}

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/_restore-fixture.js

@@ -0,0 +1,96 @@
+/**
+ * heal/_restore-fixture.ts — conformance fixture I/O for VC6B restoration rows.
+ *
+ * Sibling of `_acceptance-fixture.ts` (which owns the VC6A closure-optimization
+ * rows); split out so neither file approaches the 300-line soft limit and so the
+ * base64/BigInt decoding lives next to the contract it reconstitutes.
+ *
+ * DECODING IS THE POINT. Fixtures are canonical JSON, which cannot express bytes
+ * or bigints, so the corpus stores `originalBytesBase64` + numeric `seq`. These
+ * loaders turn those back into the REAL `ExactShardV1` / `EventV2` objects the
+ * production readers consume — no mocks, no stubs, no parallel "test shape". If
+ * the decode were lossy the digests would not match and the acceptance test would
+ * fail loudly, which is exactly the guarantee we want from a byte-identity sprint.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import assert from "node:assert/strict";
+import { V2, readManifest } from "./_acceptance-fixture.js";
+/** Read one registered restoration fixture (asserting it IS registered). */
+export function restorationFixture(id) {
+    const m = readManifest();
+    const row = m.fixtures.find((f) => f.id === id && f.path.startsWith("restoration/"));
+    assert.ok(row, `fixture ${id} registered under restoration/ in manifest`);
+    return JSON.parse(readFileSync(join(V2, row.path), "utf8"));
+}
+/** base64 -> exact bytes, byte-for-byte (invalid UTF-8 included). */
+export function decodeBytes(base64) {
+    return new Uint8Array(Buffer.from(base64, "base64"));
+}
+/** JSON number seq bounds -> the bigint bounds `ShardRange` declares. */
+export function decodeRange(r) {
+    return {
+        sessionId: r.sessionId,
+        seqStart: BigInt(r.seqStart),
+        seqEnd: BigInt(r.seqEnd),
+        byteStart: r.byteStart,
+        byteEnd: r.byteEnd,
+    };
+}
+/** Reconstitute a real `ExactShardV1` from its fixture row. */
+export function decodeShard(s) {
+    return {
+        schema: "exact-shard-v1",
+        sessionId: s.sessionId,
+        range: decodeRange(s.range),
+        kind: "exact",
+        originalBytes: decodeBytes(s.originalBytesBase64),
+        digest: s.digest,
+        byteCount: s.byteCount,
+        case: s.case,
+    };
+}
+/**
+ * Reconstitute a real `EventV2`. `utf8` is re-derived by strict classification
+ * (never lossy replacement) so an invalid-UTF-8 fixture produces the
+ * `{valid:false, base64}` discriminant the VC1A contract requires.
+ */
+export function decodeEvent(e) {
+    const bytes = decodeBytes(e.originalBytesBase64);
+    let utf8;
+    try {
+        utf8 = { valid: true, text: new TextDecoder("utf-8", { fatal: true }).decode(bytes) };
+    }
+    catch {
+        utf8 = { valid: false, base64: e.originalBytesBase64 };
+    }
+    return {
+        schema: "event-v2",
+        sessionId: e.sessionId,
+        seq: BigInt(e.seq),
+        eventId: e.eventId,
+        role: e.role,
+        kind: e.kind,
+        originalBytes: bytes,
+        bytesDigest: e.bytesDigest,
+        utf8,
+        ...(e.toolCallId !== undefined ? { toolCallId: e.toolCallId } : {}),
+        occurredAtMs: BigInt(e.occurredAtMs),
+    };
+}
+/** Flag-pinned wrapper: VC6B gated by MEGACOMPACT_VC6B (defaults ON). */
+export function withVc6bFlagsOn(fn) {
+    return () => {
+        const saved = process.env.MEGACOMPACT_VC6B;
+        process.env.MEGACOMPACT_VC6B = "1";
+        try {
+            fn();
+        }
+        finally {
+            if (saved === undefined)
+                delete process.env.MEGACOMPACT_VC6B;
+            else
+                process.env.MEGACOMPACT_VC6B = saved;
+        }
+    };
+}

package/dist/vector-cortex/heal/_vc6b-helpers.js

@@ -0,0 +1,35 @@
+/**
+ * heal/_vc6b-helpers.ts — shared decode/run helpers for VC6B acceptance tests.
+ *
+ * Extracted from vc6b-acceptance.test.ts so no single test file crosses the
+ * 300-line soft limit (soft-as-hard gate). Each sibling test file imports from
+ * here rather than duplicating the decode/runReal logic.
+ */
+import { createHash } from "node:crypto";
+import { restoreSources } from "./restore.js";
+import { verifyRestored } from "./verify.js";
+import { decodeRange, decodeShard, decodeEvent } from "./_restore-fixture.js";
+export const enc = (s) => new Uint8Array(Buffer.from(s));
+export const hex = (b) => createHash("sha256").update(b).digest("hex");
+export function decodeFx(fx) {
+    return {
+        request: {
+            schema: "restore-request-v1",
+            sessionId: fx.input.sessionId,
+            spans: fx.input.request.spans.map((s) => ({
+                nodeId: s.nodeId,
+                range: decodeRange(s.range),
+                digest: s.digest,
+            })),
+        },
+        reader: {
+            exactShards: fx.input.exactShards.map(decodeShard),
+            ledgerEvents: fx.input.ledgerEvents.map(decodeEvent),
+        },
+    };
+}
+export function runReal(fx) {
+    const { request, reader } = decodeFx(fx);
+    const result = restoreSources(request, reader);
+    return { request, reader, result, verification: verifyRestored(result, request) };
+}

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