pi-mega-compact 0.20.42 → 0.20.43

package/src/vector-cortex/_acceptance-vc2b-heads.ts

@@ -0,0 +1,234 @@
+/** 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 interface HeadsCtx {
+  withFlagsOn: (fn: () => void) => void;
+  stageVerifyingAssetDir: (maxTokens?: number) => string;
+  SET_TOKENS: number[];
+  EMPTY_TOKENS: number[];
+  ORDERED_DIMS: number[];
+}
+
+export function registerHeads(ctx: HeadsCtx): void {
+  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: string[] = [];
+        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: string[] = [];
+        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: string[] = [];
+        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: string[] = [];
+        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: string[] = [];
+        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: string[] = [];
+        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/src/vector-cortex/encoder/asset.ts

@@ -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
@@ -88,7 +89,7 @@ function isManifest(m: unknown): m is ModelManifestV1 {
  *
  *   - 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/src/vector-cortex/encoder/bench-export.ts

@@ -17,7 +17,7 @@ export interface BenchGatesV1 {
   readonly latency: boolean;
   /** steady-state marginal RSS over the process baseline <= 150 MiB. */
   readonly rss: boolean;
-  /** the loaded model's declared opset_import equals 17. */
+  /** the loaded model's declared opset_import equals ENCODER_OPSET (21, ENC-0a re-baseline). */
   readonly opset: boolean;
   /** SHA-256 of the embedding output identical across 3 runs (maxAbsDelta=0). */
   readonly determinism: boolean;
@@ -53,7 +53,7 @@ export interface BenchResultV1 {
   readonly rssBaselineMib: number | null;
   /** rssMib - rssBaselineMib: the encoder's marginal footprint. */
   readonly rssMarginalMib: number | null;
-  /** declared opset_import (17); null when no asset manifest is readable. */
+  /** declared opset_import (21, ENC-0a re-baseline); null when no asset manifest is readable. */
   readonly opset: number | null;
   /** true when the output SHA-256 is identical across 3 runs. */
   readonly deterministic: boolean;

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

@@ -0,0 +1,125 @@
+/**
+ * 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).
+ */
+
+import type { EncoderPlatform } from "./types.js";
+
+/** Backend demotion disposition for a platform row. */
+export type BackendDemotion = "none" | "wasm" | "modeB";
+
+/** One platform row: the concrete runtime + install size + demotion disposition. */
+export interface EncoderPlatformRow {
+  readonly runtime: string;
+  readonly installMiB: number;
+  readonly demotion: BackendDemotion;
+}
+
+/**
+ * EncoderBackendDecisionV1 — the locked learned-encoder runtime-backend decision.
+ *
+ * `opset` is pinned to the literal 21 (the ENC-0a re-baseline); `artifacts`
+ * carries only aggregate digests/sizes — never message content (EVAL-REDACT-002);
+ * `blockedBy` names the open hard-gate items that DEFER part of the decision
+ * (e.g. HG-4 — the darwin-x64 demotion is ENC-0e's job).
+ */
+export interface EncoderBackendDecisionV1 {
+  readonly schema: "encoder-backend-decision-v1";
+  readonly backend: "wasm" | "native";
+  readonly budgetOk: boolean;
+  readonly opset: 21;
+  readonly platformMatrix: Readonly<Record<EncoderPlatform, EncoderPlatformRow>>;
+  readonly license: { readonly spdx: "MIT"; readonly redistribution: true };
+  readonly artifacts: {
+    readonly model: { readonly path: string; readonly bytes: number; readonly sha256: string };
+    readonly tokenizer: { readonly path: string; readonly bytes: number; readonly sha256: string };
+  };
+  readonly p95Ms: number | null;
+  readonly blockedBy: readonly string[];
+}
+
+/**
+ * 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: {
+  readonly backend: "wasm" | "native";
+  readonly budgetOk: boolean;
+  readonly p95Ms: number | null;
+  readonly platformMatrix: Readonly<Record<EncoderPlatform, EncoderPlatformRow>>;
+  readonly modelPath: string;
+  readonly modelBytes: number;
+  readonly modelSha256: string;
+  readonly tokenizerPath: string;
+  readonly tokenizerBytes: number;
+  readonly tokenizerSha256: string;
+  readonly blockedBy: readonly string[];
+}): EncoderBackendDecisionV1 {
+  const { platformMatrix } = input;
+  const platforms: readonly EncoderPlatform[] = [
+    "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/src/vector-cortex/encoder/runtime-native.ts

@@ -45,7 +45,7 @@ export interface OrtNativeModule {
 
 /** The backend's inference session — a thin wrapper over the real native session. */
 export interface NativeSession {
-  /** The declared ONNX opset in the loaded manifest (normative 17). */
+  /** The declared ONNX opset in the loaded manifest (normative 21). */
   readonly opset: number;
   /** The semantic embedding width (normative 384). */
   readonly semanticWidth: number;

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

@@ -45,7 +45,7 @@ export interface OrtWasmModule {
 
 /** The backend's inference session — a thin wrapper over the real WASM session. */
 export interface WasmSession {
-  /** The declared ONNX opset in the loaded manifest (normative 17). */
+  /** The declared ONNX opset in the loaded manifest (normative 21). */
   readonly opset: number;
   /** The semantic embedding width (normative 384). */
   readonly semanticWidth: number;

package/src/vector-cortex/encoder/types-vc2c.ts

@@ -0,0 +1,124 @@
+/**
+ * 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).
+ */
+
+import type { EncoderHeadName } from "./types.js";
+
+/**
+ * Held-out metrics recorded as qualification evidence for a candidate asset
+ * (EVALUATION.md §metrics). Semantic metrics are Spearman rho + recall@10;
+ * dependency directed precision/recall; contradiction precision/recall/ECE;
+ * cache precision/recall; payload-routing macro-F1 + exact/anchor recall;
+ * reconstruction is the binary causality/exact/closure/task-success set. The
+ * qualification decision (task 3 `select.ts`) consumes ONLY the per-head rows
+ * this record carries; the true EVALUATION thresholds are the normative
+ * constants in MODEL_ASSET (mirrored in `EVALUATION_THRESHOLDS` below).
+ */
+export interface EncoderHeldOutMetrics {
+  /** Semantic: Spearman rho (>= .75) and recall@10 (>= .90). */
+  readonly semantic: { readonly spearman: number; readonly recallAt10: number };
+  /** Dependency: directed precision (>= .97) and recall (>= .95). */
+  readonly dependency: { readonly precision: number; readonly recall: number };
+  /** Contradiction: precision (>= .98), recall (>= .90), ECE (<= .05). */
+  readonly contradiction: { readonly precision: number; readonly recall: number; readonly ece: number };
+  /** Cache: precision (>= .999, zero false-stable) and recall (>= .90). */
+  readonly cacheStability: { readonly precision: number; readonly recall: number };
+  /** Payload routing: macro-F1 (>= .97) and exact/anchor recall (1.0). */
+  readonly payloadRouting: { readonly macroF1: number; readonly exactAnchorRecall: number };
+  /** Reconstruction: binary gates — zero causal/tool/anchor/exact violations. */
+  readonly reconstruction: {
+    readonly votesOk: boolean;
+    readonly dependencyClosureRecall: number;
+    readonly taskSuccessNonInferior: boolean;
+  };
+}
+
+/** 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 },
+} as const;
+
+/**
+ * CalibrationV1 — fitted temperature/isotonic calibration, frozen on the
+ * CALIBRATION split only (VC2C task 2). Held-out test labels NEVER enter the
+ * fit inputs (calibration-fit prohibition). The split digest proves the exact
+ * calibration assignment (grouped by repository+session); the frozen temp/threshold
+ * values are what `select.ts` stamps into a `QualifiedEncoderV1`.
+ */
+export interface CalibrationV1 {
+  readonly schema: "calibration-v1";
+  readonly headOrder: readonly EncoderHeadName[];
+  /** SHA-256 of the calibration split assignment (grouped repository+session). */
+  readonly calibrationSplitDigest: string;
+  /** Fitted on the calibration split only; held-out labels excluded from fit. */
+  readonly fittedOnCalibrationOnly: true;
+  /** Frozen per-head temperature (isotonic calibration reference points). */
+  readonly temperatures: Readonly<Record<EncoderHeadName, number>>;
+  /** Frozen per-head decision thresholds for the qualified decision. */
+  readonly thresholds: Readonly<Record<EncoderHeadName, number>>;
+  /** Seed of the deterministic calibration fit. */
+  readonly seed: number;
+}
+
+/**
+ * QualifiedEncoderV1 — the VC2C-owned eligibility record (mode A). Produced by
+ * `select.ts` ONLY when EVERY MODEL_ASSET + per-head EVALUATION threshold
+ * passes (atomic — one failed field demotes all of A). Pins the asset digest,
+ * the calibration digest, the held-out metrics that justified eligibility, and
+ * the calibration reference, so VC3A receives a fully self-describing candidate.
+ */
+export interface QualifiedEncoderV1 {
+  readonly schema: "qualified-encoder-v1";
+  readonly modelVersion: string;
+  readonly mode: "A";
+  /** SHA-256 of the asset manifest bytes (ModelManifestV1) that qualified.
+   *  Identical semantics to the dashboard health card's `encoderAssetDigest`
+   *  (both hash the committed manifest.json ModelManifestV1 bytes), so
+   *  downstream consumers (VC3A) pin the same digest across the seam. */
+  readonly assetDigest: string;
+  /** SHA-256 of the calibration split assignment (grouped repository+session)
+   *  that the CalibrationV1 was fitted on — the calibration's core identity. */
+  readonly calibrationDigest: string;
+  /** SHA-256 of the qualified asset's verified ONNX bytes (digest-pinned). */
+  readonly onnxDigest: string;
+  /** Held-out metrics recorded as the eligibility evidence. */
+  readonly heldOut: EncoderHeldOutMetrics;
+  /** Calibration reference this qualification is grounded in. */
+  readonly calibration: CalibrationV1;
+}
+
+/** 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",
+} as const;
+
+/** The 4 registered VC2C conformance IDs (task 1: "register ENC-017..020"). */
+export const ENC2C_IDS: readonly string[] = [
+  "ENC-017",
+  "ENC-018",
+  "ENC-019",
+  "ENC-020",
+];