pi-mega-compact 0.20.34 → 0.20.36

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/encoder/calibrate.js

@@ -22,6 +22,8 @@
  * (PREVENT-011).
  */
 import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { ML5A_ENABLED } from "../../config/vector-cortex.js";
 import { ENCODER_HEAD_ORDER, ENCODER_SEED, ENC_QUALIFICATION_FAIL, } from "./types.js";
 /** Canonical digests of a sorted stable representation (order-invariant). */
 function digestStrings(values) {
@@ -172,3 +174,56 @@ export function fitCalibration(examples, options = {}) {
     };
     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) {
+    if (!ML5A_ENABLED())
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const r = parsed;
+    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"];
+    const thresholds = r["thresholds"];
+    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 },
+        thresholds: { ...thresholds },
+        seed: Number(r["seed"] ?? ENCODER_SEED),
+    };
+}

package/dist/vector-cortex/encoder/heads.js

@@ -19,6 +19,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, ENCODER_HEAD_LOSS_WEIGHTS, ENCODER_HEAD_LOSS_SUM, ENCODER_SEED, } from "./types.js";
 import { createEncoderHeadsReporter, NOOP_VC2B_REPORTER, } from "./emit-vc2b.js";
 /** The stable head index of a head name (its position in ENCODER_HEAD_ORDER). */
@@ -110,4 +112,89 @@ export function encodeVectorSet(tokens, options = {}) {
 export function headLossWeights() {
     return { ...ENCODER_HEAD_LOSS_WEIGHTS };
 }
+/** True when every head's output dim + weight length matches the contract. */
+export function headsShapeValid(t) {
+    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) {
+    if (!ML5A_ENABLED())
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const r = parsed;
+    if (!r || r["schema"] !== "trained-heads-v1")
+        return null;
+    if (r["seed"] !== ENCODER_SEED)
+        return null;
+    const dims = r["dims"];
+    const heads = r["heads"];
+    if (!dims || !heads)
+        return null;
+    const trunkDim = Number(r["trunkDim"] ?? 0);
+    if (!Number.isFinite(trunkDim) || trunkDim <= 0)
+        return null;
+    const weights = {};
+    const temperatures = {};
+    for (const h of ENCODER_HEAD_ORDER) {
+        const hd = heads[h];
+        if (!hd || typeof hd !== "object")
+            return null;
+        const w = hd["weights"];
+        if (!Array.isArray(w))
+            return null;
+        weights[h] = Float32Array.from(w);
+        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 = {
+        schema: "trained-heads-v1",
+        seed: Number(r["seed"]),
+        trunkDim,
+        dims: { semantic: 384, dependency: 128, contradiction: 128, cacheStability: 64, payloadRouting: 32 },
+        weights: weights,
+        temperatures: temperatures,
+    };
+    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, trunk, table) {
+    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/dist/vector-cortex/encoder/select.js

@@ -33,6 +33,8 @@
  * `any` (PREVENT-011).
  */
 import { createHash } from "node:crypto";
+import { ML5A_ENABLED } from "../../config/vector-cortex.js";
+import { loadHeadProjections } from "./heads.js";
 import { ENC_QUALIFICATION_FAIL, EVALUATION_THRESHOLDS, } from "./types.js";
 import { createEncoderQualificationReporter, } from "./emit-vc2c.js";
 /** Canonical digest over a CalibrationV1's stable identity (split digest, heads,
@@ -118,6 +120,14 @@ export function selectQualifiedEncoder(candidate, options = {}) {
     }
     // Atomic: collect EVERY failed field across asset + all heads + reconstruction.
     const failed = [];
+    // 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 = ["semantic", "dependency", "contradiction", "cacheStability", "payloadRouting"];
     for (const h of heads) {

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/dashboard-server/routes-rag-settings-vector-cortex.ts

@@ -222,5 +222,11 @@ export const VECTOR_CORTEX_SETTINGS: SettingGroup = {
 			"Dashboard per-turn prompt-cache visibility: surfaces the per-turn stable-prefix ratio trend (GET /api/prefix-stability) in the CacheTab PrefixStabilityCard. Reads aggregate ratios/counts from the local monitoring events log only — no payload bytes. OFF = byte-identical predecessor (PC-B-era): /api/prefix-stability returns 404 and the CacheTab omits the PrefixStabilityCard.",
 			true,
 		),
+		boolDirect(
+			"MEGACOMPACT_ML5_A",
+			"ML5-A Five-Head Training Load",
+			"ML5-A real trained-head loading: loadHeadProjections (trained-heads-v1) feeds selectQualifiedEncoder (trainedHeadsPath atomic demotion) + loadCalibrationV1. ON (default) = a pinned trained-heads path must load for mode A. OFF = loaders return null and selection ignores trainedHeadsPath — byte-identical to the placeholder-weighted VC2C path.",
+			true,
+		),
 	],
 };

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) =>