pi-mega-compact 0.20.35 → 0.20.38

package/src/monitoring.ts

@@ -205,6 +205,30 @@ export function logRecallQuality(path: string, ev: RecallQualityEvent): void {
   }
 }
 
+// ---------------------------------------------------------------------------
+// ML5-B encoder bench events (consumer-facing for the dashboard + evidence)
+// ---------------------------------------------------------------------------
+
+/**
+ * Append a structured ML5-B bench event to events.log (best-effort, non-fatal).
+ * Mirrors the extension's appendEvent schema ({ ts, event, ...fields }) so the
+ * dashboard live-stream tail and evidence tooling parse the four
+ * `vector_cortex_encoder_bench_*` events identically. The bench is developer/
+ * evidence tooling with no runtime gating; this only records its results.
+ */
+export function logBenchEvent(
+  path: string,
+  event: string,
+  fields: Record<string, unknown>,
+): void {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, JSON.stringify({ ts: Date.now(), event, ...fields }) + "\n", "utf8");
+  } catch {
+    /* best-effort — never break the caller */
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Dedup audit trail (external-audit item #2)
 // ---------------------------------------------------------------------------

package/src/store/backfill.ts

@@ -134,6 +134,7 @@ export function backfillContentHashes(stateDir: string = getStateDir()): Backfil
 
   if (THROTTLE_MS > 0) {
     // No-op in this synchronous build; placeholder for future streaming backfill.
+    // guardrails-allow PREVENT-STUB-001: ML5-C
   }
 
   return { processed, updated, duplicatesResolved };

package/src/vector-cortex/encoder/bench-export.ts

@@ -0,0 +1,65 @@
+/**
+ * vector-cortex/encoder/bench-export.ts — ML5-B bench result contract.
+ *
+ * BenchResultV1 is the typed surface `bench.ts` parses from the qualification
+ * harness (`scripts/ml5/bench-onnx-prod.mjs`) and the dashboard / evidence
+ * tooling consume. It carries AGGREGATE measurements + a digest only — never
+ * chunk/message content (EVAL-REDACT-002).
+ *
+ * Contract-first (ENGINEERING_PRACTICES §3): this types file is the reviewed
+ * gate; implementations import from it. Pi-agnostic, dependency-free
+ * (PREVENT-PI-004 / PREVENT-011).
+ */
+
+/** The four ML5-B bench gates, each independently measured. */
+export interface BenchGatesV1 {
+  /** p95 latency at 512 tokens on `threads` threads <= 40 ms. */
+  readonly latency: boolean;
+  /** steady-state marginal RSS over the process baseline <= 150 MiB. */
+  readonly rss: boolean;
+  /** the loaded model's declared opset_import equals 17. */
+  readonly opset: boolean;
+  /** SHA-256 of the embedding output identical across 3 runs (maxAbsDelta=0). */
+  readonly determinism: boolean;
+  /** conjunctive: every gate passed. */
+  readonly all: boolean;
+}
+
+/**
+ * BenchResultV1 — one qualification run of the ONNX encoder bench.
+ *
+ * Shape is fixed by the ML5-B spec (task 4). `p95Ms`/`rssMib`/`rssMarginalMib`/
+ * `digest` are null when the runtime package is absent (degraded run) or a
+ * gate could not be measured; `gates.all` is false in that case and `error`
+ * (optional) records the honest degradation reason.
+ */
+export interface BenchResultV1 {
+  readonly timestamp: number;
+  /** `${process.platform}-${process.arch}` (e.g. linux-x64, darwin-arm64). */
+  readonly platform: string;
+  /** true = onnxruntime-node (native); false = onnxruntime-web (WASM). */
+  readonly encoderNative: boolean;
+  /** intraOpNumThreads used for the latency gate (normative 4). */
+  readonly threads: number;
+  /** token count per inference (normative 512). */
+  readonly tokens: number;
+  /** total tokens in the corpus the bench streamed over. */
+  readonly corpusTokens: number;
+  /** p95 latency in ms (null on degraded/absent runtime). */
+  readonly p95Ms: number | null;
+  /** steady-state RSS (MiB) over the process baseline, post-GC. */
+  readonly rssMib: number | null;
+  /** RSS (MiB) sampled at process start before loading the encoder. */
+  readonly rssBaselineMib: number | null;
+  /** rssMib - rssBaselineMib: the encoder's marginal footprint. */
+  readonly rssMarginalMib: number | null;
+  /** declared opset_import (17); null when no asset manifest is readable. */
+  readonly opset: number | null;
+  /** true when the output SHA-256 is identical across 3 runs. */
+  readonly deterministic: boolean;
+  /** SHA-256 of the embedding output buffer (null on degraded/absent). */
+  readonly digest: string | null;
+  readonly gates: BenchGatesV1;
+  /** Optional: honest degradation / failure reason (no runtime package, etc.). */
+  readonly error?: string;
+}

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

@@ -0,0 +1,109 @@
+/**
+ * vector-cortex/encoder/bench.ts — ML5-B bench runner (consumer-facing shell).
+ *
+ * Calls `scripts/ml5/bench-onnx-prod.mjs` via child_process, parses the
+ * BenchResultV1 it emits, and writes the four `vector_cortex_encoder_bench_*`
+ * events to the monitoring events.log (the dashboard / ML5-D surface consume
+ * them later). This is NOT a runtime path — it is developer/evidence tooling.
+ *
+ * Events written (all best-effort / non-fatal):
+ *   - vector_cortex_encoder_bench_p95_ms
+ *   - vector_cortex_encoder_bench_rss_mib
+ *   - vector_cortex_encoder_bench_opset_ok
+ *   - vector_cortex_encoder_bench_deterministic
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 — the child bench is pure local
+ * computation). No `any` (PREVENT-011).
+ */
+
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getStateDir } from "../../store.js";
+import { defaultEventsPath, logBenchEvent } from "../../monitoring.js";
+import type { BenchResultV1 } from "./bench-export.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(HERE, "..", "..", "..");
+const BENCH_SCRIPT = join(REPO_ROOT, "scripts", "ml5", "bench-onnx-prod.mjs");
+
+/** Default events.log beside the state dir (mirrors defaultEventsPath). */
+function benchEventsPath(stateDir: string): string {
+  return defaultEventsPath(stateDir);
+}
+
+/**
+ * Run the ONNX bench once and record its four events. Returns the parsed
+ * BenchResultV1. On any failure (script missing, non-zero exit, unparsable
+ * output) it returns a degraded result with gates.all:false — never throws, so
+ * the caller's agent loop is never broken (non-fatal store/write contract).
+ */
+export function runBench(stateDir: string = getStateDir()): BenchResultV1 {
+  const noop = (error: string): BenchResultV1 => ({
+    timestamp: Date.now(),
+    platform: `${process.platform}-${process.arch}`,
+    encoderNative: false,
+    threads: 4,
+    tokens: 512,
+    corpusTokens: 0,
+    p95Ms: null,
+    rssMib: null,
+    rssBaselineMib: null,
+    rssMarginalMib: null,
+    opset: null,
+    deterministic: false,
+    digest: null,
+    gates: { latency: false, rss: false, opset: false, determinism: false, all: false },
+    error,
+  });
+
+  const fallback = (error: string): BenchResultV1 => {
+    const r = noop(error);
+    emitEvents(stateDir, r);
+    return r;
+  };
+
+  try {
+    const res = spawnSync(process.execPath, ["--expose-gc", BENCH_SCRIPT], {
+      cwd: REPO_ROOT,
+      encoding: "utf8",
+      timeout: 600_000,
+    });
+    const stdout = (res.stdout ?? "").trim();
+    if (res.status === null) {
+      return fallback("bench timed out or failed to spawn");
+    }
+    const parsed: unknown = JSON.parse(stdout || "");
+    if (!isBenchResultV1(parsed)) {
+      return fallback("bench output was not a BenchResultV1");
+    }
+    emitEvents(stateDir, parsed);
+    return parsed;
+  } catch (e) {
+    return fallback(`bench failed: ${(e as Error)?.message ?? String(e)}`);
+  }
+}
+
+function isBenchResultV1(v: unknown): v is BenchResultV1 {
+  if (typeof v !== "object" || v === null) return false;
+  const o = v as Record<string, unknown>;
+  return (
+    typeof o.timestamp === "number" &&
+    typeof o.platform === "string" &&
+    typeof o.encoderNative === "boolean" &&
+    typeof o.threads === "number" &&
+    typeof o.tokens === "number" &&
+    typeof o.corpusTokens === "number" &&
+    typeof o.gates === "object" && o.gates !== null &&
+    typeof (o.gates as Record<string, unknown>).all === "boolean"
+  );
+}
+
+function emitEvents(stateDir: string, r: BenchResultV1): void {
+  const path = benchEventsPath(stateDir);
+  const run = { platform: r.platform, encoderNative: r.encoderNative, threads: r.threads, tokens: r.tokens, digest: r.digest, corpusTokens: r.corpusTokens };
+  logBenchEvent(path, "vector_cortex_encoder_bench_p95_ms", { ...run, p95Ms: r.p95Ms, pass: r.gates.latency });
+  logBenchEvent(path, "vector_cortex_encoder_bench_rss_mib", { ...run, rssMib: r.rssMib, rssBaselineMib: r.rssBaselineMib, rssMarginalMib: r.rssMarginalMib, pass: r.gates.rss });
+  logBenchEvent(path, "vector_cortex_encoder_bench_opset_ok", { ...run, opset: r.opset, pass: r.gates.opset });
+  logBenchEvent(path, "vector_cortex_encoder_bench_deterministic", { ...run, deterministic: r.deterministic, pass: r.gates.determinism });
+}

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

@@ -23,6 +23,8 @@
  */
 
 import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { ML5A_ENABLED } from "../../config/vector-cortex.js";
 import {
   ENCODER_HEAD_ORDER,
   ENCODER_SEED,
@@ -223,3 +225,50 @@ export function fitCalibration(
   };
   return { ok: true, calibration };
 }
+
+/**
+ * Load a persisted `CalibrationV1` artifact (schema "calibration-v1") from disk.
+ * ML5-A: gated on MEGACOMPACT_ML5_A; flag-off, absent file, malformed JSON,
+ * wrong schema, non-canonical five-head order, or non-finite temp/threshold each
+ * return null (non-fatal, never throws). Deterministic, local (PREVENT-PI-004).
+ */
+export function loadCalibrationV1(path: string): CalibrationV1 | null {
+  if (!ML5A_ENABLED()) return null;
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const r = parsed as Record<string, unknown> | null;
+  if (!r || r["schema"] !== "calibration-v1") return null;
+  const order = r["headOrder"];
+  if (!Array.isArray(order)) return null;
+  if (order.length !== ENCODER_HEAD_ORDER.length || !ENCODER_HEAD_ORDER.every((h, i) => order[i] === h)) {
+    return null;
+  }
+  const temperatures = r["temperatures"] as Record<string, unknown> | undefined;
+  const thresholds = r["thresholds"] as Record<string, unknown> | undefined;
+  const splitDigest = r["calibrationSplitDigest"];
+  if (!temperatures || !thresholds || typeof splitDigest !== "string" || splitDigest.length !== 64) return null;
+  for (const h of ENCODER_HEAD_ORDER) {
+    const t = Number(temperatures[h]);
+    const th = Number(thresholds[h]);
+    if (!Number.isFinite(t) || !Number.isFinite(th)) return null;
+  }
+  return {
+    schema: "calibration-v1",
+    headOrder: [...ENCODER_HEAD_ORDER],
+    calibrationSplitDigest: splitDigest,
+    fittedOnCalibrationOnly: true,
+    temperatures: { ...(temperatures as Record<EncoderHeadName, number>) },
+    thresholds: { ...(thresholds as Record<EncoderHeadName, number>) },
+    seed: Number(r["seed"] ?? ENCODER_SEED),
+  };
+}

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

@@ -20,6 +20,8 @@
  * Pi-agnostic, zero network (PREVENT-PI-004), no `any` (PREVENT-011).
  */
 
+import { readFileSync } from "node:fs";
+import { ML5A_ENABLED } from "../../config/vector-cortex.js";
 import {
   ENCODER_HEAD_DIMS,
   ENCODER_HEAD_ORDER,
@@ -139,4 +141,108 @@ export function headLossWeights(): Readonly<Record<EncoderHeadName, number>> {
   return { ...ENCODER_HEAD_LOSS_WEIGHTS };
 }
 
+// ---------------------------------------------------------------------------
+// ML5-A real trained-head loading. Produces the projection matrices that the
+// deterministic placeholder `projectHead` approximates: row-major
+// `weights[h]` of length `headDim * trunkDim`, applied `W[i*t+j]*trunk[j]`,
+// L2-normalized. Loaded from the `trained-heads-v1` JSON that
+// `training/vector-cortex/train.py` emits, under the MEGACOMPACT_ML5_A gate.
+// Non-fatal: any violation (flag off, absent, malformed, wrong seed, wrong
+// shape) yields null, never a throw (all loaders return null on violation).
+// ---------------------------------------------------------------------------
+
+/** The real loadable form of the trained five-head projection table. */
+export interface HeadProjectionTable {
+  readonly schema: "trained-heads-v1";
+  readonly seed: number;
+  /** Input/trunk embedding dimension every head projects from (uniform 384). */
+  readonly trunkDim: number;
+  /** Per-head OUTPUT dimension (semantic 384 / ... / payloadRouting 32). */
+  readonly dims: Readonly<Record<EncoderHeadName, number>>;
+  /** Row-major `[headDim * trunkDim]` projection matrix per head. */
+  readonly weights: Readonly<Record<EncoderHeadName, Float32Array>>;
+  readonly temperatures: Readonly<Record<EncoderHeadName, number>>;
+}
+
+/** True when every head's output dim + weight length matches the contract. */
+export function headsShapeValid(t: HeadProjectionTable): boolean {
+  return ENCODER_HEAD_ORDER.every(
+    (h) => t.dims[h] === ENCODER_HEAD_DIMS[h] && t.weights[h].length === ENCODER_HEAD_DIMS[h] * t.trunkDim,
+  );
+}
+
+/**
+ * Load a `trained-heads-v1` artifact into a `HeadProjectionTable`. Gated on
+ * MEGACOMPACT_ML5_A: flag-off, absent file, malformed JSON, wrong schema,
+ * wrong seed, or a shape mismatch each return null (non-fatal). Deterministic
+ * and local (PREVENT-PI-004).
+ */
+export function loadHeadProjections(path: string): HeadProjectionTable | null {
+  if (!ML5A_ENABLED()) return null;
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const r = parsed as Record<string, unknown> | null;
+  if (!r || r["schema"] !== "trained-heads-v1") return null;
+  if (r["seed"] !== ENCODER_SEED) return null;
+  const dims = r["dims"] as Record<string, unknown> | undefined;
+  const heads = r["heads"] as Record<string, unknown> | undefined;
+  if (!dims || !heads) return null;
+  const trunkDim = Number(r["trunkDim"] ?? 0);
+  if (!Number.isFinite(trunkDim) || trunkDim <= 0) return null;
+  const weights: Record<string, Float32Array> = {};
+  const temperatures: Record<string, number> = {};
+  for (const h of ENCODER_HEAD_ORDER) {
+    const hd = heads[h] as Record<string, unknown> | undefined;
+    if (!hd || typeof hd !== "object") return null;
+    const w = hd["weights"];
+    if (!Array.isArray(w)) return null;
+    weights[h] = Float32Array.from(w as number[]);
+    if (Number(hd["dim"] ?? 0) !== ENCODER_HEAD_DIMS[h]) return null;
+    temperatures[h] = Number(hd["temperature"] ?? 1);
+    if (!Number.isFinite(dims[h])) return null;
+  }
+  const table: HeadProjectionTable = {
+    schema: "trained-heads-v1",
+    seed: Number(r["seed"]),
+    trunkDim,
+    dims: { semantic: 384, dependency: 128, contradiction: 128, cacheStability: 64, payloadRouting: 32 } as unknown as Record<EncoderHeadName, number>,
+    weights: weights as unknown as Record<EncoderHeadName, Float32Array>,
+    temperatures: temperatures as unknown as Record<EncoderHeadName, number>,
+  };
+  if (!headsShapeValid(table)) return null;
+  return table;
+}
+
+/**
+ * Project a trunk embedding through a trained head's real weights, applying the
+ * row-major matrix then L2-normalizing (all-zero on zero norm). Returns a
+ * `HeadVector` of the head's normative dimension.
+ */
+export function projectHeadFromTrunk(
+  head: EncoderHeadName,
+  trunk: Float32Array,
+  table: HeadProjectionTable,
+): HeadVector {
+  const dim = ENCODER_HEAD_DIMS[head];
+  const W = table.weights[head];
+  const t = table.trunkDim;
+  const out = new Float32Array(dim);
+  for (let i = 0; i < dim; i++) {
+    let acc = 0;
+    for (let j = 0; j < t; j++) acc += W[i * t + j]! * (trunk[j] ?? 0);
+    out[i] = acc;
+  }
+  return { head, dim, values: l2Normalize(out) };
+}
+
 export { ENCODER_HEAD_ORDER, ENCODER_HEAD_DIMS, ENCODER_HEAD_LOSS_SUM, ENCODER_SEED, NOOP_VC2B_REPORTER };

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

@@ -34,6 +34,8 @@
  */
 
 import { createHash } from "node:crypto";
+import { ML5A_ENABLED } from "../../config/vector-cortex.js";
+import { loadHeadProjections } from "./heads.js";
 import {
   ENC_QUALIFICATION_FAIL,
   EVALUATION_THRESHOLDS,
@@ -83,6 +85,13 @@ export interface QualificationCandidate {
    * corrupt-qualification-manifest injection (ENC_QUALIFICATION_DIGEST_MISMATCH).
    */
   readonly expectedQualificationManifestDigest?: string;
+  /**
+   * ML5-A: path to the `trained-heads-v1` artifact. When supplied AND the
+   * MEGACOMPACT_ML5_A gate is on, the candidate qualifies to mode A only if the
+   * real trained head weights load; a load failure atomically demotes all of A
+   * to B (non-fatal, reported as THRESHOLD_FAILED / head.weights.trainedHeadsPath).
+   */
+  readonly trainedHeadsPath?: string;
 }
 
 /**
@@ -183,6 +192,14 @@ export function selectQualifiedEncoder(
 
   // Atomic: collect EVERY failed field across asset + all heads + reconstruction.
   const failed: string[] = [];
+  // ML5-A: real trained-head weights must load for mode A. When the gate is on
+  // and a trained-heads path is pinned, an unloadable/wrong-seed/malformed
+  // artifact is a qualification failure (any failed field demotes ALL of A).
+  if (ML5A_ENABLED() && candidate.trainedHeadsPath !== undefined) {
+    if (loadHeadProjections(candidate.trainedHeadsPath) === null) {
+      failed.push("head.weights.trainedHeadsPath");
+    }
+  }
   assetPasses(candidate.asset, failed);
   const heads: EncoderHeadName[] = ["semantic", "dependency", "contradiction", "cacheStability", "payloadRouting"];
   for (const h of heads) {