pi-mega-compact 0.20.45 → 0.20.47

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

@@ -0,0 +1,63 @@
+/**
+ * vector-cortex/encoder/promotion-emit.ts — ENC-0d promotion event writers.
+ *
+ * Writes the three real-asset promotion events to the monitoring `events.log`
+ * as structured append-only JSON lines via the existing `logBenchEvent` seam
+ * (`src/monitoring.ts`):
+ *
+ *   - `vector_cortex_asset_promoted`      (green digest-verified swap)
+ *   - `vector_cortex_asset_demoted`       (red qualification / digest failure)
+ *   - `vector_cortex_asset_rollback_back` (restore of a prior stack digest)
+ *
+ * Non-fatal and log-and-swallow: a write failure never breaks the agent loop
+ * (best-effort store/write contract). Each line is `{ts, event, ...fields}`
+ * shaped so the dashboard live-stream tail and evidence tooling parse it
+ * identically to every other monitoring event. Events carry digests, colors
+ * and verdicts ONLY — never message content (EVAL-REDACT-002).
+ *
+ * The path defaults to the standard state-dir events.log (mirrors
+ * defaultEventsPath). Zero network, no `any` (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { defaultEventsPath, logBenchEvent } from "../../monitoring.js";
+import { getStateDir } from "../../store.js";
+
+/** Default events.log beside the state dir (mirrors bench.ts). */
+export function promotionEventsPath(stateDir: string = getStateDir()): string {
+  return defaultEventsPath(stateDir);
+}
+
+/** The promotion event kinds this emitter can write. */
+export type PromotionEventKind =
+  | "promoted"
+  | "demoted"
+  | "rollback_back";
+
+const EVENT_NAME: Record<PromotionEventKind, string> = {
+  promoted: "vector_cortex_asset_promoted",
+  demoted: "vector_cortex_asset_demoted",
+  rollback_back: "vector_cortex_asset_rollback_back",
+};
+
+/** Fields carried by a promotion event: digests, colors and verdicts only.
+ *  Never any payload or message content (EVAL-REDACT-002). */
+export interface PromotionEventFields {
+  readonly color: "green" | "red";
+  readonly assetDigest: string | null;
+  readonly priorAssetDigest: string | null;
+  readonly verdict: string;
+}
+
+/**
+ * Append one promotion event to events.log (best-effort, non-fatal). The line
+ * is `{ts, event, ...fields}` shaped, written append-only via the monitoring
+ * logBenchEvent seam. On any write failure the event is swallowed — the agent
+ * loop is never broken.
+ */
+export function appendPromotionEvent(
+  path: string,
+  kind: PromotionEventKind,
+  fields: PromotionEventFields,
+): void {
+  logBenchEvent(path, EVENT_NAME[kind], { ...fields });
+}

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

@@ -14,6 +14,15 @@
  * an atomic digest swap (flip the committed pointer to the prior entry's
  * digest in one step) — no partial state is possible because the swap is a
  * single value assignment.
+ *
+ * ENC-0d extends the ledger to the real-asset promotion path: `PromotionV1`
+ * carries `{color, assetDigestStack}` — a promotion color from gate
+ * qualification ("green" atomically swaps to the trained asset, "red" keeps
+ * the prior asset live) and a LIFO of prior shipped digest for O(1)-by-sha256
+ * rollback. The on-disk manifest byte-swap itself (write-temp-then-rename,
+ * never in-place partial) is the promotion gate script's job; these helpers
+ * stay pure and return the restorable digest + the updated manifest/stack so
+ * the script can perform the swap in one atomic step.
  */
 
 // ---------------------------------------------------------------------------
@@ -54,6 +63,13 @@ export interface PromotionV1 {
   readonly verdict: "promoted" | "demoted" | "noop";
   /** Present only when verdict is "demoted": the demotion event name. */
   readonly demotedEvent: "demoted_new_asset" | null;
+  /** ENC-0d promotion color from gate qualification. "green" atomically swaps
+   *  the shipped manifest to the trained asset; "red" keeps the prior asset
+   *  live and emits a demotion. */
+  readonly color: "green" | "red";
+  /** ENC-0d LIFO of prior shipped asset digests for O(1)-by-sha256 rollback.
+   *  The most recent prior digest (top of the stack) is the rollback target. */
+  readonly assetDigestStack: readonly string[];
 }
 
 // ---------------------------------------------------------------------------
@@ -104,6 +120,85 @@ export function rollbackTo(
   };
 }
 
+// ---------------------------------------------------------------------------
+// ENC-0d LIFO rollback stack + atomic swap. Pure pointer arithmetic; the
+// on-disk write-temp-then-rename of the swapped manifest bytes is the gate
+// script's job so no partial state can ever be observed (PREVENT-PI-004).
+// ---------------------------------------------------------------------------
+
+/** Push a freshly-shipped digest onto the LIFO rollback stack (top = latest
+ *  prior shipped digest). Non-mutating: returns a new array. */
+export function pushAssetDigest(
+  stack: readonly string[],
+  digest: string,
+): readonly string[] {
+  return [...stack, digest];
+}
+
+/** Pop the top (most recent prior) digest off the LIFO rollback stack without
+ *  mutating it. Returns the prior digest (null when the stack is empty) plus
+ *  the remaining stack for the caller to commit (atomic card-swap fallback:
+ *  a green swap pushes the incumbent digest; a rollback pops it). */
+export function popAssetDigest(
+  stack: readonly string[],
+): { prior: string | null; rest: readonly string[] } {
+  if (stack.length === 0) return { prior: null, rest: stack };
+  const rest = stack.slice(0, -1);
+  return { prior: stack[stack.length - 1]!, rest };
+}
+
+/** Outcome of an atomic promotion swap (pure): the (possibly restored)
+ *  manifest, the updated rollback stack, and whether a digest swap occurred. */
+export interface AtomicSwapOutcome {
+  readonly manifest: AssetManifest;
+  readonly stack: readonly string[];
+  /** True when the committed pointer changed (green swap or rollback). */
+  readonly swapped: boolean;
+}
+
+/** Atomically swap the committed manifest to a real trained asset's digest.
+ *  Green: append the new entry (append-only — the incumbent stays in the
+ *  ledger, never overwritten), commit to it, and record the INCUMBENT digest
+ *  onto the LIFO stack for O(1) rollback (rollback restores the incumbent, so
+ *  the stack must hold the pre-swap committed digest — pushing the swapped-in
+ *  digest would point rollback back at the very asset being rolled back). Red
+ *  (or no candidate digest): return the manifest and stack untouched — no
+ *  swap, prior asset stays live. */
+export function atomicSwap(
+  manifest: AssetManifest,
+  entry: AssetManifestEntry,
+  color: "green" | "red",
+  stack: readonly string[],
+): AtomicSwapOutcome {
+  if (color !== "green" || !entry.assetDigest) {
+    return { manifest, stack, swapped: false };
+  }
+  const incumbent = manifest.committed;
+  const next = appendAsset(manifest, entry);
+  return {
+    manifest: next,
+    stack: incumbent === null ? stack : pushAssetDigest(stack, incumbent),
+    swapped: true,
+  };
+}
+
+/** Roll back to the previous shipped asset by SHA-256 (O(1) via the LIFO
+ *  stack): restores the most recent prior digest in the manifest and pops that
+ *  entry off the stack. Returns null when no prior digest exists or the prior
+ *  digest is no longer in the append-only manifest (defensive: append-only
+ *  means it should always be findable). Never leaves a partial state — the
+ *  committed pointer flip and the stack pop happen together or not at all. */
+export function assetRollback(
+  manifest: AssetManifest,
+  stack: readonly string[],
+): AtomicSwapOutcome | null {
+  const { prior, rest } = popAssetDigest(stack);
+  if (prior === null) return null;
+  const restored = rollbackTo(manifest, prior);
+  if (!restored) return null;
+  return { manifest: restored, stack: rest, swapped: true };
+}
+
 // ---------------------------------------------------------------------------
 // Pure decision rules.
 // ---------------------------------------------------------------------------

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;
+}