pi-mega-compact 0.20.69 → 0.20.71

package/dist/extensions/dashboard-server/setup-cortex-actions-native-ort.js

@@ -0,0 +1,107 @@
+/**
+ * dashboard-server/setup-cortex-actions-native-ort.ts — ENC-2c native onnxruntime
+ * lazy-download INSTALL action driver (actor surface for install-native-ort).
+ *
+ * Sibling of setup-cortex-actions.ts (which stays under the 300-line source soft
+ * cap). Implements the mechanics behind the VC9B `install-native-ort` action:
+ *
+ *   1. locate the committed scripts/encoder/install-native-ort.mjs by walking up
+ *      to the repo root (mirroring setup-cortex-actions.ts vc2ScriptDir);
+ *   2. spawn `node <script>` locally with a 60s timeout (npm-delegated,
+ *      sha256-verified install — the registry URL + sha256 live ONLY in
+ *      src/vector-cortex/encoder/native-install-artifacts.ts, never here);
+ *   3. capture output to <stateDir>/logs/vc9b/install-native-ort-<ts>.log;
+ *   4. REGARDLESS of the install exit code, re-qualify the binding via the ENC-2b
+ *      retest path (`runNativeRetest`) and surface the fresh result +
+ *      effective backend.
+ *
+ * PREVENT-PI-004 banner: this is an OPT-IN, confirm-gated, npm-delegated local
+ * subprocess of a committed repo script. It performs no network I/O in this
+ * module and carries NO URL literals (the codebase-wide no-URL-literal scan
+ * covers src/ + extensions/).
+ *
+ * Guardrails: PREVENT-011 (no `any`); the subprocess is a committed local script,
+ * never fetched (PREVENT-PI-004, guardrails-allow below).
+ */
+import { spawnSync } from "node:child_process"; // guardrails-allow PREVENT-PI-004: opt-in, confirm-gated, npm-delegated install subprocess (local spawn of committed repo script; no URL literals)
+import { mkdirSync, writeFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runNativeRetest } from "../../src/vector-cortex/encoder/native-qualify-retest.js";
+/** Locate scripts/encoder/install-native-ort.mjs by walking up to the repo root. */
+export function installScriptPath() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    const rel = join("scripts", "encoder", "install-native-ort.mjs");
+    for (let i = 0; i < 8; i++) {
+        const candidate = join(dir, rel);
+        // guardrails-allow PREVENT-PI-004: local repo filesystem read (loopback)
+        if (existsSync(candidate))
+            return candidate;
+        const next = dirname(dir);
+        if (next === dir)
+            break;
+        dir = next;
+    }
+    return null;
+}
+/** Ensure the vc9b log dir exists (mirrors setup-cortex-actions.ts). */
+function ensureLogDir(stateDir) {
+    const dir = join(stateDir, "logs", "vc9b");
+    // guardrails-allow PREVENT-PI-004: local state-dir filesystem write (loopback)
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+function writeLog(logPath, body) {
+    // guardrails-allow PREVENT-PI-004: local state-dir filesystem write (loopback)
+    writeFileSync(logPath, body, "utf8");
+}
+/**
+ * Run the ENC-2c lazy-download native onnxruntime INSTALL action. Locates and
+ * spawns the committed install script (npm-delegated, sha256-verified), logs the
+ * captured output, then ALWAYS runs the ENC-2b retest to re-qualify the binding
+ * (regardless of install exit code) and surfaces the fresh result.
+ *
+ * Never throws: a missing script or non-zero exit is surfaced as ok=false on the
+ * result; the retest runs even on install failure so the operator sees the
+ * post-install qualification state. Returns a combined SetupCortexActionResult
+ * with the ENC-2c additive fields (present only for pendant actions).
+ */
+// guardrails-allow PREVENT-PI-004: opt-in, confirm-gated, npm-delegated install action (subprocess of committed repo script; no URL literals)
+export async function runInstallNativeOrt(stateDir) {
+    const ts = Date.now();
+    const logName = `install-native-ort-${ts}.log`;
+    const logPath = join(ensureLogDir(stateDir), logName);
+    const scriptPath = installScriptPath();
+    if (scriptPath === null) {
+        writeLog(logPath, "install-native-ort.mjs not found in this checkout\n");
+        return {
+            action: "install-native-ort",
+            ok: false,
+            exitCode: null,
+            logPath,
+            logName,
+            spawned: true,
+        };
+    }
+    // guardrails-allow PREVENT-PI-004: opt-in, confirm-gated, npm-delegated
+    // install subprocess (local spawn of committed repo script; no URL literals)
+    const result = spawnSync(process.execPath, [scriptPath], {
+        encoding: "utf8",
+        timeout: 60_000,
+    });
+    const out = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+    writeLog(logPath, out || "(no output)\n");
+    // Re-qualify AFTER install regardless of exit code (the retest is the source of
+    // truth for whether the binding is actually usable).
+    const retest = await runNativeRetest(stateDir);
+    return {
+        action: "install-native-ort",
+        ok: result.status === 0,
+        exitCode: result.status === null ? null : result.status,
+        logPath,
+        logName,
+        spawned: true,
+        nativeOrtRetestResult: retest,
+        nativeOrtBackendEffective: retest !== null && retest.verdict === "qualified" ? "native" : "wasm",
+    };
+}

package/dist/extensions/dashboard-server/setup-cortex-actions.js

@@ -6,7 +6,9 @@
  * vc2-model-prep scripts (fetch-model.sh, bench-onnx.mjs), capturing their
  * output to <stateDir>/logs/vc9b/<action>-<ts>.log, re-running the committed
  * encoder asset verification seam for verify-asset (NO subprocess), and serving
- * a bounded + redacted log tail.
+ * a bounded + redacted log tail. ENC-2c adds the `install-native-ort` action,
+ * delegated to the sibling setup-cortex-actions-native-ort.ts (the confirm-gated,
+ * npm-delegated local install + ENC-2b re-qualification).
  *
  * This module is the ONLY place that touches the filesystem for VC9B actions.
  * The route file (routes-setup-cortex-actions.ts) carries NO path/script/blocker
@@ -23,6 +25,7 @@ import { fileURLToPath } from "node:url";
 import { readEncoderManifest, verifyEncoderAsset, detectPlatform, } from "../../src/vector-cortex/encoder/asset.js";
 import { ENC_0G_ENABLED, ENC_0F_ENABLED } from "../../src/config.js";
 import { readQualificationRecord, encoderStateDir, } from "./qualification-record.js";
+import { runInstallNativeOrt } from "./setup-cortex-actions-native-ort.js";
 /** Cap applied to every log tail served by the action-log route. */
 export const ACTION_LOG_TAIL_BYTES = 8192;
 /** Locate the commit's vc2-model-prep directory by walking up to the repo root. */
@@ -222,9 +225,13 @@ function writeLog(logPath, body) {
  * result on success; throws nothing — every failure is surfaced as a result with
  * ok=false so the route can shape the HTTP response. Never touches the network;
  * the subprocesses it may spawn are the committed local vc2-model-prep scripts.
+ * Async (ENC-2c): install-native-ort runs the npm-delegated local install then
+ * re-qualifies via the ENC-2b retest path.
  */
-export function runSetupCortexAction(action, stateDir) {
+export async function runSetupCortexAction(action, stateDir) {
     if (action === "verify-asset")
         return runVerifyAsset(stateDir);
+    if (action === "install-native-ort")
+        return runInstallNativeOrt(stateDir);
     return runSpawnedAction(action, stateDir);
 }

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

@@ -0,0 +1,38 @@
+/**
+ * config/vector-cortex-enc2c.ts — ENC-2c native onnxruntime lazy-download
+ * install-action flag (dashboard-triggered install).
+ *
+ * Sibling of vector-cortex-enc2a.ts / vector-cortex-enc2b.ts so vector-cortex.ts
+ * stays under the 300-line soft limit (soft-as-hard gate). vector-cortex.ts
+ * re-exports the flag below and root src/config.ts re-exports it, so no consumer
+ * import path changes.
+ *
+ * ENC-2c turns ENC-2a's operator run-script assist into a dashboard action: the
+ * Setup Cortex sub-tab gains an "Install Native ORT" button that, when confirmed
+ * by the operator, runs the committed `scripts/encoder/install-native-ort.mjs`
+ * subprocess locally (npm-delegated, sha256-verified) and then re-qualifies the
+ * binding via the ENC-2b retest path. This is a PREVENT-PI-004 opt-in exemption:
+ * it is confirm-gated (never automatic), delegated to a local subprocess of a
+ * committed repo script, and carries NO URL literals in src/ or extensions/
+ * (the registry URL + sha256 live only in the artifacts-module constants).
+ *
+ * `MEGACOMPACT_ENC_2C=0` disables: no install action branch, no UI button, no
+ * install-related result fields — byte-identical to the ENC-2b predecessor. The
+ * flag MUST also be a dashboard SETTINGS toggle (visible in config UI, never in
+ * EXCLUDED_SETTINGS — see `feedback_dashboard-flags-toggleable` memory).
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ *
+ * guardrails-allow PREVENT-PI-004: opt-in confirm-gated install action;
+ * delegates to local npm install subprocess, no URL literals (registry URL +
+ * sha256 live only in native-install-artifacts.ts)
+ */
+import { sprintFlag } from "./vector-cortex-flag.js";
+/**
+ * ENC-2c — lazy-download native onnxruntime install action (dashboard-triggered,
+ * npm-delegated, confirm-gated). Default ON. `MEGACOMPACT_ENC_2C=0` disables and
+ * is byte-identical to the ENC-2b predecessor: no install action POST branch, no
+ * UI button, no install result fields. This flag MUST also be a dashboard SETTINGS
+ * toggle (visible in config UI, never in EXCLUDED_SETTINGS).
+ */
+export const ENC_2C_ENABLED = () => sprintFlag("MEGACOMPACT_ENC_2C");

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

@@ -54,5 +54,7 @@ export { ENC_2BUDGET_ENABLED, ENC_2BUDGET_NATIVE_ORT_BUDGET_ENV, ENC_2BUDGET_MAX
 export { ENC_2A_ENABLED } from "./vector-cortex-enc2a.js";
 // ENC-2b native onnxruntime qualification-retest flag extracted to vector-cortex-enc2b.ts.
 export { ENC_2B_ENABLED } from "./vector-cortex-enc2b.js";
+// ENC-2c native onnxruntime lazy-download install-action flag extracted to vector-cortex-enc2c.ts.
+export { ENC_2C_ENABLED } from "./vector-cortex-enc2c.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, ENC_0C_ENABLED, ENC_0D_ENABLED, ENC_0E_ENABLED, ENC_0F_ENABLED, ENC_0G_ENABLED, ENC_1A_ENABLED, ENC_1B_ENABLED, ENC_2BUDGET_ENABLED, ENC_2BUDGET_NATIVE_ORT_BUDGET_ENV, ENC_2BUDGET_MAX_MIB, ENC_2BUDGET_DEFAULT_MIB, ENC_2A_ENABLED, ENC_2B_ENABLED, COSINE_FP_BENCH_ENABLED, COSINE_FP_REAL_ENABLED, REPO_CORPUS_ENABLED, DASH_0A_ENABLED, DASH_0B_ENABLED, DASH_0C_ENABLED, DASH_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";
+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, ENC_0E_ENABLED, ENC_0F_ENABLED, ENC_0G_ENABLED, ENC_1A_ENABLED, ENC_1B_ENABLED, ENC_2BUDGET_ENABLED, ENC_2BUDGET_NATIVE_ORT_BUDGET_ENV, ENC_2BUDGET_MAX_MIB, ENC_2BUDGET_DEFAULT_MIB, ENC_2A_ENABLED, ENC_2B_ENABLED, ENC_2C_ENABLED, COSINE_FP_BENCH_ENABLED, COSINE_FP_REAL_ENABLED, REPO_CORPUS_ENABLED, DASH_0A_ENABLED, DASH_0B_ENABLED, DASH_0C_ENABLED, DASH_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/cache/store.js

@@ -70,6 +70,11 @@ export class CrystalStore {
     writes = 0;
     duplicateWrites = 0;
     collisions = 0;
+    /** Restart-survival crystal count/bytes (LIVEWIRE rehydrate). The `committed`
+     *  map is empty in a fresh process; these offsets carry the persisted totals
+     *  so the dashboard does not reset to zero on restart. */
+    rehydratedCrystalCount = 0;
+    rehydratedTotalBytes = 0;
     /** Freeze a crystal object for a key/bytes pair (digest computed here). */
     static freeze(keyDigest, bytes, key) {
         const copy = new Uint8Array(bytes);
@@ -178,12 +183,12 @@ export class CrystalStore {
     }
     /** Reader-only aggregate for the dashboard seam — counts and bytes only. */
     stats() {
-        let totalBytes = 0;
+        let totalBytes = this.rehydratedTotalBytes;
         for (const c of this.committed.values())
             totalBytes += c.byteCount;
         return {
             mode: this.mode(),
-            crystalCount: this.committed.size,
+            crystalCount: this.rehydratedCrystalCount + this.committed.size,
             totalBytes,
             hits: this.hits,
             misses: this.misses,
@@ -193,4 +198,22 @@ export class CrystalStore {
             collisions: this.collisions,
         };
     }
+    /**
+     * Restart survival: seed the CUMULATIVE counters from a previously-persisted
+     * aggregate (LIVEWIRE). The in-memory `committed` map is naturally empty in a
+     * fresh process — this only restores the running totals the dashboard reports,
+     * so a process restart does not reset the dashboard to zero. It deliberately
+     * does NOT reconstruct crystals: frozen bytes are never persisted to the
+     * reader aggregate, only the counts.
+     */
+    rehydrate(stats) {
+        this.rehydratedCrystalCount = stats.crystalCount;
+        this.rehydratedTotalBytes = stats.totalBytes;
+        this.hits = stats.hits;
+        this.misses = stats.misses;
+        this.hitBytes = stats.hitBytes;
+        this.writes = stats.writes;
+        this.duplicateWrites = stats.duplicateWrites;
+        this.collisions = stats.collisions;
+    }
 }

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

@@ -67,7 +67,14 @@ function isManifest(m) {
         typeof o.onnx.path === "string" &&
         typeof o.onnx.sha256 === "string" &&
         typeof o.tokenizer.path === "string" &&
-        typeof o.tokenizer.sha256 === "string");
+        typeof o.tokenizer.sha256 === "string" &&
+        // ML5-A (VC2B-2): optional headWeights must, when present, be a valid
+        // ManifestAssetFile (path basename + sha256 + bytes).
+        (o.headWeights === undefined ||
+            (!!o.headWeights &&
+                typeof o.headWeights.path === "string" &&
+                typeof o.headWeights.sha256 === "string" &&
+                typeof o.headWeights.bytes === "number")));
 }
 /**
  * Verify the asset manifest + digest + constraints BEFORE allocation.
@@ -107,6 +114,11 @@ export function verifyEncoderAsset(assetDir, manifest, platform = detectPlatform
     if (!isBasename(manifest.onnx.path) || !isBasename(manifest.tokenizer.path)) {
         return { ok: false, code: ENC_FAIL.MANIFEST_INVALID };
     }
+    // ML5-A (VC2B-2): a manifest-declared headWeights path must also be a bare
+    // basename (no traversal into arbitrary paths off the asset dir).
+    if (manifest.headWeights !== undefined && !isBasename(manifest.headWeights.path)) {
+        return { ok: false, code: ENC_FAIL.MANIFEST_INVALID };
+    }
     const onnxPath = join(assetDir, manifest.onnx.path);
     const onnxDigest = digestFile(onnxPath);
     if (onnxDigest === null)
@@ -119,6 +131,19 @@ export function verifyEncoderAsset(assetDir, manifest, platform = detectPlatform
         return { ok: false, code: ENC_FAIL.ASSET_UNREADABLE };
     if (tokDigest !== manifest.tokenizer.sha256)
         return { ok: false, code: ENC_FAIL.DIGEST_MISMATCH };
+    // ML5-A (VC2B-2): verify the manifest-pinned trained-heads sibling when the
+    // manifest declares it. Absent declaration -> headWeightsDigest: null and no
+    // failure (committed placeholder bundle ships no trained weights).
+    let headWeightsDigest = null;
+    if (manifest.headWeights !== undefined) {
+        const hwPath = join(assetDir, manifest.headWeights.path);
+        const hwDigest = digestFile(hwPath);
+        if (hwDigest === null)
+            return { ok: false, code: ENC_FAIL.ASSET_UNREADABLE };
+        if (hwDigest !== manifest.headWeights.sha256)
+            return { ok: false, code: ENC_FAIL.DIGEST_MISMATCH };
+        headWeightsDigest = hwDigest;
+    }
     let embeddedBytes = 0;
     try {
         embeddedBytes = statSync(onnxPath).size + statSync(tokPath).size;
@@ -126,7 +151,14 @@ export function verifyEncoderAsset(assetDir, manifest, platform = detectPlatform
     catch {
         return { ok: false, code: ENC_FAIL.ASSET_UNREADABLE };
     }
-    return { ok: true, embeddedBytes, maxTokens: manifest.maxTokens, onnxDigest, tokenizerDigest: tokDigest };
+    return {
+        ok: true,
+        embeddedBytes,
+        maxTokens: manifest.maxTokens,
+        onnxDigest,
+        tokenizerDigest: tokDigest,
+        headWeightsDigest,
+    };
 }
 /**
  * Read + shape-check a committed ModelManifestV1 from an asset directory.

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

@@ -25,11 +25,12 @@
  * Pi-agnostic, zero network (PREVENT-PI-004), no `any` (PREVENT-011).
  */
 import { createEncoderRuntime } from "./runtime.js";
-import { encodeVectorSet } from "./heads.js";
+import { encodeVectorSet, loadHeadProjections, projectHeadFromTrunk, } from "./heads.js";
 import { embedTrigram512, selectTrigramBFallback } from "./trigram.js";
 import { embedLexical, selectLexicalC } from "./lexical.js";
 import { createEncoderHeadsReporter } from "./emit-vc2b.js";
-import { ENC_FAIL, } from "./types.js";
+import { ML5A_ENABLED } from "../../config/vector-cortex.js";
+import { ENC_FAIL, ENCODER_HEAD_ORDER, } from "./types.js";
 /** Deterministic text derived from an int token sequence so the asset-free
  *  fallback producers operate on the same authority the learned path encoded. */
 function textFromTokens(tokens) {
@@ -92,9 +93,36 @@ export function encodeOrFallback(input, assetDir, options = {}) {
     if (!inferred.ok) {
         return fallbackFromLoad({ ok: false, mode: "B", code: inferred.code }, reporter, tokens);
     }
-    const vectorSet = encodeVectorSet(tokens, { reporter, seed: options.seed });
+    const vectorSet = produceVectorSet(inferred.semantic, tokens, options, reporter);
     return { ok: true, mode: "A", vectorSet, code: null };
 }
+/**
+ * Produce a mode-A `VectorSetV1` from the [1,384] trunk embedding (the
+ * `runtime.infer` result). VC2B-2 ML5-A: when real trained heads are loaded
+ * (`MEGACOMPACT_ML5_A` on + a `trainedHeadsPath` that loads), the multi-head
+ * output is projected through the real trained projection matrices via
+ * `projectHeadFromTrunk`. Otherwise (flag-off / absent / unloadable artifact)
+ * the deterministic LCG placeholder `encodeVectorSet` serves mode A —
+ * byte-identical to the VC2B predecessor. Non-fatal: an unloadable artifact
+ * degrades to the placeholder, never a throw.
+ */
+function produceVectorSet(trunkEmbedding, tokens, options, reporter) {
+    const table = ML5A_ENABLED() && options.trainedHeadsPath !== undefined
+        ? loadHeadProjections(options.trainedHeadsPath)
+        : null;
+    if (table !== null) {
+        const heads = ENCODER_HEAD_ORDER.map((h) => projectHeadFromTrunk(h, trunkEmbedding, table));
+        reporter.headsEmitted({
+            heads: heads.length,
+            dims: heads.map((h) => h.dim).join("/"),
+            normalized: true,
+            tokens: tokens.length,
+        });
+        return { schema: "vector-set-v1", inputTokens: [...tokens], heads, normalized: true };
+    }
+    // ML5-A placeholder fallback (byte-identical predecessor).
+    return encodeVectorSet(tokens, { reporter, seed: options.seed });
+}
 /**
  * Catch a (real or forced) A load failure (ok === false only) and select the
  * B/C fallback that emits `vector_cortex_encoder_fallback_selected` from the

package/dist/src/vector-cortex/livewire/livewire-live.js

@@ -0,0 +1,163 @@
+/**
+ * vector-cortex/livewire/livewire-live.ts — LIVEWIRE in-process live state.
+ *
+ * Holds the LIVE subsystem objects for ONE stateDir: the VC7A `CrystalStore`,
+ * the VC7C cache breaker, the per-miss-class tallies, the VC8B shadow metrics,
+ * and the VC7B economics computed bit. This is the object the RUNTIME accumulates
+ * into (`recordMiss`, `recordServeBlocked`, `recordShadowRun`, ...) and that the
+ * reader-only dashboard routes snapshot out of. Kept separate from the registry
+ * (which owns the per-stateDir `Map` + persistence) so neither file crosses the
+ * 300-line soft-as-hard gate.
+ *
+ * AGGREGATE-FIRST, COUNTS ONLY. `snapshotOf` projects the live objects down to
+ * the SECURITY_PRIVACY-safe `LivewireSnapshot` (counts + codes + triad mode) that
+ * gets persisted and rendered. No session id, digest, range, profile id, bytes,
+ * or prompt text can pass through ANY of these fields.
+ *
+ * PREVENT-PI-004: no network. PREVENT-011: no `any`. Non-fatal: every derive is
+ * a pure read.
+ */
+import { CrystalStore } from "../cache/store.js";
+import { createCacheBreaker } from "../cache/breaker.js";
+import { validateProfileEconomics } from "../provider/economics.js";
+import { BASE_PROVIDER_PROFILES } from "../provider/registry.js";
+/**
+ * Static VC7B economics profile tallies derived from the base provider registry.
+ * `profileCount` counts profiles that declare economics; `provenExclusions` /
+ * `unprovenExclusions` tally the exclusion sets validated against the fixture
+ * rule. This is PURE (no storage/clock/network) and identical regardless of the
+ * `MEGACOMPACT_VC7B` flag — only the emission/route seam is flag-gated.
+ */
+function baseEconomicsTallies() {
+    let profileCount = 0;
+    let provenExclusions = 0;
+    let unprovenExclusions = 0;
+    for (const bundle of BASE_PROVIDER_PROFILES) {
+        const econ = bundle.profile.economics;
+        if (econ === null)
+            continue;
+        profileCount += 1;
+        const codes = validateProfileEconomics(bundle.profile, econ);
+        const failed = new Set(codes);
+        for (const _ex of bundle.profile.excludedJsonPointers) {
+            if (failed.has("ECON_EXCLUSION_UNPROVEN")) {
+                unprovenExclusions += 1;
+            }
+            else {
+                provenExclusions += 1;
+            }
+        }
+    }
+    return { profileCount, provenExclusions, unprovenExclusions };
+}
+/** A zeroed per-class tally map. */
+function zeroTallies() {
+    return {
+        profile: 0,
+        range: 0,
+        dependency: 0,
+        request: 0,
+        generation: 0,
+        unknown: 0,
+    };
+}
+/** Build a fresh (empty) live state with real subsystem objects. */
+export function createLiveState() {
+    const econTallies = baseEconomicsTallies();
+    return {
+        crystalStore: new CrystalStore(),
+        breaker: createCacheBreaker(),
+        diagnostics: {
+            tallies: zeroTallies(),
+            serveBlocked: 0,
+            breakerState: "CLOSED_A",
+            lastFailure: null,
+        },
+        economics: {
+            computed: false,
+            profileCount: econTallies.profileCount,
+            provenExclusions: econTallies.provenExclusions,
+            unprovenExclusions: econTallies.unprovenExclusions,
+            lastFailure: null,
+        },
+        shadow: {
+            shadowDecisions: 0,
+            clampedDecisions: 0,
+            rejectedInputs: 0,
+            liveMutations: 0,
+            pressureVersion: 1,
+            lastFailure: null,
+        },
+    };
+}
+/** Project the live state down to the persisted, reader-only aggregate. */
+export function snapshotOf(state) {
+    const crystals = state.crystalStore.stats();
+    const diag = {
+        profileMisses: state.diagnostics.tallies.profile,
+        rangeMisses: state.diagnostics.tallies.range,
+        dependencyMisses: state.diagnostics.tallies.dependency,
+        requestMisses: state.diagnostics.tallies.request,
+        generationMisses: state.diagnostics.tallies.generation,
+        unknownMisses: state.diagnostics.tallies.unknown,
+        serveBlocked: state.diagnostics.serveBlocked,
+        breakerState: state.diagnostics.breakerState,
+        lastFailure: state.diagnostics.lastFailure,
+    };
+    const econ = {
+        profileCount: state.economics.profileCount,
+        provenExclusions: state.economics.provenExclusions,
+        unprovenExclusions: state.economics.unprovenExclusions,
+        computed: state.economics.computed,
+        lastFailure: state.economics.lastFailure,
+    };
+    const policy = {
+        shadowDecisions: state.shadow.shadowDecisions,
+        clampedDecisions: state.shadow.clampedDecisions,
+        rejectedInputs: state.shadow.rejectedInputs,
+        liveMutations: state.shadow.liveMutations,
+        pressureVersion: state.shadow.pressureVersion,
+        lastFailure: state.shadow.lastFailure,
+    };
+    return {
+        schema: "vector-cortex-livewire-v1",
+        crystals: {
+            mode: crystals.mode,
+            crystalCount: crystals.crystalCount,
+            totalBytes: crystals.totalBytes,
+            hits: crystals.hits,
+            misses: crystals.misses,
+            hitBytes: crystals.hitBytes,
+            writes: crystals.writes,
+            duplicateWrites: crystals.duplicateWrites,
+            collisions: crystals.collisions,
+        },
+        diagnostics: diag,
+        economics: econ,
+        policy,
+    };
+}
+/** Seed a fresh live state's CUMULATIVE counters from a persisted snapshot. */
+export function rehydrateLive(state, snap) {
+    state.crystalStore.rehydrate(snap.crystals);
+    state.diagnostics.tallies.profile = snap.diagnostics.profileMisses;
+    state.diagnostics.tallies.range = snap.diagnostics.rangeMisses;
+    state.diagnostics.tallies.dependency = snap.diagnostics.dependencyMisses;
+    state.diagnostics.tallies.request = snap.diagnostics.requestMisses;
+    state.diagnostics.tallies.generation = snap.diagnostics.generationMisses;
+    state.diagnostics.tallies.unknown = snap.diagnostics.unknownMisses;
+    state.diagnostics.serveBlocked = snap.diagnostics.serveBlocked;
+    state.diagnostics.breakerState = snap.diagnostics.breakerState;
+    state.diagnostics.lastFailure = snap.diagnostics.lastFailure;
+    state.economics.computed = snap.economics.computed;
+    state.economics.profileCount = snap.economics.profileCount;
+    state.economics.provenExclusions = snap.economics.provenExclusions;
+    state.economics.unprovenExclusions = snap.economics.unprovenExclusions;
+    state.economics.lastFailure = snap.economics.lastFailure;
+    state.shadow.shadowDecisions = snap.policy.shadowDecisions;
+    state.shadow.clampedDecisions = snap.policy.clampedDecisions;
+    state.shadow.rejectedInputs = snap.policy.rejectedInputs;
+    state.shadow.liveMutations = snap.policy.liveMutations;
+    state.shadow.pressureVersion = snap.policy.pressureVersion;
+    state.shadow.lastFailure = snap.policy.lastFailure;
+}

package/dist/src/vector-cortex/livewire/livewire-registry.js

@@ -0,0 +1,73 @@
+/**
+ * vector-cortex/livewire/livewire-registry.ts — per-stateDir LIWIRE registry.
+ *
+ * The single seam the runtime and the reader-only dashboard routes BOTH access.
+ * It owns a `Map<stateDir, LivewireLiveState>` (one live subsystem cluster per
+ * repo) and lazily opens a state on first access, rehydrating its cumulative
+ * counters from the persisted aggregate snapshot (`livewire-snapshot.ts`) so a
+ * freshly-spawned process — e.g. the dashboard server — reports the same counts
+ * the runtime has already accumulated.
+ *
+ * The runtime WRITES through this registry (see `livewire-runtime.ts`): each
+ * mutation persists a reduced, count-only snapshot. The routes READ through
+ * `livewireOf(stateDir)` and call the pure `snapshotOf`. There is no other path.
+ *
+ * BEST-EFFORT + NON-FATAL. `openLivewire` never throws: persistence failures are
+ * swallowed by the snapshot layer and state is always returned. PREVENT-PI-004
+ * (local in-process Map + filesystem only), PREVENT-011 (no `any`).
+ */
+import { createLiveState, rehydrateLive, snapshotOf, } from "./livewire-live.js";
+import { loadLivewireSnapshot, saveLivewireSnapshot, } from "./livewire-snapshot.js";
+/** The per-stateDir registry (process-local; a fresh process starts empty). */
+const REGISTRY = new Map();
+let activeLogger;
+/**
+ * Bind the structured logger the snapshot layer uses for its non-fatal write
+ * failures. The runtime calls this once at startup with its JSON logger.
+ */
+export function setLivewireLogger(logger) {
+    activeLogger = logger;
+}
+/**
+ * Open (or return the cached) live state for a stateDir. Lazy: on first access
+ * it rehydrates from the persisted aggregate so a separate dashboard process
+ * reflects prior runtime work. Never throws.
+ */
+export function livewireOf(stateDir) {
+    const cached = REGISTRY.get(stateDir);
+    if (cached !== undefined)
+        return cached;
+    const state = createLiveState();
+    const snap = loadLivewireSnapshot(stateDir);
+    if (snap !== null)
+        rehydrateLive(state, snap);
+    REGISTRY.set(stateDir, state);
+    return state;
+}
+/**
+ * Persist a state's reduced aggregate (counts + codes only). Best-effort and
+ * non-fatal. Called by the runtime after every mutation so the snapshot stays
+ * fresh for any reader process.
+ */
+export function persistLivewire(state, stateDir) {
+    saveLivewireSnapshot(stateDir, snapshotOf(state), activeLogger);
+}
+/** Persist the live state for a stateDir (convenience over open + persist). */
+export function flushLivewire(stateDir) {
+    const state = REGISTRY.get(stateDir);
+    if (state === undefined)
+        return;
+    persistLivewire(state, stateDir);
+}
+/**
+ * Build the reader aggregate for one stateDir WITHOUT persisting — the reader
+ * seam the dashboard routes call. Reads the live state (rehydrated from disk on
+ * first access) and projects it to the count-only snapshot.
+ */
+export function readLivewireSnapshot(stateDir) {
+    return snapshotOf(livewireOf(stateDir));
+}
+/** For tests: drop the registry so a fresh stateDir is fully rehydrated. */
+export function _resetLivewireRegistryForTests() {
+    REGISTRY.clear();
+}