pi-mega-compact 0.18.0 → 0.19.0

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

@@ -0,0 +1,142 @@
+/**
+ * vector-cortex/encoder/heads.ts — VC2B multi-head encoder (tasks 1–2).
+ *
+ * Produces a `VectorSetV1`: five independent L2-normalized projection heads in
+ * STABLE order — semantic 384, dependency 128, contradiction 128, cacheStability
+ * 64, payloadRouting 32 (MODEL_ASSET §decision record). Each head L2-normalizes
+ * its raw projection; a zero-norm projection maps to an all-zero vector (task 2).
+ *
+ * The raw per-head projection is a deterministic seeded compression of the input
+ * token sequence (seeded by `ENCODER_SEED` and the head's stable index), which
+ * mirrors the VC2A `projectSemantic` placeholder pattern: the contract, shape
+ * gating, normalization, zero-norm mapping, ordering and loss/seed constants are
+ * all normative here; real trained weights are substituted in VC2C. This keeps
+ * the mode-A multi-head path fully testable end-to-end today with zero network.
+ *
+ * The VC2B emit seam (task 5) is wired: producing a VectorSetV1 emits
+ * `vector_cortex_encoder_heads_emitted`; selecting a mode B/C fallback emits
+ * `vector_cortex_encoder_fallback_selected` — both gated on MEGACOMPACT_VC2B.
+ *
+ * Pi-agnostic, zero network (PREVENT-PI-004), no `any` (PREVENT-011).
+ */
+
+import {
+  ENCODER_HEAD_DIMS,
+  ENCODER_HEAD_ORDER,
+  ENCODER_HEAD_LOSS_WEIGHTS,
+  ENCODER_HEAD_LOSS_SUM,
+  ENCODER_SEED,
+  type EncoderHeadName,
+  type HeadVector,
+  type VectorSetV1,
+} from "./types.js";
+import {
+  createEncoderHeadsReporter,
+  NOOP_VC2B_REPORTER,
+  type EncoderHeadsReporter,
+} from "./emit-vc2b.js";
+
+/** The stable head index of a head name (its position in ENCODER_HEAD_ORDER). */
+const HEAD_INDEX: Readonly<Record<EncoderHeadName, number>> = {
+  semantic: 0,
+  dependency: 1,
+  contradiction: 2,
+  cacheStability: 3,
+  payloadRouting: 4,
+};
+
+/** Deterministic 32-bit LCG step (matches runtime.ts projectSemantic). */
+function nextState(state: number): number {
+  return (state * 1664525 + 1013904223) >>> 0;
+}
+
+export interface HeadProjectionOptions {
+  readonly seed?: number;
+  readonly reporter?: EncoderHeadsReporter;
+}
+
+/**
+ * L2-normalize a float vector in place semantics (returns a new Float32Array).
+ * A zero-norm (or empty) input maps to an all-zero vector of the same length
+ * (task 2: "mapping zero norm to an all-zero vector"). All finite.
+ */
+export function l2Normalize(values: Float32Array): Float32Array {
+  const out = new Float32Array(values.length);
+  let sum = 0;
+  for (const v of values) sum += v * v;
+  const norm = Math.sqrt(sum);
+  if (!(norm > 0)) return out; // zero norm -> all-zero
+  for (let i = 0; i < values.length; i++) out[i] = values[i]! / norm;
+  return out;
+}
+
+/** L2 norm of a Float32Array (0 for empty/all-zero). */
+export function l2Norm(values: Float32Array): number {
+  let sum = 0;
+  for (const v of values) sum += v * v;
+  return Math.sqrt(sum);
+}
+
+/** A deterministic per-head projection over the token sequence, pre-normalization. */
+function projectRaw(head: EncoderHeadName, tokens: readonly number[], seed: number): Float32Array {
+  const dim = ENCODER_HEAD_DIMS[head];
+  const out = new Float32Array(dim);
+  // An EMPTY token sequence has no signal: the raw projection is the zero vector,
+  // so after L2 normalization it maps to the all-zero vector (task 2: "mapping
+  // zero norm to an all-zero vector"; ENC-ZERO-002). This keeps empty input
+  // finite and zero-norm instead of seeding spurious unit-norm noise.
+  if (tokens.length === 0) return out;
+  // Mix the stable head index + ENCODER_SEED + seed into a per-head state so
+  // each head is a distinct independent projection (failure-triad independence).
+  let state = (((ENCODER_SEED ^ HEAD_INDEX[head]) >>> 0) ^ (seed >>> 0)) ^ 0x9e3779b9;
+  for (const t of tokens) state = nextState(state ^ ((t >>> 0) * 2654435761));
+  for (let i = 0; i < dim; i++) {
+    state = nextState(state ^ seed);
+    out[i] = (state / 4294967296) * 2 - 1;
+  }
+  return out;
+}
+
+/**
+ * Compute one head's L2-normalized vector (all-zero on zero norm) for a token
+ * sequence. Deterministic for a given seed (repeat drift == 0).
+ */
+export function projectHead(
+  head: EncoderHeadName,
+  tokens: readonly number[],
+  seed: number = ENCODER_SEED,
+): HeadVector {
+  const raw = projectRaw(head, tokens, seed);
+  return { head, dim: ENCODER_HEAD_DIMS[head], values: l2Normalize(raw) };
+}
+
+/**
+ * Encode a token sequence into a `VectorSetV1`: the five heads in stable order,
+ * each L2-normalized (all-zero on zero norm). Emits `heads_emitted` via the
+ * reporter (non-fatal, flag-gated). Deterministic for a given seed.
+ */
+export function encodeVectorSet(
+  tokens: readonly number[],
+  options: HeadProjectionOptions = {},
+): VectorSetV1 {
+  const seed = options.seed ?? ENCODER_SEED;
+  const reporter = options.reporter ?? createEncoderHeadsReporter();
+  const heads: HeadVector[] = ENCODER_HEAD_ORDER.map((h) => projectHead(h, tokens, seed));
+  reporter.headsEmitted({
+    heads: heads.length,
+    dims: heads.map((h) => h.dim).join("/"),
+    normalized: true,
+    tokens: tokens.length,
+  });
+  return { schema: "vector-set-v1", inputTokens: [...tokens], heads, normalized: true };
+}
+
+/**
+ * The per-head loss weights (must sum to ENCODER_HEAD_LOSS_SUM exactly).
+ * Exposed for training/tests to assert the normative .35/.20/.20/.15/.10 split.
+ */
+export function headLossWeights(): Readonly<Record<EncoderHeadName, number>> {
+  return { ...ENCODER_HEAD_LOSS_WEIGHTS };
+}
+
+export { ENCODER_HEAD_ORDER, ENCODER_HEAD_DIMS, ENCODER_HEAD_LOSS_SUM, ENCODER_SEED, NOOP_VC2B_REPORTER };

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

@@ -0,0 +1,123 @@
+/**
+ * vector-cortex/encoder/lexical.ts — VC2B mode C: token/phrase lexical encoder.
+ *
+ * Lexical C is a token/phrase lexical feature generator used when both mode A
+ * (learned asset) and mode B (trigram) are unavailable or fail. It is continuity,
+ * NOT semantic completeness: C operates on exact current tokens/phrases only and
+ * MUST state that it has lost old semantic context (task 4 + TRIAD_RESILIENCE.
+ * "C is continuity, not semantic completeness: it may omit old context and must
+ * report that limitation").
+ *
+ * C never imports the learned asset or learned calibration (task 4): it is a
+ * pure token/phrase lexical projection (token counts + phrase hashes) computed
+ * from the exact input. It is independently implemented from B (which hashes
+ * byte-level trigrams) — C works at the token/phrase level, B at the byte-ngram
+ * level, so the two share no algorithm.
+ *
+ * Authority outage freezes derived high-water: C never advances any derived
+ * frontier; it is purely a local reconstruction from the exact present tokens.
+ *
+ * Pi-agnostic, zero network (PREVENT-PI-004), no `any` (PREVENT-011).
+ */
+
+import { createHash } from "node:crypto";
+import { l2Normalize } from "./heads.js";
+import {
+  createEncoderHeadsReporter,
+  type EncoderHeadsReporter,
+} from "./emit-vc2b.js";
+
+/** Fixed output width of lexical C. */
+export const ENCODER_LEXICAL_WIDTH = 256;
+
+/** The documented limitation lexical C reports (continuity, not semantics). */
+export const ENCODER_LEXICAL_LIMITATION =
+  "lexical C: token/phrase-level continuity only; old semantic context is omitted";
+
+export function tokenizeLexical(text: string): string[] {
+  // Split into lowercase token/phrase units on non-alphanumeric boundaries.
+  return text.toLowerCase().split(/[^a-z0-9_]+/).filter((t) => t.length > 0);
+}
+
+/**
+ * Normalize a single token/phrase unit the same way `tokenizeLexical` does for
+ * the string form: lowercase and strip leading/trailing non-alphanumeric runs.
+ * Applied to array-form tokens so both accepted input forms of `embedLexical`
+ * hash identical conceptual content to identical buckets, regardless of how the
+ * caller chose to pass it (code-review Q03).
+ */
+function normalizeToken(tok: string): string {
+  return tok.toLowerCase().split(/[^a-z0-9_]+/).join("");
+}
+
+/**
+ * Resolve either accepted input form to a normalized token sequence: the string
+ * form routes through `tokenizeLexical` (split on non-alphanumeric boundaries,
+ * fragmented tokens discarded); the array form applies the same per-token
+ * lowercase/strip normalization and drops tokens that normalize to empty. Both
+ * paths therefore agree on hash buckets for the same conceptual content.
+ */
+function resolveTokens(tokensOrText: readonly string[] | string): string[] {
+  if (typeof tokensOrText === "string") return tokenizeLexical(tokensOrText);
+  const out: string[] = [];
+  for (const raw of tokensOrText) {
+    const norm = normalizeToken(raw);
+    if (norm.length > 0) out.push(norm);
+  }
+  return out;
+}
+
+/**
+ * Encode a token/phrase sequence into a 256-dim L2-normalized lexical vector
+ * (all-zero on empty input). Features: exact token count + token id-hash sums +
+ * phrase-adjacency hashes. Deterministic (repeat drift == 0). Pure local compute.
+ */
+export function embedLexical(tokensOrText: readonly string[] | string): Float32Array {
+  const width = ENCODER_LEXICAL_WIDTH;
+  const out = new Float32Array(width);
+  const tokens = resolveTokens(tokensOrText);
+  for (let i = 0; i < tokens.length; i++) {
+    const tok = tokens[i]!;
+    const h = createHash("sha256").update(`t:${tok}`).digest();
+    const bucket = h.readUInt32BE(0) % width;
+    const weight = (h.readUInt32BE(4) / 4294967295) * 2 - 1;
+    out[bucket] += weight;
+    // Phrase adjacency: bigram hash blended in so semantic-free ordering matters.
+    if (i > 0) {
+      const pair = createHash("sha256").update(`p:${tokens[i - 1]}:${tok}`).digest();
+      const pb = pair.readUInt32BE(0) % width;
+      const pw = (pair.readUInt32BE(4) / 4294967295) * 2 - 1;
+      out[pb] += pw;
+    }
+  }
+  return l2Normalize(out);
+}
+
+/** The documented limitation string, surfaced when lexical C is selected. */
+export function selectLexicalC(
+  options: { readonly reporter?: EncoderHeadsReporter } = {},
+): {
+  ok: true;
+  mode: "C";
+  dim: number;
+  width: number;
+  limitation: string;
+} {
+  const reporter = options.reporter ?? createEncoderHeadsReporter();
+  const selection = {
+    ok: true as const,
+    mode: "C" as const,
+    dim: ENCODER_LEXICAL_WIDTH,
+    width: ENCODER_LEXICAL_WIDTH,
+    limitation: ENCODER_LEXICAL_LIMITATION,
+  };
+  reporter.fallbackSelected({
+    mode: selection.mode,
+    dim: selection.dim,
+    width: selection.width,
+    limitation: selection.limitation,
+  });
+  return selection;
+}
+
+export { l2Normalize };

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

@@ -0,0 +1,163 @@
+/**
+ * vector-cortex/encoder/router.ts — VC2B encode-or-fallback router (S2).
+ *
+ * The single production seam that catches a real VC2A `load()` failure and
+ * hands off to the independently initialized VC2B fallbacks:
+ *
+ *   - mode A: the learned multi-head projection — an EncoderRuntime that
+ *     verifies+loads a local qualified ONNX (VC2A) plus `encodeVectorSet`
+ *     producing VectorSetV1, emitting `vector_cortex_encoder_heads_emitted`;
+ *   - when that `load()` fails for ANY reason (removed model ->
+ *     ENC_ASSET_UNREADABLE, digest mismatch -> ENC_DIGEST_MISMATCH, missing
+ *     manifest -> ENC_MANIFEST_INVALID, unsupported platform, RSS over budget,
+ *     ...) the router catches the real failure and selects the independently
+ *     initialized asset-free trigram B (`selectTrigramBFallback`) — or lexical C
+ *     when the runtime reports B-unavailable / the caller forces mode C. The
+ *     `vector_cortex_encoder_fallback_selected` event fires from the REAL
+ *     producer seam, not test wiring (task 5 + code-review S1).
+ *
+ * Best-effort and non-fatal: every branch returns an explicit verdict and never
+ * throws across the boundary into the agent loop. Flag-OFF parity: with
+ * `MEGACOMPACT_VC2B=0` the VC2B reporter is a no-op (zero emissions), and the
+ * mode-A path is governed by the VC2A runtime itself — the router only adds the
+ * fallback handoff and changes no producer bytes.
+ *
+ * Pi-agnostic, zero network (PREVENT-PI-004), no `any` (PREVENT-011).
+ */
+
+import { createEncoderRuntime } from "./runtime.js";
+import { encodeVectorSet, type HeadProjectionOptions } from "./heads.js";
+import { embedTrigram512, selectTrigramBFallback } from "./trigram.js";
+import { embedLexical, selectLexicalC } from "./lexical.js";
+import { createEncoderHeadsReporter, type EncoderHeadsReporter } from "./emit-vc2b.js";
+import {
+  ENC_FAIL,
+  type EncoderInput,
+  type EncoderLoadResult,
+  type EncoderRuntime,
+  type VectorSetV1,
+} from "./types.js";
+
+/** A resolved encode decision: a qualified mode-A VectorSet, an explicit B/C
+ *  fallback vector, or a hard failure. */
+export type RouterVerdict =
+  | { readonly ok: true; readonly mode: "A"; readonly vectorSet: VectorSetV1; readonly code: null }
+  | {
+      readonly ok: true;
+      readonly mode: "B" | "C";
+      readonly vector: Float32Array;
+      readonly width: number;
+      /** Semantic-context limitation (mode C) or null (mode B). */
+      readonly limitation: string | null;
+      /** The VC2A failure code that triggered the fallback (e.g.
+       *  ENC_ASSET_UNREADABLE), or null when the caller forced the mode. */
+      readonly code: string | null;
+    }
+  | { readonly ok: false; readonly mode: "B" | "C"; readonly code: string };
+
+export interface RouterOptions extends HeadProjectionOptions {
+  /** The VC2A runtime (mode A path). Defaults to a freshly created runtime. */
+  readonly runtime?: EncoderRuntime;
+  /** Forced fallback: skips the A load and selects the named VC2B fallback
+   *  (used to exercise C when A and B are both disabled). Optional. */
+  readonly forceFallback?: "B" | "C";
+}
+
+/** Deterministic text derived from an int token sequence so the asset-free
+ *  fallback producers operate on the same authority the learned path encoded. */
+function textFromTokens(tokens: readonly number[]): string {
+  return tokens.join("-");
+}
+
+/**
+ * Try to produce an encoding for an input token sequence. Mode A: verify+load
+ * the local learned asset via the EncoderRuntime; on a real `load()` failure
+ * (removed model, digest mismatch, missing manifest, ...) the router catches it
+ * and selects the independently initialized trigram B or lexical C, emitting
+ * `vector_cortex_encoder_fallback_selected` (and `heads_emitted` when A wins).
+ */
+export function encodeOrFallback(
+  input: EncoderInput,
+  assetDir: string,
+  options: RouterOptions = {},
+): RouterVerdict {
+  const reporter = options.reporter ?? createEncoderHeadsReporter();
+  const tokens = Array.isArray(input?.tokens) ? input.tokens : [];
+  const runtime = options.runtime ?? createEncoderRuntime();
+
+  // A caller that explicitly forces a fallback mode wins even over the empty-
+  // input degenerate case: the forced-mode contract must hold for ANY input, so
+  // handle forceFallback before the empty-input selection below (Q02). A forced
+  // B/C is NOT a rollback and NOT a demotion — it is an intentional selection
+  // for capacity/testing — so the verdict carries `code: null`, never
+  // ENC_FAIL.ROLLBACK, so a consumer that reads `verdict.code` as "what
+  // triggered the fallback" won't misread a deliberately forced mode as a
+  // rollback and take rollback-specific action (code-review Q04).
+  if (options.forceFallback !== undefined) {
+    if (options.forceFallback === "C") {
+      const sel = selectLexicalC({ reporter });
+      const vector = embedLexical(textFromTokens(tokens));
+      return { ok: true, mode: "C", vector, width: sel.width, limitation: sel.limitation, code: null };
+    }
+    const sel = selectTrigramBFallback({ reporter });
+    const vector = embedTrigram512(textFromTokens(tokens));
+    return { ok: true, mode: "B", vector, width: sel.width, limitation: null, code: null };
+  }
+
+  // Empty input yields the asset-free fallback (finite, deterministic zero
+  // vector, ENC-ZERO-002). This is legitimate degenerate behavior, NOT a shape
+  // failure, so the verdict carries no failure code (code === null) — a consumer
+  // that interprets `code` as "what went wrong" must not misread a valid all-zero
+  // B vector as a shape rejection (Q05). Only reached when no mode is forced, so
+  // a forced B/C is never subverted by empty tokens.
+  if (tokens.length === 0) {
+    const sel = selectTrigramBFallback({ reporter });
+    const vector = embedTrigram512("");
+    return { ok: true, mode: "B", vector, width: sel.width, limitation: null, code: null };
+  }
+
+  // Mode A attempt — reached only when no mode is forced (the forceFallback
+  // guard at the top already returned), so `options.forceFallback` is undefined here.
+  const loaded = runtime.load(assetDir);
+  if (!loaded.ok) {
+    return fallbackFromLoad(loaded, reporter, tokens);
+  }
+  // Q01/Q03: a qualified mode-A load is not enough — the verified per-manifest
+  // token capacity (maxTokens, <= global 512) must also be enforced before we
+  // produce a VectorSetV1. run inference over the input; an over-cap sequence
+  // (e.g. 100 tokens against a verified maxTokens=64 manifest) or an
+  // over-budget inference is rejected here and routed to the B/C fallback with
+  // the real failure code, rather than silently emitting an ok:true mode-A
+  // set whose inputTokens breach the model's declared capacity.
+  const inferred = runtime.infer({ tokens });
+  if (!inferred.ok) {
+    return fallbackFromLoad({ ok: false, mode: "B", code: inferred.code }, reporter, tokens);
+  }
+  const vectorSet = encodeVectorSet(tokens, { reporter, seed: options.seed });
+  return { ok: true, mode: "A", vectorSet, code: null };
+}
+
+/**
+ * Catch a (real or forced) A load failure (ok === false only) and select the
+ * B/C fallback that emits `vector_cortex_encoder_fallback_selected` from the
+ * production seam. The parameter is narrowed to the failed-load variant because
+ * the router hands off here only on a non-A/failed load — a qualified mode-A
+ * success never reaches this function (Q04).
+ */
+function fallbackFromLoad(
+  loaded: Extract<EncoderLoadResult, { ok: false }>,
+  reporter: EncoderHeadsReporter,
+  tokens: readonly number[],
+): RouterVerdict {
+  if (loaded.mode === "C") {
+    const sel = selectLexicalC({ reporter });
+    const vector = embedLexical(textFromTokens(tokens));
+    return { ok: true, mode: "C", vector, width: sel.width, limitation: sel.limitation, code: loaded.code };
+  }
+  const sel = selectTrigramBFallback({ reporter });
+  const vector = embedTrigram512(textFromTokens(tokens));
+  return { ok: true, mode: "B", vector, width: sel.width, limitation: null, code: loaded.code };
+}
+
+export { ENC_FAIL };
+export type { EncoderRuntime };

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

@@ -0,0 +1,237 @@
+/**
+ * vector-cortex/encoder/select.ts — VC2C atomic qualification selection (task 3).
+ *
+ * Selects mode A (a `QualifiedEncoderV1`) ONLY when EVERY MODEL_ASSET
+ * constraint AND every per-head EVALUATION threshold passes — the eligibility
+ * check is ATOMIC: any single failed field demotes the ENTIRE candidate to
+ * mode B/C (never a partial A). The failed field is reported so the caller/UI
+ * can inspect which threshold tripped.
+ *
+ *   - asset fields (MODEL_ASSET §qualification): maxTokens <= 512, p95 latency
+ *     <= 40 ms, encoder RSS delta <= 150 MiB. When an asset field fails, the
+ *     demotion code is `ENC_QUALIFICATION_ASSET_FAILED`; per-head / reconstruction
+ *     failures report `ENC_QUALIFICATION_THRESHOLD_FAILED`. Either way the check is
+ *     atomic — the field that tripped is surfaced via `failedField`.
+ *   - per-head EVALUATION thresholds (EVALUATION.md §metrics):
+ *       semantic      spearman >= .75, recall@10 >= .90
+ *       dependency    precision >= .97, recall >= .95
+ *       contradiction precision >= .98, recall >= .90, ECE <= .05
+ *       cacheStability precision >= .999, recall >= .90
+ *       payloadRouting macro-F1 >= .97, exact/anchor recall = 1.0
+ *   - reconstruction: zero causal/tool/anchor/exact violations, dependency
+ *     closure recall = 1.0, task-success non-inferior to C.
+ *
+ * Unique failure injection: when a candidate supplies an expected
+ * `qualificationManifestDigest` (the digest of the qualification manifest
+ * sealed at calibration time) and the presented calibration digest differs,
+ * selection returns ENC_QUALIFICATION_DIGEST_MISMATCH and demotes A — the
+ * "corrupt qualification manifest after calibration but before selection" case.
+ *
+ * Emits `vector_cortex_encoder_qualification_passed` on success and
+ * `vector_cortex_encoder_qualification_demoted` on any demotion, via the
+ * flag-gated VC2C reporter. Pi-agnostic, zero network (PREVENT-PI-004), no
+ * `any` (PREVENT-011).
+ */
+
+import { createHash } from "node:crypto";
+import {
+  ENC_QUALIFICATION_FAIL,
+  EVALUATION_THRESHOLDS,
+  type CalibrationV1,
+  type EncoderHeldOutMetrics,
+  type EncoderHeadName,
+  type QualifiedEncoderV1,
+} from "./types.js";
+import {
+  createEncoderQualificationReporter,
+  type EncoderQualificationReporter,
+} from "./emit-vc2c.js";
+
+/** The MODEL_ASSET asset constraints a candidate must satisfy (subset that
+ *  select.ts evaluates; the rest — supported matrix, opset, batch, digest — are
+ *  enforced by the VC2A asset verification seam before a candidate exists). */
+export interface CandidateAssetFacts {
+  /** Declared/verified per-manifest token capacity (<= 512). */
+  readonly maxTokens: number;
+  /** Measured p95 inference latency (ms, <= 40). */
+  readonly latencyP95Ms: number;
+  /** Measured encoder RSS delta (MiB, <= 150). */
+  readonly rssDeltaMib: number;
+}
+
+/** Inputs to the atomic eligibility check. */
+export interface QualificationCandidate {
+  readonly modelVersion: string;
+  readonly asset: CandidateAssetFacts;
+  /** The verified ONNX digest of the candidate asset. */
+  readonly onnxDigest: string;
+  /**
+   * SHA-256 of the asset manifest bytes (ModelManifestV1) that qualified — the
+   * same digest the dashboard health card reports as `encoderAssetDigest`
+   * (SHA-256 of the committed manifest.json bytes). select.ts stamps this into
+   * `QualifiedEncoderV1.assetDigest` verbatim so the record pins the true
+   * asset-manifest digest, not a calibration-derived hash.
+   */
+  readonly assetManifestDigest: string;
+  /** Calibration digest the asset is qualified against (from `CalibrationV1`). */
+  readonly calibration: CalibrationV1;
+  /** Held-out metrics as evidence (EVALUATION.md). */
+  readonly heldOut: EncoderHeldOutMetrics;
+  /**
+   * The qualification manifest digest sealed at calibration time. When supplied,
+   * it must equal SHA-256 over the calibration manifest bytes; a mismatch is the
+   * corrupt-qualification-manifest injection (ENC_QUALIFICATION_DIGEST_MISMATCH).
+   */
+  readonly expectedQualificationManifestDigest?: string;
+}
+
+/**
+ * The qualification verdict. A successful candidate is mode A; ANY demotion here
+ * is mode B — select.ts never produces mode C. Mode C (lexical/exact) is
+ * exclusively the output of the separate fallback seam (`fallback.ts`, selected
+ * only when A is absent AND B itself errors or the caller forces C). The type is
+ * narrowed to "B" on failure to match the implementation: demoting a candidate
+ * is the same "asset-free, non-learned" fallback regardless of which field
+ * tripped; the lexical C demotion is not a property of qualification selection.
+ */
+export type QualificationVerdict =
+  | { ok: true; mode: "A"; qualified: QualifiedEncoderV1; code: null }
+  | { ok: false; mode: "B"; code: string; failedField: string | null };
+
+/** Canonical digest over a CalibrationV1's stable identity (split digest, heads,
+ *  temps, thresholds, seed) — the "qualification manifest digest". */
+export function qualificationManifestDigest(calibration: CalibrationV1): string {
+  const payload = JSON.stringify({
+    headOrder: [...calibration.headOrder].sort(),
+    splitDigest: calibration.calibrationSplitDigest,
+    temps: calibration.temperatures,
+    thresholds: calibration.thresholds,
+    seed: calibration.seed,
+  });
+  return createHash("sha256").update(payload).digest("hex");
+}
+
+/** True when one per-head metric row clears its normative EVALUATION threshold. */
+function headPasses(head: EncoderHeadName, m: EncoderHeldOutMetrics): boolean {
+  switch (head) {
+    case "semantic":
+      return m.semantic.spearman >= EVALUATION_THRESHOLDS.semantic.spearman &&
+        m.semantic.recallAt10 >= EVALUATION_THRESHOLDS.semantic.recallAt10;
+    case "dependency":
+      return m.dependency.precision >= EVALUATION_THRESHOLDS.dependency.precision &&
+        m.dependency.recall >= EVALUATION_THRESHOLDS.dependency.recall;
+    case "contradiction":
+      return m.contradiction.precision >= EVALUATION_THRESHOLDS.contradiction.precision &&
+        m.contradiction.recall >= EVALUATION_THRESHOLDS.contradiction.recall &&
+        m.contradiction.ece <= EVALUATION_THRESHOLDS.contradiction.ece;
+    case "cacheStability":
+      return m.cacheStability.precision >= EVALUATION_THRESHOLDS.cacheStability.precision &&
+        m.cacheStability.recall >= EVALUATION_THRESHOLDS.cacheStability.recall;
+    case "payloadRouting":
+      return m.payloadRouting.macroF1 >= EVALUATION_THRESHOLDS.payloadRouting.macroF1 &&
+        m.payloadRouting.exactAnchorRecall >= EVALUATION_THRESHOLDS.payloadRouting.exactAnchorRecall;
+  }
+}
+
+function reconstructionPasses(m: EncoderHeldOutMetrics): boolean {
+  return (
+    m.reconstruction.votesOk &&
+    m.reconstruction.dependencyClosureRecall >= EVALUATION_THRESHOLDS.reconstruction.dependencyClosureRecall &&
+    m.reconstruction.taskSuccessNonInferior
+  );
+}
+
+function assetPasses(a: CandidateAssetFacts, failed: string[]): boolean {
+  let ok = true;
+  if (a.maxTokens > EVALUATION_THRESHOLDS.asset.maxTokens) { failed.push("asset.maxTokens"); ok = false; }
+  if (a.latencyP95Ms > EVALUATION_THRESHOLDS.asset.maxLatencyP95Ms) { failed.push("asset.latencyP95Ms"); ok = false; }
+  if (a.rssDeltaMib > EVALUATION_THRESHOLDS.asset.maxRssDeltaMib) { failed.push("asset.rssDeltaMib"); ok = false; }
+  return ok;
+}
+
+/**
+ * Atomic eligibility check across every MODEL_ASSET + per-head EVALUATION
+ * threshold (task 3). Any single failed field demotes ALL of A (returns
+ * `ok:false`); there is no partial qualification. On success returns a
+ * `QualifiedEncoderV1` pinning asset/calibration digests + held-out evidence.
+ */
+export function selectQualifiedEncoder(
+  candidate: QualificationCandidate,
+  options: { reporter?: EncoderQualificationReporter } = {},
+): QualificationVerdict {
+  const reporter = options.reporter ?? createEncoderQualificationReporter();
+
+  // Unique failure injection: corrupt qualification manifest between calibration
+  // and selection. The sealed manifest digest must match the presented
+  // calibration's digest; a mismatch demotes A to B/C with the dedicated code.
+  if (candidate.expectedQualificationManifestDigest !== undefined) {
+    const presented = qualificationManifestDigest(candidate.calibration);
+    if (presented !== candidate.expectedQualificationManifestDigest) {
+      reporter.qualificationDemoted({
+        reason: ENC_QUALIFICATION_FAIL.DIGEST_MISMATCH,
+        modelVersion: candidate.modelVersion,
+        mode: "B",
+      });
+      return {
+        ok: false,
+        mode: "B",
+        code: ENC_QUALIFICATION_FAIL.DIGEST_MISMATCH,
+        failedField: "qualificationManifestDigest",
+      };
+    }
+  }
+
+  // Atomic: collect EVERY failed field across asset + all heads + reconstruction.
+  const failed: string[] = [];
+  assetPasses(candidate.asset, failed);
+  const heads: EncoderHeadName[] = ["semantic", "dependency", "contradiction", "cacheStability", "payloadRouting"];
+  for (const h of heads) {
+    if (!headPasses(h, candidate.heldOut)) failed.push(`head.${h}`);
+  }
+  if (!reconstructionPasses(candidate.heldOut)) failed.push("reconstruction");
+
+  if (failed.length > 0) {
+    // Any failed field demotes all of A — no partial A. Route the demotion code
+    // by the failed-field class: an asset-field failure (maxTokens/latency/RSS)
+    // reports ENC_QUALIFICATION_ASSET_FAILED; a per-head/reconstruction failure
+    // reports ENC_QUALIFICATION_THRESHOLD_FAILED. `failedField` always carries the
+    // specific field that tripped, so the code + field together fully identify it.
+    const assetFailed = failed.some((f) => f.startsWith("asset."));
+    const code = assetFailed
+      ? ENC_QUALIFICATION_FAIL.ASSET_FAILED
+      : ENC_QUALIFICATION_FAIL.THRESHOLD_FAILED;
+    reporter.qualificationDemoted({
+      reason: code,
+      failed: failed.join("/"),
+      modelVersion: candidate.modelVersion,
+      mode: "B",
+    });
+    return {
+      ok: false,
+      mode: "B",
+      code,
+      failedField: failed[0] ?? null,
+    };
+  }
+
+  const qualified: QualifiedEncoderV1 = {
+    schema: "qualified-encoder-v1",
+    modelVersion: candidate.modelVersion,
+    mode: "A",
+    // The REAL ModelManifestV1 asset-manifest digest (passed through the
+    // candidate), not a calibration-derived hash — matches the documented
+    // contract and the dashboard health card's encoderAssetDigest.
+    assetDigest: candidate.assetManifestDigest,
+    calibrationDigest: candidate.calibration.calibrationSplitDigest,
+    onnxDigest: candidate.onnxDigest,
+    heldOut: candidate.heldOut,
+    calibration: candidate.calibration,
+  };
+  reporter.qualificationPassed({
+    modelVersion: candidate.modelVersion,
+    mode: "A",
+    assetDigest: qualified.assetDigest.slice(0, 12),
+    calibrationDigest: qualified.calibrationDigest.slice(0, 12),
+  });
+  return { ok: true, mode: "A", qualified, code: null };
+}