pi-mega-compact 0.20.42 → 0.20.44

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

package/src/vector-cortex/_acceptance-vc2a-conformance.ts

@@ -0,0 +1,119 @@
+/**
+ * _acceptance-vc2a-conformance.ts — ENC-001..008 conformance rows + the named
+ * assertions (ENC-ASSET-001 / ENC-DIGEST-002 / ENC-PLATFORM-003), each driven
+ * through the REAL encoder asset/runtime (no mocks). Extracted from
+ * vc2a-acceptance.test.ts so the aggregator stays under the tests/ soft limit.
+ *
+ * The aggregator passes its shared imports/helpers as a context object, so this
+ * sibling never imports the aggregator (no import cycle at module load).
+ */
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import type { EncoderLoadResult } from "./encoder/types.js";
+
+/** Context from the aggregator — only domain-specific helpers, not node:test/assert. */
+export interface Vc2aConformanceCtx {
+  ENC_IDS: readonly string[];
+  ENC_FAIL: typeof import("./encoder/types.js").ENC_FAIL;
+  fixture: (id: string) => {
+    id: string;
+    input: { scenario: string };
+    expected: { ok: boolean; code?: string; mode?: string };
+  };
+  buildDir: (scenario: string) => Built;
+  rmBuilt: (b: Built) => void;
+  optionsFor: (scenario: string) => import("./encoder/runtime.js").CreateEncoderRuntimeOptions;
+  createEncoderRuntime: typeof import("./encoder/runtime.js").createEncoderRuntime;
+  verifyEncoderAsset: typeof import("./encoder/asset.js").verifyEncoderAsset;
+  readEncoderManifest: typeof import("./encoder/asset.js").readEncoderManifest;
+}
+
+/* Structural stand-in for the aggregator's local `Built` (dir + scenario). */
+interface Built {
+  dir: string;
+  scenario: string;
+}
+
+export function registerVc2aConformance(ctx: Vc2aConformanceCtx): void {
+  const {
+    ENC_IDS,
+    ENC_FAIL,
+    fixture,
+    buildDir,
+    rmBuilt,
+    optionsFor,
+    createEncoderRuntime,
+    verifyEncoderAsset,
+    readEncoderManifest,
+  } = ctx;
+
+  // -------------------------------------------------------------------------
+  // ENC-001..008 conformance rows through the real runtime
+  // -------------------------------------------------------------------------
+  describe("ENC-001..008 conformance rows", () => {
+    for (const id of ENC_IDS) {
+      test(`${id}: resolves through the real runtime to the documented result`, () => {
+        const fx = fixture(id);
+        const built = buildDir(fx.input.scenario);
+        try {
+          const rt = createEncoderRuntime(optionsFor(fx.input.scenario));
+          const load: EncoderLoadResult = rt.load(built.dir);
+          assert.equal(load.ok, fx.expected.ok, `${id} ok`);
+          if (!load.ok) {
+            assert.equal(load.code, fx.expected.code, `${id} exact failure code`);
+            if (fx.expected.mode) assert.equal(load.mode, fx.expected.mode, `${id} mode`);
+          } else {
+            assert.equal(load.mode, "A", `${id} should be mode A`);
+          }
+        } finally {
+          rmBuilt(built);
+        }
+      });
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // VC2A named assertions
+  // -------------------------------------------------------------------------
+  describe("VC2A named assertions", () => {
+    test("ENC-ASSET-001: opset21 manifest + matching digests load as mode A", () => {
+      const fx = fixture("ENC-ASSET-001");
+      assert.equal(fx.expected.ok, true);
+      const built = buildDir("valid");
+      try {
+        const load = createEncoderRuntime().load(built.dir);
+        assert.equal(load.ok, true);
+        if (load.ok) assert.equal(load.mode, "A");
+      } finally {
+        rmBuilt(built);
+      }
+    });
+    test("ENC-DIGEST-002: one-byte model mutation demotes before load", () => {
+      const fx = fixture("ENC-DIGEST-002");
+      assert.equal(fx.expected.code, ENC_FAIL.DIGEST_MISMATCH);
+      const built = buildDir("mutate-onnx");
+      try {
+        const res = verifyEncoderAsset(built.dir, readEncoderManifest(built.dir));
+        assert.equal(res.ok, false);
+        if (!res.ok) assert.equal(res.code, ENC_FAIL.DIGEST_MISMATCH);
+      } finally {
+        rmBuilt(built);
+      }
+    });
+    test("ENC-PLATFORM-003: unsupported architecture selects trigram B", () => {
+      const fx = fixture("ENC-PLATFORM-003");
+      assert.equal(fx.expected.mode, "B");
+      const built = buildDir("valid");
+      try {
+        const load = createEncoderRuntime({ platform: () => null }).load(built.dir);
+        assert.equal(load.ok, false);
+        if (!load.ok) {
+          assert.equal(load.mode, "B", "trigram B selected");
+          assert.equal(load.code, ENC_FAIL.PLATFORM_UNSUPPORTED);
+        }
+      } finally {
+        rmBuilt(built);
+      }
+    });
+  });
+}

package/src/vector-cortex/_acceptance-vc2a-runtime.ts

@@ -0,0 +1,300 @@
+/** 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";
+import type { ModelManifestV1 } from "./encoder/types.js";
+
+/** Context from the aggregator — only domain-specific helpers, not node:test/assert. */
+export interface Vc2aRuntimeCtx {
+  ENC_FAIL: typeof import("./encoder/types.js").ENC_FAIL;
+  ENCODER_RSS_BUDGET_BYTES: number;
+  ENCODER_LATENCY_P95_MS: number;
+  tmpAsset: (prefix: string) => string;
+  baseManifest: (over?: Partial<ModelManifestV1>) => ModelManifestV1;
+  buildDir: (scenario: string) => Built;
+  rmBuilt: (b: Built) => void;
+  sha256: (bytes: Uint8Array) => string;
+  percentile: (sorted: number[], p: number) => number;
+  createEncoderRuntime: typeof import("./encoder/runtime.js").createEncoderRuntime;
+  verifyEncoderAsset: typeof import("./encoder/asset.js").verifyEncoderAsset;
+  readEncoderManifest: typeof import("./encoder/asset.js").readEncoderManifest;
+}
+
+/* Structural stand-in for the aggregator's local `Built` (dir + scenario). */
+interface Built {
+  dir: string;
+  scenario: string;
+}
+
+export function registerVc2aRuntime(ctx: Vc2aRuntimeCtx): void {
+  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: number[] = [];
+        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"] as const) {
+        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/src/vector-cortex/_acceptance-vc2b-conformance.ts

@@ -0,0 +1,121 @@
+/** 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,
+  type EncoderHeadName,
+} from "./encoder/types.js";
+import { encodeVectorSet, projectHead, l2Norm } from "./encoder/heads.js";
+import {
+  embedTrigram512,
+  ENCODER_TRIGRAM_WIDTH,
+  selectTrigramBFallback,
+} from "./encoder/trigram.js";
+import type { EFixture } from "./vc2b-acceptance.test.js";
+
+export interface ConformanceCtx {
+  fixture: (id: string) => EFixture;
+  SET_TOKENS: number[];
+  EMPTY_TOKENS: number[];
+  ORDERED_DIMS: number[];
+}
+
+export function registerConformanceRows(ctx: ConformanceCtx): void {
+  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 as EncoderHeadName;
+        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);
+    });
+  });
+}