pi-mega-compact 0.20.42 → 0.20.43

package/dist/vector-cortex/_acceptance-vc2b-heads.js

@@ -0,0 +1,221 @@
+/** VC2B acceptance — multi-head invariant + independence + forced triad through
+ *  the REAL encode-or-fallback router (no mocks, including unique failure
+ *  injection where the learned asset is deleted after A selection but before
+ *  inference). Extracted from vc2b-acceptance.test.ts so the aggregator stays
+ *  under the soft line limit. Shared context (withFlagsOn, stageVerifyingAssetDir,
+ *  token/order constants) is injected by the aggregator to avoid a circular import.
+ */
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { ENC_FAIL, ENCODER_HEAD_DIMS } from "./encoder/types.js";
+import { encodeVectorSet, l2Norm } from "./encoder/heads.js";
+import { ENCODER_TRIGRAM_WIDTH } from "./encoder/trigram.js";
+import { embedLexical, ENCODER_LEXICAL_WIDTH } from "./encoder/lexical.js";
+import { encodeOrFallback } from "./encoder/router.js";
+import { createEncoderRuntime } from "./encoder/runtime.js";
+import { createEncoderHeadsReporter } from "./encoder/emit-vc2b.js";
+export function registerHeads(ctx) {
+    const { withFlagsOn, stageVerifyingAssetDir, SET_TOKENS, EMPTY_TOKENS, ORDERED_DIMS } = ctx;
+    // Suite 4 — invariant + unique failure injection + forced triad
+    describe("multi-head invariant + independence + triad", () => {
+        test("invariant: every emitted norm is 0 or within 1e-6 of 1", () => {
+            for (const tokens of [SET_TOKENS, EMPTY_TOKENS, [7], Array.from({ length: 300 }, (_, i) => i)]) {
+                const set = encodeVectorSet(tokens);
+                for (const hv of set.heads) {
+                    const n = l2Norm(hv.values);
+                    assert.equal(n === 0 || Math.abs(n - 1) <= 1e-6, true, `${hv.head} norm ${n}`);
+                }
+            }
+        });
+        test("repeat drift <= 1e-6 across repeated seeded exports (all five heads)", () => {
+            for (let rep = 0; rep < 3; rep++) {
+                const a = encodeVectorSet(SET_TOKENS);
+                const b = encodeVectorSet(SET_TOKENS);
+                for (let i = 0; i < a.heads.length; i++) {
+                    for (let j = 0; j < a.heads[i].values.length; j++) {
+                        assert.equal(Math.abs(a.heads[i].values[j] - b.heads[i].values[j]) <= 1e-6, true);
+                    }
+                }
+            }
+        });
+        test("unique failure injection: delete model after A selection but before inference; router catches the real load() failure and selects independently initialized B", () => {
+            // This scenario is ON-dependent: it asserts a fallback emission, which is
+            // VC2B-flag-gated, and drives the VC2A runtime into an A load — so it self-pins
+            // both flags ON and is thus valid under either the default-ON run or the
+            // MEGACOMPACT_VC2B=0 parity run.
+            withFlagsOn(() => {
+                // Stage a learned asset the VC2A runtime would VERIFY into mode A, then
+                // REMOVE model.onnx before encoding. The router's load() returns the real
+                // ENC_ASSET_UNREADABLE failure code and must hand off to the independently
+                // initialized asset-free trigram B — emitting vector_cortex_encoder_fallback_selected
+                // from the production seam (S2: a true end-to-end router test, not a
+                // simulated direct call to selectTrigramBFallback).
+                const dir = stageVerifyingAssetDir();
+                const emitted = [];
+                const reporter = createEncoderHeadsReporter((e) => emitted.push(e));
+                try {
+                    // A is selectable at this point (a staging runtime verifies it).
+                    const probe = createEncoderRuntime();
+                    assert.equal(probe.load(dir).ok, true, "staged asset verifies into A");
+                    // "After A selection but before inference": the on-disk model is gone.
+                    rmSync(join(dir, "model.onnx"), { force: true });
+                    const verdict = encodeOrFallback({ tokens: SET_TOKENS }, dir, { reporter });
+                    assert.equal(verdict.ok, true);
+                    assert.equal(verdict.mode, "B", "router handoff selects independently initialized B");
+                    assert.equal(verdict.width, 512);
+                    if (verdict.ok) {
+                        assert.equal(verdict.vector.length, 512);
+                        assert.equal(verdict.code, ENC_FAIL.ASSET_UNREADABLE, "load() reported the real failure code");
+                    }
+                    assert.ok(emitted.includes("vector_cortex_encoder_fallback_selected"), "fallback-selected fired from the real router seam: " + emitted.join(","));
+                    // Distinct vectors for distinct inputs — the fallback is not a constant.
+                    const again = encodeOrFallback({ tokens: [9, 8, 7, 6] }, dir, { reporter });
+                    assert.equal(again.ok, true);
+                    if (verdict.ok && again.ok && verdict.mode === "B" && again.mode === "B") {
+                        let diff = 0;
+                        for (let i = 0; i < verdict.vector.length; i++)
+                            diff += Math.abs(verdict.vector[i] - again.vector[i]);
+                        assert.ok(diff > 1e-3, "independent trigram B is input-sensitive");
+                    }
+                }
+                finally {
+                    rmSync(dir, { recursive: true, force: true });
+                }
+            });
+        });
+        test("forced triad A / B / C through the encode-or-fallback router", () => {
+            // ON-dependent: asserts heads_emitted / fallback_selected emissions, so it
+            // self-pins both flags ON (valid under either the default-ON run or the
+            // MEGACOMPACT_VC2B=0 parity run).
+            withFlagsOn(() => {
+                // A = learned projections: a verifying asset dir routes to a VectorSetV1 with
+                // the five heads in ordered dims (emitting heads_emitted).
+                const dirA = stageVerifyingAssetDir();
+                const emittedA = [];
+                try {
+                    const reporterA = createEncoderHeadsReporter((e) => emittedA.push(e));
+                    const a = encodeOrFallback({ tokens: SET_TOKENS }, dirA, { reporter: reporterA });
+                    assert.equal(a.ok, true);
+                    assert.equal(a.mode, "A");
+                    if (a.ok) {
+                        assert.equal(a.vectorSet.heads.length, 5);
+                        assert.deepEqual(a.vectorSet.heads.map((h) => h.dim), ORDERED_DIMS);
+                    }
+                    assert.ok(emittedA.includes("vector_cortex_encoder_heads_emitted"));
+                }
+                finally {
+                    rmSync(dirA, { recursive: true, force: true });
+                }
+                // B = 512d trigram selected when the learned asset directory is REMOVED: the
+                // router's load() fails (no manual fetch) and hands off to B. Remove a staged
+                // asset dir so the directory is genuinely absent, proving B needs no asset.
+                const dirB = stageVerifyingAssetDir();
+                rmSync(dirB, { recursive: true, force: true }); // asset directory REMOVED
+                const emittedB = [];
+                const reporterB = createEncoderHeadsReporter((e) => emittedB.push(e));
+                const b = encodeOrFallback({ tokens: SET_TOKENS }, dirB, { reporter: reporterB });
+                assert.equal(b.ok, true);
+                assert.equal(b.mode, "B", "B works without an asset dir");
+                assert.equal(b.width, 512);
+                if (b.ok) {
+                    assert.equal(b.vector.length, 512);
+                    assert.equal(b.limitation, null);
+                }
+                assert.ok(emittedB.includes("vector_cortex_encoder_fallback_selected"), "B selection emits fallback-selected");
+                // C = token/phrase lexical forced when both A and B runtimes are disabled.
+                const emittedC = [];
+                const reporterC = createEncoderHeadsReporter((e) => emittedC.push(e));
+                const c = encodeOrFallback({ tokens: SET_TOKENS }, dirB, { reporter: reporterC, forceFallback: "C" });
+                assert.equal(c.ok, true);
+                assert.equal(c.mode, "C");
+                assert.equal(c.width, ENCODER_LEXICAL_WIDTH);
+                if (c.ok && c.mode === "C") {
+                    assert.equal(c.vector.length, ENCODER_LEXICAL_WIDTH);
+                    assert.ok((c.limitation ?? "").length > 0, "C reports its semantic-context limitation");
+                    // Q04: a FORCED C is an intentional selection, not a demotion or rollback,
+                    // so it must NOT be stamped with ENC_FAIL.ROLLBACK.
+                    assert.equal(c.code, null, "forced C is not a rollback/demotion (code = null)");
+                }
+                assert.ok(emittedC.includes("vector_cortex_encoder_fallback_selected"), "C selection emits fallback-selected");
+                // Widths are disjoint across the triad (no shared feature space).
+                const aWidths = Object.values(ENCODER_HEAD_DIMS);
+                for (const w of [...aWidths, ENCODER_LEXICAL_WIDTH])
+                    assert.notEqual(w, ENCODER_TRIGRAM_WIDTH);
+            });
+        });
+        test("forced fallback (B/C) wins over the empty-input degenerate case (Q02)", () => {
+            // Q02: a caller that explicitly forces a fallback mode must get that mode
+            // even for EMPTY input — empty tokens must NOT silently short-circuit to B.
+            // Asserts fallback_selected emissions → ON-dependent, so it self-pins via
+            // withFlagsOn (valid under either external env, same as the forced-triad test).
+            withFlagsOn(() => {
+                const emittedC = [];
+                const reporterC = createEncoderHeadsReporter((e) => emittedC.push(e));
+                const c = encodeOrFallback({ tokens: EMPTY_TOKENS }, "", { reporter: reporterC, forceFallback: "C" });
+                assert.equal(c.ok, true);
+                assert.equal(c.mode, "C", "forced C must win over empty-input B selection");
+                if (c.ok && c.mode === "C") {
+                    assert.equal(c.vector.length, ENCODER_LEXICAL_WIDTH);
+                    assert.equal(c.code, null, "forced C carries no rollback/demotion code (Q04)");
+                }
+                assert.ok(emittedC.includes("vector_cortex_encoder_fallback_selected"));
+                // Forced B on empty input also stays B (force mode is honored, no failure
+                // code — a forced mode is not a rollback/demotion, so code is null).
+                const emittedB = [];
+                const reporterB = createEncoderHeadsReporter((e) => emittedB.push(e));
+                const b = encodeOrFallback({ tokens: EMPTY_TOKENS }, "", { reporter: reporterB, forceFallback: "B" });
+                assert.equal(b.ok, true);
+                assert.equal(b.mode, "B");
+                if (b.ok && b.mode === "B") {
+                    assert.equal(b.vector.length, ENCODER_TRIGRAM_WIDTH);
+                    assert.equal(b.code, null, "forced B carries no rollback/demotion code (Q04)");
+                }
+            });
+        });
+        test("A/B/C use disjoint widths and independent algorithms", () => {
+            // A head widths are 384/128/128/64/32; B is 512; C is 256 — no shared space.
+            const aWidths = Object.values(ENCODER_HEAD_DIMS);
+            const bWidth = ENCODER_TRIGRAM_WIDTH;
+            const cWidth = ENCODER_LEXICAL_WIDTH;
+            for (const w of [...aWidths, cWidth])
+                assert.notEqual(w, bWidth);
+            // B works with the asset absent; C works with both vector runtimes disabled
+            // (C does not depend on B or A — it embeds tokens directly).
+            const cTokens = embedLexical("independently computed lexical with vector runtimes disabled");
+            assert.equal(cTokens.length, ENCODER_LEXICAL_WIDTH);
+        });
+        test("router seam enforces the verified per-manifest token capacity: over-cap input routes to B with ENC_SHAPE_INVALID, never an over-cap A VectorSet", () => {
+            // Q01: the router's mode-A path must enforce the VC2A contract
+            // "only batch1/<=maxTokens verified assets reach inference" at its own seam.
+            // A verified asset declaring maxTokens=64 with an input of 100 tokens must
+            // NOT produce an ok:true mode-A VectorSetV1 whose inputTokens breach the
+            // model's declared capacity — instead the router rejects it and falls back
+            // to the asset-free trigram B, reporting the real shape failure code.
+            withFlagsOn(() => {
+                const dir = stageVerifyingAssetDir(64); // verified low-cap manifest
+                try {
+                    const over = encodeOrFallback({ tokens: Array.from({ length: 100 }, (_, i) => i) }, dir);
+                    assert.equal(over.ok, true, "over-cap input still yields a usable (fallback) verdict");
+                    assert.equal(over.mode, "B", "over-cap input must route to the B fallback, not an A VectorSet");
+                    if (over.ok) {
+                        assert.equal(over.code, ENC_FAIL.SHAPE_INVALID, "reported the real shape failure code");
+                        assert.equal(over.vector.length, ENCODER_TRIGRAM_WIDTH);
+                    }
+                    // A within-cap input against the SAME verified manifest still reaches a
+                    // qualified mode-A VectorSet — the capacity rejection is input-scoped,
+                    // not a blanket demotion of the verified asset.
+                    const within = encodeOrFallback({ tokens: SET_TOKENS }, dir);
+                    assert.equal(within.ok, true);
+                    assert.equal(within.mode, "A", "within-cap input still reaches mode A");
+                    if (within.ok)
+                        assert.equal(within.vectorSet.heads.length, 5);
+                }
+                finally {
+                    rmSync(dir, { recursive: true, force: true });
+                }
+            });
+        });
+    });
+}

package/dist/vector-cortex/encoder/asset.js

@@ -2,7 +2,8 @@
  * vector-cortex/encoder/asset.ts — VC2A asset verification (task 2).
  *
  * Verifies a ModelManifestV1 before any allocation: SHA-256 the ONNX and
- * tokenizer against the manifest digests, require opset 17, batch exactly 1 and
+ * tokenizer against the manifest digests, require opset 21 (ENC-0a re-baseline),
+ * batch exactly 1 and
  * maximum 512 tokens, and confirm the current platform is in the supported
  * matrix. On ANY of these the caller demotes to mode B (asset-free trigram) —
  * never a remote fetch (PREVENT-PI-004). A truncated/unreadable asset during
@@ -73,7 +74,7 @@ function isManifest(m) {
  *
  *   - manifest parse/shape failure      -> ENC_MANIFEST_INVALID -> mode B
  *   - unsupported platform              -> ENC_PLATFORM_UNSUPPORTED -> mode B
- *   - opset != 17                       -> ENC_OPSET_INVALID -> mode B
+ *   - opset != 21                       -> ENC_OPSET_INVALID -> mode B
  *   - batch != 1                        -> ENC_BATCH_INVALID -> mode B
  *   - maxTokens > 512                   -> ENC_TOKENS_EXCEEDED -> mode B
  *   - on-disk digest != manifest digest -> ENC_DIGEST_MISMATCH (one-byte mutation)

package/dist/vector-cortex/encoder/decision.js

@@ -0,0 +1,75 @@
+/**
+ * vector-cortex/encoder/decision.ts — ENC-0a backend-decision contract.
+ *
+ * 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.
+ *
+ * ENC-0a is the DECISION + MEASUREMENT sprint: this contract is what the
+ * deterministic resolver (`scripts/encoder/resolve-backend-decision.mjs`) and
+ * the durable record (`docs/vector-cortex/encoder-backend-decision.md`) both
+ * consume. ENC-0a also owns the opset flip: ENCODER_OPSET is re-baselined to 21
+ * in `types.ts` alongside the placeholder manifest (the 2026-08-05 trunk
+ * research dropped the earlier Xenova opset-17 requirement). ENC-0b asserts the
+ * staged real asset is opset 21 — no further constant change.
+ *
+ * Contract-first (ENGINEERING_PRACTICES §3). Pi-agnostic, dependency-free
+ * (PREVENT-PI-004 — local computation only, never a fetch). No `any`
+ * (PREVENT-011).
+ */
+/**
+ * The normative ENC-0a budget: the 80 MiB install/asset cap (MODEL_ASSET.md
+ * §Qualification). Backend qualifies (budgetOk) iff the shipped byte-count fits.
+ */
+export const ENCODER_INSTALL_BUDGET_MIB = 80;
+/** The p95 latency gate at 512 tokens / 4 threads on linux-x64 (ms). */
+export const ENCODER_DECISION_P95_MS = 40;
+/**
+ * buildDecision — assemble a valid, platform-complete EncoderBackendDecisionV1.
+ *
+ * Pure helper consumed by the acceptance aggregator (and any TS consumer of the
+ * decision). Every EncoderPlatform must resolve to a row, and the passed
+ * per-platform rows must be complete (no row omitted) — a partial matrix is a
+ * contract violation, not a valid decision. All fields are passed in; this is a
+ * structural constructor, not a rules engine (the resolver owns the decision
+ * rule).
+ */
+export function buildDecision(input) {
+    const { platformMatrix } = input;
+    const platforms = [
+        "linux-x64",
+        "linux-arm64",
+        "darwin-x64",
+        "darwin-arm64",
+        "win32-x64",
+    ];
+    for (const p of platforms) {
+        if (!Object.prototype.hasOwnProperty.call(platformMatrix, p)) {
+            throw new Error(`platform matrix is incomplete: missing row for ${p}`);
+        }
+    }
+    return {
+        schema: "encoder-backend-decision-v1",
+        backend: input.backend,
+        budgetOk: input.budgetOk,
+        opset: 21,
+        platformMatrix,
+        license: { spdx: "MIT", redistribution: true },
+        artifacts: {
+            model: {
+                path: input.modelPath,
+                bytes: input.modelBytes,
+                sha256: input.modelSha256,
+            },
+            tokenizer: {
+                path: input.tokenizerPath,
+                bytes: input.tokenizerBytes,
+                sha256: input.tokenizerSha256,
+            },
+        },
+        p95Ms: input.p95Ms,
+        blockedBy: input.blockedBy,
+    };
+}

package/dist/vector-cortex/encoder/types-vc2c.js

@@ -0,0 +1,41 @@
+/**
+ * vector-cortex/encoder/types-vc2c.ts — VC2C qualification + calibration
+ * contracts (QualifiedEncoderV1 / CalibrationV1 / EVALUATION_THRESHOLDS).
+ *
+ * Extracted from types.ts (delegate-shell split) when types.ts crossed the
+ * 300-line soft limit. types.ts re-exports everything here; consumers import
+ * from types.ts unchanged.
+ *
+ * Pi-agnostic and dependency-free (PREVENT-PI-004). No `any` (PREVENT-011).
+ */
+/** Normative per-head + asset qualification thresholds (MODEL_ASSET §qualification
+ *  + EVALUATION.md §metrics). These are the constants `select.ts` evaluates the
+ *  candidate's held-out metrics against (task 3 atomic check). */
+export const EVALUATION_THRESHOLDS = {
+    semantic: { spearman: 0.75, recallAt10: 0.9 },
+    dependency: { precision: 0.97, recall: 0.95 },
+    contradiction: { precision: 0.98, recall: 0.9, ece: 0.05 },
+    cacheStability: { precision: 0.999, recall: 0.9 },
+    payloadRouting: { macroF1: 0.97, exactAnchorRecall: 1.0 },
+    reconstruction: { dependencyClosureRecall: 1.0 },
+    asset: { maxTokens: 512, maxLatencyP95Ms: 40, maxRssDeltaMib: 150 },
+};
+/** VC2C-specific qualification failure codes (returned, never thrown). */
+export const ENC_QUALIFICATION_FAIL = {
+    /** The qualification manifest hash does not match the calibration that was fit
+     *  (corrupt qualification manifest after calibration before selection). */
+    DIGEST_MISMATCH: "ENC_QUALIFICATION_DIGEST_MISMATCH",
+    /** One or more per-head EVALUATION thresholds failed (demotes all of A). */
+    THRESHOLD_FAILED: "ENC_QUALIFICATION_THRESHOLD_FAILED",
+    /** An asset-field qualification check (asset/latency/RSS) failed. */
+    ASSET_FAILED: "ENC_QUALIFICATION_ASSET_FAILED",
+    /** Calibration was attempted using held-out labels (fit prohibition). */
+    HELD_OUT_IN_FIT: "ENC_QUALIFICATION_HELD_OUT_IN_FIT",
+};
+/** The 4 registered VC2C conformance IDs (task 1: "register ENC-017..020"). */
+export const ENC2C_IDS = [
+    "ENC-017",
+    "ENC-018",
+    "ENC-019",
+    "ENC-020",
+];

package/dist/vector-cortex/encoder/types.js

@@ -24,8 +24,13 @@ export const ENCODER_SUPPORTED_PLATFORMS = [
     "darwin-arm64",
     "win32-x64",
 ];
-/** ONNX opset required by the normative v1 target (opset 17). */
-export const ENCODER_OPSET = 17;
+/** ONNX opset required by the normative v1 target. ENC-0a re-baselines from 17
+ *  to 21: the committed placeholder asset (assets/vector-cortex/encoder-v1/)
+ *  declares opset 21 in its manifest (the 2026-08-05 BAAI/bge-small-en-v1.5
+ *  upstream export is opset 21; the earlier Xenova opset-17 requirement was
+ *  dropped). The locked decision is recorded in
+ *  docs/vector-cortex/encoder-backend-decision.md. */
+export const ENCODER_OPSET = 21;
 /** Batch must be exactly 1 (single-request inference). */
 export const ENCODER_BATCH = 1;
 /** Maximum accepted token count (WordPiece, deterministic truncation). */
@@ -45,7 +50,7 @@ export const ENCODER_LATENCY_P95_MS = 40;
 export const ENCODER_SEMANTIC_WIDTH = 384;
 /** Exact VC2A failure codes (returned, never thrown across the boundary). */
 export const ENC_FAIL = {
-    /** opset != 17. */
+    /** opset != 21 (ENC-0a re-baseline applied; placeholder manifest updated alongside). */
     OPSET_INVALID: "ENC_OPSET_INVALID",
     /** batch != 1. */
     BATCH_INVALID: "ENC_BATCH_INVALID",
@@ -136,34 +141,8 @@ export const ENC2B_IDS = [
     "ENC-015",
     "ENC-016",
 ];
-/** Normative per-head + asset qualification thresholds (MODEL_ASSET §qualification
- *  + EVALUATION.md §metrics). These are the constants `select.ts` evaluates the
- *  candidate's held-out metrics against (task 3 atomic check). */
-export const EVALUATION_THRESHOLDS = {
-    semantic: { spearman: 0.75, recallAt10: 0.9 },
-    dependency: { precision: 0.97, recall: 0.95 },
-    contradiction: { precision: 0.98, recall: 0.9, ece: 0.05 },
-    cacheStability: { precision: 0.999, recall: 0.9 },
-    payloadRouting: { macroF1: 0.97, exactAnchorRecall: 1.0 },
-    reconstruction: { dependencyClosureRecall: 1.0 },
-    asset: { maxTokens: 512, maxLatencyP95Ms: 40, maxRssDeltaMib: 150 },
-};
-/** VC2C-specific qualification failure codes (returned, never thrown). */
-export const ENC_QUALIFICATION_FAIL = {
-    /** The qualification manifest hash does not match the calibration that was fit
-     *  (corrupt qualification manifest after calibration before selection). */
-    DIGEST_MISMATCH: "ENC_QUALIFICATION_DIGEST_MISMATCH",
-    /** One or more per-head EVALUATION thresholds failed (demotes all of A). */
-    THRESHOLD_FAILED: "ENC_QUALIFICATION_THRESHOLD_FAILED",
-    /** An asset-field qualification check (asset/latency/RSS) failed. */
-    ASSET_FAILED: "ENC_QUALIFICATION_ASSET_FAILED",
-    /** Calibration was attempted using held-out labels (fit prohibition). */
-    HELD_OUT_IN_FIT: "ENC_QUALIFICATION_HELD_OUT_IN_FIT",
-};
-/** The 4 registered VC2C conformance IDs (task 1: "register ENC-017..020"). */
-export const ENC2C_IDS = [
-    "ENC-017",
-    "ENC-018",
-    "ENC-019",
-    "ENC-020",
-];
+// ---------------------------------------------------------------------------
+// VC2C — encoder qualification + calibration: extracted to types-vc2c.ts
+// (delegate-shell split, soft-limit compliance). Re-exported here.
+// ---------------------------------------------------------------------------
+export { EVALUATION_THRESHOLDS, ENC_QUALIFICATION_FAIL, ENC2C_IDS, } from "./types-vc2c.js";

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

@@ -252,5 +252,11 @@ export const VECTOR_CORTEX_SETTINGS: SettingGroup = {
 			"Dedup tier-attribution rollup: per-tier dedup catch shares (L0/L1/L2/new percent of dedup decisions) read from the local events.log dedup_audit stream (GET /api/dedup-tier-attribution). OFF = 404 + no cache file, byte-identical predecessor.",
 			true,
 		),
+		boolDirect(
+			"MEGACOMPACT_ENC_0A",
+			"ENC-0a Encoder Backend Decision",
+			"ENC-0a learned-encoder backend-decision lock: records the transformers.js/WASM vs onnxruntime-node choice, per-platform install matrix, opset-21 baseline and pinned digests in docs/vector-cortex/encoder-backend-decision.md. OFF = no decision record written / no resolver runs, mode B trigram byte-identical predecessor.",
+			true,
+		),
 	],
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.42",
+  "version": "0.20.43",
   "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-enc0a.ts

@@ -0,0 +1,34 @@
+/**
+ * config/vector-cortex-enc0a.ts — ENC-0a learned-encoder backend-decision flag.
+ *
+ * Extracted from vector-cortex.ts so that file stays under the 300-line soft
+ * limit (soft-as-hard gate), exactly as vector-cortex-vc9a.ts..vector-cortex-vc9d.ts
+ * were. This is the first ENC (real learned encoder) sprint flag. vector-cortex.ts
+ * re-exports the ENUM below and root src/config.ts re-exports it, so no consumer
+ * import path changes.
+ *
+ * ENC-0a locks the runtime-backend choice (transformers.js/WASM vs
+ * onnxruntime-node native), the per-platform install-size matrix, the opset
+ * baseline (re-baselined 17 -> 21) and the license/pinning audit. It writes a
+ * durable decision record and bench JSON but touches neither the store schema
+ * nor stateDir tables (pure migration).
+ *
+ * The split is purely mechanical: ENC_0A_ENABLED is byte-identical in name,
+ * semantics, and default to the definition it replaces, and vector-cortex.ts
+ * re-exports it so every existing `from "./config/vector-cortex.js"` import
+ * keeps resolving unchanged.
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { sprintFlag } from "./vector-cortex-flag.js";
+
+/**
+ * ENC-0a — learned-encoder backend-decision lock. Default ON.
+ * `MEGACOMPACT_ENC_0A=0` disables and is byte-identical to the predecessor
+ * (placeholder encoder): no decision record is written and no newer
+ * backend-resolution script runs — the runtime keeps serving mode B trigram
+ * exactly as before. This flag MUST also be a dashboard SETTINGS toggle (visible
+ * in config UI, never in EXCLUDED_SETTINGS), mirroring VC4A..VC9D.
+ */
+export const ENC_0A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_ENC_0A");

package/src/config/vector-cortex.ts

@@ -5,8 +5,7 @@
  * `=0`/`_DISABLED` off. Flag-OFF is byte-identical to the predecessor sprint's
  * behavior (for VC0A: mode C — observer absent, zero evaluation writes).
  *
- * The breaker/triad constants (TRIAD_RESILIENCE.md) live here so VC0C consumes
- * them without re-declaring the ownership boundary. Pi-agnostic, dependency-free.
+ * Breaker/triad constants (TRIAD_RESILIENCE.md) live here; pi-agnostic, dep-free.
  */
 
 import { sprintFlag } from "./vector-cortex-flag.js";
@@ -281,6 +280,7 @@ export { ML5C_ENABLED } from "./vector-cortex-ml5c.js";
 export { ML5D_ENABLED } from "./vector-cortex-ml5d.js";
 export { ML5E_ENABLED } from "./vector-cortex-ml5e.js";
 export { DEDUP_ATTR_ENABLED } from "./vector-cortex-dedup-attr.js";
+export { ENC_0A_ENABLED } from "./vector-cortex-enc0a.js";
 
 // Breaker constants (TRIAD_RESILIENCE.md §breaker) extracted to vector-cortex-breakers.ts.
 export {

package/src/config.ts

@@ -189,6 +189,7 @@ export {
   ML5D_ENABLED,
   ML5E_ENABLED,
   DEDUP_ATTR_ENABLED,
+  ENC_0A_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

package/src/vector-cortex/_acceptance-enc0a-contract.ts

@@ -0,0 +1,71 @@
+/** ENC-0a buildDecision contract constructor suite — extracted from
+ *  enc0a-acceptance.test.ts for soft-limit compliance. Receives the contract
+ *  constructor + constants from the aggregator (no import cycle).
+ */
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import type { EncoderPlatformRow } from "./encoder/decision.js";
+
+export interface Enc0aContractCtx {
+  buildDecision: typeof import("./encoder/decision.js").buildDecision;
+  PLATFORMS: readonly ["linux-x64", "linux-arm64", "darwin-x64", "darwin-arm64", "win32-x64"];
+}
+
+export function registerEnc0aContract(ctx: Enc0aContractCtx): void {
+  const { buildDecision, PLATFORMS } = ctx;
+
+  describe("buildDecision contract constructor", () => {
+    test("rejects an incomplete platform matrix", () => {
+      const matrix = {
+        "linux-x64": { runtime: "onnxruntime-web", installMiB: 33, demotion: "none" },
+        "linux-arm64": { runtime: "onnxruntime-web", installMiB: 33, demotion: "none" },
+        "darwin-x64": { runtime: "onnxruntime-web", installMiB: 33, demotion: "wasm" },
+        "darwin-arm64": { runtime: "onnxruntime-web", installMiB: 33, demotion: "none" },
+        // win32-x64 omitted
+      } as Record<(typeof PLATFORMS)[number], EncoderPlatformRow>;
+      assert.throws(() =>
+        buildDecision({
+          backend: "wasm",
+          budgetOk: true,
+          p95Ms: 18.2,
+          platformMatrix: matrix,
+          modelPath: "model.onnx",
+          modelBytes: 1,
+          modelSha256: "a".repeat(64),
+          tokenizerPath: "tokenizer.json",
+          tokenizerBytes: 1,
+          tokenizerSha256: "b".repeat(64),
+          blockedBy: [],
+        }),
+      );
+    });
+
+    test("builds a valid decision with opset 21 + MIT license for a complete matrix", () => {
+      const matrix = {
+        "linux-x64": { runtime: "onnxruntime-web", installMiB: 33, demotion: "none" },
+        "linux-arm64": { runtime: "onnxruntime-web", installMiB: 33, demotion: "none" },
+        "darwin-x64": { runtime: "onnxruntime-web", installMiB: 33, demotion: "wasm" },
+        "darwin-arm64": { runtime: "onnxruntime-web", installMiB: 33, demotion: "none" },
+        "win32-x64": { runtime: "onnxruntime-web", installMiB: 33, demotion: "none" },
+      } as Record<(typeof PLATFORMS)[number], EncoderPlatformRow>;
+      const d = buildDecision({
+        backend: "wasm",
+        budgetOk: true,
+        p95Ms: 18.2,
+        platformMatrix: matrix,
+        modelPath: "model.onnx",
+        modelBytes: 24117248,
+        modelSha256: "a".repeat(64),
+        tokenizerPath: "tokenizer.json",
+        tokenizerBytes: 50000,
+        tokenizerSha256: "b".repeat(64),
+        blockedBy: [],
+      });
+      assert.equal(d.schema, "encoder-backend-decision-v1");
+      assert.equal(d.opset, 21);
+      assert.equal(d.backend, "wasm");
+      assert.deepEqual(d.license, { spdx: "MIT", redistribution: true });
+      assert.equal(d.platformMatrix["darwin-x64"].demotion, "wasm");
+    });
+  });
+}