pi-mega-compact 0.20.44 → 0.20.46

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

@@ -0,0 +1,35 @@
+/**
+ * config/vector-cortex-enc0c.ts — ENC-0c five-head supervision transfer flag.
+ *
+ * Extracted from vector-cortex.ts so that file stays under the 300-line soft
+ * limit (soft-as-hard gate), exactly as vector-cortex-enc0a.ts / enc0b.ts and
+ * the VC8C/VC9A-D/ML5A-E/DEDUP_ATTR siblings were. vector-cortex.ts re-exports
+ * the flag below and root src/config.ts re-exports it, so no consumer import
+ * path changes.
+ *
+ * ENC-0c trains the five real heads onto the frozen ENC-0b bge-small trunk via
+ * supervision transfer, and stages a qualified candidate under
+ * ~/.pi/mega-compact-encoder/candidates/ (only when the developer trains it —
+ * the extension never stages one by itself). When the flag is ON and a
+ * qualified candidate exists, `loadHeadCandidate` (encoder/heads.ts seam) serves
+ * the trained head weights; when the flag is OFF (MEGACOMPACT_ENC_0C=0) or no
+ * candidate is staged, the heads keep serving the ENC-0b survivor exactly —
+ * byte-identical, no weight change. The flag gates ONLY the candidate-load seam;
+ * the survivor path is untouched.
+ *
+ * The split is purely mechanical: ENC_0C_ENABLED follows ENC_0B_ENABLED in name,
+ * semantics, and default, 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";
+/**
+ * ENC-0c — five-head supervision transfer on the frozen bge-small trunk.
+ * Default ON. `MEGACOMPACT_ENC_0C=0` disables and is byte-identical to the
+ * predecessor (ENC-0b): no head candidate is loaded and the heads keep serving
+ * the ENC-0b survivor defaults exactly as before. This flag MUST also be a
+ * dashboard SETTINGS toggle (visible in config UI, never in EXCLUDED_SETTINGS),
+ * mirroring ENC_0A and ENC_0B.
+ */
+export const ENC_0C_ENABLED = () => sprintFlag("MEGACOMPACT_ENC_0C");

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

@@ -0,0 +1,39 @@
+/**
+ * config/vector-cortex-enc0d.ts — ENC-0d promotion gate over real trained assets.
+ *
+ * Extracted from vector-cortex.ts so that file stays under the 300-line soft
+ * limit (soft-as-hard gate), exactly as vector-cortex-enc0a.ts / enc0b.ts /
+ * enc0c.ts and the VC8C/VC9A-D/ML5A-E/DEDUP_ATTR siblings were. vector-cortex.ts
+ * re-exports the flag below and root src/config.ts re-exports it, so no
+ * consumer import path changes.
+ *
+ * ENC-0d turns the ML5-E promotion gate into the real-asset promotion path:
+ * it accepts a `{color}` real candidate manifest (the ENC-0c trained head
+ * weights + the ENC-0b trunk, staged under
+ * ~/.pi/mega-compact-encoder/candidates/), digest-verifies every staged byte
+ * before any swap, and performs an atomic asset swap with rollback-to-previous
+ * on qualification failure. The extension itself never stages candidate assets —
+ * only the operator trains them. When the flag is ON and a digest-verified
+ * green candidate exists, an atomic swap is performed and the runtime flips into
+ * qualified mode A; a red qualification (or any verification failure) keeps the
+ * prior asset live and emits a demotion.
+ *
+ * `MEGACOMPACT_ENC_0D=0` accepts no candidate, swaps nothing, emits nothing, and
+ * the shipped manifest stays at the ENC-0c survivor — byte-identical predecessor.
+ *
+ * The split is purely mechanical: ENC_0D_ENABLED follows ENC_0C_ENABLED in name,
+ * semantics, and default, 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";
+/**
+ * ENC-0d — atomic real-asset promotion over trained candidates. Default ON.
+ * `MEGACOMPACT_ENC_0D=0` disables and is byte-identical to the predecessor
+ * (ENC-0c): no candidate is accepted, no swap is performed, no promote/
+ * demote/rollback events are emitted, and the shipped manifest stays at the
+ * ENC-0c survivor. This flag MUST also be a dashboard SETTINGS toggle (visible
+ * in config UI, never in EXCLUDED_SETTINGS), mirroring ENC_0A/ENC_0B/ENC_0C.
+ */
+export const ENC_0D_ENABLED = () => sprintFlag("MEGACOMPACT_ENC_0D");

package/dist/config/vector-cortex.js

@@ -251,5 +251,7 @@ export { ML5E_ENABLED } from "./vector-cortex-ml5e.js";
 export { DEDUP_ATTR_ENABLED } from "./vector-cortex-dedup-attr.js";
 export { ENC_0A_ENABLED } from "./vector-cortex-enc0a.js";
 export { ENC_0B_ENABLED } from "./vector-cortex-enc0b.js";
+export { ENC_0C_ENABLED } from "./vector-cortex-enc0c.js";
+export { ENC_0D_ENABLED } from "./vector-cortex-enc0d.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, ML5A_ENABLED, ML5B_ENABLED, ML5C_ENABLED, ML5D_ENABLED, ML5E_ENABLED, DEDUP_ATTR_ENABLED, ENC_0A_ENABLED, ENC_0B_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, ML5B_ENABLED, ML5C_ENABLED, ML5D_ENABLED, ML5E_ENABLED, DEDUP_ATTR_ENABLED, ENC_0A_ENABLED, ENC_0B_ENABLED, ENC_0C_ENABLED, ENC_0D_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

@@ -60,5 +60,7 @@ export const VECTOR_CORTEX_SETTINGS = {
         boolDirect("MEGACOMPACT_DEDUP_ATTR", "Dedup Tier Attribution Rollup", "Dedup tier-attribution rollup: per-tier dedup catch shares (L0/L1/L2/new percent of dedup decisions) read from the local events.log dedup_audit stream (GET /api/dedup-tier-attribution). OFF = 404 + no cache file, byte-identical predecessor.", true),
         boolDirect("MEGACOMPACT_ENC_0A", "ENC-0a Encoder Backend Decision", "ENC-0a learned-encoder backend-decision lock: records the transformers.js/WASM vs onnxruntime-node choice, per-platform install matrix, opset-21 baseline and pinned digests in docs/vector-cortex/encoder-backend-decision.md. OFF = no decision record written / no resolver runs, mode B trigram byte-identical predecessor.", true),
         boolDirect("MEGACOMPACT_ENC_0B", "ENC-0b Real Trunk Fetch & Gated Path", "ENC-0b real ONNX trunk fetch + gated inference: replaces the LCG placeholder with the real bge-small int8 model through an ONNX InferenceSession (onnxruntime-web WASM). OFF = LCG placeholder serves byte-identical predecessor output, no ONNX session built.", true),
+        boolDirect("MEGACOMPACT_ENC_0C", "ENC-0c Five-Head Supervision Transfer", "ENC-0c five-head supervision transfer on the frozen bge-small trunk: when a developer-trained head candidate is staged under ~/.pi/mega-compact-encoder/candidates/, the five heads serve the trained weights. OFF = no candidate is loaded, the heads serve byte-identical ENC-0b survivor defaults.", true),
+        boolDirect("MEGACOMPACT_ENC_0D", "ENC-0d Real-Asset Promotion Gate", "ENC-0d promotion gate over real trained assets: accepts a {color} real candidate manifest (the ENC-0c trained head weights + the ENC-0b trunk), digest-verifies every staged byte, and atomically swaps the shipped manifest to a green candidate with rollback-to-previous on qualification failure. OFF = accepts no candidate, swaps nothing, emits nothing, shipped manifest stays at the ENC-0c survivor.", true),
     ],
 };

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

@@ -0,0 +1,35 @@
+/**
+ * config/vector-cortex-enc0c.ts — ENC-0c five-head supervision transfer flag.
+ *
+ * Extracted from vector-cortex.ts so that file stays under the 300-line soft
+ * limit (soft-as-hard gate), exactly as vector-cortex-enc0a.ts / enc0b.ts and
+ * the VC8C/VC9A-D/ML5A-E/DEDUP_ATTR siblings were. vector-cortex.ts re-exports
+ * the flag below and root src/config.ts re-exports it, so no consumer import
+ * path changes.
+ *
+ * ENC-0c trains the five real heads onto the frozen ENC-0b bge-small trunk via
+ * supervision transfer, and stages a qualified candidate under
+ * ~/.pi/mega-compact-encoder/candidates/ (only when the developer trains it —
+ * the extension never stages one by itself). When the flag is ON and a
+ * qualified candidate exists, `loadHeadCandidate` (encoder/heads.ts seam) serves
+ * the trained head weights; when the flag is OFF (MEGACOMPACT_ENC_0C=0) or no
+ * candidate is staged, the heads keep serving the ENC-0b survivor exactly —
+ * byte-identical, no weight change. The flag gates ONLY the candidate-load seam;
+ * the survivor path is untouched.
+ *
+ * The split is purely mechanical: ENC_0C_ENABLED follows ENC_0B_ENABLED in name,
+ * semantics, and default, 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";
+/**
+ * ENC-0c — five-head supervision transfer on the frozen bge-small trunk.
+ * Default ON. `MEGACOMPACT_ENC_0C=0` disables and is byte-identical to the
+ * predecessor (ENC-0b): no head candidate is loaded and the heads keep serving
+ * the ENC-0b survivor defaults exactly as before. This flag MUST also be a
+ * dashboard SETTINGS toggle (visible in config UI, never in EXCLUDED_SETTINGS),
+ * mirroring ENC_0A and ENC_0B.
+ */
+export const ENC_0C_ENABLED = () => sprintFlag("MEGACOMPACT_ENC_0C");

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

@@ -0,0 +1,39 @@
+/**
+ * config/vector-cortex-enc0d.ts — ENC-0d promotion gate over real trained assets.
+ *
+ * Extracted from vector-cortex.ts so that file stays under the 300-line soft
+ * limit (soft-as-hard gate), exactly as vector-cortex-enc0a.ts / enc0b.ts /
+ * enc0c.ts and the VC8C/VC9A-D/ML5A-E/DEDUP_ATTR siblings were. vector-cortex.ts
+ * re-exports the flag below and root src/config.ts re-exports it, so no
+ * consumer import path changes.
+ *
+ * ENC-0d turns the ML5-E promotion gate into the real-asset promotion path:
+ * it accepts a `{color}` real candidate manifest (the ENC-0c trained head
+ * weights + the ENC-0b trunk, staged under
+ * ~/.pi/mega-compact-encoder/candidates/), digest-verifies every staged byte
+ * before any swap, and performs an atomic asset swap with rollback-to-previous
+ * on qualification failure. The extension itself never stages candidate assets —
+ * only the operator trains them. When the flag is ON and a digest-verified
+ * green candidate exists, an atomic swap is performed and the runtime flips into
+ * qualified mode A; a red qualification (or any verification failure) keeps the
+ * prior asset live and emits a demotion.
+ *
+ * `MEGACOMPACT_ENC_0D=0` accepts no candidate, swaps nothing, emits nothing, and
+ * the shipped manifest stays at the ENC-0c survivor — byte-identical predecessor.
+ *
+ * The split is purely mechanical: ENC_0D_ENABLED follows ENC_0C_ENABLED in name,
+ * semantics, and default, 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";
+/**
+ * ENC-0d — atomic real-asset promotion over trained candidates. Default ON.
+ * `MEGACOMPACT_ENC_0D=0` disables and is byte-identical to the predecessor
+ * (ENC-0c): no candidate is accepted, no swap is performed, no promote/
+ * demote/rollback events are emitted, and the shipped manifest stays at the
+ * ENC-0c survivor. This flag MUST also be a dashboard SETTINGS toggle (visible
+ * in config UI, never in EXCLUDED_SETTINGS), mirroring ENC_0A/ENC_0B/ENC_0C.
+ */
+export const ENC_0D_ENABLED = () => sprintFlag("MEGACOMPACT_ENC_0D");

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

@@ -251,5 +251,7 @@ export { ML5E_ENABLED } from "./vector-cortex-ml5e.js";
 export { DEDUP_ATTR_ENABLED } from "./vector-cortex-dedup-attr.js";
 export { ENC_0A_ENABLED } from "./vector-cortex-enc0a.js";
 export { ENC_0B_ENABLED } from "./vector-cortex-enc0b.js";
+export { ENC_0C_ENABLED } from "./vector-cortex-enc0c.js";
+export { ENC_0D_ENABLED } from "./vector-cortex-enc0d.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, ML5A_ENABLED, ML5B_ENABLED, ML5C_ENABLED, ML5D_ENABLED, ML5E_ENABLED, DEDUP_ATTR_ENABLED, ENC_0A_ENABLED, ENC_0B_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, ML5B_ENABLED, ML5C_ENABLED, ML5D_ENABLED, ML5E_ENABLED, DEDUP_ATTR_ENABLED, ENC_0A_ENABLED, ENC_0B_ENABLED, ENC_0C_ENABLED, ENC_0D_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/heads-candidate.js

@@ -0,0 +1,127 @@
+/**
+ * encoder/heads-candidate.ts — ENC-0c head-candidate load seam (delegate impl).
+ *
+ * Loads/validates a `head-candidate-v1` five-head candidate staged under
+ * `~/.pi/mega-compact-encoder/candidates/<version>/` after training on the
+ * frozen ENC-0b bge-small trunk. Flag-off / absent / malformed / wrong dims /
+ * non-finite / digest / trunk mismatch each return null or {ok:false} — a bad
+ * candidate is NEVER force-loaded; the runtime keeps the ENC-0b survivor
+ * byte-identical. No `any` (PREVENT-011), local-only, structured logging.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ENC_0C_ENABLED } from "../../config/vector-cortex.js";
+import { ENCODER_HEAD_DIMS, ENCODER_HEAD_ORDER } from "./types.js";
+export const HEAD_CANDIDATE_SCHEMA = "head-candidate-v1";
+const MANIFEST_FILE = "manifest.json";
+export const HEAD_CANDIDATE_FAIL = {
+    INVALID: "ENC0C_CANDIDATE_INVALID",
+    TRUNK_MISMATCH: "ENC0C_TRUNK_MISMATCH",
+    DIM_MISMATCH: "ENC0C_DIM_MISMATCH",
+    NON_FINITE: "ENC0C_NON_FINITE",
+    DIGEST_MISMATCH: "ENC0C_DIGEST_MISMATCH",
+};
+function sha256(buf) { return createHash("sha256").update(buf).digest("hex"); }
+function finiteDim(values, dim) {
+    if (values.length !== dim)
+        return false;
+    for (const v of values)
+        if (!Number.isFinite(v))
+            return false;
+    return true;
+}
+function parseManifest(m) {
+    if (!m || m["schema"] !== HEAD_CANDIDATE_SCHEMA)
+        return null;
+    const version = typeof m["version"] === "string" ? m["version"] : "";
+    const trunkDigest = typeof m["trunkDigest"] === "string" ? m["trunkDigest"] : "";
+    if (!version || !trunkDigest || !Array.isArray(m["heads"]))
+        return null;
+    const heads = [];
+    for (const item of m["heads"]) {
+        const rec = item;
+        if (!rec || typeof rec !== "object")
+            return null;
+        const name = rec["name"];
+        if (typeof name !== "string" || !ENCODER_HEAD_ORDER.includes(name))
+            return null;
+        heads.push({
+            name: name,
+            dim: Number(rec["dim"] ?? 0),
+            sha256: typeof rec["sha256"] === "string" ? rec["sha256"] : "",
+            bytes: Number(rec["bytes"] ?? 0),
+        });
+    }
+    return { version, trunkDigest, heads };
+}
+/** All 5 dims match, weights finite, digests hold. */
+export function validateHeadCandidate(candidate) {
+    for (const h of ENCODER_HEAD_ORDER) {
+        const dim = candidate.dims[h];
+        if (dim !== ENCODER_HEAD_DIMS[h])
+            return { ok: false, code: HEAD_CANDIDATE_FAIL.DIM_MISMATCH };
+        const w = candidate.weights[h];
+        if (!w || !finiteDim(w, dim))
+            return { ok: false, code: HEAD_CANDIDATE_FAIL.NON_FINITE };
+        const buf = new Uint8Array(w.buffer, w.byteOffset, w.byteLength);
+        if (sha256(buf) !== candidate.digests[h])
+            return { ok: false, code: HEAD_CANDIDATE_FAIL.DIGEST_MISMATCH };
+    }
+    return { ok: true };
+}
+/** Load a candidate against the frozen trunk; null on any violation, never throws. */
+export function loadHeadCandidate(candidateDir, manifest) {
+    if (!ENC_0C_ENABLED())
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(join(candidateDir, MANIFEST_FILE), "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const m = parseManifest(parsed);
+    if (!m || m.trunkDigest !== manifest.onnx.sha256)
+        return null;
+    const weights = {};
+    const digests = {};
+    const dims = {};
+    for (const rec of m.heads) {
+        const want = rec.dim * 4;
+        if (!Number.isInteger(want) || want <= 0 || rec.dim !== ENCODER_HEAD_DIMS[rec.name])
+            return null;
+        let bytes;
+        try {
+            bytes = readFileSync(join(candidateDir, `${rec.name}.bin`));
+        }
+        catch {
+            return null;
+        }
+        const f = new Float32Array(bytes.buffer, bytes.byteOffset, rec.dim);
+        const d = sha256(bytes);
+        if (bytes.length !== want || d !== rec.sha256)
+            return null;
+        weights[rec.name] = f.slice();
+        digests[rec.name] = d;
+        dims[rec.name] = rec.dim;
+    }
+    for (const h of ENCODER_HEAD_ORDER) {
+        if (weights[h] === undefined || digests[h] === undefined || dims[h] === undefined)
+            return null;
+    }
+    const candidate = {
+        schema: HEAD_CANDIDATE_SCHEMA, version: m.version, trunkDigest: m.trunkDigest,
+        dims: dims,
+        weights: weights,
+        digests: digests,
+    };
+    return validateHeadCandidate(candidate).ok ? candidate : null;
+}

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

@@ -198,3 +198,7 @@ export function projectHeadFromTrunk(head, trunk, table) {
     return { head, dim, values: l2Normalize(out) };
 }
 export { ENCODER_HEAD_ORDER, ENCODER_HEAD_DIMS, ENCODER_HEAD_LOSS_SUM, ENCODER_SEED, NOOP_VC2B_REPORTER };
+// ENC-0c five-head candidate seam (delegate-shell): the load/validate impl
+// lives in heads-candidate.ts; these re-exports keep the public import path
+// stable at heads.ts without growing this survivor file over the soft limit.
+export { HEAD_CANDIDATE_SCHEMA, HEAD_CANDIDATE_FAIL, loadHeadCandidate, validateHeadCandidate, } from "./heads-candidate.js";

package/dist/src/vector-cortex/encoder/promotion-emit.js

@@ -0,0 +1,40 @@
+/**
+ * vector-cortex/encoder/promotion-emit.ts — ENC-0d promotion event writers.
+ *
+ * Writes the three real-asset promotion events to the monitoring `events.log`
+ * as structured append-only JSON lines via the existing `logBenchEvent` seam
+ * (`src/monitoring.ts`):
+ *
+ *   - `vector_cortex_asset_promoted`      (green digest-verified swap)
+ *   - `vector_cortex_asset_demoted`       (red qualification / digest failure)
+ *   - `vector_cortex_asset_rollback_back` (restore of a prior stack digest)
+ *
+ * Non-fatal and log-and-swallow: a write failure never breaks the agent loop
+ * (best-effort store/write contract). Each line is `{ts, event, ...fields}`
+ * shaped so the dashboard live-stream tail and evidence tooling parse it
+ * identically to every other monitoring event. Events carry digests, colors
+ * and verdicts ONLY — never message content (EVAL-REDACT-002).
+ *
+ * The path defaults to the standard state-dir events.log (mirrors
+ * defaultEventsPath). Zero network, no `any` (PREVENT-PI-004 / PREVENT-011).
+ */
+import { defaultEventsPath, logBenchEvent } from "../../monitoring.js";
+import { getStateDir } from "../../store.js";
+/** Default events.log beside the state dir (mirrors bench.ts). */
+export function promotionEventsPath(stateDir = getStateDir()) {
+    return defaultEventsPath(stateDir);
+}
+const EVENT_NAME = {
+    promoted: "vector_cortex_asset_promoted",
+    demoted: "vector_cortex_asset_demoted",
+    rollback_back: "vector_cortex_asset_rollback_back",
+};
+/**
+ * Append one promotion event to events.log (best-effort, non-fatal). The line
+ * is `{ts, event, ...fields}` shaped, written append-only via the monitoring
+ * logBenchEvent seam. On any write failure the event is swallowed — the agent
+ * loop is never broken.
+ */
+export function appendPromotionEvent(path, kind, fields) {
+    logBenchEvent(path, EVENT_NAME[kind], { ...fields });
+}

package/dist/src/vector-cortex/encoder/promotion.js

@@ -14,6 +14,15 @@
  * an atomic digest swap (flip the committed pointer to the prior entry's
  * digest in one step) — no partial state is possible because the swap is a
  * single value assignment.
+ *
+ * ENC-0d extends the ledger to the real-asset promotion path: `PromotionV1`
+ * carries `{color, assetDigestStack}` — a promotion color from gate
+ * qualification ("green" atomically swaps to the trained asset, "red" keeps
+ * the prior asset live) and a LIFO of prior shipped digest for O(1)-by-sha256
+ * rollback. The on-disk manifest byte-swap itself (write-temp-then-rename,
+ * never in-place partial) is the promotion gate script's job; these helpers
+ * stay pure and return the restorable digest + the updated manifest/stack so
+ * the script can perform the swap in one atomic step.
  */
 // ---------------------------------------------------------------------------
 // PromotionV1 — the ledger row recording one nightly training + promotion run.
@@ -42,6 +51,61 @@ export function rollbackTo(manifest, digest) {
     };
 }
 // ---------------------------------------------------------------------------
+// ENC-0d LIFO rollback stack + atomic swap. Pure pointer arithmetic; the
+// on-disk write-temp-then-rename of the swapped manifest bytes is the gate
+// script's job so no partial state can ever be observed (PREVENT-PI-004).
+// ---------------------------------------------------------------------------
+/** Push a freshly-shipped digest onto the LIFO rollback stack (top = latest
+ *  prior shipped digest). Non-mutating: returns a new array. */
+export function pushAssetDigest(stack, digest) {
+    return [...stack, digest];
+}
+/** Pop the top (most recent prior) digest off the LIFO rollback stack without
+ *  mutating it. Returns the prior digest (null when the stack is empty) plus
+ *  the remaining stack for the caller to commit (atomic card-swap fallback:
+ *  a green swap pushes the incumbent digest; a rollback pops it). */
+export function popAssetDigest(stack) {
+    if (stack.length === 0)
+        return { prior: null, rest: stack };
+    const rest = stack.slice(0, -1);
+    return { prior: stack[stack.length - 1], rest };
+}
+/** Atomically swap the committed manifest to a real trained asset's digest.
+ *  Green: append the new entry (append-only — the incumbent stays in the
+ *  ledger, never overwritten), commit to it, and record the INCUMBENT digest
+ *  onto the LIFO stack for O(1) rollback (rollback restores the incumbent, so
+ *  the stack must hold the pre-swap committed digest — pushing the swapped-in
+ *  digest would point rollback back at the very asset being rolled back). Red
+ *  (or no candidate digest): return the manifest and stack untouched — no
+ *  swap, prior asset stays live. */
+export function atomicSwap(manifest, entry, color, stack) {
+    if (color !== "green" || !entry.assetDigest) {
+        return { manifest, stack, swapped: false };
+    }
+    const incumbent = manifest.committed;
+    const next = appendAsset(manifest, entry);
+    return {
+        manifest: next,
+        stack: incumbent === null ? stack : pushAssetDigest(stack, incumbent),
+        swapped: true,
+    };
+}
+/** Roll back to the previous shipped asset by SHA-256 (O(1) via the LIFO
+ *  stack): restores the most recent prior digest in the manifest and pops that
+ *  entry off the stack. Returns null when no prior digest exists or the prior
+ *  digest is no longer in the append-only manifest (defensive: append-only
+ *  means it should always be findable). Never leaves a partial state — the
+ *  committed pointer flip and the stack pop happen together or not at all. */
+export function assetRollback(manifest, stack) {
+    const { prior, rest } = popAssetDigest(stack);
+    if (prior === null)
+        return null;
+    const restored = rollbackTo(manifest, prior);
+    if (!restored)
+        return null;
+    return { manifest: restored, stack: rest, swapped: true };
+}
+// ---------------------------------------------------------------------------
 // Pure decision rules.
 // ---------------------------------------------------------------------------
 /** Evaluate the promotion gate: promote only when all five heads pass AND the

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

@@ -0,0 +1,127 @@
+/**
+ * encoder/heads-candidate.ts — ENC-0c head-candidate load seam (delegate impl).
+ *
+ * Loads/validates a `head-candidate-v1` five-head candidate staged under
+ * `~/.pi/mega-compact-encoder/candidates/<version>/` after training on the
+ * frozen ENC-0b bge-small trunk. Flag-off / absent / malformed / wrong dims /
+ * non-finite / digest / trunk mismatch each return null or {ok:false} — a bad
+ * candidate is NEVER force-loaded; the runtime keeps the ENC-0b survivor
+ * byte-identical. No `any` (PREVENT-011), local-only, structured logging.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ENC_0C_ENABLED } from "../../config/vector-cortex.js";
+import { ENCODER_HEAD_DIMS, ENCODER_HEAD_ORDER } from "./types.js";
+export const HEAD_CANDIDATE_SCHEMA = "head-candidate-v1";
+const MANIFEST_FILE = "manifest.json";
+export const HEAD_CANDIDATE_FAIL = {
+    INVALID: "ENC0C_CANDIDATE_INVALID",
+    TRUNK_MISMATCH: "ENC0C_TRUNK_MISMATCH",
+    DIM_MISMATCH: "ENC0C_DIM_MISMATCH",
+    NON_FINITE: "ENC0C_NON_FINITE",
+    DIGEST_MISMATCH: "ENC0C_DIGEST_MISMATCH",
+};
+function sha256(buf) { return createHash("sha256").update(buf).digest("hex"); }
+function finiteDim(values, dim) {
+    if (values.length !== dim)
+        return false;
+    for (const v of values)
+        if (!Number.isFinite(v))
+            return false;
+    return true;
+}
+function parseManifest(m) {
+    if (!m || m["schema"] !== HEAD_CANDIDATE_SCHEMA)
+        return null;
+    const version = typeof m["version"] === "string" ? m["version"] : "";
+    const trunkDigest = typeof m["trunkDigest"] === "string" ? m["trunkDigest"] : "";
+    if (!version || !trunkDigest || !Array.isArray(m["heads"]))
+        return null;
+    const heads = [];
+    for (const item of m["heads"]) {
+        const rec = item;
+        if (!rec || typeof rec !== "object")
+            return null;
+        const name = rec["name"];
+        if (typeof name !== "string" || !ENCODER_HEAD_ORDER.includes(name))
+            return null;
+        heads.push({
+            name: name,
+            dim: Number(rec["dim"] ?? 0),
+            sha256: typeof rec["sha256"] === "string" ? rec["sha256"] : "",
+            bytes: Number(rec["bytes"] ?? 0),
+        });
+    }
+    return { version, trunkDigest, heads };
+}
+/** All 5 dims match, weights finite, digests hold. */
+export function validateHeadCandidate(candidate) {
+    for (const h of ENCODER_HEAD_ORDER) {
+        const dim = candidate.dims[h];
+        if (dim !== ENCODER_HEAD_DIMS[h])
+            return { ok: false, code: HEAD_CANDIDATE_FAIL.DIM_MISMATCH };
+        const w = candidate.weights[h];
+        if (!w || !finiteDim(w, dim))
+            return { ok: false, code: HEAD_CANDIDATE_FAIL.NON_FINITE };
+        const buf = new Uint8Array(w.buffer, w.byteOffset, w.byteLength);
+        if (sha256(buf) !== candidate.digests[h])
+            return { ok: false, code: HEAD_CANDIDATE_FAIL.DIGEST_MISMATCH };
+    }
+    return { ok: true };
+}
+/** Load a candidate against the frozen trunk; null on any violation, never throws. */
+export function loadHeadCandidate(candidateDir, manifest) {
+    if (!ENC_0C_ENABLED())
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(join(candidateDir, MANIFEST_FILE), "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const m = parseManifest(parsed);
+    if (!m || m.trunkDigest !== manifest.onnx.sha256)
+        return null;
+    const weights = {};
+    const digests = {};
+    const dims = {};
+    for (const rec of m.heads) {
+        const want = rec.dim * 4;
+        if (!Number.isInteger(want) || want <= 0 || rec.dim !== ENCODER_HEAD_DIMS[rec.name])
+            return null;
+        let bytes;
+        try {
+            bytes = readFileSync(join(candidateDir, `${rec.name}.bin`));
+        }
+        catch {
+            return null;
+        }
+        const f = new Float32Array(bytes.buffer, bytes.byteOffset, rec.dim);
+        const d = sha256(bytes);
+        if (bytes.length !== want || d !== rec.sha256)
+            return null;
+        weights[rec.name] = f.slice();
+        digests[rec.name] = d;
+        dims[rec.name] = rec.dim;
+    }
+    for (const h of ENCODER_HEAD_ORDER) {
+        if (weights[h] === undefined || digests[h] === undefined || dims[h] === undefined)
+            return null;
+    }
+    const candidate = {
+        schema: HEAD_CANDIDATE_SCHEMA, version: m.version, trunkDigest: m.trunkDigest,
+        dims: dims,
+        weights: weights,
+        digests: digests,
+    };
+    return validateHeadCandidate(candidate).ok ? candidate : null;
+}

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

@@ -198,3 +198,7 @@ export function projectHeadFromTrunk(head, trunk, table) {
     return { head, dim, values: l2Normalize(out) };
 }
 export { ENCODER_HEAD_ORDER, ENCODER_HEAD_DIMS, ENCODER_HEAD_LOSS_SUM, ENCODER_SEED, NOOP_VC2B_REPORTER };
+// ENC-0c five-head candidate seam (delegate-shell): the load/validate impl
+// lives in heads-candidate.ts; these re-exports keep the public import path
+// stable at heads.ts without growing this survivor file over the soft limit.
+export { HEAD_CANDIDATE_SCHEMA, HEAD_CANDIDATE_FAIL, loadHeadCandidate, validateHeadCandidate, } from "./heads-candidate.js";

package/dist/vector-cortex/encoder/promotion-emit.js

@@ -0,0 +1,40 @@
+/**
+ * vector-cortex/encoder/promotion-emit.ts — ENC-0d promotion event writers.
+ *
+ * Writes the three real-asset promotion events to the monitoring `events.log`
+ * as structured append-only JSON lines via the existing `logBenchEvent` seam
+ * (`src/monitoring.ts`):
+ *
+ *   - `vector_cortex_asset_promoted`      (green digest-verified swap)
+ *   - `vector_cortex_asset_demoted`       (red qualification / digest failure)
+ *   - `vector_cortex_asset_rollback_back` (restore of a prior stack digest)
+ *
+ * Non-fatal and log-and-swallow: a write failure never breaks the agent loop
+ * (best-effort store/write contract). Each line is `{ts, event, ...fields}`
+ * shaped so the dashboard live-stream tail and evidence tooling parse it
+ * identically to every other monitoring event. Events carry digests, colors
+ * and verdicts ONLY — never message content (EVAL-REDACT-002).
+ *
+ * The path defaults to the standard state-dir events.log (mirrors
+ * defaultEventsPath). Zero network, no `any` (PREVENT-PI-004 / PREVENT-011).
+ */
+import { defaultEventsPath, logBenchEvent } from "../../monitoring.js";
+import { getStateDir } from "../../store.js";
+/** Default events.log beside the state dir (mirrors bench.ts). */
+export function promotionEventsPath(stateDir = getStateDir()) {
+    return defaultEventsPath(stateDir);
+}
+const EVENT_NAME = {
+    promoted: "vector_cortex_asset_promoted",
+    demoted: "vector_cortex_asset_demoted",
+    rollback_back: "vector_cortex_asset_rollback_back",
+};
+/**
+ * Append one promotion event to events.log (best-effort, non-fatal). The line
+ * is `{ts, event, ...fields}` shaped, written append-only via the monitoring
+ * logBenchEvent seam. On any write failure the event is swallowed — the agent
+ * loop is never broken.
+ */
+export function appendPromotionEvent(path, kind, fields) {
+    logBenchEvent(path, EVENT_NAME[kind], { ...fields });
+}

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

@@ -14,6 +14,15 @@
  * an atomic digest swap (flip the committed pointer to the prior entry's
  * digest in one step) — no partial state is possible because the swap is a
  * single value assignment.
+ *
+ * ENC-0d extends the ledger to the real-asset promotion path: `PromotionV1`
+ * carries `{color, assetDigestStack}` — a promotion color from gate
+ * qualification ("green" atomically swaps to the trained asset, "red" keeps
+ * the prior asset live) and a LIFO of prior shipped digest for O(1)-by-sha256
+ * rollback. The on-disk manifest byte-swap itself (write-temp-then-rename,
+ * never in-place partial) is the promotion gate script's job; these helpers
+ * stay pure and return the restorable digest + the updated manifest/stack so
+ * the script can perform the swap in one atomic step.
  */
 // ---------------------------------------------------------------------------
 // PromotionV1 — the ledger row recording one nightly training + promotion run.
@@ -42,6 +51,61 @@ export function rollbackTo(manifest, digest) {
     };
 }
 // ---------------------------------------------------------------------------
+// ENC-0d LIFO rollback stack + atomic swap. Pure pointer arithmetic; the
+// on-disk write-temp-then-rename of the swapped manifest bytes is the gate
+// script's job so no partial state can ever be observed (PREVENT-PI-004).
+// ---------------------------------------------------------------------------
+/** Push a freshly-shipped digest onto the LIFO rollback stack (top = latest
+ *  prior shipped digest). Non-mutating: returns a new array. */
+export function pushAssetDigest(stack, digest) {
+    return [...stack, digest];
+}
+/** Pop the top (most recent prior) digest off the LIFO rollback stack without
+ *  mutating it. Returns the prior digest (null when the stack is empty) plus
+ *  the remaining stack for the caller to commit (atomic card-swap fallback:
+ *  a green swap pushes the incumbent digest; a rollback pops it). */
+export function popAssetDigest(stack) {
+    if (stack.length === 0)
+        return { prior: null, rest: stack };
+    const rest = stack.slice(0, -1);
+    return { prior: stack[stack.length - 1], rest };
+}
+/** Atomically swap the committed manifest to a real trained asset's digest.
+ *  Green: append the new entry (append-only — the incumbent stays in the
+ *  ledger, never overwritten), commit to it, and record the INCUMBENT digest
+ *  onto the LIFO stack for O(1) rollback (rollback restores the incumbent, so
+ *  the stack must hold the pre-swap committed digest — pushing the swapped-in
+ *  digest would point rollback back at the very asset being rolled back). Red
+ *  (or no candidate digest): return the manifest and stack untouched — no
+ *  swap, prior asset stays live. */
+export function atomicSwap(manifest, entry, color, stack) {
+    if (color !== "green" || !entry.assetDigest) {
+        return { manifest, stack, swapped: false };
+    }
+    const incumbent = manifest.committed;
+    const next = appendAsset(manifest, entry);
+    return {
+        manifest: next,
+        stack: incumbent === null ? stack : pushAssetDigest(stack, incumbent),
+        swapped: true,
+    };
+}
+/** Roll back to the previous shipped asset by SHA-256 (O(1) via the LIFO
+ *  stack): restores the most recent prior digest in the manifest and pops that
+ *  entry off the stack. Returns null when no prior digest exists or the prior
+ *  digest is no longer in the append-only manifest (defensive: append-only
+ *  means it should always be findable). Never leaves a partial state — the
+ *  committed pointer flip and the stack pop happen together or not at all. */
+export function assetRollback(manifest, stack) {
+    const { prior, rest } = popAssetDigest(stack);
+    if (prior === null)
+        return null;
+    const restored = rollbackTo(manifest, prior);
+    if (!restored)
+        return null;
+    return { manifest: restored, stack: rest, swapped: true };
+}
+// ---------------------------------------------------------------------------
 // Pure decision rules.
 // ---------------------------------------------------------------------------
 /** Evaluate the promotion gate: promote only when all five heads pass AND the

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

@@ -264,5 +264,17 @@ export const VECTOR_CORTEX_SETTINGS: SettingGroup = {
 			"ENC-0b real ONNX trunk fetch + gated inference: replaces the LCG placeholder with the real bge-small int8 model through an ONNX InferenceSession (onnxruntime-web WASM). OFF = LCG placeholder serves byte-identical predecessor output, no ONNX session built.",
 			true,
 		),
+		boolDirect(
+			"MEGACOMPACT_ENC_0C",
+			"ENC-0c Five-Head Supervision Transfer",
+			"ENC-0c five-head supervision transfer on the frozen bge-small trunk: when a developer-trained head candidate is staged under ~/.pi/mega-compact-encoder/candidates/, the five heads serve the trained weights. OFF = no candidate is loaded, the heads serve byte-identical ENC-0b survivor defaults.",
+			true,
+		),
+		boolDirect(
+			"MEGACOMPACT_ENC_0D",
+			"ENC-0d Real-Asset Promotion Gate",
+			"ENC-0d promotion gate over real trained assets: accepts a {color} real candidate manifest (the ENC-0c trained head weights + the ENC-0b trunk), digest-verifies every staged byte, and atomically swaps the shipped manifest to a green candidate with rollback-to-previous on qualification failure. OFF = accepts no candidate, swaps nothing, emits nothing, shipped manifest stays at the ENC-0c survivor.",
+			true,
+		),
 	],
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.44",
+  "version": "0.20.46",
   "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-enc0c.ts

@@ -0,0 +1,37 @@
+/**
+ * config/vector-cortex-enc0c.ts — ENC-0c five-head supervision transfer flag.
+ *
+ * Extracted from vector-cortex.ts so that file stays under the 300-line soft
+ * limit (soft-as-hard gate), exactly as vector-cortex-enc0a.ts / enc0b.ts and
+ * the VC8C/VC9A-D/ML5A-E/DEDUP_ATTR siblings were. vector-cortex.ts re-exports
+ * the flag below and root src/config.ts re-exports it, so no consumer import
+ * path changes.
+ *
+ * ENC-0c trains the five real heads onto the frozen ENC-0b bge-small trunk via
+ * supervision transfer, and stages a qualified candidate under
+ * ~/.pi/mega-compact-encoder/candidates/ (only when the developer trains it —
+ * the extension never stages one by itself). When the flag is ON and a
+ * qualified candidate exists, `loadHeadCandidate` (encoder/heads.ts seam) serves
+ * the trained head weights; when the flag is OFF (MEGACOMPACT_ENC_0C=0) or no
+ * candidate is staged, the heads keep serving the ENC-0b survivor exactly —
+ * byte-identical, no weight change. The flag gates ONLY the candidate-load seam;
+ * the survivor path is untouched.
+ *
+ * The split is purely mechanical: ENC_0C_ENABLED follows ENC_0B_ENABLED in name,
+ * semantics, and default, 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";
+
+/**
+ * ENC-0c — five-head supervision transfer on the frozen bge-small trunk.
+ * Default ON. `MEGACOMPACT_ENC_0C=0` disables and is byte-identical to the
+ * predecessor (ENC-0b): no head candidate is loaded and the heads keep serving
+ * the ENC-0b survivor defaults exactly as before. This flag MUST also be a
+ * dashboard SETTINGS toggle (visible in config UI, never in EXCLUDED_SETTINGS),
+ * mirroring ENC_0A and ENC_0B.
+ */
+export const ENC_0C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_ENC_0C");

package/src/config/vector-cortex-enc0d.ts

@@ -0,0 +1,41 @@
+/**
+ * config/vector-cortex-enc0d.ts — ENC-0d promotion gate over real trained assets.
+ *
+ * Extracted from vector-cortex.ts so that file stays under the 300-line soft
+ * limit (soft-as-hard gate), exactly as vector-cortex-enc0a.ts / enc0b.ts /
+ * enc0c.ts and the VC8C/VC9A-D/ML5A-E/DEDUP_ATTR siblings were. vector-cortex.ts
+ * re-exports the flag below and root src/config.ts re-exports it, so no
+ * consumer import path changes.
+ *
+ * ENC-0d turns the ML5-E promotion gate into the real-asset promotion path:
+ * it accepts a `{color}` real candidate manifest (the ENC-0c trained head
+ * weights + the ENC-0b trunk, staged under
+ * ~/.pi/mega-compact-encoder/candidates/), digest-verifies every staged byte
+ * before any swap, and performs an atomic asset swap with rollback-to-previous
+ * on qualification failure. The extension itself never stages candidate assets —
+ * only the operator trains them. When the flag is ON and a digest-verified
+ * green candidate exists, an atomic swap is performed and the runtime flips into
+ * qualified mode A; a red qualification (or any verification failure) keeps the
+ * prior asset live and emits a demotion.
+ *
+ * `MEGACOMPACT_ENC_0D=0` accepts no candidate, swaps nothing, emits nothing, and
+ * the shipped manifest stays at the ENC-0c survivor — byte-identical predecessor.
+ *
+ * The split is purely mechanical: ENC_0D_ENABLED follows ENC_0C_ENABLED in name,
+ * semantics, and default, 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";
+
+/**
+ * ENC-0d — atomic real-asset promotion over trained candidates. Default ON.
+ * `MEGACOMPACT_ENC_0D=0` disables and is byte-identical to the predecessor
+ * (ENC-0c): no candidate is accepted, no swap is performed, no promote/
+ * demote/rollback events are emitted, and the shipped manifest stays at the
+ * ENC-0c survivor. This flag MUST also be a dashboard SETTINGS toggle (visible
+ * in config UI, never in EXCLUDED_SETTINGS), mirroring ENC_0A/ENC_0B/ENC_0C.
+ */
+export const ENC_0D_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_ENC_0D");

package/src/config/vector-cortex.ts

@@ -7,7 +7,6 @@
  *
  * Breaker/triad constants (TRIAD_RESILIENCE.md) live here; pi-agnostic, dep-free.
  */
-
 import { sprintFlag } from "./vector-cortex-flag.js";
 
 // VC0/VC1/VC2 foundation-phase flags in vector-cortex-early.ts; re-exported
@@ -281,7 +280,8 @@ export { ML5E_ENABLED } from "./vector-cortex-ml5e.js";
 export { DEDUP_ATTR_ENABLED } from "./vector-cortex-dedup-attr.js";
 export { ENC_0A_ENABLED } from "./vector-cortex-enc0a.js";
 export { ENC_0B_ENABLED } from "./vector-cortex-enc0b.js";
-
+export { ENC_0C_ENABLED } from "./vector-cortex-enc0c.js";
+export { ENC_0D_ENABLED } from "./vector-cortex-enc0d.js";
 // Breaker constants (TRIAD_RESILIENCE.md §breaker) extracted to vector-cortex-breakers.ts.
 export {
   BREAKER_WINDOW_MS,

package/src/config.ts

@@ -191,6 +191,8 @@ export {
   DEDUP_ATTR_ENABLED,
   ENC_0A_ENABLED,
   ENC_0B_ENABLED,
+  ENC_0C_ENABLED,
+  ENC_0D_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

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

@@ -0,0 +1,148 @@
+/**
+ * encoder/heads-candidate.ts — ENC-0c head-candidate load seam (delegate impl).
+ *
+ * Loads/validates a `head-candidate-v1` five-head candidate staged under
+ * `~/.pi/mega-compact-encoder/candidates/<version>/` after training on the
+ * frozen ENC-0b bge-small trunk. Flag-off / absent / malformed / wrong dims /
+ * non-finite / digest / trunk mismatch each return null or {ok:false} — a bad
+ * candidate is NEVER force-loaded; the runtime keeps the ENC-0b survivor
+ * byte-identical. No `any` (PREVENT-011), local-only, structured logging.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { ENC_0C_ENABLED } from "../../config/vector-cortex.js";
+import { ENCODER_HEAD_DIMS, ENCODER_HEAD_ORDER } from "./types.js";
+import type { EncoderHeadName, ModelManifestV1 } from "./types.js";
+
+export const HEAD_CANDIDATE_SCHEMA = "head-candidate-v1" as const;
+const MANIFEST_FILE = "manifest.json";
+
+export interface HeadCandidateHeadDigest {
+  readonly name: EncoderHeadName;
+  readonly dim: number;
+  readonly sha256: string;
+  readonly bytes: number;
+}
+
+/** On-disk candidate contract; `trunkDigest` pins the frozen trunk. */
+export interface HeadCandidateManifest {
+  readonly schema: typeof HEAD_CANDIDATE_SCHEMA;
+  readonly version: string;
+  readonly trunkDigest: string;
+  readonly heads: readonly HeadCandidateHeadDigest[];
+  readonly totalBytes: number;
+}
+
+/** Loaded candidate: parsed Float32Array weights per head. */
+export interface HeadCandidate {
+  readonly schema: typeof HEAD_CANDIDATE_SCHEMA;
+  readonly version: string;
+  readonly trunkDigest: string;
+  readonly dims: Readonly<Record<EncoderHeadName, number>>;
+  readonly weights: Readonly<Record<EncoderHeadName, Float32Array>>;
+  readonly digests: Readonly<Record<EncoderHeadName, string>>;
+}
+
+export type HeadCandidateValidation = { readonly ok: true } | { readonly ok: false; readonly code: string };
+
+export const HEAD_CANDIDATE_FAIL = {
+  INVALID: "ENC0C_CANDIDATE_INVALID",
+  TRUNK_MISMATCH: "ENC0C_TRUNK_MISMATCH",
+  DIM_MISMATCH: "ENC0C_DIM_MISMATCH",
+  NON_FINITE: "ENC0C_NON_FINITE",
+  DIGEST_MISMATCH: "ENC0C_DIGEST_MISMATCH",
+} as const;
+
+function sha256(buf: Uint8Array): string { return createHash("sha256").update(buf).digest("hex"); }
+function finiteDim(values: Float32Array, dim: number): boolean {
+  if (values.length !== dim) return false;
+  for (const v of values) if (!Number.isFinite(v)) return false;
+  return true;
+}
+
+/** Parse the candidate manifest object, or null if invalid. */
+type ParsedManifest = { version: string; trunkDigest: string; heads: HeadCandidateHeadDigest[] };
+function parseManifest(m: Record<string, unknown> | null): ParsedManifest | null {
+  if (!m || m["schema"] !== HEAD_CANDIDATE_SCHEMA) return null;
+  const version = typeof m["version"] === "string" ? m["version"] : "";
+  const trunkDigest = typeof m["trunkDigest"] === "string" ? m["trunkDigest"] : "";
+  if (!version || !trunkDigest || !Array.isArray(m["heads"])) return null;
+  const heads: HeadCandidateHeadDigest[] = [];
+  for (const item of m["heads"] as unknown[]) {
+    const rec = item as Record<string, unknown> | null;
+    if (!rec || typeof rec !== "object") return null;
+    const name = rec["name"];
+    if (typeof name !== "string" || !ENCODER_HEAD_ORDER.includes(name as EncoderHeadName)) return null;
+    heads.push({
+      name: name as EncoderHeadName,
+      dim: Number(rec["dim"] ?? 0),
+      sha256: typeof rec["sha256"] === "string" ? rec["sha256"] : "",
+      bytes: Number(rec["bytes"] ?? 0),
+    });
+  }
+  return { version, trunkDigest, heads };
+}
+
+/** All 5 dims match, weights finite, digests hold. */
+export function validateHeadCandidate(candidate: HeadCandidate): HeadCandidateValidation {
+  for (const h of ENCODER_HEAD_ORDER) {
+    const dim = candidate.dims[h];
+    if (dim !== ENCODER_HEAD_DIMS[h]) return { ok: false, code: HEAD_CANDIDATE_FAIL.DIM_MISMATCH };
+    const w = candidate.weights[h];
+    if (!w || !finiteDim(w, dim)) return { ok: false, code: HEAD_CANDIDATE_FAIL.NON_FINITE };
+    const buf = new Uint8Array(w.buffer, w.byteOffset, w.byteLength);
+    if (sha256(buf) !== candidate.digests[h]) return { ok: false, code: HEAD_CANDIDATE_FAIL.DIGEST_MISMATCH };
+  }
+  return { ok: true };
+}
+
+/** Load a candidate against the frozen trunk; null on any violation, never throws. */
+export function loadHeadCandidate(candidateDir: string, manifest: ModelManifestV1): HeadCandidate | null {
+  if (!ENC_0C_ENABLED()) return null;
+  let raw: string;
+  try {
+    raw = readFileSync(join(candidateDir, MANIFEST_FILE), "utf8");
+  } catch {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const m = parseManifest(parsed as Record<string, unknown> | null);
+  if (!m || m.trunkDigest !== manifest.onnx.sha256) return null;
+  const weights: Partial<Record<EncoderHeadName, Float32Array>> = {};
+  const digests: Partial<Record<EncoderHeadName, string>> = {};
+  const dims: Partial<Record<EncoderHeadName, number>> = {};
+  for (const rec of m.heads) {
+    const want = rec.dim * 4;
+    if (!Number.isInteger(want) || want <= 0 || rec.dim !== ENCODER_HEAD_DIMS[rec.name]) return null;
+    let bytes: Buffer;
+    try {
+      bytes = readFileSync(join(candidateDir, `${rec.name}.bin`));
+    } catch {
+      return null;
+    }
+    const f = new Float32Array(bytes.buffer, bytes.byteOffset, rec.dim);
+    const d = sha256(bytes);
+    if (bytes.length !== want || d !== rec.sha256) return null;
+    weights[rec.name] = f.slice();
+    digests[rec.name] = d;
+    dims[rec.name] = rec.dim;
+  }
+  for (const h of ENCODER_HEAD_ORDER) {
+    if (weights[h] === undefined || digests[h] === undefined || dims[h] === undefined) return null;
+  }
+  const candidate: HeadCandidate = {
+    schema: HEAD_CANDIDATE_SCHEMA, version: m.version, trunkDigest: m.trunkDigest,
+    dims: dims as Record<EncoderHeadName, number>,
+    weights: weights as Record<EncoderHeadName, Float32Array>,
+    digests: digests as Record<EncoderHeadName, string>,
+  };
+  return validateHeadCandidate(candidate).ok ? candidate : null;
+}

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

@@ -246,3 +246,17 @@ export function projectHeadFromTrunk(
 }
 
 export { ENCODER_HEAD_ORDER, ENCODER_HEAD_DIMS, ENCODER_HEAD_LOSS_SUM, ENCODER_SEED, NOOP_VC2B_REPORTER };
+
+// ENC-0c five-head candidate seam (delegate-shell): the load/validate impl
+// lives in heads-candidate.ts; these re-exports keep the public import path
+// stable at heads.ts without growing this survivor file over the soft limit.
+export {
+  HEAD_CANDIDATE_SCHEMA,
+  HEAD_CANDIDATE_FAIL,
+  loadHeadCandidate,
+  validateHeadCandidate,
+  type HeadCandidate,
+  type HeadCandidateManifest,
+  type HeadCandidateHeadDigest,
+  type HeadCandidateValidation,
+} from "./heads-candidate.js";

package/src/vector-cortex/encoder/promotion-emit.ts

@@ -0,0 +1,63 @@
+/**
+ * vector-cortex/encoder/promotion-emit.ts — ENC-0d promotion event writers.
+ *
+ * Writes the three real-asset promotion events to the monitoring `events.log`
+ * as structured append-only JSON lines via the existing `logBenchEvent` seam
+ * (`src/monitoring.ts`):
+ *
+ *   - `vector_cortex_asset_promoted`      (green digest-verified swap)
+ *   - `vector_cortex_asset_demoted`       (red qualification / digest failure)
+ *   - `vector_cortex_asset_rollback_back` (restore of a prior stack digest)
+ *
+ * Non-fatal and log-and-swallow: a write failure never breaks the agent loop
+ * (best-effort store/write contract). Each line is `{ts, event, ...fields}`
+ * shaped so the dashboard live-stream tail and evidence tooling parse it
+ * identically to every other monitoring event. Events carry digests, colors
+ * and verdicts ONLY — never message content (EVAL-REDACT-002).
+ *
+ * The path defaults to the standard state-dir events.log (mirrors
+ * defaultEventsPath). Zero network, no `any` (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { defaultEventsPath, logBenchEvent } from "../../monitoring.js";
+import { getStateDir } from "../../store.js";
+
+/** Default events.log beside the state dir (mirrors bench.ts). */
+export function promotionEventsPath(stateDir: string = getStateDir()): string {
+  return defaultEventsPath(stateDir);
+}
+
+/** The promotion event kinds this emitter can write. */
+export type PromotionEventKind =
+  | "promoted"
+  | "demoted"
+  | "rollback_back";
+
+const EVENT_NAME: Record<PromotionEventKind, string> = {
+  promoted: "vector_cortex_asset_promoted",
+  demoted: "vector_cortex_asset_demoted",
+  rollback_back: "vector_cortex_asset_rollback_back",
+};
+
+/** Fields carried by a promotion event: digests, colors and verdicts only.
+ *  Never any payload or message content (EVAL-REDACT-002). */
+export interface PromotionEventFields {
+  readonly color: "green" | "red";
+  readonly assetDigest: string | null;
+  readonly priorAssetDigest: string | null;
+  readonly verdict: string;
+}
+
+/**
+ * Append one promotion event to events.log (best-effort, non-fatal). The line
+ * is `{ts, event, ...fields}` shaped, written append-only via the monitoring
+ * logBenchEvent seam. On any write failure the event is swallowed — the agent
+ * loop is never broken.
+ */
+export function appendPromotionEvent(
+  path: string,
+  kind: PromotionEventKind,
+  fields: PromotionEventFields,
+): void {
+  logBenchEvent(path, EVENT_NAME[kind], { ...fields });
+}

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

@@ -14,6 +14,15 @@
  * an atomic digest swap (flip the committed pointer to the prior entry's
  * digest in one step) — no partial state is possible because the swap is a
  * single value assignment.
+ *
+ * ENC-0d extends the ledger to the real-asset promotion path: `PromotionV1`
+ * carries `{color, assetDigestStack}` — a promotion color from gate
+ * qualification ("green" atomically swaps to the trained asset, "red" keeps
+ * the prior asset live) and a LIFO of prior shipped digest for O(1)-by-sha256
+ * rollback. The on-disk manifest byte-swap itself (write-temp-then-rename,
+ * never in-place partial) is the promotion gate script's job; these helpers
+ * stay pure and return the restorable digest + the updated manifest/stack so
+ * the script can perform the swap in one atomic step.
  */
 
 // ---------------------------------------------------------------------------
@@ -54,6 +63,13 @@ export interface PromotionV1 {
   readonly verdict: "promoted" | "demoted" | "noop";
   /** Present only when verdict is "demoted": the demotion event name. */
   readonly demotedEvent: "demoted_new_asset" | null;
+  /** ENC-0d promotion color from gate qualification. "green" atomically swaps
+   *  the shipped manifest to the trained asset; "red" keeps the prior asset
+   *  live and emits a demotion. */
+  readonly color: "green" | "red";
+  /** ENC-0d LIFO of prior shipped asset digests for O(1)-by-sha256 rollback.
+   *  The most recent prior digest (top of the stack) is the rollback target. */
+  readonly assetDigestStack: readonly string[];
 }
 
 // ---------------------------------------------------------------------------
@@ -104,6 +120,85 @@ export function rollbackTo(
   };
 }
 
+// ---------------------------------------------------------------------------
+// ENC-0d LIFO rollback stack + atomic swap. Pure pointer arithmetic; the
+// on-disk write-temp-then-rename of the swapped manifest bytes is the gate
+// script's job so no partial state can ever be observed (PREVENT-PI-004).
+// ---------------------------------------------------------------------------
+
+/** Push a freshly-shipped digest onto the LIFO rollback stack (top = latest
+ *  prior shipped digest). Non-mutating: returns a new array. */
+export function pushAssetDigest(
+  stack: readonly string[],
+  digest: string,
+): readonly string[] {
+  return [...stack, digest];
+}
+
+/** Pop the top (most recent prior) digest off the LIFO rollback stack without
+ *  mutating it. Returns the prior digest (null when the stack is empty) plus
+ *  the remaining stack for the caller to commit (atomic card-swap fallback:
+ *  a green swap pushes the incumbent digest; a rollback pops it). */
+export function popAssetDigest(
+  stack: readonly string[],
+): { prior: string | null; rest: readonly string[] } {
+  if (stack.length === 0) return { prior: null, rest: stack };
+  const rest = stack.slice(0, -1);
+  return { prior: stack[stack.length - 1]!, rest };
+}
+
+/** Outcome of an atomic promotion swap (pure): the (possibly restored)
+ *  manifest, the updated rollback stack, and whether a digest swap occurred. */
+export interface AtomicSwapOutcome {
+  readonly manifest: AssetManifest;
+  readonly stack: readonly string[];
+  /** True when the committed pointer changed (green swap or rollback). */
+  readonly swapped: boolean;
+}
+
+/** Atomically swap the committed manifest to a real trained asset's digest.
+ *  Green: append the new entry (append-only — the incumbent stays in the
+ *  ledger, never overwritten), commit to it, and record the INCUMBENT digest
+ *  onto the LIFO stack for O(1) rollback (rollback restores the incumbent, so
+ *  the stack must hold the pre-swap committed digest — pushing the swapped-in
+ *  digest would point rollback back at the very asset being rolled back). Red
+ *  (or no candidate digest): return the manifest and stack untouched — no
+ *  swap, prior asset stays live. */
+export function atomicSwap(
+  manifest: AssetManifest,
+  entry: AssetManifestEntry,
+  color: "green" | "red",
+  stack: readonly string[],
+): AtomicSwapOutcome {
+  if (color !== "green" || !entry.assetDigest) {
+    return { manifest, stack, swapped: false };
+  }
+  const incumbent = manifest.committed;
+  const next = appendAsset(manifest, entry);
+  return {
+    manifest: next,
+    stack: incumbent === null ? stack : pushAssetDigest(stack, incumbent),
+    swapped: true,
+  };
+}
+
+/** Roll back to the previous shipped asset by SHA-256 (O(1) via the LIFO
+ *  stack): restores the most recent prior digest in the manifest and pops that
+ *  entry off the stack. Returns null when no prior digest exists or the prior
+ *  digest is no longer in the append-only manifest (defensive: append-only
+ *  means it should always be findable). Never leaves a partial state — the
+ *  committed pointer flip and the stack pop happen together or not at all. */
+export function assetRollback(
+  manifest: AssetManifest,
+  stack: readonly string[],
+): AtomicSwapOutcome | null {
+  const { prior, rest } = popAssetDigest(stack);
+  if (prior === null) return null;
+  const restored = rollbackTo(manifest, prior);
+  if (!restored) return null;
+  return { manifest: restored, stack: rest, swapped: true };
+}
+
 // ---------------------------------------------------------------------------
 // Pure decision rules.
 // ---------------------------------------------------------------------------