pi-mega-compact 0.20.51 → 0.20.53

package/extensions/dashboard-server/api-contracts/setup.ts

@@ -55,6 +55,15 @@ export interface SetupStatusResponse {
    *  falls back (e.g. native selected but onnxruntime-node absent / darwin-x64
    *  demoted), surfaced verbatim; null when no demotion (additive, flag-gated). */
   readonly encoderDemotionReason?: string | null;
+  /** ENC-2a: the persisted `MEGACOMPACT_NATIVE_ORT_BUDGET_MIB` value as its
+   *  numeric string, when configured (additive, flag-gated). Absent when the
+   *  operator has not set the knob. */
+  readonly nativeOrtBudgetMib?: string;
+  /** ENC-2a: the EFFECTIVE budget `installBudgetMib()` resolves to (integer
+   *  MiB as a numeric string), so the dashboard can show the runtime's actual
+   *  operand — persists even when `nativeOrtBudgetMib` is absent because the
+   *  runtime applies the default when unset. Additive, flag-gated. */
+  readonly nativeOrtBudgetEffectiveMib?: string;
 }
 
 /**
@@ -119,6 +128,10 @@ export interface SetupConfigureRequest {
   /** ENC-1b: opt in to `MEGACOMPACT_ENCODER_NATIVE` (onnxruntime-node native
    *  backend; additive, flag-gated). */
   readonly encoderNativeOptIn?: boolean;
+  /** ENC-2a: persisted `MEGACOMPACT_NATIVE_ORT_BUDGET_MIB` install budget as a
+   *  positive integer string within `ENC_2BUDGET_MAX_MIB` (validated; additive,
+   *  flag-gated). */
+  readonly nativeOrtBudgetMib?: string;
 }
 
 /** Response for POST /api/setup-configure. */

package/extensions/dashboard-server/api-contracts/vector-cortex-ledger.ts

@@ -0,0 +1,39 @@
+/**
+ * api-contracts/vector-cortex-ledger.ts — VC1B occurrence-ledger surface.
+ *
+ * Extracted from `vector-cortex.ts` so the combined api-contracts module stays
+ * under the 400-line `extensions/` soft limit. Owns the reader-only ledger
+ * views (VC1B aggregate + identity rows). PREVENT-PI-004: type definitions
+ * only, no network code. PREVENT-011: no `any` type.
+ */
+
+/** Live-state derivation shared across the VC views (mirrors vector-cortex.ts). */
+type VcStatus = "live" | "awaiting_data" | "deferred" | "structural" | "off";
+
+/**
+ * Reader-only occurrence-ledger identity view for GET /api/vector-cortex/ledger (VC1B).
+ * Built on the LedgerReader capability surface. Exposes occurrence IDENTITY
+ * (seq/eventId/kind/digest/toolCallId) and the per-session high-water/count —
+ * NEVER sourceBytes or prompt text, honoring the reader-only no-ledger-text rule.
+ */
+export interface VectorCortexLedgerView {
+  /** Whether the VC1B occurrence ledger flag is enabled in this process. */
+  readonly enabled: boolean;
+  /** The ledger session whose occurrences are returned. */
+  readonly session: string;
+  /** Durable contiguous high-water (stringified bigint) for the session. */
+  readonly highWater: string;
+  /** Number of accepted occurrences for the session. */
+  readonly count: number;
+  /** Capped identity rows (ascending seq). No source bytes, never payload text. */
+  readonly occurrences: readonly {
+    readonly seq: string;
+    readonly eventId: string;
+    readonly kind: string;
+    readonly digest: string;
+    readonly toolCallId?: string;
+  }[];
+  /** ISO timestamp of the snapshot. */
+  readonly updatedAt: string;
+  readonly status?: VcStatus;
+}

package/extensions/dashboard-server/api-contracts/vector-cortex.ts

@@ -44,6 +44,13 @@ export interface VectorCortexEvaluationSummary {
   };
   /** Evaluator rejections (EVAL_*) observed in this window. */
   readonly rejects: readonly string[];
+  /**
+   * ML5-D dashboard "Improve Cortex" flag state. Additive and omitted when
+   * MEGACOMPACT_ML5_D is off, so the client omits the ModelImprovementCard
+   * (byte-identical to the ML5-C-era tab). Present (true) only when the flag
+   * is enabled. Reader-only aggregate — never job verdicts or training bytes.
+   */
+  readonly ml5dEnabled?: boolean;
   /** ISO timestamp of the summary. */
   readonly updatedAt: string;
   readonly status?: VcStatus;
@@ -365,36 +372,11 @@ export interface VectorCortexRolloutView {
   readonly status?: VcStatus;
 }
 
-/**
- * Reader-only occurrence-ledger identity view for GET /api/vector-cortex/ledger (VC1B).
- * Built on the LedgerReader capability surface. Exposes occurrence IDENTITY
- * (seq/eventId/kind/digest/toolCallId) and the per-session high-water/count —
- * NEVER sourceBytes or prompt text, honoring the reader-only no-ledger-text rule.
- */
-export interface VectorCortexLedgerView {
-  /** Whether the VC1B occurrence ledger flag is enabled in this process. */
-  readonly enabled: boolean;
-  /** The ledger session whose occurrences are returned. */
-  readonly session: string;
-  /** Durable contiguous high-water (stringified bigint) for the session. */
-  readonly highWater: string;
-  /** Number of accepted occurrences for the session. */
-  readonly count: number;
-  /** Capped identity rows (ascending seq). No source bytes, never payload text. */
-  readonly occurrences: readonly {
-    readonly seq: string;
-    readonly eventId: string;
-    readonly kind: string;
-    readonly digest: string;
-    readonly toolCallId?: string;
-  }[];
-  /** ISO timestamp of the snapshot. */
-  readonly updatedAt: string;
-  readonly status?: VcStatus;
-}
-
 export type {
   VectorCortexClosureProofView,
   VectorCortexRestoreView,
   VectorCortexRepairView,
 } from "./vector-cortex-heal.js";
+export type {
+  VectorCortexLedgerView,
+} from "./vector-cortex-ledger.js";

package/extensions/dashboard-server/routes-rag-settings-vector-cortex.ts

@@ -306,5 +306,11 @@ export const VECTOR_CORTEX_SETTINGS: SettingGroup = {
 			"ENC-1b completes the embedder API Settings surface (dim / headers / allow-remote persisted to the per-repo .mega-compact.env) and surfaces the ONNX runtime selection knob (MEGACOMPACT_ENCODER_NATIVE) as a toggle plus the current effective backend + demotion reason. OFF = no new GET fields, no writer branch, no new Settings rows or toggle (byte-identical ENC-1a predecessor).",
 			true,
 		),
+		boolDirect(
+			"MEGACOMPACT_ENC_2BUDGET",
+			"ENC-2a operator-configurable native install-budget knob",
+			"ENC-2a exposes the runtime operator knob MEGACOMPACT_NATIVE_ORT_BUDGET_MIB (default 300 MiB, clamp 8192) as a dashboard Settings field. The knob gates budgetOk in the encoder runtime decision (decision.ts installBudgetMib + runtime-select.ts selectRuntimeBackend). Persisted to the per-repo .mega-compact.env via the setup-configure writer branch; the GET status route surfaces the persisted value AND the effective integer installBudgetMib() resolves to (so the dashboard shows the runtime's actual operand). OFF = no new GET fields, no writer branch, no new Settings rows (byte-identical ENC-1b predecessor).",
+			true,
+		),
 	],
 };

package/extensions/dashboard-server/routes-setup-enc2budget.ts

@@ -0,0 +1,171 @@
+/**
+ * dashboard-server/routes-setup-enc2budget.ts — ENC-2a operator-configurable
+ * native onnxruntime install budget (MiB) Settings read/write + the additive
+ * writer branch.
+ *
+ * Extracted out of routes-setup.ts (which hovers at the 300-line source soft
+ * cap, mirroring the ENC-1a/ENC-1b sibling extracts) so the ENC-2a additive
+ * read/write of the per-repo `.mega-compact.env` key lives in a sibling impl
+ * file. One key is managed here: `MEGACOMPACT_NATIVE_ORT_BUDGET_MIB` — the exact
+ * name `installBudgetMib()` (`src/vector-cortex/encoder/decision.ts`) reads at
+ * runtime.
+ *
+ * The write is create-or-append: it upserts the key into the existing per-repo
+ * `.mega-compact.env`, preserving every unrelated line and never deleting
+ * another key. The read reports the persisted raw string AND the effective
+ * integer `installBudgetMib()` resolves to (so the dashboard shows what the
+ * runtime will actually use — including the 300 MiB default fallback when the
+ * knob is unset or invalid). Reader-only: setter/getter never reimplements
+ * `installBudgetMib()`'s clamp rule, it imports it.
+ *
+ * Guardrails: PREVENT-PI-004 (local filesystem reads/writes only — zero
+ * network), PREVENT-001 (null-safe), PREVENT-011 (no `any`).
+ */
+
+import { writeFileSync, mkdirSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import {
+  ENC_2BUDGET_ENABLED,
+  ENC_2BUDGET_MAX_MIB,
+  ENC_2BUDGET_NATIVE_ORT_BUDGET_ENV,
+} from "../../src/config/vector-cortex.js";
+import {
+  installBudgetMib,
+  resolveInstallBudgetMib,
+} from "../../src/vector-cortex/encoder/decision.js";
+import type { SetupConfigureRequest } from "./api-contracts/setup.js";
+
+function envPath(stateDir: string): string {
+  return join(stateDir, ".mega-compact.env");
+}
+
+/** Extract the value of `export MEGACOMPACT_X="..."` (or unquoted) from a line. */
+function lineValue(line: string, key: string): string | null {
+  const m = line.match(new RegExp(`^export\\s+${key}=(.*)$`));
+  if (!m) return null;
+  const rest = m[1].trim();
+  if (rest.length === 0) return null;
+  const q = rest.match(/^"([^"]*)"$/);
+  return q ? q[1] : rest;
+}
+
+/** True when the payload carries the ENC-2a key (flag-gated). */
+export function wantsEnc2Budget(body: SetupConfigureRequest): boolean {
+  return ENC_2BUDGET_ENABLED() && typeof body.nativeOrtBudgetMib === "string";
+}
+
+/** Read the ENC-2a knob from the per-repo `.mega-compact.env`. Returns the raw
+ *  persisted string when present, or null when absent. */
+export function readEnc2BudgetEnv(stateDir: string): { raw: string | null } {
+  try {
+    const p = envPath(stateDir);
+    if (!existsSync(p)) return { raw: null };
+    const lines = readFileSync(p, "utf8").split(/\r?\n/);
+    for (const line of lines) {
+      const v = lineValue(line, ENC_2BUDGET_NATIVE_ORT_BUDGET_ENV);
+      if (v !== null && v.length > 0) return { raw: v };
+    }
+    return { raw: null };
+  } catch {
+    return { raw: null };
+  }
+}
+
+/**
+ * ENC-2a additive GET status fields. Omitted when flag-off. Surfaces the raw
+ * persisted value (when set) AND the effective runtime operand — the integer
+ * MiB `installBudgetMib()` actually resolves to. Reading `installBudgetMib()`
+ * here (instead of reimplementing the clamp) keeps the dashboard honest when
+ * the env var is unset or out-of-range.
+ */
+export function enc2BudgetStatusFields(stateDir: string): {
+  nativeOrtBudgetMib?: string;
+  nativeOrtBudgetEffectiveMib?: string;
+} {
+  if (!ENC_2BUDGET_ENABLED()) return {};
+  const { raw } = readEnc2BudgetEnv(stateDir);
+  // The EFFECTIVE operand is what the runtime WILL use: if a value has been
+  // persisted to the disk file, resolve THAT through the clamp (the operator
+  // just POSTed it; the running process has not re-sourced `.mega-compact.env`
+  // yet so `installBudgetMib()` reads the stale env). On restart the saved
+  // value is what the runtime loads. When nothing is persisted, fall back to
+  // the live env var / process.env (= `installBudgetMib()`).
+  const effective = raw !== null ? resolveInstallBudgetMib(raw) : installBudgetMib();
+  return {
+    ...(raw !== null ? { nativeOrtBudgetMib: raw } : {}),
+    nativeOrtBudgetEffectiveMib: String(effective),
+  };
+}
+
+/** Upsert the ENC-2a knob into the per-repo `.mega-compact.env`. Creates the
+ *  file if absent; preserves every unrelated line; never deletes other keys.
+ *  `entries.raw === null` leaves the key's line untouched. */
+export function writeEnc2BudgetEnv(
+  stateDir: string,
+  entries: { raw?: string | null },
+): string {
+  const p = envPath(stateDir);
+  const existingLines: string[] = existsSync(p) ? readFileSync(p, "utf8").split(/\r?\n/) : [];
+  const out: string[] = [];
+  let written = false;
+  for (const line of existingLines) {
+    if (
+      entries.raw !== null &&
+      entries.raw !== undefined &&
+      lineValue(line, ENC_2BUDGET_NATIVE_ORT_BUDGET_ENV) !== null
+    ) {
+      out.push(`export ${ENC_2BUDGET_NATIVE_ORT_BUDGET_ENV}="${entries.raw}"`);
+      written = true;
+      continue;
+    }
+    out.push(line);
+  }
+  if (entries.raw !== null && entries.raw !== undefined && !written) {
+    out.push(`export ${ENC_2BUDGET_NATIVE_ORT_BUDGET_ENV}="${entries.raw}"`);
+  }
+  mkdirSync(stateDir, { recursive: true });
+  writeFileSync(p, out.join("\n"), "utf-8");
+  return p;
+}
+
+/** Validate `nativeOrtBudgetMib` as a positive integer string within
+ *  `ENC_2BUDGET_MAX_MIB`. Returns `null` when valid, else the error code.
+ *  Exported so the routes host (combined-payload path) and the aggregator share
+ *  the same rule. */
+export function validateNativeOrtBudgetMib(value: unknown): string | null {
+  if (typeof value !== "string" || value.trim().length === 0) return "invalid_native_ort_budget_mib";
+  if (!/^\d+$/.test(value)) return "invalid_native_ort_budget_mib";
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n < 1 || n > ENC_2BUDGET_MAX_MIB) {
+    return "invalid_native_ort_budget_mib";
+  }
+
+  return null;
+}
+
+/**
+ * Combined-payload upsert: after the main embedder write has freshly written
+ * the per-repo env, append the ENC-2a key when carried alongside a valid
+ * embedder selection (flag-gated, additive). No-op when flag-off or no ENC-2a
+ * key present.
+ */
+export function tryEnc2BudgetInto(stateDir: string, body: SetupConfigureRequest): void {
+  if (!wantsEnc2Budget(body)) return;
+  writeEnc2BudgetEnv(stateDir, {
+    raw: typeof body.nativeOrtBudgetMib === "string" ? body.nativeOrtBudgetMib : null,
+  });
+}
+
+/**
+ * Combined-path validation: the routes host runs this before the combined
+ * upsert when a payload ALSO carries a valid embedder — returned as the error
+ * code string, or `null` if validation passes (or the flag is off).
+ */
+export function enc2BudgetValidateCombined(body: SetupConfigureRequest): string | null {
+  if (!ENC_2BUDGET_ENABLED()) return null;
+  if (body.nativeOrtBudgetMib !== undefined) {
+    const e = validateNativeOrtBudgetMib(body.nativeOrtBudgetMib);
+    if (e !== null) return e;
+  }
+  return null;
+}

package/extensions/dashboard-server/routes-setup.ts

@@ -16,6 +16,11 @@ import type { RouteContext } from "./routes-core.js";
 import { VC9D_ENABLED } from "../../src/config.js";
 import { enc1aStatusFields, writeEnc1aEnv, tryEnc1aConfigure, wantsEnc1a } from "./routes-setup-enc1a.js";
 import { enc1bStatusFields, tryEnc1bConfigure, tryEnc1bInto, enc1bValidateCombined } from "./routes-setup-enc1b.js";
+import {
+	enc2BudgetStatusFields,
+	tryEnc2BudgetInto,
+	enc2BudgetValidateCombined,
+} from "./routes-setup-enc2budget.js";
 import { writeEmbedderEnv } from "./routes-setup-env-upsert.js";
 import {
 	detectOllama,
@@ -94,6 +99,7 @@ export function handleSetupStatus(
 			(process.env["MEGACOMPACT_MINILM"] ?? "").trim().toLowerCase(),
 		),
 		...enc1aStatusFields(ctx.stateDir), ...enc1bStatusFields(ctx.stateDir),
+		...enc2BudgetStatusFields(ctx.stateDir),
 	};
 	// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
 	res.writeHead(200, { "Content-Type": "application/json" });
@@ -232,6 +238,18 @@ export function handleSetupConfigure(
 			res.end(JSON.stringify({ error: combinedError }));
 			return;
 		}
+		// ENC-2a combined-payload validation: when a payload carries a valid
+		// embedder PLUS the budget key, validate the budget BEFORE the upsert so
+		// the combined path is rejected with the same 400 code. Flag-off:
+		// enc2BudgetValidateCombined returns null (byte-identical predecessor —
+		// the unknown key falls through untouched).
+		const budgetCombinedError = enc2BudgetValidateCombined(body);
+		if (budgetCombinedError !== null) {
+			// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+			res.writeHead(400, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ error: budgetCombinedError }));
+			return;
+		}
 		const embedder = body.embedder;
 		if (embedder !== "ollama" && embedder !== "llama" && embedder !== "trigram" && embedder !== "custom" && embedder !== "onnx") {
 			res.writeHead(400, { "Content-Type": "application/json" });
@@ -281,6 +299,7 @@ export function handleSetupConfigure(
 			});
 		}
 		tryEnc1bInto(stateDir, body); // ENC-1b combined upsert (dim/headers/allow-remote/native)
+		tryEnc2BudgetInto(stateDir, body); // ENC-2a combined upsert (native budget MiB)
 		// Detect if the new config matches what's already active (no restart needed).
 		const currentUrl = process.env["MEGACOMPACT_EMBEDDING_URL"];
 		const alreadyActive = (resolvedUrl === null && !currentUrl) || (resolvedUrl !== null && currentUrl === resolvedUrl);

package/extensions/dashboard-server/routes-vector-cortex-eval.ts

@@ -12,7 +12,7 @@
 
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteContext } from "./routes-core.js";
-import { VC0A_ENABLED } from "../../src/config.js";
+import { VC0A_ENABLED, ML5D_ENABLED } from "../../src/config.js";
 import { readEvalRows } from "../../src/vector-cortex/eval/persist.js";
 import { summarizeEvalRows } from "../../src/vector-cortex/eval/reader.js";
 import { sendJson } from "./routes-vector-cortex-shared.js";
@@ -53,6 +53,9 @@ export function handleVectorCortexEvaluation(
       total: summary.histogram.total,
     },
     rejects: [], // VC0C wires live breaker/reject telemetry here
+    // ML5-D: additive, present only when the flag is enabled → the client can
+    // omit the ModelImprovementCard when off (byte-identical to ML5-C-era tab).
+    ...(ML5D_ENABLED() ? { ml5dEnabled: true } : {}),
     updatedAt: new Date().toISOString(),
     status: deriveVcStatus({ enabled, hasData: summary.samples > 0 }),
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.51",
+  "version": "0.20.53",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",

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

@@ -0,0 +1,51 @@
+/**
+ * config/vector-cortex-enc2budget.ts — ENC-2a operator-configurable native
+ * onnxruntime install-budget knob (dashboard Settings surface).
+ *
+ * Sibling of vector-cortex-enc1a.ts / vector-cortex-enc1b.ts so vector-cortex.ts
+ * stays under the 300-line soft limit (soft-as-hard gate). vector-cortex.ts
+ * re-exports the flag + constants below and root src/config.ts re-exports them,
+ * so no consumer import path changes.
+ *
+ * ENC-2a exposes the runtime's operator knob `MEGACOMPACT_NATIVE_ORT_BUDGET_MIB`
+ * as a dashboard Settings field. The knob itself is read at runtime by
+ * `installBudgetMib()` (`src/vector-cortex/encoder/decision.ts`) and gates the
+ * `budgetOk` decision in `src/vector-cortex/encoder/runtime-select.ts`. Setting
+ * it persists to the per-repo `.mega-compact.env` via the same upsert-writer
+ * path ENC-1a/ENC-1b use (never the global state dir — see the
+ * `statedir-per-repo-vs-global` memory).
+ *
+ * Bounds (mirror `decision.ts` clamp): positive integer, 1..8192 MiB. Out-of-
+ * range input is rejected by validation (400) and falls back to the default
+ * (300) in `installBudgetMib()` at runtime. Default 300 MiB was set on
+ * 2026-08-07 when the user lifted the prior 80 MiB restriction ("remove the
+ * 80mb limit that wasn't my design decision" → "set it to a number that is in
+ * the dashboard that defaults to lets say 300mb").
+ *
+ * `MEGACOMPACT_ENC_2BUDGET=0` disables: no new GET fields, no writer branch, no
+ * new Settings rows — byte-identical to the ENC-1b predecessor. The flag MUST
+ * also be a dashboard SETTINGS toggle (visible in config UI, never in
+ * EXCLUDED_SETTINGS — see `feedback_dashboard-flags-toggleable` memory).
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { sprintFlag } from "./vector-cortex-flag.js";
+
+/** ENC-2a knob: persisted env name, read by `installBudgetMib()` at runtime. */
+export const ENC_2BUDGET_NATIVE_ORT_BUDGET_ENV = "MEGACOMPACT_NATIVE_ORT_BUDGET_MIB";
+
+/** Upper bound on the budget (MiB). Mirrors decision.ts's clamp. */
+export const ENC_2BUDGET_MAX_MIB = 8192;
+
+/** Default budget (MiB) when the env var is unset or invalid. */
+export const ENC_2BUDGET_DEFAULT_MIB = 300;
+
+/**
+ * ENC-2a — operator-configurable native install budget Settings surface.
+ * Default ON. `MEGACOMPACT_ENC_2BUDGET=0` disables and is byte-identical to the
+ * ENC-1b predecessor: no new GET fields, no writer branch, no new Settings rows.
+ * This flag MUST also be a dashboard SETTINGS toggle (visible in config UI,
+ * never in EXCLUDED_SETTINGS).
+ */
+export const ENC_2BUDGET_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_ENC_2BUDGET");

package/src/config/vector-cortex.ts

@@ -71,6 +71,12 @@ export {
   ENC_1B_ALLOW_REMOTE_EMBEDDER_ENV,
   ENC_1B_ENCODER_NATIVE_ENV,
 } from "./vector-cortex-enc1b.js";
+export {
+  ENC_2BUDGET_ENABLED,
+  ENC_2BUDGET_NATIVE_ORT_BUDGET_ENV,
+  ENC_2BUDGET_MAX_MIB,
+  ENC_2BUDGET_DEFAULT_MIB,
+} from "./vector-cortex-enc2budget.js";
 // Breaker constants (TRIAD_RESILIENCE.md §breaker) extracted to vector-cortex-breakers.ts.
 export {
   BREAKER_WINDOW_MS,

package/src/config.ts

@@ -198,6 +198,10 @@ export {
   ENC_0G_ENABLED,
   ENC_1A_ENABLED,
   ENC_1B_ENABLED,
+  ENC_2BUDGET_ENABLED,
+  ENC_2BUDGET_NATIVE_ORT_BUDGET_ENV,
+  ENC_2BUDGET_MAX_MIB,
+  ENC_2BUDGET_DEFAULT_MIB,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

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

@@ -3,9 +3,10 @@
  *
  * The durable EncoderBackendDecisionV1 record: which ONNX runtime backend the
  * real learned encoder ships on (transformers.js/WASM vs onnxruntime-node
- * native), whether the 80 MiB install budget holds, the per-platform install
- * matrix, the opset baseline (locked 21 by ENC-0a), the license verdict, and
- * the pinned model/tokenizer sha256 digests.
+ * native), whether the configurable install budget holds (default 300 MiB;
+ * operator-overridable via `MEGACOMPACT_NATIVE_ORT_BUDGET_MIB`), the per-platform
+ * install matrix, the opset baseline (locked 21 by ENC-0a), the license
+ * verdict, and the pinned model/tokenizer sha256 digests.
  *
  * ENC-0a is the DECISION + MEASUREMENT sprint: this contract is what the
  * deterministic resolver (`scripts/encoder/resolve-backend-decision.mjs`) and
@@ -83,10 +84,40 @@ export interface EncoderBackendDecisionV1 {
 }
 
 /**
- * The normative ENC-0a budget: the 80 MiB install/asset cap (MODEL_ASSET.md
- * §Qualification). Backend qualifies (budgetOk) iff the shipped byte-count fits.
+ * The operator-configurable native-ort install byte-budget (MiB). Default 300
+ * (shipped 5-platform ~160 MiB comfortably fits); override via
+ * `MEGACOMPACT_NATIVE_ORT_BUDGET_MIB`. Safe upper clamp `INSTALL_BUDGET_CLAMP_MIB`
+ * rejects absurd values. Backend qualifies (`budgetOk`) iff the shipped
+ * byte-count fits the configured budget.
  */
-export const ENCODER_INSTALL_BUDGET_MIB = 80;
+export const INSTALL_BUDGET_CLAMP_MIB = 8192;
+export const INSTALL_BUDGET_DEFAULT_MIB = 300;
+
+/**
+ * Pure resolver: given a raw string (or null/undefined when the env var is
+ * unset), return the integer budget the runtime will use. Out-of-range /
+ * non-integer / empty input falls back to the default. Exported so the
+ * dashboard Settings surface can compute the EFFECTIVE operand from a
+ * persisted-but-not-yet-env-loaded value (the operator just POSTed a new
+ * budget to disk; the running process has not sourced `.mega-compact.env`,
+ * so `installBudgetMib()` reads the stale env, but the dashboard should show
+ * what the runtime WILL use after the restart the dashboard itself tells the
+ * operator is required).
+ */
+export function resolveInstallBudgetMib(
+  raw: string | null | undefined,
+): number {
+  if (raw === undefined || raw === null || raw === "") return INSTALL_BUDGET_DEFAULT_MIB;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n <= 0 || n > INSTALL_BUDGET_CLAMP_MIB) {
+    return INSTALL_BUDGET_DEFAULT_MIB;
+  }
+  return n;
+}
+
+export function installBudgetMib(): number {
+  return resolveInstallBudgetMib(process.env.MEGACOMPACT_NATIVE_ORT_BUDGET_MIB);
+}
 
 /** The p95 latency gate at 512 tokens / 4 threads on linux-x64 (ms). */
 export const ENCODER_DECISION_P95_MS = 40;

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

@@ -25,6 +25,7 @@ import {
 } from "./types.js";
 import type { BenchResultV1 } from "./bench-export.js";
 import { ML5C_ENABLED, ENC_0E_ENABLED } from "../../config/vector-cortex.js";
+import { installBudgetMib } from "./decision.js";
 import type { EncoderPlatformRow } from "./decision.js";
 import {
   DARWIN_X64_DEMOTION_REASON,
@@ -53,7 +54,7 @@ export interface RuntimeSelectionInput {
 export interface RuntimeSelectionResult {
   /** The chosen backend. */
   readonly backend: RuntimeBackendChoice;
-  /** HG-3 closure state: whether the 80 MiB install budget is satisfied. */
+  /** HG-3 closure state: whether the operator-configured install budget (`MEGACOMPACT_NATIVE_ORT_BUDGET_MIB`, default 300 MiB) is satisfied. */
   readonly budgetOk: boolean;
   /** The measured p95 (ms) that drove the decision, from BenchResultV1. */
   readonly p95Ms: number | null;
@@ -69,17 +70,14 @@ export interface RuntimeSelectionResult {
   readonly demotionReason: string | null;
 }
 
-/** 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.
+ * included so the resolver lands on a concrete row at install time). Compared
+ * against the configurable install budget (`installBudgetMib()`, default 300
+ * MiB) to set `budgetOk` — the per-host INSTALLED footprint (one row only,
+ * 28–35 MiB) is irrelevant to this ceiling; the budget covers the shipped
+ * tarball, not the single-platform install.
  */
 export const NATIVE_FOOTPRINT_MIB: Readonly<Record<EncoderPlatform, number>> = {
   "linux-x64": 33,
@@ -132,41 +130,43 @@ export function selectRuntimeBackend(input: RuntimeSelectionInput): RuntimeSelec
   }
 
   // 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).
+  // The budget compares the SHIPPED byte-count (sum across every platform row
+  // in the package's optionalDependencies map) against the configurable
+  // `installBudgetMib()` ceiling (default 300 MiB; operator-overridable). At
+  // the default, shipped ~160 MiB fits — budgetOk:true. The operator may lower
+  // it (e.g. 100) to surface a budget breach in `budgetOk:false` and the
+  // rationale string; the decision rule does not gate on it.
   if (input.nativeOptIn) {
     const shippedMib = Object.values(NATIVE_FOOTPRINT_MIB).reduce((a, b) => a + b, 0);
+    const budgetMib = installBudgetMib();
     return {
       backend: "native",
-      budgetOk: shippedMib <= RUNTIME_NATIVE_INSTALL_BUDGET_MIB,
+      budgetOk: shippedMib <= budgetMib,
       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`,
+      rationale: `native opt-in (MEGACOMPACT_ENCODER_NATIVE=1); shipped ${shippedMib} MiB across 5 platforms vs ${budgetMib} MiB budget`,
       demotionReason: null,
     };
   }
 
   // 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.
+  // with the SAME budget comparison as the opt-in path above (configurable).
   if (!input.benchRecord || !input.benchRecord.gates.all || input.benchRecord.p95Ms === null) {
     const shippedMib = Object.values(NATIVE_FOOTPRINT_MIB).reduce((a, b) => a + b, 0);
+    const budgetMib = installBudgetMib();
     return {
       backend: "native",
-      budgetOk: false, // amended: native ships > 80 MiB across the 5-platform matrix
+      budgetOk: shippedMib <= budgetMib,
       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)`,
+      rationale: `no qualifying bench record — native fallback (shipped ${shippedMib} MiB vs ${budgetMib} MiB budget)`,
       demotionReason: null,
     };
   }
 
   // The decision rule: WASM iff p95 <= 40 ms (linux-x64, 512 tokens, 4 threads) —
-  // native required otherwise, with the same budget amendment recorded.
+  // native required otherwise, with the same configurable budget comparison.
   if (input.benchRecord.p95Ms <= ENCODER_LATENCY_P95_MS) {
     return {
       backend: "wasm",
@@ -178,12 +178,14 @@ export function selectRuntimeBackend(input: RuntimeSelectionInput): RuntimeSelec
     };
   }
 
+  const shippedMib = Object.values(NATIVE_FOOTPRINT_MIB).reduce((a, b) => a + b, 0);
+  const budgetMib = installBudgetMib();
   return {
     backend: "native",
-    budgetOk: false, // amended: native exceeds the 80 MiB budget per the evidence
+    budgetOk: shippedMib <= budgetMib,
     p95Ms: input.benchRecord.p95Ms,
     platform: input.platform,
-    rationale: `native required: p95 ${input.benchRecord.p95Ms}ms > ${ENCODER_LATENCY_P95_MS}ms on WASM`,
+    rationale: `native required: p95 ${input.benchRecord.p95Ms}ms > ${ENCODER_LATENCY_P95_MS}ms on WASM (shipped ${shippedMib} MiB vs ${budgetMib} MiB budget)`,
     demotionReason: null,
   };
 }

package/src/vector-cortex/setup-cortex-blockers-compute.ts

@@ -85,11 +85,11 @@ export const SETUP_CORTEX_BLOCKERS: readonly SetupCortexBlockerV1[] = [
   },
   {
     id: "HG-3",
-    title: "onnxruntime-node install exceeds the 80 MiB asset budget",
+    title: "native onnxruntime-node install path unresolved (needs operator install + probe), currently demoted to WASM",
     severity: "blocker",
     status: "open",
     resolution:
-      "onnxruntime-node bundles ~258 MiB across all platforms. Candidate: transformers.js v4.2.0 (9.5 MiB shell, pure-Node via onnxruntime-web WASM) measured against budget + p95 gate before committing.",
+      "operator-run install of the pinned onnxruntime-node version into ~/.pi/mega-compact/native-ort, then re-run the ENC-0f qualification gate. The install byte-budget is operator-configurable (MEGACOMPACT_NATIVE_ORT_BUDGET_MIB, default 300 MiB; shipped 5-platform ~160 MiB fits at the default).",
   },
   {
     id: "HG-4",