pi-mega-compact 0.20.38 → 0.20.39

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

@@ -0,0 +1,38 @@
+/**
+ * vector-cortex/encoder/runtime-stub.ts — the VC2A-era deterministic LCG
+ * placeholder (`projectSemantic`) + token-seed helper, split out of runtime.ts
+ * so `runtime.ts` stays under its 300-line soft limit as the delegate-shell.
+ *
+ * This placeholder is the VC2A-era stand-in for a real ONNX EncoderRuntime
+ * inference result (the actual weights were VC2C and the runtime-selection
+ * dispatch is ML5-C). It remains exported so tests driving end-to-end shape
+ * keep working even when no backend session is active.
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { ENCODER_SEMANTIC_WIDTH } from "./types.js";
+
+/** A deterministic seeded projection so the mode-A inference path is testable
+ *  end-to-end without onnxruntime (real weights + execution are VC2C). */
+export function projectSemantic(seed: number, n: number): Float32Array {
+  const out = new Float32Array(n);
+  let state = (seed >>> 0) ^ 0x9e3779b9;
+  let sum = 0;
+  for (let i = 0; i < n; i++) {
+    state = (state * 1664525 + 1013904223) >>> 0;
+    out[i] = (state / 4294967296) * 2 - 1;
+    sum += out[i]! * out[i]!;
+  }
+  const norm = Math.sqrt(sum) || 1;
+  for (let i = 0; i < n; i++) out[i] = out[i]! / norm;
+  return out;
+}
+
+/** Deterministic token seed derived from the verified asset bytes count. */
+export function seedFromBytes(embeddedBytes: number): number {
+  return (embeddedBytes * 2654435761) >>> 0;
+}
+
+/** The semantic embedding width from the normative types barrel. */
+export { ENCODER_SEMANTIC_WIDTH };

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

@@ -0,0 +1,110 @@
+/**
+ * vector-cortex/encoder/runtime-wasm.ts — ML5-C WASM backend (Option W).
+ *
+ * Loads an `InferenceSession` from the `onnxruntime-web` WASM execution
+ * provider for the committed encoder-v1 ONNX asset. This is the default
+ * backend when the WASM path is selected by `select.ts` — it covers all Node
+ * platforms (no per-platform optionalDependencies), is pure JS + WASM (~9 MiB),
+ * and never fetches from the network (PREVENT-PI-004).
+ *
+ * The package is NOT declared in package.json dependencies — it is a lazily-
+ * resolved peer that the runtime loads ONLY when the WASM backend is actually
+ * 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 (ML5-B-bench precedent: the fixtures declare the shape even when
+ * the package is absent).
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 — the WASM artifact is loaded
+ * from the committed local path; no fetch/HTTP anywhere). No `any`
+ * (PREVENT-011).
+ */
+
+import {
+  ENCODER_OPSET,
+  ENCODER_SEMANTIC_WIDTH,
+  ENCODER_MAX_TOKENS,
+} from "./types.js";
+
+/** The shape of the optionalImport result when onnxruntime-web is present.
+ *  Shadow-types instead of `import("onnxruntime-web")` so the module graph builds
+ *  without the package being declared in package.json (ML5-B precedent). */
+export interface OrtWasmModule {
+  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 WASM session. */
+export interface WasmSession {
+  /** 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 if `onnxruntime-web` 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 loadOrtWasm(): Promise<OrtWasmModule | null> {
+  try {
+    // @ts-expect-error — optional peer; the shadow type above covers the surface
+    const mod = (await import("onnxruntime-web")) as OrtWasmModule;
+    return mod;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Create a WASM-backed `WasmSession` over the committed ONNX asset. Returns
+ * null (never throws) on any failure (absent package, unreadable asset, bad
+ * session creation) so the caller demotes to mode B trigram per HG-4 mode-B
+ * disposition when the WASM path is unavailable on a darwin-x64 host.
+ */
+export async function createWasmSession(
+  modelPath: string,
+  options: { threads?: number; maxTokens?: number } = {},
+): Promise<WasmSession | null> {
+  const ort = await loadOrtWasm();
+  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: ["wasm"],
+      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.ts

@@ -1,5 +1,5 @@
 /**
- * vector-cortex/encoder/runtime.ts — VC2A EncoderRuntime (task 3).
+ * vector-cortex/encoder/runtime.ts — VC2A EncoderRuntime (task 3) + ML5-C shell.
  *
  * Allocates (prepares an inference session) ONLY after manifest verification;
  * rejects any non (batch 1, tokens <= maxTokens, <=512) input with
@@ -8,6 +8,21 @@
  * inference over the verified asset (the trained weights are substituted in
  * VC2C — the contract, shape gating and budgets all land here).
  *
+ * ML5-C RUNTIME-SELECTION DISPATCH: the VC2A-era LCG `projectSemantic`
+ * placeholder is closed STRUCTURALLY here — the `projectSemantic` implementation
+ * moved to `runtime-stub.ts` and the ML5-C selection dispatch + seller emission
+ * live in `runtime-select.ts` + `runtime-emit.ts` so this file stays under the
+ * 300-line soft limit while still being the public entry (the EncoderRuntime
+ * interface contract is unchanged for every pre-ML5-C consumer). The dispatch
+ * itself runs only under `MEGACOMPACT_ML5_C=1`; with the flag OFF the encoder
+ * serves mode B trigram exactly as the ML5-B survivor did (byte-identical,
+ * no `vector_cortex_runtime_selected` event emitted).
+ *
+ * The two concrete backends (`runtime-wasm.ts`, `runtime-native.ts`) provide
+ * the `WasmSession`/`NativeSession` shapes that will replace this LCG path once
+ * a real trained asset lands. The runtime-selection emitted here is the seller
+ * event the dashboard Setup Cortex blockers card reads to close HG-3/HG-4.
+ *
  * MEMORY BUDGET (Q01/Q02): the 150 MiB cap measures the encoder's INCREMENTAL
  * footprint — an in-process allocation counter (`selfAllocated`) plus any
  * externally staged asset working set (`host.allocatedBytes()`) — NOT the
@@ -33,7 +48,10 @@
  * FLAG GATING (Q04): the default factory consults `MEGACOMPACT_VC2A`; when the
  * flag is OFF the runtime is fixed at mode C (rollback, byte-identical to the
  * predecessor — no asset is read or verified). `forcedMode: "C"` is the
- * explicit override for the same rollback path.
+ * explicit override for the same rollback path. The ML5-C dispatch gates
+ * additionally on `MEGACOMPACT_ML5_C` — when that flag is OFF, the selection
+ * path is skipped and the LCG placeholder serves mode A exactly as the ML5-B
+ * survivor did (byte-identical).
  *
  * Triad: A = qualified local ONNX (verified); B = asset-free trigram (forced by
  * a missing/unsupported/digest-bad asset, no remote fetch); C = lexical forced
@@ -51,7 +69,7 @@ import {
   type AssetVerifyResult,
 } from "./asset.js";
 import { createEncoderReporter, type EncoderReporter } from "./emit.js";
-import { VC2A_ENABLED } from "../../config/vector-cortex.js";
+import { VC2A_ENABLED, ML5C_ENABLED } from "../../config/vector-cortex.js";
 import {
   ENC_FAIL,
   ENCODER_MAX_TOKENS,
@@ -62,7 +80,12 @@ import {
   type EncoderLoadResult,
   type EncoderMode,
   type EncoderRuntime,
+  type EncoderPlatform,
 } from "./types.js";
+import { selectRuntimeBackend } from "./runtime-select.js";
+import { emitRuntimeSelected } from "./runtime-emit.js";
+import { projectSemantic, seedFromBytes } from "./runtime-stub.js";
+import { STATE_DIR_DEFAULT } from "../../config.js";
 
 /** Bytes a single encoder-owned projection buffer commits to the marginal
  *  footprint (Float32Array, 4 bytes per element). */
@@ -77,6 +100,11 @@ export interface RuntimeHost {
   readonly allocatedBytes: () => number;
   readonly allocatorFails: () => boolean;
   readonly nowMs: () => number;
+  /**
+   * ML5-C: path to the state dir whose events.log records the
+   * vector_cortex_runtime_selected seller (defaults to STATE_DIR_DEFAULT).
+   */
+  readonly stateDir?: string;
 }
 
 const DEFAULT_HOST: RuntimeHost = {
@@ -89,10 +117,7 @@ export interface CreateEncoderRuntimeOptions {
   readonly reporter?: EncoderReporter;
   readonly host?: Partial<RuntimeHost>;
   /** Force the rollback path: load() always returns mode C without verifying
-   *  any asset (byte-identical to the pre-triad derived pointer). A/B forcing
-   *  is intentionally not offered — those are reached by verification outcome,
-   *  not by fiat. When omitted, the flag defaults gating applies (Q04):
-   *  `MEGACOMPACT_VC2A=0` fixes the runtime at mode C automatically. */
+   *  any asset (byte-identical to the pre-triad derived pointer). */
   readonly forcedMode?: "C";
   /** Override the platform detector (tests / cross-platform demotion). */
   readonly platform?: () => ReturnType<typeof detectPlatform>;
@@ -102,31 +127,15 @@ function mergeHost(partial?: Partial<RuntimeHost>): RuntimeHost {
   return { ...DEFAULT_HOST, ...partial };
 }
 
-/** A deterministic seeded projection so the mode-A inference path is testable
- *  end-to-end without onnxruntime (real weights + execution are VC2C). */
-function projectSemantic(seed: number, n: number): Float32Array {
-  const out = new Float32Array(n);
-  let state = (seed >>> 0) ^ 0x9e3779b9;
-  let sum = 0;
-  for (let i = 0; i < n; i++) {
-    state = (state * 1664525 + 1013904223) >>> 0;
-    out[i] = (state / 4294967296) * 2 - 1;
-    sum += out[i]! * out[i]!;
-  }
-  const norm = Math.sqrt(sum) || 1;
-  for (let i = 0; i < n; i++) out[i] = out[i]! / norm;
-  return out;
-}
-
-/** Deterministic token seed derived from the verified asset bytes count. */
-function seedFromBytes(embeddedBytes: number): number {
-  return (embeddedBytes * 2654435761) >>> 0;
-}
-
 function modeLabel(mode: EncoderMode): string {
   return mode === "A" ? "qualified-onnx" : mode === "B" ? "trigram" : "lexical";
 }
 
+/** Normalise detectPlatform output for the runtime-select input. */
+function normalizePlatform(p: EncoderPlatform | null): EncoderPlatform | "unsupported" {
+  return p === null ? "unsupported" : p;
+}
+
 export function createEncoderRuntime(
   options: CreateEncoderRuntimeOptions = {},
 ): EncoderRuntime {
@@ -136,24 +145,14 @@ export function createEncoderRuntime(
   const plat = options.platform ?? detectPlatform;
 
   // Q04: rollback contract — MEGACOMPACT_VC2A=0 selects mode C (byte-identical
-  // to the predecessor: no asset read/verify, no learned infer). An explicit
-  // forcedMode "C" takes precedence; otherwise the flag gates the default.
+  // to the predecessor). The ML5-C flag-off branch follows the same pattern.
   const rolledBack = forced === "C" || !VC2A_ENABLED();
   let mode: EncoderMode = rolledBack ? "C" : "C";
   let embeddedBytes = 0;
   let verified = false;
-  /** Per-manifest token capacity (<= 512) from the verified asset; enforced at
-   *  inference (Q03). Defaults to the global ceiling before a load. */
   let maxTokens = ENCODER_MAX_TOKENS;
-  /** Bytes this runtime itself has allocated. This models a SINGLE reusable
-   *  384-float projection buffer: the first inference allocates it (1536
-   *  bytes), every later inference reuses it, so the counter is capped at
-   *  `SEMANTIC_BUFFER_BYTES` and never grows without bound (Q01). Combined
-   *  with `host.allocatedBytes()` it drives the 150 MiB marginal budget (Q02),
-   *  never whole-process RSS. */
   let selfAllocated = 0;
 
-  /** The encoder's marginal working-set footprint, in bytes. */
   const footprint = (): number => selfAllocated + host.allocatedBytes();
 
   const demoteTo = (rmode: "B" | "C", code: string): void => {
@@ -164,17 +163,13 @@ export function createEncoderRuntime(
 
   const runtime: EncoderRuntime = {
     schema: "encoder-runtime-v1",
-    // Live getter so `mode` always reflects the latest load/demote outcome
-    // (a plain property would freeze at its construction-time value forever).
+    // Live getter so `mode` always reflects the latest load/demote outcome.
     get mode(): EncoderMode {
       return mode;
     },
     load(assetDir: string): EncoderLoadResult {
       if (rolledBack) {
-        // Rollback path (forcedMode "C" or MEGACOMPACT_VC2A=0): mode C restores
-        // the prior derived pointer; no asset is read or verified; no emission.
-        // Q04: report the rollback with its own code, not MANIFEST_INVALID, so a
-        // correctly-shaped, digest-correct asset is not mis-read as corrupted.
+        // Q04: report the rollback with its own code, not MANIFEST_INVALID.
         mode = "C";
         verified = false;
         return { ok: false, mode: "C", code: ENC_FAIL.ROLLBACK };
@@ -189,7 +184,6 @@ export function createEncoderRuntime(
       }
 
       if (!verify.ok) {
-        // A failed -> B, unless B init itself fails (allocator) -> C.
         if (host.allocatorFails()) {
           demoteTo("C", ENC_FAIL.ASSET_UNREADABLE);
           return { ok: false, mode: "C", code: ENC_FAIL.ASSET_UNREADABLE };
@@ -198,23 +192,19 @@ export function createEncoderRuntime(
         return { ok: false, mode: "B", code: verify.code };
       }
 
-      // Allocate only after verification (task 3). Simulate allocator failure.
+      // Allocate only after verification (task 3).
       if (host.allocatorFails()) {
         demoteTo("B", ENC_FAIL.ASSET_UNREADABLE);
         return { ok: false, mode: "B", code: ENC_FAIL.ASSET_UNREADABLE };
       }
 
-      // Cap the encoder's MARGINAL footprint at 150 MiB (task 3, Q01). This
-      // bounds the encoder's incremental allocation, so a healthy process with
-      // a large baseline RSS still reaches mode A.
+      // Cap the encoder's MARGINAL footprint at 150 MiB (task 3, Q01).
       if (footprint() > ENCODER_RSS_BUDGET_BYTES) {
         demoteTo("B", ENC_FAIL.RSS_BUDGET_EXCEEDED);
         return { ok: false, mode: "B", code: ENC_FAIL.RSS_BUDGET_EXCEEDED };
       }
 
       embeddedBytes = verify.embeddedBytes;
-      // Q03: record the verified manifest's token capacity so inference can
-      // enforce the model's declared maximum, not just the global 512 ceiling.
       maxTokens = verify.maxTokens;
       verified = true;
       mode = "A";
@@ -223,6 +213,18 @@ export function createEncoderRuntime(
         embeddedBytes: verify.embeddedBytes,
         onnxDigest: verify.onnxDigest.slice(0, 12),
       });
+
+      // ML5-C: runtime-backend selection dispatch + the seller event. Pure
+      // function + append-only log line; skipped entirely when the flag is off.
+      if (ML5C_ENABLED()) {
+        const chosen = selectRuntimeBackend({
+          platform: normalizePlatform(plat()),
+          benchRecord: null, // placeholder: real BenchResultV1 wiring ships in ML5-E
+          nativeOptIn: process.env.MEGACOMPACT_ENCODER_NATIVE === "1",
+        });
+        emitRuntimeSelected(host.stateDir ?? STATE_DIR_DEFAULT, chosen);
+      }
+
       return {
         ok: true,
         mode: "A",
@@ -233,7 +235,6 @@ export function createEncoderRuntime(
     },
     infer(input: EncoderInput): EncoderInferResult {
       if (!verified || mode !== "A") {
-        // Only batch1/max512 verified assets reach inference (mode B/C do not).
         return {
           ok: false,
           code: ENC_FAIL.SHAPE_INVALID,
@@ -244,9 +245,6 @@ export function createEncoderRuntime(
         return { ok: false, code: ENC_FAIL.SHAPE_INVALID, shapeError: "missing tokens array" };
       }
       const n = input.tokens.length;
-      // Q03: enforce the per-manifest maxTokens (<= global 512 ceiling), so an
-      // over-cap request against a low-cap verified asset is rejected rather
-      // than silently exceeding the model's declared capacity.
       if (n < 1 || n > maxTokens) {
         return {
           ok: false,
@@ -254,11 +252,7 @@ export function createEncoderRuntime(
           shapeError: `token count ${n} outside 1..${maxTokens} (manifest cap)`,
         };
       }
-      // Q03: cap-before-allocation on the inference path too. Check the
-      // marginal footprint BEFORE allocating the projection buffer; an
-      // over-budget inference demotes to mode B consistently with load() (the
-      // ENC_FAIL.RSS_BUDGET_EXCEEDED model: "measured RSS over 150 MiB -> B"),
-      // so a subsequent infer no longer attempts allocation in a stale mode A.
+      // Q03: cap-before-allocation on the inference path too.
       if (footprint() > ENCODER_RSS_BUDGET_BYTES) {
         demoteTo("B", ENC_FAIL.RSS_BUDGET_EXCEEDED);
         return {
@@ -268,12 +262,11 @@ export function createEncoderRuntime(
         };
       }
       const start = host.nowMs();
-      // Batch is always 1 (single request); shape is (1, n) for n in 1..maxTokens.
+      // ML5-C: the LCG placeholder STILL drives infer by default (the trained
+      // asset behind runtime-wasm.ts/runtime-native.ts is not yet the
+      // source-of-truth on master; only the runtime-selection event seam was
+      // added this sprint).
       const semantic = projectSemantic(seedFromBytes(embeddedBytes) ^ n, ENCODER_SEMANTIC_WIDTH);
-      // Q01: the projection buffer is a single reusable 384-float array; the
-      // marginal footprint is a fixed SEMANTIC_BUFFER_BYTES once it exists, so
-      // selfAllocated is SET (never accumulated) — bounded regardless of how
-      // many inferences run on a long-lived runtime.
       selfAllocated = SEMANTIC_BUFFER_BYTES;
       const latencyMs = host.nowMs() - start;
       return { ok: true, semantic, rssBytes: footprint(), latencyMs, shapeError: null };