pi-mega-compact 0.20.35 → 0.20.36

package/dist/config/vector-cortex-ml5a.js

@@ -0,0 +1,28 @@
+/**
+ * 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 = () => sprintFlag("MEGACOMPACT_ML5_A");

package/dist/config/vector-cortex.js

@@ -239,16 +239,15 @@ export const VC8A_ENABLED = () => sprintFlag("MEGACOMPACT_VC8A");
  * mirroring VC4A..VC8A.
  */
 export const VC8B_ENABLED = () => 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 { BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./vector-cortex-breakers.js";

package/dist/config.js

@@ -114,4 +114,4 @@ export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
 // default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
 // so root consumers share one source of truth.
 // ---------------------------------------------------------------------------
-export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, VC7B_ENABLED, VC7C_ENABLED, VC8A_ENABLED, VC8B_ENABLED, VC8C_ENABLED, VC9A_ENABLED, VC9B_ENABLED, VC9C_ENABLED, VC9D_ENABLED, PCC_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, VC7B_ENABLED, VC7C_ENABLED, VC8A_ENABLED, VC8B_ENABLED, VC8C_ENABLED, VC9A_ENABLED, VC9B_ENABLED, VC9C_ENABLED, VC9D_ENABLED, PCC_ENABLED, ML5A_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";

package/dist/extensions/dashboard-server/routes-rag-settings-vector-cortex.js

@@ -53,5 +53,6 @@ export const VECTOR_CORTEX_SETTINGS = {
         boolDirect("MEGACOMPACT_VC9C", "VC9C SetupTab Cortex Sub-tab", "SetupTab Cortex sub-tab (client UI): a Cortex sub-tab inside SetupTab that consumes the VC9A status endpoint (GET /api/setup-cortex-status) + the VC9B action endpoints. It surfaces the encoder mode A/B/C, asset digest prefix, qualification verdict + threshold failures, the open hard-gate blockers, and the confirmation-gated fetch/bench/verify actions. OFF = byte-identical predecessor (VC9B-era): the Cortex sub-tab is filtered from SUB_TABS and the Setup tab renders exactly as before.", true),
         boolDirect("MEGACOMPACT_VC9D", "VC9D Embedder Detect Consolidation", "Embedder-detect consolidation + VC9 workstream roll-up: memoizes /api/setup-detect against the mutable input (resolved binary path + mtime) so consecutive requests reuse the result without re-spawning, and unifies the embedder + cortex sub-tabs' 5s poll contract. OFF = byte-identical predecessor (VC9C-era): detect spawns fresh per request and the embedder poll keeps its previous cadence.", true),
         boolDirect("MEGACOMPACT_PC_C", "PC-C Dashboard Cache Visibility", "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/dist/src/config/vector-cortex-ml5a.js

@@ -0,0 +1,28 @@
+/**
+ * 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 = () => sprintFlag("MEGACOMPACT_ML5_A");

package/dist/src/config/vector-cortex.js

@@ -239,16 +239,15 @@ export const VC8A_ENABLED = () => sprintFlag("MEGACOMPACT_VC8A");
  * mirroring VC4A..VC8A.
  */
 export const VC8B_ENABLED = () => 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 { BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./vector-cortex-breakers.js";

package/dist/src/config.js

@@ -114,4 +114,4 @@ export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
 // default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
 // so root consumers share one source of truth.
 // ---------------------------------------------------------------------------
-export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, VC7B_ENABLED, VC7C_ENABLED, VC8A_ENABLED, VC8B_ENABLED, VC8C_ENABLED, VC9A_ENABLED, VC9B_ENABLED, VC9C_ENABLED, VC9D_ENABLED, PCC_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, VC7B_ENABLED, VC7C_ENABLED, VC8A_ENABLED, VC8B_ENABLED, VC8C_ENABLED, VC9A_ENABLED, VC9B_ENABLED, VC9C_ENABLED, VC9D_ENABLED, PCC_ENABLED, ML5A_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";

package/dist/src/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/src/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/src/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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.35",
+  "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) {