pi-mega-compact 0.20.50 → 0.20.51

package/dist/config/vector-cortex-enc1b.js

@@ -0,0 +1,46 @@
+/**
+ * config/vector-cortex-enc1b.ts — ENC-1b ONNX runtime backend + embedder API
+ * Settings fields.
+ *
+ * Extracted from vector-cortex.ts so that file stays under the 300-line soft
+ * limit (soft-as-hard gate), exactly as the ENC-1a sibling was. vector-cortex.ts
+ * re-exports the flag + constants below and root src/config.ts re-exports them,
+ * so no consumer import path changes.
+ *
+ * ENC-1b adds two Settings surfaces. (A) Embedder API completion: the three
+ * remaining env vars the runtime reads (src/httpEmbedder.ts:embeddingConfigFromEnv)
+ * gain dashboard-visible fields — `MEGACOMPACT_EMBEDDING_DIM` (numeric, validated
+ * positive int bounded by `ENC_1B_MAX_EMBEDDING_DIM`), `MEGACOMPACT_EMBEDDING_HEADERS`
+ * (JSON object string — secret-bearing, written verbatim to the per-repo
+ * `.mega-compact.env`, NEVER echoed raw; the GET reports only a boolean
+ * presence marker), and `MEGACOMPACT_ALLOW_REMOTE_EMBEDDER` (boolDirect toggle,
+ * default off — a deliberate escape hatch that skips the loopback-only check).
+ * (B) ONNX runtime selection surface: `MEGACOMPACT_ENCODER_NATIVE` is persisted
+ * to the per-repo env + surfaced as a Settings toggle, and the GET status route
+ * computes the current effective backend + demotion reason through the existing
+ * `selectRuntimeBackend` (reader-only — no selection literals reimplemented).
+ *
+ * `MEGACOMPACT_ENC_1B=0` disables: no new GET fields, no writer branch, no new
+ * Settings rows or toggle — byte-identical to the ENC-1a predecessor. The flag
+ * MUST also be a dashboard SETTINGS toggle (visible in config UI, never in
+ * EXCLUDED_SETTINGS).
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ */
+import { sprintFlag } from "./vector-cortex-flag.js";
+/** ENC-1b `MEGACOMPACT_EMBEDDING_DIM` upper bound (positive integer string). */
+export const ENC_1B_MAX_EMBEDDING_DIM = 8192;
+/** Persisted env names pinned here so the aggregator scan + the routes share
+ *  one source of truth (exactly the names embeddingConfigFromEnv reads). */
+export const ENC_1B_EMBEDDING_DIM_ENV = "MEGACOMPACT_EMBEDDING_DIM";
+export const ENC_1B_EMBEDDING_HEADERS_ENV = "MEGACOMPACT_EMBEDDING_HEADERS";
+export const ENC_1B_ALLOW_REMOTE_EMBEDDER_ENV = "MEGACOMPACT_ALLOW_REMOTE_EMBEDDER";
+export const ENC_1B_ENCODER_NATIVE_ENV = "MEGACOMPACT_ENCODER_NATIVE";
+/**
+ * ENC-1b — ONNX runtime backend + embedder API Settings fields. Default ON.
+ * `MEGACOMPACT_ENC_1B=0` disables and is byte-identical to the ENC-1a
+ * predecessor: no new GET fields, no writer branch, no new Settings rows or
+ * toggle. This flag MUST also be a dashboard SETTINGS toggle (visible in config
+ * UI, never in EXCLUDED_SETTINGS).
+ */
+export const ENC_1B_ENABLED = () => sprintFlag("MEGACOMPACT_ENC_1B");

package/dist/config/vector-cortex.js

@@ -33,5 +33,6 @@ export { ENC_0E_ENABLED } from "./vector-cortex-enc0e.js";
 export { ENC_0F_ENABLED } from "./vector-cortex-enc0f.js";
 export { ENC_0G_ENABLED } from "./vector-cortex-enc0g.js";
 export { ENC_1A_ENABLED } from "./vector-cortex-enc1a.js";
+export { ENC_1B_ENABLED, ENC_1B_MAX_EMBEDDING_DIM, ENC_1B_EMBEDDING_DIM_ENV, ENC_1B_EMBEDDING_HEADERS_ENV, ENC_1B_ALLOW_REMOTE_EMBEDDER_ENV, ENC_1B_ENCODER_NATIVE_ENV, } from "./vector-cortex-enc1b.js";
 // Breaker constants (TRIAD_RESILIENCE.md §breaker) extracted to vector-cortex-breakers.ts.
 export { BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./vector-cortex-breakers.js";

package/dist/config.js

@@ -114,4 +114,4 @@ export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
 // default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
 // so root consumers share one source of truth.
 // ---------------------------------------------------------------------------
-export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, VC7B_ENABLED, VC7C_ENABLED, VC8A_ENABLED, VC8B_ENABLED, VC8C_ENABLED, VC9A_ENABLED, VC9B_ENABLED, VC9C_ENABLED, VC9D_ENABLED, PCC_ENABLED, ML5A_ENABLED, ML5B_ENABLED, ML5C_ENABLED, ML5D_ENABLED, ML5E_ENABLED, DEDUP_ATTR_ENABLED, ENC_0A_ENABLED, ENC_0B_ENABLED, ENC_0C_ENABLED, ENC_0D_ENABLED, ENC_0E_ENABLED, ENC_0F_ENABLED, ENC_0G_ENABLED, ENC_1A_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, VC7B_ENABLED, VC7C_ENABLED, VC8A_ENABLED, VC8B_ENABLED, VC8C_ENABLED, VC9A_ENABLED, VC9B_ENABLED, VC9C_ENABLED, VC9D_ENABLED, PCC_ENABLED, ML5A_ENABLED, ML5B_ENABLED, ML5C_ENABLED, ML5D_ENABLED, ML5E_ENABLED, DEDUP_ATTR_ENABLED, ENC_0A_ENABLED, ENC_0B_ENABLED, ENC_0C_ENABLED, ENC_0D_ENABLED, ENC_0E_ENABLED, ENC_0F_ENABLED, ENC_0G_ENABLED, ENC_1A_ENABLED, ENC_1B_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";

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

@@ -66,5 +66,6 @@ export const VECTOR_CORTEX_SETTINGS = {
         boolDirect("MEGACOMPACT_ENC_0F", "ENC-0f p95 + marginal-RSS Qualification Gate", "ENC-0f p95 + marginal-RSS qualification gate (real trained asset → mode A): runs the ENC-0d-promoted trained asset through the bench under --expose-gc, asserts p95 ≤ 40 ms @ 512/4 threads, marginal RSS ≤ 150 MiB (baseline-subtracted), determinism, and opset-21; on pass emits QualificationV1 + flips runtime to qualified mode A, on failure asset stays demoted to mode B. OFF = no qualification gate runs, no QualificationV1 written, runtime keeps serving the ENC-0d survivor (byte-identical predecessor).", true),
         boolDirect("MEGACOMPACT_ENC_0G", "ENC-0g Setup Cortex honest state (verdict override + live blockers)", "ENC-0g makes the Setup Cortex status route honest: reads the ENC-0f QualificationV1 record (when ENC_0F is ON and a record exists) and lets its verdict override the structural verify for the qualification field; computes the blocker list from (platform, record, manifest head-count) with corrected HG statuses/wording; re-derives VC9B action gating from live blockers. OFF = verdict from verifyEncoderAsset alone, static SETUP_CORTEX_BLOCKERS, static action gating (byte-identical ENC-0f predecessor).", true),
         boolDirect("MEGACOMPACT_ENC_1A", "ENC-1a external embedder API key + endpoint Settings fields", "ENC-1a adds a Settings-visible field pair for the external embedder endpoint URL + optional Bearer API key, persisted by the setup-configure writer branch to the per-repo .mega-compact.env (MEGACOMPACT_EMBEDDING_URL / MEGACOMPACT_EMBEDDING_KEY). The GET status route echoes the endpoint URL and reports embeddingApiKeySet as a boolean ONLY — the raw key is never returned. OFF = no new GET fields, no writer branch, no new Settings text rows (byte-identical ENC-0g predecessor).", true),
+        boolDirect("MEGACOMPACT_ENC_1B", "ENC-1b ONNX runtime backend + embedder API settings", "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),
     ],
 };

package/dist/extensions/dashboard-server/routes-setup-enc1b.js

@@ -0,0 +1,297 @@
+/**
+ * dashboard-server/routes-setup-enc1b.ts — ENC-1b embedder API completion +
+ * ONNX runtime selection 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 sibling extract) so the ENC-1b additive read/write
+ * of the per-repo `.mega-compact.env` keys AND the runtime-backend computation
+ * live in a sibling impl file. Four keys are managed here:
+ * `MEGACOMPACT_EMBEDDING_DIM`, `MEGACOMPACT_EMBEDDING_HEADERS`,
+ * `MEGACOMPACT_ALLOW_REMOTE_EMBEDDER`, `MEGACOMPACT_ENCODER_NATIVE` — the exact
+ * names `embeddingConfigFromEnv` (src/httpEmbedder.ts) and the runtime selector
+ * read at runtime.
+ *
+ * The write is create-or-append: it upserts the four keys into the existing
+ * per-repo `.mega-compact.env`, preserving every unrelated line and never
+ * deleting another key. The read reports the persisted dim, booleans for
+ * headers-set / allow-remote / native-opt-in, and computes the current
+ * effective backend + demotion reason through the EXISTING `selectRuntimeBackend`
+ * (reader-only — the runtime's own selection, never a reimplemented literal,
+ * never install logic). The raw headers JSON is NEVER returned, logged or
+ * emitted (redaction invariant — it may carry secrets such as an Authorization
+ * header for a TEI/ONNX server).
+ *
+ * Guardrails: PREVENT-PI-004 (local filesystem reads/writes + in-memory
+ * runtime selection only, zero network), PREVENT-001 (null-safe JSON),
+ * PREVENT-011 (no `any`).
+ */
+import { writeFileSync, mkdirSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { ENC_1B_ENABLED, ENC_1B_MAX_EMBEDDING_DIM, ENC_1B_EMBEDDING_DIM_ENV, ENC_1B_EMBEDDING_HEADERS_ENV, ENC_1B_ALLOW_REMOTE_EMBEDDER_ENV, ENC_1B_ENCODER_NATIVE_ENV, } from "../../src/config/vector-cortex.js";
+import { selectRuntimeBackend } from "../../src/vector-cortex/encoder/runtime-select.js";
+import { detectPlatform } from "../../src/vector-cortex/encoder/asset.js";
+function envPath(stateDir) {
+    return join(stateDir, ".mega-compact.env");
+}
+/** Extract the value of `export MEGACOMPACT_X="..."` (or unquoted) from a line. */
+function lineValue(line, key) {
+    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 any ENC-1b key (flag-gated). */
+export function wantsEnc1b(body) {
+    return (ENC_1B_ENABLED() &&
+        (typeof body.embeddingDim === "string" ||
+            typeof body.embeddingHeaders === "string" ||
+            typeof body.allowRemoteEmbedder === "boolean" ||
+            typeof body.encoderNativeOptIn === "boolean"));
+}
+/** Read the ENC-1b keys from the per-repo `.mega-compact.env`. The headers
+ *  value is NEVER surfaced to callers — only its presence boolean. */
+export function readEnc1bEnv(stateDir) {
+    try {
+        const p = envPath(stateDir);
+        if (!existsSync(p))
+            return { dim: null, headersSet: false, allowRemote: false, nativeOptIn: false };
+        const lines = readFileSync(p, "utf8").split(/\r?\n/);
+        let dim = null;
+        let headersSet = false;
+        let allowRemote = false;
+        let nativeOptIn = false;
+        for (const line of lines) {
+            const d = lineValue(line, ENC_1B_EMBEDDING_DIM_ENV);
+            if (d !== null && d.length > 0)
+                dim = d;
+            const h = lineValue(line, ENC_1B_EMBEDDING_HEADERS_ENV);
+            if (h !== null && h.length > 0)
+                headersSet = true;
+            const a = lineValue(line, ENC_1B_ALLOW_REMOTE_EMBEDDER_ENV);
+            if (a !== null && ["1", "true", "yes"].includes(a.trim().toLowerCase()))
+                allowRemote = true;
+            const n = lineValue(line, ENC_1B_ENCODER_NATIVE_ENV);
+            if (n !== null && ["1", "true", "yes"].includes(n.trim().toLowerCase()))
+                nativeOptIn = true;
+        }
+        return { dim, headersSet, allowRemote, nativeOptIn };
+    }
+    catch {
+        return { dim: null, headersSet: false, allowRemote: false, nativeOptIn: false };
+    }
+}
+/**
+ * ENC-1b additive GET status fields. All omitted when flag-off. The Cortex
+ * trio (native opt-in + effective backend + demotion reason) is computed here
+ * (reader-only): the stored opt-in + current platform drive the EXISTING
+ * `selectRuntimeBackend`, whose own demotion reason is surfaced verbatim when
+ * the runtime falls back. `modeB` (flag-off selection) is projected to `wasm`
+ * for display. Returns `{}` when the flag is off (byte-identical predecessor).
+ */
+export function enc1bStatusFields(stateDir) {
+    if (!ENC_1B_ENABLED())
+        return {};
+    const env = readEnc1bEnv(stateDir);
+    const platform = detectPlatform();
+    const chosen = selectRuntimeBackend({
+        platform: platform ?? "unsupported",
+        benchRecord: null,
+        nativeOptIn: env.nativeOptIn,
+    });
+    const backend = chosen.backend === "native" ? "native" : "wasm";
+    return {
+        ...(env.dim !== null ? { embeddingDim: env.dim } : {}),
+        embeddingHeadersSet: env.headersSet,
+        allowRemoteEmbedder: env.allowRemote,
+        encoderNativeOptIn: env.nativeOptIn,
+        encoderBackend: backend,
+        encoderDemotionReason: chosen.demotionReason,
+    };
+}
+/** Upsert the ENC-1b keys into the per-repo `.mega-compact.env`. Creates the
+ *  file if absent; preserves every unrelated line; never deletes other keys.
+ *  A `null` entry leaves that key's line untouched. The headers value is
+ *  wrapped in single quotes so the inner JSON double quotes survive the env
+ *  loader's outer-quote strip (shell-sourceable + loader-compatible). */
+export function writeEnc1bEnv(stateDir, entries) {
+    const p = envPath(stateDir);
+    const existingLines = existsSync(p) ? readFileSync(p, "utf8").split(/\r?\n/) : [];
+    const out = [];
+    const keys = new Set([
+        {
+            key: ENC_1B_EMBEDDING_DIM_ENV,
+            present: () => entries.dim !== null,
+            push: () => out.push(`export ${ENC_1B_EMBEDDING_DIM_ENV}="${entries.dim ?? ""}"`),
+        },
+        {
+            key: ENC_1B_EMBEDDING_HEADERS_ENV,
+            present: () => entries.headers !== null,
+            push: () => out.push(`export ${ENC_1B_EMBEDDING_HEADERS_ENV}='${entries.headers ?? ""}'`),
+        },
+        {
+            key: ENC_1B_ALLOW_REMOTE_EMBEDDER_ENV,
+            present: () => entries.allowRemote !== null,
+            push: () => out.push(entries.allowRemote
+                ? `export ${ENC_1B_ALLOW_REMOTE_EMBEDDER_ENV}="1"`
+                : `export ${ENC_1B_ALLOW_REMOTE_EMBEDDER_ENV}="0"`),
+        },
+        {
+            key: ENC_1B_ENCODER_NATIVE_ENV,
+            present: () => entries.nativeOptIn !== null,
+            push: () => out.push(entries.nativeOptIn
+                ? `export ${ENC_1B_ENCODER_NATIVE_ENV}="1"`
+                : `export ${ENC_1B_ENCODER_NATIVE_ENV}="0"`),
+        },
+    ]);
+    const written = new Set();
+    for (const line of existingLines) {
+        let replaced = false;
+        for (const k of keys) {
+            if (k.present() && lineValue(line, k.key) !== null) {
+                k.push();
+                written.add(k.key);
+                replaced = true;
+                break;
+            }
+        }
+        if (!replaced)
+            out.push(line);
+    }
+    for (const k of keys) {
+        if (k.present() && !written.has(k.key))
+            k.push();
+    }
+    mkdirSync(stateDir, { recursive: true });
+    writeFileSync(p, out.join("\n"), "utf-8");
+    return p;
+}
+/** Validate `embeddingDim` as a positive integer string within the ENC-1b cap.
+ *  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 validateDim(value) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        return "invalid_embedding_dim";
+    if (!/^\d+$/.test(value))
+        return "invalid_embedding_dim";
+    const n = Number(value);
+    if (!Number.isSafeInteger(n) || n < 1 || n > ENC_1B_MAX_EMBEDDING_DIM) {
+        return "invalid_embedding_dim";
+    }
+    return null;
+}
+/** Validate `embeddingHeaders` as a string that parses to a JSON object.
+ *  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 validateHeaders(value) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        return "invalid_embedding_headers";
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        return "invalid_embedding_headers";
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return "invalid_embedding_headers";
+    }
+    return null;
+}
+/**
+ * Combined-payload upsert: after the main embedder write has freshly written
+ * the per-repo env, append any ENC-1b keys carried alongside a valid embedder
+ * selection (flag-gated, additive). No-op when flag-off or no ENC-1b key.
+ */
+export function tryEnc1bInto(stateDir, body) {
+    if (!wantsEnc1b(body))
+        return;
+    writeEnc1bEnv(stateDir, {
+        dim: typeof body.embeddingDim === "string" ? body.embeddingDim : null,
+        headers: typeof body.embeddingHeaders === "string" ? body.embeddingHeaders : null,
+        allowRemote: typeof body.allowRemoteEmbedder === "boolean" ? body.allowRemoteEmbedder : null,
+        nativeOptIn: typeof body.encoderNativeOptIn === "boolean" ? body.encoderNativeOptIn : null,
+    });
+}
+/**
+ * If the payload is a pure ENC-1b configure (new keys, no embedder selection),
+ * validate + write them additively to the per-repo env and reply. Returns true
+ * when it fully handled the request. On a validation failure it replies 400
+ * with the code and leaves the file byte-unchanged. Flag-off = keys are not
+ * recognized and this returns false (byte-identical ENC-1a predecessor).
+ */
+/**
+ * Combined-path validation: the standalone `tryEnc1bConfigure` handles the
+ * pure-ENC-1b shape; when a payload ALSO carries a valid embedder the sibling
+ * writer returns false and the routes host is responsible for running the same
+ * dim/headers validation before the combined upsert — returned as the error
+ * code string, or `null` if everything passes (or the flag is off).
+ */
+export function enc1bValidateCombined(body) {
+    if (!ENC_1B_ENABLED())
+        return null;
+    if (body.embeddingDim !== undefined) {
+        const e = validateDim(body.embeddingDim);
+        if (e !== null)
+            return e;
+    }
+    if (body.embeddingHeaders !== undefined) {
+        const e = validateHeaders(body.embeddingHeaders);
+        if (e !== null)
+            return e;
+    }
+    return null;
+}
+export function tryEnc1bConfigure(body, res, ctx) {
+    if (!wantsEnc1b(body))
+        return false;
+    const embedder = body.embedder;
+    const embedderValid = !!embedder &&
+        (embedder === "ollama" || embedder === "llama" || embedder === "trigram" ||
+            embedder === "custom" || embedder === "onnx");
+    if (embedderValid)
+        return false; // combined payload — integrated after the embedder write
+    // Each key is optional: only validate the ones actually carried in the
+    // payload (absent keys are left untouched, never rejected).
+    const dimError = body.embeddingDim === undefined ? null : validateDim(body.embeddingDim);
+    if (dimError !== null) {
+        // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: dimError }));
+        return true;
+    }
+    const headersError = body.embeddingHeaders === undefined ? null : validateHeaders(body.embeddingHeaders);
+    if (headersError !== null) {
+        // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: headersError }));
+        return true;
+    }
+    try {
+        const envPath = writeEnc1bEnv(ctx.stateDir, {
+            dim: typeof body.embeddingDim === "string" ? body.embeddingDim : null,
+            headers: typeof body.embeddingHeaders === "string" ? body.embeddingHeaders : null,
+            allowRemote: typeof body.allowRemoteEmbedder === "boolean" ? body.allowRemoteEmbedder : null,
+            nativeOptIn: typeof body.encoderNativeOptIn === "boolean" ? body.encoderNativeOptIn : null,
+        });
+        const resp = {
+            embedder: "custom",
+            url: null,
+            envPath,
+            restartRequired: true,
+            alreadyActive: false,
+        };
+        // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(resp));
+        return true;
+    }
+    catch (e) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: `write_failed: ${e instanceof Error ? e.message : String(e)}` }));
+        return true;
+    }
+}

package/dist/extensions/dashboard-server/routes-setup-env-upsert.js

@@ -0,0 +1,79 @@
+/**
+ * routes-setup-env-upsert.ts — upsert-style write of the per-repo
+ * `.mega-compact.env` for the primary embedder selection.
+ *
+ * Extracted from routes-setup.ts so the route stays under the 300-line soft
+ * cap. The writer preserves every unrelated line (ENC-1a's endpoint/key,
+ * ENC-1b's dim/headers, operator comments) and replaces only the three keys
+ * this primary write owns — MEGACOMPACT_EMBEDDING_URL,
+ * MEGACOMPACT_ALLOW_REMOTE_EMBEDDER, MEGACOMPACT_MINILM. URLs already persisted
+ * by enc1a/enc1b helpers are NOT clobbered across a later native-opt-in POST
+ * (the ENC-1b defect class caught in live review).
+ */
+import { writeFileSync, mkdirSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+/** Line-prefix recognizer for an owned key (covers active, commented, and prose forms). */
+function ownsKey(line, key) {
+    return (line.startsWith(`export ${key}=`) ||
+        line.startsWith(`# export ${key}=`) ||
+        line.startsWith(`# ${key} `));
+}
+const OWNED_PREFIXES = [
+    "MEGACOMPACT_EMBEDDING_URL",
+    "MEGACOMPACT_ALLOW_REMOTE_EMBEDDER",
+    "MEGACOMPACT_MINILM",
+];
+const SCAFFOLD_COMMENTS = new Set([
+    "# Mega-Compact Embedder Configuration",
+    "# trigram: built-in embedder, no URL needed",
+    "# unset MEGACOMPACT_EMBEDDING_URL (commented to override any shell-set value)",
+    "# MEGACOMPACT_ALLOW_REMOTE_EMBEDDER not set (loopback-only)",
+]);
+function isScaffoldComment(line) {
+    return (SCAFFOLD_COMMENTS.has(line) ||
+        line.startsWith("# Configured via dashboard Setup tab at "));
+}
+/**
+ * Write the embedder selection upsert-style into `<stateDir>/.mega-compact.env`.
+ * `resolvedUrl === null` selects the trigram (built-in) path — the emitted
+ * lines carry only the scaffold comments for that case (the URL/remote lines
+ * are intentionally absent, matching the pre-refactor byte shape).
+ */
+export function writeEmbedderEnv(stateDir, resolvedUrl, allowRemote) {
+    const envPath = join(stateDir, ".mega-compact.env");
+    const existingLines = (() => {
+        try {
+            return existsSync(envPath) ? readFileSync(envPath, "utf-8").split("\n") : [];
+        }
+        catch {
+            return [];
+        }
+    })();
+    const preserved = existingLines.filter((l) => l.trim().length > 0 &&
+        !isScaffoldComment(l) &&
+        !OWNED_PREFIXES.some((p) => ownsKey(l, p)));
+    const next = [
+        "# Mega-Compact Embedder Configuration",
+        `# Configured via dashboard Setup tab at ${new Date().toISOString()}`,
+        ...preserved,
+    ];
+    if (resolvedUrl !== null) {
+        next.push(`export MEGACOMPACT_EMBEDDING_URL="${resolvedUrl}"`);
+        if (allowRemote) {
+            next.push(`export MEGACOMPACT_ALLOW_REMOTE_EMBEDDER="1"`);
+        }
+        else {
+            next.push(`# MEGACOMPACT_ALLOW_REMOTE_EMBEDDER not set (loopback-only)`);
+        }
+    }
+    else {
+        next.push("# trigram: built-in embedder, no URL needed");
+        next.push("# unset MEGACOMPACT_EMBEDDING_URL (commented to override any shell-set value)");
+        next.push("# export MEGACOMPACT_EMBEDDING_URL=");
+        next.push("# export MEGACOMPACT_ALLOW_REMOTE_EMBEDDER=");
+    }
+    next.push("");
+    mkdirSync(stateDir, { recursive: true });
+    writeFileSync(envPath, next.join("\n"), "utf-8");
+    return envPath;
+}

package/dist/extensions/dashboard-server/routes-setup.js

@@ -8,10 +8,12 @@
  * The detection commands run local subprocesses via spawnSync, NOT network calls.
  * Each decoration line carries a guardrails-allow annotation.
  */
-import { writeFileSync, mkdirSync, readFileSync, existsSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 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 { writeEmbedderEnv } from "./routes-setup-env-upsert.js";
 import { detectOllama, detectLlamaCpp, detectOnnx, memoizedDetectOllama, memoizedDetectLlamaCpp, memoizedDetectOnnx, } from "./routes-setup-detect-cache.js";
 // ---------------------------------------------------------------------------
 // handleSetupStatus — "/api/setup-status"
@@ -68,7 +70,7 @@ export function handleSetupStatus(req, res, ctx) {
         embeddingUrl: process.env["MEGACOMPACT_EMBEDDING_URL"] ?? configured.url,
         embedCache: process.env["MEGACOMPACT_EMBED_CACHE"] ?? null,
         minilm: ["1", "true", "yes"].includes((process.env["MEGACOMPACT_MINILM"] ?? "").trim().toLowerCase()),
-        ...enc1aStatusFields(ctx.stateDir),
+        ...enc1aStatusFields(ctx.stateDir), ...enc1bStatusFields(ctx.stateDir),
     };
     // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
     res.writeHead(200, { "Content-Type": "application/json" });
@@ -176,6 +178,22 @@ export function handleSetupConfigure(req, res, ctx) {
         // pre-ENC-1a embedder path below (byte-identical predecessor).
         if (tryEnc1aConfigure(body, res, ctx))
             return;
+        if (tryEnc1bConfigure(body, res, ctx))
+            return; // pure ENC-1b configure (dim/headers/allow-remote/native)
+        // ENC-1b combined-payload validation: when a payload carries a valid
+        // embedder PLUS the ENC-1b keys, tryEnc1bConfigure above returned false
+        // (it handles only the pure-ENC-1b shape) and tryEnc1bInto below would
+        // write WITHOUT validating. Run the same dim/headers validation here so
+        // the combined path is rejected with the same 400 codes. Flag-off:
+        // enc1bValidateCombined returns null (byte-identical predecessor — the
+        // unknown keys fall through untouched).
+        const combinedError = enc1bValidateCombined(body);
+        if (combinedError !== null) {
+            // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: combinedError }));
+            return;
+        }
         const embedder = body.embedder;
         if (embedder !== "ollama" && embedder !== "llama" && embedder !== "trigram" && embedder !== "custom" && embedder !== "onnx") {
             res.writeHead(400, { "Content-Type": "application/json" });
@@ -204,32 +222,14 @@ export function handleSetupConfigure(req, res, ctx) {
         }
         else
             resolvedUrl = null;
-        // Write .mega-compact.env to the state dir (loaded by env-loader at next startup).
+        // Upsert-style write of the per-repo .mega-compact.env (sibling impl):
+        // preserves ENC-1a's endpoint/key + ENC-1b's dim/headers lines and any
+        // operator comments, replacing only the three keys this primary embedder
+        // write owns (URL / ALLOW_REMOTE / MINILM).
         const stateDir = ctx.stateDir;
-        const envPath = join(stateDir, ".mega-compact.env");
-        const lines = [
-            "# Mega-Compact Embedder Configuration",
-            `# Configured via dashboard Setup tab at ${new Date().toISOString()}`,
-        ];
-        if (resolvedUrl) {
-            lines.push(`export MEGACOMPACT_EMBEDDING_URL="${resolvedUrl}"`);
-            if (allowRemote) {
-                lines.push(`export MEGACOMPACT_ALLOW_REMOTE_EMBEDDER="1"`);
-            }
-            else {
-                lines.push(`# MEGACOMPACT_ALLOW_REMOTE_EMBEDDER not set (loopback-only)`);
-            }
-        }
-        else {
-            lines.push("# trigram: built-in embedder, no URL needed");
-            lines.push("# unset MEGACOMPACT_EMBEDDING_URL (commented to override any shell-set value)");
-            lines.push("# export MEGACOMPACT_EMBEDDING_URL=");
-            lines.push("# export MEGACOMPACT_ALLOW_REMOTE_EMBEDDER=");
-        }
-        lines.push("");
+        let envPath;
         try {
-            mkdirSync(stateDir, { recursive: true });
-            writeFileSync(envPath, lines.join("\n"), "utf-8");
+            envPath = writeEmbedderEnv(stateDir, resolvedUrl, allowRemote);
         }
         catch (e) {
             res.writeHead(500, { "Content-Type": "application/json" });
@@ -246,6 +246,7 @@ export function handleSetupConfigure(req, res, ctx) {
                 apiKey: typeof body.embeddingApiKey === "string" ? body.embeddingApiKey : null,
             });
         }
+        tryEnc1bInto(stateDir, body); // ENC-1b combined upsert (dim/headers/allow-remote/native)
         // 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/dist/src/config/vector-cortex-enc1b.js

@@ -0,0 +1,46 @@
+/**
+ * config/vector-cortex-enc1b.ts — ENC-1b ONNX runtime backend + embedder API
+ * Settings fields.
+ *
+ * Extracted from vector-cortex.ts so that file stays under the 300-line soft
+ * limit (soft-as-hard gate), exactly as the ENC-1a sibling was. vector-cortex.ts
+ * re-exports the flag + constants below and root src/config.ts re-exports them,
+ * so no consumer import path changes.
+ *
+ * ENC-1b adds two Settings surfaces. (A) Embedder API completion: the three
+ * remaining env vars the runtime reads (src/httpEmbedder.ts:embeddingConfigFromEnv)
+ * gain dashboard-visible fields — `MEGACOMPACT_EMBEDDING_DIM` (numeric, validated
+ * positive int bounded by `ENC_1B_MAX_EMBEDDING_DIM`), `MEGACOMPACT_EMBEDDING_HEADERS`
+ * (JSON object string — secret-bearing, written verbatim to the per-repo
+ * `.mega-compact.env`, NEVER echoed raw; the GET reports only a boolean
+ * presence marker), and `MEGACOMPACT_ALLOW_REMOTE_EMBEDDER` (boolDirect toggle,
+ * default off — a deliberate escape hatch that skips the loopback-only check).
+ * (B) ONNX runtime selection surface: `MEGACOMPACT_ENCODER_NATIVE` is persisted
+ * to the per-repo env + surfaced as a Settings toggle, and the GET status route
+ * computes the current effective backend + demotion reason through the existing
+ * `selectRuntimeBackend` (reader-only — no selection literals reimplemented).
+ *
+ * `MEGACOMPACT_ENC_1B=0` disables: no new GET fields, no writer branch, no new
+ * Settings rows or toggle — byte-identical to the ENC-1a predecessor. The flag
+ * MUST also be a dashboard SETTINGS toggle (visible in config UI, never in
+ * EXCLUDED_SETTINGS).
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ */
+import { sprintFlag } from "./vector-cortex-flag.js";
+/** ENC-1b `MEGACOMPACT_EMBEDDING_DIM` upper bound (positive integer string). */
+export const ENC_1B_MAX_EMBEDDING_DIM = 8192;
+/** Persisted env names pinned here so the aggregator scan + the routes share
+ *  one source of truth (exactly the names embeddingConfigFromEnv reads). */
+export const ENC_1B_EMBEDDING_DIM_ENV = "MEGACOMPACT_EMBEDDING_DIM";
+export const ENC_1B_EMBEDDING_HEADERS_ENV = "MEGACOMPACT_EMBEDDING_HEADERS";
+export const ENC_1B_ALLOW_REMOTE_EMBEDDER_ENV = "MEGACOMPACT_ALLOW_REMOTE_EMBEDDER";
+export const ENC_1B_ENCODER_NATIVE_ENV = "MEGACOMPACT_ENCODER_NATIVE";
+/**
+ * ENC-1b — ONNX runtime backend + embedder API Settings fields. Default ON.
+ * `MEGACOMPACT_ENC_1B=0` disables and is byte-identical to the ENC-1a
+ * predecessor: no new GET fields, no writer branch, no new Settings rows or
+ * toggle. This flag MUST also be a dashboard SETTINGS toggle (visible in config
+ * UI, never in EXCLUDED_SETTINGS).
+ */
+export const ENC_1B_ENABLED = () => sprintFlag("MEGACOMPACT_ENC_1B");

package/dist/src/config/vector-cortex.js

@@ -33,5 +33,6 @@ export { ENC_0E_ENABLED } from "./vector-cortex-enc0e.js";
 export { ENC_0F_ENABLED } from "./vector-cortex-enc0f.js";
 export { ENC_0G_ENABLED } from "./vector-cortex-enc0g.js";
 export { ENC_1A_ENABLED } from "./vector-cortex-enc1a.js";
+export { ENC_1B_ENABLED, ENC_1B_MAX_EMBEDDING_DIM, ENC_1B_EMBEDDING_DIM_ENV, ENC_1B_EMBEDDING_HEADERS_ENV, ENC_1B_ALLOW_REMOTE_EMBEDDER_ENV, ENC_1B_ENCODER_NATIVE_ENV, } from "./vector-cortex-enc1b.js";
 // Breaker constants (TRIAD_RESILIENCE.md §breaker) extracted to vector-cortex-breakers.ts.
 export { BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./vector-cortex-breakers.js";

package/dist/src/config.js

@@ -114,4 +114,4 @@ export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
 // default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
 // so root consumers share one source of truth.
 // ---------------------------------------------------------------------------
-export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, VC7B_ENABLED, VC7C_ENABLED, VC8A_ENABLED, VC8B_ENABLED, VC8C_ENABLED, VC9A_ENABLED, VC9B_ENABLED, VC9C_ENABLED, VC9D_ENABLED, PCC_ENABLED, ML5A_ENABLED, ML5B_ENABLED, ML5C_ENABLED, ML5D_ENABLED, ML5E_ENABLED, DEDUP_ATTR_ENABLED, ENC_0A_ENABLED, ENC_0B_ENABLED, ENC_0C_ENABLED, ENC_0D_ENABLED, ENC_0E_ENABLED, ENC_0F_ENABLED, ENC_0G_ENABLED, ENC_1A_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, VC7B_ENABLED, VC7C_ENABLED, VC8A_ENABLED, VC8B_ENABLED, VC8C_ENABLED, VC9A_ENABLED, VC9B_ENABLED, VC9C_ENABLED, VC9D_ENABLED, PCC_ENABLED, ML5A_ENABLED, ML5B_ENABLED, ML5C_ENABLED, ML5D_ENABLED, ML5E_ENABLED, DEDUP_ATTR_ENABLED, ENC_0A_ENABLED, ENC_0B_ENABLED, ENC_0C_ENABLED, ENC_0D_ENABLED, ENC_0E_ENABLED, ENC_0F_ENABLED, ENC_0G_ENABLED, ENC_1A_ENABLED, ENC_1B_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";