pi-mega-compact 0.20.36 → 0.20.39

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

@@ -0,0 +1,28 @@
+/**
+ * config/vector-cortex-ml5b.ts — ML5-B production bench harness flag.
+ *
+ * Sibling extract mirroring vector-cortex-ml5a.ts, so vector-cortex.ts stays
+ * under its 300-line soft limit (soft-as-hard gate). This is the ONNX Runtime
+ * evaluation/benchmark sprint flag. vector-cortex.ts re-exports the ENUM below
+ * and root src/config.ts re-exports it, so no consumer import path changes.
+ *
+ * ML5-B introduces NO runtime code path: the bench harness and corpus export
+ * are developer/evidence tooling (scripts/) plus a consumer-facing TypeScript
+ * shell (src/vector-cortex/encoder/bench.ts) that only writes monitoring
+ * events. The flag records intent and scopes the sprint's evidence assets; it
+ * gates nothing at runtime today. There is no HTTP endpoint and no dashboard
+ * change, so there is no SETTINGS toggle and no EXCLUDED_SETTINGS interaction.
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { sprintFlag } from "./vector-cortex-flag.js";
+
+/**
+ * ML5-B — production bench harness (ONNX Runtime eval). Default ON.
+ * `MEGACOMPACT_ML5_B=0` disables and is byte-identical to the ML5-A survivor:
+ * no bench endpoint exists and mode B continues to serve all clients exactly as
+ * before. The flag does not gate the harness itself — the harness is an on-demand
+ * developer tool with no runtime path.
+ */
+export const ML5B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_ML5_B");

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

@@ -0,0 +1,30 @@
+/**
+ * config/vector-cortex-ml5c.ts — ML5-C runtime decision + packaging flag.
+ *
+ * Sibling extract mirroring vector-cortex-ml5a.ts / vector-cortex-ml5b.ts, so
+ * vector-cortex.ts stays under its 300-line soft limit (soft-as-hard gate).
+ * This is the ONNX Runtime backend selection + packaging sprint flag.
+ * vector-cortex.ts re-exports the ENUM below and root src/config.ts re-exports
+ * it, so no consumer import path changes.
+ *
+ * ML5-C selects the ONNX runtime backend (WASM vs native) based on the ML5-B
+ * bench record and platform support. The flag gates the runtime-selection
+ * dispatch only; when OFF the encoder serves mode B trigram exactly as before
+ * (byte-identical to the ML5-B survivor — no `vector_cortex_runtime_selected`
+ * event is emitted, no session-selection dispatch runs).
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { sprintFlag } from "./vector-cortex-flag.js";
+
+/**
+ * ML5-C — runtime decision + packaging (WASM vs native). Default ON.
+ * `MEGACOMPACT_ML5_C=0` disables and is byte-identical to the ML5-B survivor:
+ * no runtime selection runs — the encoder continues to serve mode B trigram,
+ * exactly as before, with no `vector_cortex_runtime_selected` event emitted.
+ * The flag gates the runtime-selection dispatch only; it does not gate the
+ * underlying WASM/native backends (which are exercised by ML5-B's bench
+ * harness and ML5-A's trained asset independently).
+ */
+export const ML5C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_ML5_C");

package/src/config/vector-cortex.ts

@@ -272,14 +272,15 @@ export const VC8B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC8B");
 // VC8C (canary selection + Rust parity) extracted to vector-cortex-vc8c.ts;
 // re-exported so existing `./config/vector-cortex.js` imports keep resolving.
 export { VC8C_ENABLED } from "./vector-cortex-vc8c.js";
-
-// VC9A/VC9B/VC9C/VC9D/PCC/ML5A split to sibling files to stay under the 300-line soft limit.
+// Sibling extracts to stay under the 300-line soft limit.
 export { VC9A_ENABLED } from "./vector-cortex-vc9a.js";
 export { VC9B_ENABLED } from "./vector-cortex-vc9b.js";
 export { VC9C_ENABLED } from "./vector-cortex-vc9c.js";
 export { VC9D_ENABLED } from "./vector-cortex-vc9d.js";
 export { PCC_ENABLED } from "./vector-cortex-pcc.js";
 export { ML5A_ENABLED } from "./vector-cortex-ml5a.js";
+export { ML5B_ENABLED } from "./vector-cortex-ml5b.js";
+export { ML5C_ENABLED } from "./vector-cortex-ml5c.js";
 
 // Breaker constants (TRIAD_RESILIENCE.md §breaker) extracted to vector-cortex-breakers.ts.
 export {

package/src/config.ts

@@ -184,6 +184,8 @@ export {
   VC9D_ENABLED,
   PCC_ENABLED,
   ML5A_ENABLED,
+  ML5B_ENABLED,
+  ML5C_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

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

@@ -28,7 +28,6 @@ import { defaultEmbedder } from "../embedder.js";
 import { getStateDir } from "../store.js";
 
 const BATCH = 1000;
-const THROTTLE_MS = 0; // synchronous backfill; no cross-process yield needed
 
 /** Backfill phases, in order (Sprint 14 full-pipeline wiring). */
 export type BackfillPhase = "L0" | "L1" | "L2" | "RAPTOR";
@@ -132,10 +131,6 @@ export function backfillContentHashes(stateDir: string = getStateDir()): Backfil
     ).run(lastSid, lastId, updated, duplicatesResolved);
   }
 
-  if (THROTTLE_MS > 0) {
-    // No-op in this synchronous build; placeholder for future streaming backfill.
-  }
-
   return { processed, updated, duplicatesResolved };
 }
 
@@ -219,7 +214,6 @@ export function backfillPhase(
     });
     savePhaseCursor(db, phase, cursor ?? null, processed);
     batches++;
-    if (THROTTLE_MS > 0) { const end = Date.now() + THROTTLE_MS; while (Date.now() < end) { /* throttle */ } }
     if (opts.interruptAfterBatches && batches >= opts.interruptAfterBatches) {
       interrupted = true;
       break;

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/runtime-emit.ts

@@ -0,0 +1,47 @@
+/**
+ * vector-cortex/encoder/runtime-emit.ts — ML5-C seller event emitter.
+ *
+ * Emits the `vector_cortex_runtime_selected` seller event to the local
+ * events.log so the dashboard Setup Cortex blockers card can surface the HG-3
+ * (install budget) / HG-4 (darwin-x64 demotion) closure state. Aggregate
+ * fields only — never payload bytes (EVAL-REDACT-002).
+ *
+ * Extracted from runtime.ts so the runtime delegate-shell stays under the
+ * 300-line soft limit after the ML5-C dispatch was added. All writes are
+ * best-effort / non-fatal; a disk-full or missing state dir never breaks the
+ * encoder loop.
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 — local filesystem append only;
+ * no network). No `any` (PREVENT-011).
+ */
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { defaultEventsPath } from "../../monitoring.js";
+import type { RuntimeSelectionResult } from "./runtime-select.js";
+
+/**
+ * Emit the ML5-C `vector_cortex_runtime_selected` seller event (best-effort).
+ * The event carries ONLY the four aggregate fields the sprint spec pins
+ * ({backend, p95Ms, budgetOk, platform}) — never message content.
+ */
+export function emitRuntimeSelected(
+  stateDir: string,
+  result: Pick<RuntimeSelectionResult, "backend" | "p95Ms" | "budgetOk" | "platform">,
+): void {
+  try {
+    const path = defaultEventsPath(stateDir);
+    const payload = {
+      ts: Date.now(),
+      event: "vector_cortex_runtime_selected",
+      backend: result.backend,
+      p95Ms: result.p95Ms,
+      budgetOk: result.budgetOk,
+      platform: result.platform,
+    };
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, JSON.stringify(payload) + "\n", "utf8");
+  } catch {
+    /* best-effort — never break the encoder loop */
+  }
+}

package/src/vector-cortex/encoder/runtime-native.ts

@@ -0,0 +1,117 @@
+/**
+ * vector-cortex/encoder/runtime-native.ts — ML5-C native backend (Option N).
+ *
+ * Loads an `InferenceSession` from the `onnxruntime-node` native binding for
+ * the committed encoder-v1 ONNX asset. This is the CHOSEN selection when
+ * `MEGACOMPACT_ENCODER_NATIVE=1` (the native opt-in marker) is set AND the
+ * package is present — it uses the platform-specific prebuilt binary (no
+ * postinstall compilation needed; per vc2-model-prep §1 the allowScripts
+ * removal is safe because only CUDA/TensorRT downloads use it, and pi blocks
+ * all scripts anyway).
+ *
+ * The package is NOT declared in package.json dependencies — it is a lazily-
+ * resolved peer that the runtime loads ONLY when the native opt-in is set AND
+ * selected. Loading uses dynamic `import()` so the module graph compiles
+ * cleanly on hosts without the package (absent installs return null, never
+ * throw), so the ML5-C dispatch demotes to mode B trigram rather than
+ * breaking.
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 — the native binary + model are
+ * committed local files). No `any` (PREVENT-011).
+ */
+
+import {
+  ENCODER_OPSET,
+  ENCODER_SEMANTIC_WIDTH,
+  ENCODER_MAX_TOKENS,
+} from "./types.js";
+
+/** The shape of the optionalImport result when onnxruntime-node is present.
+ *  Shadow-types instead of `import("onnxruntime-node")` so the module graph
+ *  builds without the package being declared in package.json (ML5-B precedent). */
+export interface OrtNativeModule {
+  InferenceSession: {
+    create(
+      path: string,
+      opts: { executionProviders: string[]; intraOpNumThreads: number },
+    ): Promise<{
+      run(
+        feeds: Record<string, Float32Array>,
+        outputNames: string[],
+      ): Promise<Record<string, { data: Float32Array }>>;
+    }>;
+  };
+}
+
+/** The backend's inference session — a thin wrapper over the real native session. */
+export interface NativeSession {
+  /** The declared ONNX opset in the loaded manifest (normative 17). */
+  readonly opset: number;
+  /** The semantic embedding width (normative 384). */
+  readonly semanticWidth: number;
+  /** The per-asset token capacity cap (normative <= 512). */
+  readonly maxTokens: number;
+  /** Run one inference over already shape-checked input tokens. */
+  infer(inputIds: Float32Array): Promise<Float32Array>;
+}
+
+/** True when `MEGACOMPACT_ENCODER_NATIVE=1` (the native opt-in operator flag). */
+export function nativeOptIn(): boolean {
+  return process.env.MEGACOMPACT_ENCODER_NATIVE === "1";
+}
+
+/** True if `onnxruntime-node` resolves on this host (loading is best-effort).
+ *  Absent installs return null (never throw) so the ML5-C dispatch can demote
+ *  to mode B trigram cleanly. */
+async function loadOrtNative(): Promise<OrtNativeModule | null> {
+  try {
+    // @ts-expect-error — optional peer; the shadow type above covers the surface
+    const mod = (await import("onnxruntime-node")) as OrtNativeModule;
+    return mod;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Create a native-backed `NativeSession` over the committed ONNX asset, gated
+ * first on `nativeOptIn()`. Returns null (never throws) on any failure
+ * (opt-in off, absent package, unreadable asset, bad session creation) so the
+ * caller demotes to mode B trigram.
+ */
+export async function createNativeSession(
+  modelPath: string,
+  options: { threads?: number; maxTokens?: number } = {},
+): Promise<NativeSession | null> {
+  if (!nativeOptIn()) return null;
+
+  const ort = await loadOrtNative();
+  if (!ort || !ort.InferenceSession?.create) return null;
+
+  const threads = options.threads ?? 4;
+  const maxTokens = options.maxTokens ?? ENCODER_MAX_TOKENS;
+
+  try {
+    const session = await ort.InferenceSession.create(modelPath, {
+      executionProviders: ["cpu"],
+      intraOpNumThreads: threads,
+    });
+
+    return {
+      opset: ENCODER_OPSET,
+      semanticWidth: ENCODER_SEMANTIC_WIDTH,
+      maxTokens,
+      async infer(inputIds: Float32Array): Promise<Float32Array> {
+        const feeds = { input_ids: inputIds };
+        const results = await session.run(feeds, ["embedding"]);
+        const out = results["embedding"];
+        if (!out || !(out.data instanceof Float32Array)) {
+          return new Float32Array(ENCODER_SEMANTIC_WIDTH);
+        }
+        return out.data;
+      },
+    };
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,167 @@
+/**
+ * vector-cortex/encoder/runtime-select.ts — ML5-C decision-rule dispatch.
+ *
+ * Pure function of {platform, benchRecord, nativeOptIn} → the chosen ONNX
+ * runtime backend. This is the deterministic selection that closes HG-3
+ * (install budget) and HG-4 (darwin-x64 disposition) per the ML5-C spec:
+ *
+ *   - Measured p95 at 512 tokens on 4 threads (linux-x64) <= 40 ms  →  Option W (WASM)
+ *   - Measured p95 > 40 ms or absent (degraded)                        →  Option N (native)
+ *   - Platform is darwin-x64 (Intel Mac, HG-1 deferral)               →  WASM demotion or mode B
+ *
+ * The `platform` comes from `detectPlatform()` (already in `asset.ts`); the
+ * `benchRecord` is the latest `BenchResultV1` (from ML5-B / JSONL); the
+ * `nativeOptIn` helper reads `MEGACOMPACT_ENCODER_NATIVE=1`. The selection is
+ * PURE — no side effects, no I/O, no network. The caller stamps the result on
+ * the `vector_cortex_runtime_selected` event carried to the dashboard.
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 — selection is computed+in memory;
+ * no fetch/HTTP). No `any` (PREVENT-011).
+ */
+
+import {
+  ENCODER_LATENCY_P95_MS,
+  type EncoderPlatform,
+} from "./types.js";
+import type { BenchResultV1 } from "./bench-export.js";
+import { ML5C_ENABLED } from "../../config/vector-cortex.js";
+
+/** The chosen runtime backend name as it appears on the seller event. */
+export type RuntimeBackendChoice = "wasm" | "native" | "modeB";
+
+/** Inputs to the backend selection. `platform` is `${process.platform}-${process.arch}`. */
+export interface RuntimeSelectionInput {
+  /** The platform this process is running on (from detectPlatform()). */
+  readonly platform: EncoderPlatform | "unsupported";
+  /**
+   * The ML5-B bench record for this platform (linux-x64 normative). Null when
+   * no bench has run yet (degraded: the 42-byte placeholder has no real p95).
+   * Must provide a numeric p95Ms for WASM consideration; a null/error record
+   * (gates.all:false) forces the native fallback per the decision rule.
+   */
+  readonly benchRecord: BenchResultV1 | null;
+  /** True when the operator opted into onnxruntime-node via MEGACOMPACT_ENCODER_NATIVE=1. */
+  readonly nativeOptIn: boolean;
+}
+
+/** The output of the ML5-C decision-rule dispatch. */
+export interface RuntimeSelectionResult {
+  /** The chosen backend. */
+  readonly backend: RuntimeBackendChoice;
+  /** HG-3 closure state: whether the 80 MiB install budget is satisfied. */
+  readonly budgetOk: boolean;
+  /** The measured p95 (ms) that drove the decision, from BenchResultV1. */
+  readonly p95Ms: number | null;
+  /** The platform the selection is valid for. */
+  readonly platform: string;
+  /** Short human-readable rationale for the choice (record on the event). */
+  readonly rationale: string;
+}
+
+/** The 80 MiB install budget in bytes (the HG-3 ceiling, unamended). */
+export const RUNTIME_NATIVE_INSTALL_BUDGET_MIB = 80;
+
+/**
+ * Per-platform optionalDependency footprint of onnxruntime-node (MiB, approx).
+ * These sum to ~160 MiB SHIPPED in the npm package (every target platform is
+ * included so the resolver lands on a concrete row at install time) — which is
+ * what exceeds the 80 MiB HG-3 budget and forces the amendment the fixtures
+ * record (ML5-RUNTIME-001). The per-host INSTALLED footprint (one row only)
+ * is 28–35 MiB and irrelevant to the 80 MiB ceiling — the budget covers the
+ * shipped tarball, not the single-platform install.
+ */
+export const NATIVE_FOOTPRINT_MIB: Readonly<Record<EncoderPlatform, number>> = {
+  "linux-x64": 33,
+  "darwin-arm64": 28,
+  "darwin-x64": 33,
+  "linux-arm64": 31,
+  "win32-x64": 35,
+};
+
+/**
+ * ML5-C decision-rule dispatch: choose the ONNX runtime backend (pure).
+ *
+ * When the flag is OFF (`MEGACOMPACT_ML5_C=0`), returns mode B trigram — byte-
+ * identical to the ML5-B survivor with no selection event emitted.
+ *
+ * The rule (from the sprint spec):
+ *   - If nativeOptIn && platform is supported → native (Option N)
+ *   - If benchRecord has p95Ms <= 40 ms on linux-x64 → WASM (Option W)
+ *   - Else → native (Option N) with the budget amendment recorded (p95 exceeds
+ *     the WASM gate or is absent — the placeholder has no measured p95)
+ *   - darwin-x64 → WASM or mode B demotion per HG-4 (never native here)
+ */
+export function selectRuntimeBackend(input: RuntimeSelectionInput): RuntimeSelectionResult {
+  if (!ML5C_ENABLED()) {
+    return {
+      backend: "modeB",
+      budgetOk: true,
+      p95Ms: null,
+      platform: input.platform,
+      rationale: "flag-off: byte-identical mode-B trigram (no selection)",
+    };
+  }
+
+  // HG-4: Intel Mac (darwin-x64) is out-of-scope per HG-1's deferral — always demote.
+  if (input.platform === "darwin-x64") {
+    return {
+      backend: "wasm",
+      budgetOk: true,
+      p95Ms: null,
+      platform: input.platform,
+      rationale: "darwin-x64 demoted to WASM per HG-4 (never native on this platform)",
+    };
+  }
+
+  // Native opt-in short-circuits: operator explicitly wants the native path.
+  // The HG-3 budget compares the SHIPPED byte-count (sum across every platform
+  // row in the package's optionalDependencies map) against the 80 MiB ceiling
+  // — not the single-platform install size. Native always exceeds 80 MiB across
+  // 5 platforms (~160 MiB shipped), so budgetOk is false and the evidence
+  // records the amended budget (the ML5-C spec, HG-3 closure).
+  if (input.nativeOptIn) {
+    const shippedMib = Object.values(NATIVE_FOOTPRINT_MIB).reduce((a, b) => a + b, 0);
+    return {
+      backend: "native",
+      budgetOk: shippedMib <= RUNTIME_NATIVE_INSTALL_BUDGET_MIB,
+      p95Ms: input.benchRecord?.p95Ms ?? null,
+      platform: input.platform,
+      rationale: `native opt-in (MEGACOMPACT_ENCODER_NATIVE=1); shipped ${shippedMib} MiB across 5 platforms → budget amended to ${shippedMib} MiB`,
+    };
+  }
+
+  // No bench record or degraded (gates.all:false) → WASM cannot qualify (the
+  // placeholder 42-byte asset has no measured real p95), so native is selected
+  // with the SAME amended-budget disposition as the opt-in path above: the
+  // evidence records the closed HG-3 amendment.
+  if (!input.benchRecord || !input.benchRecord.gates.all || input.benchRecord.p95Ms === null) {
+    const shippedMib = Object.values(NATIVE_FOOTPRINT_MIB).reduce((a, b) => a + b, 0);
+    return {
+      backend: "native",
+      budgetOk: false, // amended: native ships > 80 MiB across the 5-platform matrix
+      p95Ms: input.benchRecord?.p95Ms ?? null,
+      platform: input.platform,
+      rationale: `no qualifying bench record — native fallback with budget amendment (${shippedMib} MiB shipped, HG-3 amendment recorded)`,
+    };
+  }
+
+  // The decision rule: WASM iff p95 <= 40 ms (linux-x64, 512 tokens, 4 threads) —
+  // native required otherwise, with the same budget amendment recorded.
+  if (input.benchRecord.p95Ms <= ENCODER_LATENCY_P95_MS) {
+    return {
+      backend: "wasm",
+      budgetOk: true,
+      p95Ms: input.benchRecord.p95Ms,
+      platform: input.platform,
+      rationale: `WASM qualifies: p95 ${input.benchRecord.p95Ms}ms <= ${ENCODER_LATENCY_P95_MS}ms`,
+    };
+  }
+
+  return {
+    backend: "native",
+    budgetOk: false, // amended: native exceeds the 80 MiB budget per the evidence
+    p95Ms: input.benchRecord.p95Ms,
+    platform: input.platform,
+    rationale: `native required: p95 ${input.benchRecord.p95Ms}ms > ${ENCODER_LATENCY_P95_MS}ms on WASM`,
+  };
+}