pi-mega-compact 0.20.42 → 0.20.44

package/dist/src/vector-cortex/_acceptance-vc2a-runtime.js

@@ -0,0 +1,285 @@
+/** VC2A runtime invariant + injection + triad + budget acceptance suites.
+ *  Extracted from vc2a-acceptance.test.ts (soft-limit compliance). Context injected. */
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+export function registerVc2aRuntime(ctx) {
+    const { ENC_FAIL, ENCODER_RSS_BUDGET_BYTES, ENCODER_LATENCY_P95_MS, tmpAsset, baseManifest, buildDir, rmBuilt, sha256, percentile, createEncoderRuntime, verifyEncoderAsset, readEncoderManifest, } = ctx;
+    // -------------------------------------------------------------------------
+    // Invariant + unique failure injection + forced triad
+    // -------------------------------------------------------------------------
+    describe("encoder runtime invariant + injection + triad", () => {
+        test("invariant: only batch1/max512 verified assets reach inference", () => {
+            const built = buildDir("valid");
+            try {
+                const rt = createEncoderRuntime();
+                const load = rt.load(built.dir);
+                assert.equal(load.ok, true);
+                if (load.ok)
+                    assert.equal(load.mode, "A");
+                // dims 1..512 infer; 0 and 513+ are shape-rejected.
+                for (const n of [1, 64, 512]) {
+                    const inf = rt.infer({ tokens: Array.from({ length: n }, (_, i) => i % 500) });
+                    assert.equal(inf.ok, true, `dim ${n} infers`);
+                }
+                for (const n of [0, 513, 1000]) {
+                    const inf = rt.infer({ tokens: Array.from({ length: n }) });
+                    assert.equal(inf.ok, false, `dim ${n} shape-rejected`);
+                    if (!inf.ok)
+                        assert.equal(inf.code, ENC_FAIL.SHAPE_INVALID);
+                }
+                // A batch>1 manifest never reaches inference: verification demotes to B.
+                const bad = buildDir("batch-2");
+                try {
+                    const checker = createEncoderRuntime();
+                    const check = checker.load(bad.dir);
+                    assert.equal(check.ok, false);
+                    if (!check.ok)
+                        assert.equal(check.code, ENC_FAIL.BATCH_INVALID);
+                }
+                finally {
+                    rmBuilt(bad);
+                }
+            }
+            finally {
+                rmBuilt(built);
+            }
+        });
+        test("1..513 maxTokens manifests: 1..512 verify+infer, 513 demotes TOKENS_EXCEEDED", () => {
+            for (const maxTok of [1, 64, 512]) {
+                const dir = tmpAsset("vc2a-dim");
+                mkdirSync(dir, { recursive: true });
+                const onnx = Buffer.from(`dim-${maxTok}`, "binary");
+                const tok = Buffer.from('{"vocab":[]}', "utf8");
+                writeFileSync(join(dir, "model.onnx"), onnx);
+                writeFileSync(join(dir, "tokenizer.json"), tok);
+                const m = baseManifest({
+                    maxTokens: maxTok,
+                    onnx: { path: "model.onnx", sha256: sha256(onnx), bytes: onnx.length },
+                    tokenizer: { path: "tokenizer.json", sha256: sha256(tok), bytes: tok.length },
+                });
+                writeFileSync(join(dir, "manifest.json"), JSON.stringify(m));
+                assert.equal(verifyEncoderAsset(dir, readEncoderManifest(dir)).ok, true, `maxTokens ${maxTok} verifies`);
+                const rt = createEncoderRuntime();
+                assert.equal(rt.load(dir).ok, true, `maxTokens ${maxTok} loads`);
+                const inf = rt.infer({ tokens: Array.from({ length: maxTok }) });
+                assert.equal(inf.ok, true, `cap ${maxTok} infers`);
+                rmSync(dir, { recursive: true, force: true });
+            }
+            // 513 demotes.
+            const dir513 = tmpAsset("vc2a-dim-513");
+            mkdirSync(dir513, { recursive: true });
+            const onnx513 = Buffer.from("dim-513", "binary");
+            const tok513 = Buffer.from('{"vocab":[]}', "utf8");
+            writeFileSync(join(dir513, "model.onnx"), onnx513);
+            writeFileSync(join(dir513, "tokenizer.json"), tok513);
+            const m513 = baseManifest({
+                maxTokens: 513,
+                onnx: { path: "model.onnx", sha256: sha256(onnx513), bytes: onnx513.length },
+                tokenizer: { path: "tokenizer.json", sha256: sha256(tok513), bytes: tok513.length },
+            });
+            writeFileSync(join(dir513, "manifest.json"), JSON.stringify(m513));
+            const res = verifyEncoderAsset(dir513, readEncoderManifest(dir513));
+            assert.equal(res.ok, false);
+            if (!res.ok)
+                assert.equal(res.code, ENC_FAIL.TOKENS_EXCEEDED);
+            rmSync(dir513, { recursive: true, force: true });
+        });
+        test("truncated ONNX during digest read demotes ENC_ASSET_UNREADABLE", () => {
+            // LIVE-platform manifest with absent model.onnx -> unreadable -> ASSET_UNREADABLE.
+            const built = buildDir("missing-onnx");
+            try {
+                const load = createEncoderRuntime().load(built.dir);
+                assert.equal(load.ok, false);
+                if (!load.ok) {
+                    assert.equal(load.code, ENC_FAIL.ASSET_UNREADABLE);
+                    assert.equal(load.mode, "B");
+                }
+            }
+            finally {
+                rmBuilt(built);
+            }
+        });
+        test("allocator failure after verification demotes ENC_ASSET_UNREADABLE", () => {
+            const built = buildDir("valid");
+            try {
+                const load = createEncoderRuntime({ host: { allocatorFails: () => true } }).load(built.dir);
+                assert.equal(load.ok, false);
+                if (!load.ok)
+                    assert.equal(load.code, ENC_FAIL.ASSET_UNREADABLE);
+            }
+            finally {
+                rmBuilt(built);
+            }
+        });
+        test("forced triad A / B / C", () => {
+            const dirA = buildDir("valid");
+            try {
+                assert.equal(createEncoderRuntime().load(dirA.dir).ok, true);
+            }
+            finally {
+                rmBuilt(dirA);
+            }
+            // B: missing asset => asset-free trigram.
+            const dirB = buildDir("missing-onnx");
+            try {
+                const load = createEncoderRuntime().load(dirB.dir);
+                assert.equal(load.ok, false);
+                if (!load.ok)
+                    assert.equal(load.mode, "B");
+            }
+            finally {
+                rmBuilt(dirB);
+            }
+            // C: lexical forced by mode C (rollback path).
+            const dirC = tmpAsset("vc2a-C");
+            mkdirSync(dirC, { recursive: true });
+            try {
+                const load = createEncoderRuntime({ forcedMode: "C" }).load(dirC);
+                assert.equal(load.ok, false);
+                if (!load.ok)
+                    assert.equal(load.mode, "C");
+            }
+            finally {
+                rmSync(dirC, { recursive: true, force: true });
+            }
+        });
+        test("acceptance budgets: infer p95 <=40ms and encoder marginal footprint <=150MiB", () => {
+            // Q02: rssBytes = encoder MARGINAL footprint, never whole-process RSS.
+            // p95 via linear interpolation — not max sample.
+            const built = buildDir("valid");
+            try {
+                const rt = createEncoderRuntime();
+                assert.equal(rt.load(built.dir).ok, true);
+                const latencies = [];
+                for (let i = 0; i < 200; i++) {
+                    const inf = rt.infer({ tokens: Array.from({ length: 128 }, (_, k) => k) });
+                    assert.equal(inf.ok, true);
+                    if (inf.ok) {
+                        latencies.push(inf.latencyMs);
+                        assert.ok(inf.rssBytes <= ENCODER_RSS_BUDGET_BYTES, "encoder marginal footprint <=150MiB");
+                    }
+                }
+                const p95 = percentile(latencies, 0.95);
+                assert.ok(p95 <= ENCODER_LATENCY_P95_MS, `p95 ${p95} <= 40ms`);
+            }
+            finally {
+                rmBuilt(built);
+            }
+        });
+        test("Q01: a long-lived runtime cannot drift over the 150MiB marginal budget", () => {
+            // selfAllocated models a REUSABLE projection buffer — must not accumulate.
+            // 100k inferences prove no irreversible budget demotion.
+            const built = buildDir("valid");
+            try {
+                const rt = createEncoderRuntime();
+                assert.equal(rt.load(built.dir).ok, true);
+                let firstRss = 0;
+                for (let i = 0; i < 100_000; i++) {
+                    const inf = rt.infer({ tokens: Array.from({ length: 4 }, () => i % 500) });
+                    assert.equal(inf.ok, true, `infer #${i} still ok`);
+                    if (inf.ok) {
+                        if (i === 0)
+                            firstRss = inf.rssBytes;
+                        assert.equal(inf.rssBytes, firstRss, `marginal footprint flat at infer #${i}`);
+                        assert.ok(inf.rssBytes <= ENCODER_RSS_BUDGET_BYTES, `still within budget at infer #${i}`);
+                    }
+                }
+                assert.equal(rt.mode, "A", "mode A survives 100k inferences (no irreversible budget demotion)");
+            }
+            finally {
+                rmBuilt(built);
+            }
+        });
+        test("Q03: per-manifest maxTokens is enforced at inference (over-cap rejected)", () => {
+            // maxTokens=64 manifest: 65..512 tokens must be SHAPE_INVALID.
+            const dir = tmpAsset("vc2a-q03");
+            mkdirSync(dir, { recursive: true });
+            const onnx = Buffer.from("q03-lowcap", "binary");
+            const tok = Buffer.from('{"vocab":[]}', "utf8");
+            writeFileSync(join(dir, "model.onnx"), onnx);
+            writeFileSync(join(dir, "tokenizer.json"), tok);
+            const m = baseManifest({
+                maxTokens: 64,
+                onnx: { path: "model.onnx", sha256: sha256(onnx), bytes: onnx.length },
+                tokenizer: { path: "tokenizer.json", sha256: sha256(tok), bytes: tok.length },
+            });
+            writeFileSync(join(dir, "manifest.json"), JSON.stringify(m));
+            try {
+                const rt = createEncoderRuntime();
+                assert.equal(rt.load(dir).ok, true, "maxTokens=64 manifest loads (mode A)");
+                assert.equal(rt.infer({ tokens: Array.from({ length: 64 }, (_, k) => k) }).ok, true, "cap 64 infers");
+                for (const over of [65, 128, 512]) {
+                    const inf = rt.infer({ tokens: Array.from({ length: over }) });
+                    assert.equal(inf.ok, false, `${over} tokens rejected against a 64-cap manifest`);
+                    if (!inf.ok)
+                        assert.equal(inf.code, ENC_FAIL.SHAPE_INVALID);
+                }
+            }
+            finally {
+                rmSync(dir, { recursive: true, force: true });
+            }
+        });
+        test("Q04: MEGACOMPACT_VC2A=0 makes the default factory select mode C (rollback)", () => {
+            // Flag OFF => default factory is fixed at mode C (byte-identical predecessor).
+            const saved = process.env.MEGACOMPACT_VC2A;
+            process.env.MEGACOMPACT_VC2A = "0";
+            try {
+                // An explicitly forced "C" also reports ROLLBACK (existing contract).
+                const forced = createEncoderRuntime({ forcedMode: "C" });
+                // The default factory under flag-off must match that exactly.
+                const byFlag = createEncoderRuntime();
+                for (const rt of [forced, byFlag]) {
+                    assert.equal(rt.mode, "C", "flag-off / forced runtime starts in mode C");
+                    const built = buildDir("valid");
+                    try {
+                        const load = rt.load(built.dir);
+                        assert.equal(load.ok, false);
+                        if (!load.ok) {
+                            assert.equal(load.mode, "C", "flag-off default factory reports mode C");
+                            assert.equal(load.code, ENC_FAIL.ROLLBACK, "ROLLBACK, not MANIFEST_INVALID");
+                        }
+                    }
+                    finally {
+                        rmBuilt(built);
+                    }
+                    const inf = rt.infer({ tokens: [1, 2, 3] });
+                    assert.equal(inf.ok, false, "no learned infer on the flag-off path");
+                }
+            }
+            finally {
+                if (saved === undefined)
+                    delete process.env.MEGACOMPACT_VC2A;
+                else
+                    process.env.MEGACOMPACT_VC2A = saved;
+            }
+            // Restore the module-scope pin (flag ON) for subsequent scenarios.
+            process.env.MEGACOMPACT_VC2A = "1";
+        });
+        test("all digest corruptions demote before load", () => {
+            for (const which of ["onnx", "tokenizer", "both"]) {
+                const dir = tmpAsset("vc2a-corr");
+                mkdirSync(dir, { recursive: true });
+                const onnx = Buffer.from("corrupt-me-onnx", "binary");
+                const tok = Buffer.from('{"vocab":[]}', "utf8");
+                writeFileSync(join(dir, "model.onnx"), onnx);
+                writeFileSync(join(dir, "tokenizer.json"), tok);
+                const m = baseManifest({
+                    onnx: { path: "model.onnx", sha256: sha256(onnx), bytes: onnx.length },
+                    tokenizer: { path: "tokenizer.json", sha256: sha256(tok), bytes: tok.length },
+                });
+                if (which === "onnx" || which === "both")
+                    writeFileSync(join(dir, "model.onnx"), Buffer.concat([onnx, Buffer.from("X")]));
+                if (which === "tokenizer" || which === "both")
+                    writeFileSync(join(dir, "tokenizer.json"), Buffer.concat([tok, Buffer.from("X")]));
+                writeFileSync(join(dir, "manifest.json"), JSON.stringify(m));
+                const res = verifyEncoderAsset(dir, readEncoderManifest(dir));
+                assert.equal(res.ok, false, `corrupt ${which} demotes`);
+                if (!res.ok)
+                    assert.equal(res.code, ENC_FAIL.DIGEST_MISMATCH, `corrupt ${which} code`);
+                rmSync(dir, { recursive: true, force: true });
+            }
+        });
+    });
+}

package/dist/src/vector-cortex/_acceptance-vc2b-conformance.js

@@ -0,0 +1,92 @@
+/** VC2B acceptance — ENC-009..016 conformance rows + the ENC-HEAD-001 /
+ *  ENC-ZERO-002 / ENC-FALLBACK-003 named assertions, resolved through the REAL
+ *  heads/trigram producers (no mocks). Extracted from vc2b-acceptance.test.ts so
+ *  the aggregator stays under the soft line limit. Context (fixture loader,
+ *  shared 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 { ENC2B_IDS, ENCODER_HEAD_DIMS, } from "./encoder/types.js";
+import { encodeVectorSet, projectHead, l2Norm } from "./encoder/heads.js";
+import { embedTrigram512, ENCODER_TRIGRAM_WIDTH, selectTrigramBFallback, } from "./encoder/trigram.js";
+export function registerConformanceRows(ctx) {
+    const { fixture, SET_TOKENS, EMPTY_TOKENS, ORDERED_DIMS } = ctx;
+    // Suite 2 — ENC-009..016 conformance rows through the real producers
+    describe("ENC-009..016 conformance rows", () => {
+        test("ENC-009: full-set produces five heads with ordered dims", () => {
+            const fx = fixture("ENC-009");
+            assert.equal(fx.expected.ok, true);
+            const set = encodeVectorSet(SET_TOKENS);
+            assert.equal(set.heads.length, fx.expected.heads);
+            assert.deepEqual(set.heads.map((h) => h.dim), fx.expected.dims, "ordered dims");
+        });
+        for (const id of ENC2B_IDS.slice(1, 6)) {
+            test(`${id}: ${fixture(id).input.head} head emits its declared dim`, () => {
+                const fx = fixture(id);
+                assert.equal(fx.expected.ok, true);
+                const head = fx.input.head;
+                assert.ok(head);
+                const hv = projectHead(head, SET_TOKENS);
+                assert.equal(hv.dim, ENCODER_HEAD_DIMS[head]);
+                assert.equal(hv.dim, fx.expected.dim, "declared dim");
+                assert.equal(hv.values.length, hv.dim);
+            });
+        }
+        test("ENC-015: zero-input produces finite all-zero vectors for every head", () => {
+            const fx = fixture("ENC-015");
+            assert.equal(fx.expected.ok, true);
+            assert.equal(fx.expected.zero, true);
+            const set = encodeVectorSet(EMPTY_TOKENS);
+            assert.equal(set.heads.length, fx.expected.heads);
+            for (const hv of set.heads) {
+                for (const v of hv.values)
+                    assert.equal(Number.isFinite(v), true, "finite");
+                assert.equal(hv.values.every((v) => v === 0), true, `head ${hv.head} all-zero`);
+                assert.equal(l2Norm(hv.values), 0);
+            }
+        });
+        test("ENC-016: asset-free trigram B emits 512 dims", () => {
+            const fx = fixture("ENC-016");
+            assert.equal(fx.expected.ok, true);
+            assert.equal(fx.expected.mode, "B");
+            assert.equal(fx.expected.width, 512);
+            const v = embedTrigram512("the model is removed but trigram B still works");
+            assert.equal(v.length, ENCODER_TRIGRAM_WIDTH);
+            assert.equal(v.length, 512);
+            const n = l2Norm(v);
+            assert.equal(n === 0 || Math.abs(n - 1) <= 1e-6, true);
+        });
+    });
+    // Suite 3 — named assertions
+    describe("VC2B named assertions", () => {
+        test("ENC-HEAD-001: all five output shapes match ordered dims", () => {
+            const fx = fixture("ENC-HEAD-001");
+            assert.equal(fx.expected.ok, true);
+            const set = encodeVectorSet(SET_TOKENS);
+            assert.deepEqual(set.heads.map((h) => h.dim), ORDERED_DIMS);
+        });
+        test("ENC-ZERO-002: empty input produces finite zero vectors", () => {
+            const fx = fixture("ENC-ZERO-002");
+            assert.equal(fx.expected.ok, true);
+            const set = encodeVectorSet(EMPTY_TOKENS);
+            for (const hv of set.heads) {
+                assert.equal(hv.values.every((v) => v === 0), true);
+                assert.equal(hv.values.every((v) => Number.isFinite(v)), true);
+            }
+        });
+        test("ENC-FALLBACK-003: removed model still yields 512d trigram B", () => {
+            const fx = fixture("ENC-FALLBACK-003");
+            assert.equal(fx.expected.ok, true);
+            assert.equal(fx.expected.mode, "B");
+            assert.equal(fx.expected.width, 512);
+            // The learned asset is gone (asset dir absent); the asset-free trigram B
+            // still produces a full 512-dim vector — no import of the learned asset.
+            const v = embedTrigram512("no learned model present, trigram independent");
+            assert.equal(v.length, 512);
+            const sel = selectTrigramBFallback();
+            assert.equal(sel.mode, "B");
+            assert.equal(sel.dim, 512);
+        });
+    });
+}

package/dist/src/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/src/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)