pi-mega-compact 0.20.46 → 0.20.48

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

@@ -25,13 +25,40 @@ import type { EncoderPlatform } from "./types.js";
 /** Backend demotion disposition for a platform row. */
 export type BackendDemotion = "none" | "wasm" | "modeB";
 
-/** One platform row: the concrete runtime + install size + demotion disposition. */
+/**
+ * One platform row: the concrete runtime + install size + demotion disposition.
+ *
+ * `demotionReason` is the ENC-0e canonical reason string for a demoted platform
+ * (single source of truth — no literals scattered in routes or the event writer).
+ */
 export interface EncoderPlatformRow {
   readonly runtime: string;
   readonly installMiB: number;
   readonly demotion: BackendDemotion;
+  readonly demotionReason?: string;
 }
 
+/**
+ * The ENC-0e canonical darwin-x64 demotion reason (HG-4 / ENC-0e).
+ *
+ * macOS Intel has no native onnxruntime-node binary upstream (arm64-only; a
+ * darwin-x64 transform-class package ships only WASM), so the runtime demotes
+ * to mode-B WASM. This is the SINGLE canonical string — consumed by
+ * runtime-select.ts (the runtime-selection event) and the Setup Cortex blockers
+ * card. No string literal for this reason survives anywhere else.
+ */
+export const DARWIN_X64_DEMOTION_REASON =
+  "darwin-x64: no native binary upstream (arm64-only); mode-B WASM per HG-4";
+
+/**
+ * Deterministic sentinel used when a darwin-x64 platform-matrix row is missing
+ * the `demotionReason` string (unique-failure injection per the ENC-0e spec):
+ * the selection must still choose mode-B WASM, never throw, and never fabricate
+ * a native claim — the reason just falls back to this sentinel.
+ */
+export const DARWIN_X64_DEMOTION_REASON_SENTINEL =
+  "darwin-x64: demoted to WASM (reason unavailable in platform matrix)";
+
 /**
  * EncoderBackendDecisionV1 — the locked learned-encoder runtime-backend decision.
  *

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

@@ -0,0 +1,83 @@
+/**
+ * vector-cortex/encoder/qualify.ts — ENC-0f pure qualification function.
+ *
+ * Constructs a {@link QualificationV1} record from a {@link BenchResultV1} by
+ * asserting four independent gates (latency, marginal-RSS, determinism, opset)
+ * plus the bench's own conjunctive `gates.all`. A gated-off bench can NEVER be
+ * swept into mode A by a sub-threshold p95 alone — `bench_gates_not_green`
+ * forces `"failed"` regardless of the sub-threshold values.
+ *
+ * Pure (TRIAD_RESILIENCE §pure): no `any` (PREVENT-011), no casts, no clock, no
+ * storage, no network (PREVENT-PI-004). Thresholds are sourced from
+ * {@link ENCODER_LATENCY_P95_MS} / {@link ENCODER_RSS_BUDGET_BYTES} /
+ * {@link ENCODER_OPSET} — never magic numbers.
+ */
+
+import type { BenchResultV1 } from "./bench-export.js";
+import {
+  ENCODER_LATENCY_P95_MS,
+  ENCODER_RSS_BUDGET_BYTES,
+  ENCODER_OPSET,
+} from "./types.js";
+
+/** The qualification verdict for a real trained encoder asset. */
+export interface QualificationV1 {
+  readonly schema: "qualification-v1";
+  readonly verdict: "qualified" | "failed";
+  readonly reasons: string[];
+  readonly platform: string;
+  readonly p95Ms: number;
+  readonly rssMib: number;
+  readonly opset: number;
+  /** SHA-256 hex of the bench run's embedding output (never payload content). */
+  readonly digest: string;
+}
+
+/**
+ * Qualify a bench result against the four independent gates + the bench's own
+ * conjunctive gate. Returns a QualificationV1 with `verdict:"qualified"` only
+ * when ALL gates pass and `bench.gates.all` is true.
+ */
+export function qualifyEncodedAsset(
+  bench: BenchResultV1,
+  platform: string,
+): QualificationV1 {
+  const reasons: string[] = [];
+
+  if (bench.p95Ms !== null && bench.p95Ms > ENCODER_LATENCY_P95_MS) {
+    reasons.push("latency");
+  }
+
+  if (
+    bench.rssMarginalMib !== null &&
+    bench.rssMarginalMib * 1024 * 1024 > ENCODER_RSS_BUDGET_BYTES
+  ) {
+    reasons.push("rss");
+  }
+
+  if (!bench.deterministic) {
+    reasons.push("determinism");
+  }
+
+  if (bench.opset !== null && bench.opset !== ENCODER_OPSET) {
+    reasons.push("opset");
+  }
+
+  if (!bench.gates.all && !reasons.includes("bench_gates_not_green")) {
+    reasons.push("bench_gates_not_green");
+  }
+
+  const verdict: "qualified" | "failed" =
+    reasons.length === 0 && bench.gates.all ? "qualified" : "failed";
+
+  return {
+    schema: "qualification-v1",
+    verdict,
+    reasons,
+    platform,
+    p95Ms: bench.p95Ms ?? 0,
+    rssMib: bench.rssMarginalMib ?? 0,
+    opset: bench.opset ?? 0,
+    digest: bench.digest ?? "",
+  };
+}

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

@@ -22,16 +22,29 @@ 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.
+ * The event carries ONLY the aggregate fields the sprint specs pin
+ * ({backend, p95Ms, budgetOk, platform}) plus the ENC-0e additively-carried
+ * `demotionReason` (non-null only on a demoted platform under flag ON) —
+ * never message content. The event writer never throws.
  */
 export function emitRuntimeSelected(
   stateDir: string,
-  result: Pick<RuntimeSelectionResult, "backend" | "p95Ms" | "budgetOk" | "platform">,
+  result: Pick<
+    RuntimeSelectionResult,
+    "backend" | "p95Ms" | "budgetOk" | "platform" | "demotionReason"
+  >,
 ): void {
   try {
     const path = defaultEventsPath(stateDir);
-    const payload = {
+    const payload: {
+      ts: number;
+      event: string;
+      backend: string;
+      p95Ms: number | null;
+      budgetOk: boolean;
+      platform: string;
+      demotionReason?: string;
+    } = {
       ts: Date.now(),
       event: "vector_cortex_runtime_selected",
       backend: result.backend,
@@ -39,6 +52,10 @@ export function emitRuntimeSelected(
       budgetOk: result.budgetOk,
       platform: result.platform,
     };
+    // ENC-0e: carry the demotion reason additively, only when present.
+    if (result.demotionReason !== null && result.demotionReason !== undefined) {
+      payload.demotionReason = result.demotionReason;
+    }
     mkdirSync(dirname(path), { recursive: true });
     appendFileSync(path, JSON.stringify(payload) + "\n", "utf8");
   } catch {

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

@@ -24,7 +24,12 @@ import {
   type EncoderPlatform,
 } from "./types.js";
 import type { BenchResultV1 } from "./bench-export.js";
-import { ML5C_ENABLED } from "../../config/vector-cortex.js";
+import { ML5C_ENABLED, ENC_0E_ENABLED } from "../../config/vector-cortex.js";
+import type { EncoderPlatformRow } from "./decision.js";
+import {
+  DARWIN_X64_DEMOTION_REASON,
+  DARWIN_X64_DEMOTION_REASON_SENTINEL,
+} from "./decision.js";
 
 /** The chosen runtime backend name as it appears on the seller event. */
 export type RuntimeBackendChoice = "wasm" | "native" | "modeB";
@@ -56,6 +61,12 @@ export interface RuntimeSelectionResult {
   readonly platform: string;
   /** Short human-readable rationale for the choice (record on the event). */
   readonly rationale: string;
+  /**
+   * ENC-0e explicit demotion reason (non-null ONLY on a demoted platform under
+   * `MEGACOMPACT_ENC_0E`). Null on every other platform and on flag-off, so the
+   * flag-off selection is byte-identical to the ENC-0d predecessor.
+   */
+  readonly demotionReason: string | null;
 }
 
 /** The 80 MiB install budget in bytes (the HG-3 ceiling, unamended). */
@@ -99,6 +110,7 @@ export function selectRuntimeBackend(input: RuntimeSelectionInput): RuntimeSelec
       p95Ms: null,
       platform: input.platform,
       rationale: "flag-off: byte-identical mode-B trigram (no selection)",
+      demotionReason: null,
     };
   }
 
@@ -110,6 +122,12 @@ export function selectRuntimeBackend(input: RuntimeSelectionInput): RuntimeSelec
       p95Ms: null,
       platform: input.platform,
       rationale: "darwin-x64 demoted to WASM per HG-4 (never native on this platform)",
+      // ENC-0e: the reason is the single canonical string from the ENC-0a
+      // platform matrix (decision.ts). Under flag-off the reason is stripped
+      // (null), keeping the flag-off selection byte-identical to the ENC-0d
+      // predecessor. If the matrix row ever lacks the reason, fall back to a
+      // deterministic sentinel — never throw, never fabricate a native claim.
+      demotionReason: ENC_0E_ENABLED() ? darwinX64DemotionReason(undefined) : null,
     };
   }
 
@@ -127,6 +145,7 @@ export function selectRuntimeBackend(input: RuntimeSelectionInput): RuntimeSelec
       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`,
+      demotionReason: null,
     };
   }
 
@@ -142,6 +161,7 @@ export function selectRuntimeBackend(input: RuntimeSelectionInput): RuntimeSelec
       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)`,
+      demotionReason: null,
     };
   }
 
@@ -154,6 +174,7 @@ export function selectRuntimeBackend(input: RuntimeSelectionInput): RuntimeSelec
       p95Ms: input.benchRecord.p95Ms,
       platform: input.platform,
       rationale: `WASM qualifies: p95 ${input.benchRecord.p95Ms}ms <= ${ENCODER_LATENCY_P95_MS}ms`,
+      demotionReason: null,
     };
   }
 
@@ -163,5 +184,29 @@ export function selectRuntimeBackend(input: RuntimeSelectionInput): RuntimeSelec
     p95Ms: input.benchRecord.p95Ms,
     platform: input.platform,
     rationale: `native required: p95 ${input.benchRecord.p95Ms}ms > ${ENCODER_LATENCY_P95_MS}ms on WASM`,
+    demotionReason: null,
   };
 }
+
+/**
+ * ENC-0e — resolve the canonical darwin-x64 demotion reason (pure).
+ *
+ * `provider` is the ENC-0a platform-matrix row for darwin-x64 if the caller has
+ * one (the resolver owns a concrete matrix; runtime-select normally passes
+ * none and falls back to the canonical constant). Resolution order:
+ *   1. the provider row's `demotionReason` (single canonical source);
+ *   2. the canonical DARWIN_X64_DEMOTION_REASON constant;
+ *   3. the deterministic SENTINEL when a row EXISTS but lacks the reason
+ *      (unique-failure injection per ENC-0e) — never a throw, never a
+ *      fabricated native claim.
+ * Kept pure so tests inject the platform seam with no real Mac.
+ */
+export function darwinX64DemotionReason(provider: EncoderPlatformRow | undefined): string {
+  if (provider) {
+    if (provider.demotionReason && provider.demotionReason.length > 0) {
+      return provider.demotionReason;
+    }
+    return DARWIN_X64_DEMOTION_REASON_SENTINEL;
+  }
+  return DARWIN_X64_DEMOTION_REASON;
+}