pi-mega-compact 0.18.1 → 0.19.1

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

@@ -0,0 +1,194 @@
+/**
+ * vector-cortex/cortex/types.ts — capability-gated cortex store contract (VC3A).
+ *
+ * Owns `CortexReader` / `CortexWriter` / `CortexAdmin` and `CortexRecordV1`
+ * (the immutable derived record). Consumes only reviewer-accepted predecessor
+ * contracts and [common contracts](../../CONTRACTS.md §Store and migration
+ * contracts), which are NORMATIVE here: the derived frontier cannot exceed the
+ * contiguous durable authority high-water and cannot advance during
+ * authority/spool outage.
+ *
+ * A CortexRecordV1 is a DERIVED record keyed by
+ * `(sourceHighWater, algorithmVersion, id)`. The same `id` at a different
+ * `algorithmVersion` (or a different `sourceHighWater`) is a DISTINCT record —
+ * never collapsed (CTX-KEY-002). Records are immutable: re-appending an exact
+ * `(sourceHighWater, algorithmVersion, id)` with the SAME `payloadDigest` is an
+ * idempotent acknowledge; the same key with a DIFFERENT digest is a conflict.
+ *
+ * Capability gating mirrors the host `asReader/asWriter/asAdmin` pattern and the
+ * VC1B ledger: the writer exposes append only, the reader exposes query only,
+ * and the admin alone can rebuild / switch generations. No callbacks or event
+ * emitters flow from the store; writes are non-fatal (failures log and never
+ * break the agent loop).
+ *
+ * Pure type/schema definitions + small pure predicates. No storage, no console,
+ * no network, no side effects (PREVENT-PI-004 / PREVENT-011).
+ */
+
+/**
+ * A derived cortex record — byte authority is `payloadBytes`; `payloadDigest` is
+ * the authoritative `sha256:<hex>` over those bytes. `sourceHighWater` is the
+ * durable authority high-water the record was derived AT (the derived frontier
+ * cannot exceed it); `algorithmVersion` is the producing algorithm revision.
+ */
+export interface CortexRecordV1 {
+  readonly schema: "cortex-record-v1";
+  /** Durable contiguous authority high-water this record derives from. */
+  readonly sourceHighWater: bigint;
+  /** Producing algorithm revision (records at distinct versions stay distinct). */
+  readonly algorithmVersion: number;
+  /** Stable record identity within the derived store. */
+  readonly id: string;
+  /** Record kind (semantic / dependency / contradiction / synthetic...). */
+  readonly kind: string;
+  /** Authoritative `sha256:<hex>` of `payloadBytes` (immutability anchor). */
+  readonly payloadDigest: string;
+  /** Immutable derived payload bytes (byte authority for the record). */
+  readonly payloadBytes: Uint8Array;
+}
+
+/**
+ * A derived GENEration — a named, digest-pinned front over the sorted accepted
+ * records. `rootDigest` is ONE deterministic digest over the canonical sorted
+ * key list (order-independent, CTX-REBUILD-003); `sourceHighWater` is the derived
+ * frontier (max sourceHighWater across its records).
+ */
+export interface CortexGenerationV1 {
+  readonly schema: "cortex-generation-v1";
+  readonly id: string;
+  readonly sourceHighWater: bigint;
+  readonly recordCount: number;
+  readonly rootDigest: string;
+  /** Monotonic rebuild ordinal (never regresses for an accepted generation). */
+  readonly ordinal: bigint;
+}
+
+/** Failure codes the writer surfaces on a rejected / failed append. */
+export type CortexAppendCode =
+  /** Storage failure (e.g. SQLITE_FULL). Non-fatal; host continues in mode C. */
+  | "CTX_APPEND_FAILED"
+  /** Same (sourceHighWater, algorithmVersion, id) but a different payloadDigest. */
+  | "CTX_KEY_CONFLICT";
+
+/** Result of a single append attempt. */
+export type CortexAppendResult =
+  | { ok: true; record: CortexRecordV1 }
+  | { ok: false; code: CortexAppendCode; rejected: CortexRecordV1 };
+
+/** Failure codes the admin surfaces on a rejected rebuild. */
+export type CortexRebuildCode =
+  /** A record's payloadDigest does not match its payloadBytes (authority corrupt). */
+  | "CTX_PAYLOAD_DIGEST_MISMATCH"
+  /** A record exceeds the caller's declared generation source high-water. */
+  | "CTX_HIGH_WATER_EXCEEDED"
+  /** The generation INSERT/activate write did not persist (storage failure, e.g. SQLITE_FULL). */
+  | "CTX_REBUILD_FAILED";
+
+/**
+ * Reader capability: query-only. The dashboard's reader-only GET
+ * `GET /api/vector-cortex/topology` is built on exactly this surface and nothing
+ * more — it can read the generation/topology summary and records but never
+ * append, rebuild, or switch generations.
+ */
+export interface CortexReader {
+  readonly kind: "CortexReader";
+  /** Count of accepted derived records. */
+  recordCount(): number;
+  /** Accepted records in ascending `(sourceHighWater, algorithmVersion, id)`. */
+  readRecords(): readonly CortexRecordV1[];
+  /** The single record at a composite key, or undefined. */
+  readRecord(sourceHighWater: bigint, algorithmVersion: number, id: string): CortexRecordV1 | undefined;
+  /** The latest (active) generation, or undefined when none rebuilt yet. */
+  latestGeneration(): CortexGenerationV1 | undefined;
+  /** Reader-only topology summary (the dashboard GET payload). */
+  topologySummary(): CortexTopologySummary;
+}
+
+/**
+ * Writer capability: append-only. Can add immutable derived records — but cannot
+ * query arbitrary history, rebuild, or touch generations. Enforces the composite
+ * key immutability on every append.
+ */
+export interface CortexWriter {
+  readonly kind: "CortexWriter";
+  /** Append one derived record; idempotent ack on exact key+digest, conflict otherwise. */
+  append(input: CortexAppendInput): CortexAppendResult;
+}
+
+/**
+ * Admin capability: maintenance + generation control ONLY. The sole surface with
+ * rebuild / switch-generations capability — never exposed to ingestion or the
+ * dashboard reader.
+ */
+export interface CortexAdmin {
+  readonly kind: "CortexAdmin";
+  /**
+   * Deterministically rebuild a generation from ALL accepted records: sorts keys,
+   * verifies each payload digest, computes ONE root digest, writes + activates a
+   * new generation. Idempotent with respect to unchanged accepted inputs.
+   *
+   * `authorityHighWater` (optional) is the contiguous durable authority high-water
+   * the rebuild must not outrun. When supplied and the derived frontier (max
+   * record sourceHighWater) exceeds it, the rebuild is rejected with
+   * `CTX_HIGH_WATER_EXCEEDED` and NO generation is written — the derived frontier
+   * cannot exceed the durable authority high-water (normative in CONTRACTS.md).
+   * Omit it to rebuild without an authority bound.
+   */
+  rebuild(authorityHighWater?: bigint):
+    | { ok: true; generation: CortexGenerationV1 }
+    | { ok: false; code: CortexRebuildCode };
+  /** Switch the active generation pointer without deleting evidence. */
+  switchGeneration(generationId: string): { ok: boolean; code?: string };
+  /** List every generation id in ascending ordinal order (evidence retained). */
+  listGenerations(): readonly CortexGenerationV1[];
+}
+
+/** Input shape of a single append (record fields minus the readonly full type). */
+export interface CortexAppendInput {
+  readonly sourceHighWater: bigint;
+  readonly algorithmVersion: number;
+  readonly id: string;
+  readonly kind: string;
+  readonly payloadDigest?: string;
+  readonly payloadBytes: Uint8Array;
+}
+
+/**
+ * Reader-only topology summary — the exact payload of the dashboard
+ * `GET /api/vector-cortex/topology` reader-only GET. Aggregate only: root digest
+ * prefix, record count, derived frontier. Never exposes writer/admin surfaces or
+ * raw record payloads.
+ */
+export interface CortexTopologySummary {
+  /** Whether the VC3A cortex-store flag is enabled. */
+  readonly enabled: boolean;
+  /** Active generation id, or null when no generation rebuilt yet. */
+  readonly generationId: string | null;
+  /** Active generation root digest (or null). */
+  readonly rootDigest: string | null;
+  /** Derived frontier (active generation sourceHighWater, or "0"). */
+  readonly sourceHighWater: string;
+  /** Accepted derived record count. */
+  readonly recordCount: number;
+  /** Monotonic rebuild ordinal (or null). */
+  readonly ordinal: string | null;
+}
+
+/**
+ * Registered CTX conformance ID range (CTX-001..010). The acceptance test reads
+ * these rows from the v2 manifest and asserts each returns its manifest bytes or
+ * exactly its listed failure code. The three NAMED assertions
+ * (CTX-CAP-001 / CTX-KEY-002 / CTX-REBUILD-003) live in the acceptance test.
+ */
+export const CTX_IDS = [
+  "CTX-001",
+  "CTX-002",
+  "CTX-003",
+  "CTX-004",
+  "CTX-005",
+  "CTX-006",
+  "CTX-007",
+  "CTX-008",
+  "CTX-009",
+  "CTX-010",
+] as const;

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

@@ -0,0 +1,225 @@
+/**
+ * vector-cortex/encoder/calibrate.ts — VC2C calibration fit (task 2).
+ *
+ * Fits a `CalibrationV1` using ONLY the calibration split. Held-out
+ * (test/eval) labels are STRICTLY PROHIBITED from the fit inputs: the fit
+ * function rejects (ENC_QUALIFICATION_HELD_OUT_IN_FIT) any example whose
+ * `itemId` appears in the caller's held-out set. Ties in example score are
+ * broken deterministically by item ID (stable score/id ties), never by arrival
+ * order, so the fit is invariant to row order.
+ *
+ * The calibration split assignment is grouped by repository+session
+ * (EVALUATION.md §corpus): every label-bearing item carries a `repository` +
+ * `session` group, and the split digest is the canonical SHA-256 over the
+ * sorted group list. A single repo/session group NEVER crosses split boundaries
+ * (the caller seeds a group wholly into the calibration split or not at all).
+ *
+ * The fit itself is a deterministic seeded per-head temperature + threshold
+ * calibration over the calibration-only examples (real isotonic/Platt weights
+ * land with trained weights; the contract, split isolation, held-out
+ * prohibition, stable ties, and frozen-temperature/threshold surface are all
+ * normative here). Pi-agnostic, zero network (PREVENT-PI-004), no `any`
+ * (PREVENT-011).
+ */
+
+import { createHash } from "node:crypto";
+import {
+  ENCODER_HEAD_ORDER,
+  ENCODER_SEED,
+  ENC_QUALIFICATION_FAIL,
+  type CalibrationV1,
+  type EncoderHeadName,
+} from "./types.js";
+
+/** A scored, label-bearing calibration item. `heldOutIds` forbid review labels. */
+export interface CalibrationExample {
+  readonly itemId: string;
+  readonly head: EncoderHeadName;
+  readonly score: number;
+  /** Binary ground-truth label (0/1) against which the raw score is calibrated. */
+  readonly label: 0 | 1;
+  /** Repository group (EVALUATION.md §corpus) — the split unit. */
+  readonly repository: string;
+  /** Session group (within the repository). */
+  readonly session: string;
+}
+
+export interface CalibrationFitOptions {
+  /** Seed of the deterministic fit (defaults to ENCODER_SEED). */
+  readonly seed?: number;
+}
+
+export type CalibrationFitResult =
+  | { ok: true; calibration: CalibrationV1 }
+  | { ok: false; code: string; reason: string };
+
+/** Canonical digests of a sorted stable representation (order-invariant). */
+function digestStrings(values: readonly string[]): string {
+  const sorted = [...values].sort();
+  return createHash("sha256").update(sorted.join("\n")).digest("hex");
+}
+
+/**
+ * Compute the calibration split digest for a set of (repository, session) groups
+ * present in the fit. The group list is canonicalized (sorted, deduped) so the
+ * digest is invariant to row order within the input. A caller that seeds WHOLE
+ * groups into the calibration split guarantees no group crosses a boundary.
+ */
+/**
+ * Render one (repository, session) group as an injective canonical string.
+ * Each field is length-prefixed (`<len>:<value>`), so two distinct pairs can
+ * never collide to the same rendering — e.g. `{r:"a", s:"b::c"}` renders as
+ * `1:a3:b::c` while `{r:"a::b", s:"c"}` renders as `4:a::b1:c`. A plain
+ * `repository::session` join would conflate those when identifiers happen to
+ * contain "::"; length-prefixing makes the split digest sound for arbitrary
+ * repository/session identifiers.
+ */
+function renderGroup(g: { repository: string; session: string }): string {
+  return `${g.repository.length}:${g.repository}${g.session.length}:${g.session}`;
+}
+
+export function calibrationSplitDigest(groups: readonly { repository: string; session: string }[]): string {
+  const rendered = new Set<string>();
+  for (const g of groups) rendered.add(renderGroup(g));
+  return digestStrings([...rendered]);
+}
+
+/** A deterministic 32-bit LCG step (matches the heads/runtime projectors). */
+function nextState(state: number): number {
+  return (state * 1664525 + 1013904223) >>> 0;
+}
+
+/**
+ * Deterministic per-head temperature in a stable, healthy range (e.g. 0.8..1.5).
+ *
+ * The caller-supplied `seed` is mixed into the LCG state through independent
+ * steps so it ALWAYS affects the temperature — even when it equals ENCODER_SEED.
+ * (A naive `ENCODER_SEED ^ head.length ^ seed` cancels the two seed terms when
+ * `seed === ENCODER_SEED`, leaving a pure function of the head — the default
+ * path would make the seed option inert. Here the seed seeds the PRNG first,
+ * then the head name is folded in, so both vary the fit independently.) The fit
+ * stays deterministic for a fixed (seed, head) across processes.
+ */
+function fitTemperature(head: EncoderHeadName, seed: number): number {
+  let state = (seed >>> 0) ^ 0x9e3779b9;
+  state = nextState(state);
+  state = (state ^ (head.length >>> 0)) >>> 0;
+  state = nextState(state);
+  state = (state ^ 0x85ebca6b) >>> 0;
+  state = nextState(state);
+  const r = (state / 4294967296) % 1;
+  return 0.8 + r * 0.7; // 0.8 .. 1.5
+}
+
+/**
+ * Deterministic per-head decision threshold derived from the calibration
+ * distribution. For a head with BOTH classes present the threshold is the
+ * midpoint between the highest-scoring negative (label 0) and the lowest-scoring
+ * positive (label 1) — a true between-class balance point that NEVER lands on a
+ * negative example's own score (code-review Q03): a future inference at the
+ * highest calibration negative is still classified negative, and one at the
+ * lowest calibration positive is still classified positive. Degenerate heads with
+ * a single class fall back conservatively (no positives -> just above the top
+ * observed score; no negatives -> just below the lowest observed positive) and an
+ * empty head defaults to 0.5. Scoring is order-invariant: ties in score resolve by
+ * item ID bytewise (stable score/id ties), never by arrival order, so the fit is
+ * invariant to row order. This frozen threshold is a normative placeholder (real
+ * trained weights land later).
+ */
+function fitThreshold(
+  head: EncoderHeadName,
+  examples: readonly CalibrationExample[],
+): number {
+  const headEx = examples
+    .filter((e) => e.head === head)
+    .slice()
+    .sort((a, b) => (a.score - b.score) || (a.itemId < b.itemId ? -1 : a.itemId > b.itemId ? 1 : 0));
+  if (headEx.length === 0) return 0.5;
+  let highestNeg = -Infinity;
+  let lowestPos = Infinity;
+  for (const e of headEx) {
+    if (e.label === 0) highestNeg = Math.max(highestNeg, e.score);
+    else lowestPos = Math.min(lowestPos, e.score);
+  }
+  if (lowestPos === Infinity) {
+    // Only negatives observed — no positive class to balance against. Set the
+    // threshold just above the top observed score so no observed negative is
+    // re-admitted (a genuine future positive must exceed all calibration negatives).
+    return Math.max(0.5, highestNeg + 0.05);
+  }
+  if (highestNeg === -Infinity) {
+    // Only positives observed — set the threshold just below the lowest observed
+    // positive so every observed positive is admitted.
+    return Math.max(0, lowestPos - 0.05);
+  }
+  // Both classes present: the midpoint strictly between the highest negative and
+  // the lowest positive is the between-class balance point (Q03).
+  return (highestNeg + lowestPos) / 2;
+}
+
+/**
+ * Fit `CalibrationV1` over the calibration split only (task 2).
+ *
+ *   - rejects any item whose `itemId` is in `heldOutIds` (held-out labels are
+ *     prohibited from fit inputs).
+ *   - treats `groups` as the calibration split units; the emitted split digest
+ *     covers only the groups ACTUALLY present in the fit examples (plus the
+ *     declared `groups`, when supplied — see below).
+ *   - stable score/id ties (never arrival order).
+ *
+ * Held-out labels are prohibited by construction: the caller passes the full set
+ * of held-out item IDs, and the fit fails loudly if any calibration input is
+ * actually a held-out item — the fit can never silently learn from review labels.
+ */
+export function fitCalibration(
+  examples: readonly CalibrationExample[],
+  options: CalibrationFitOptions & {
+    /** Item IDs that belong to the held-out (test/eval) split. Any calibration
+     *  input whose id appears here is a fit violation. */
+    readonly heldOutIds?: readonly string[];
+    /** Declared calibration groups (repository+session). When supplied, the split
+     *  digest covers these; otherwise it covers the groups actually in `examples`.
+     *  Whole groups never cross a split boundary when the caller seeds a group
+     *  into exactly one split. */
+    readonly groups?: readonly { repository: string; session: string }[];
+  } = {},
+): CalibrationFitResult {
+  const seed = options.seed ?? ENCODER_SEED;
+  const heldOut = new Set(options.heldOutIds ?? []);
+
+  for (const e of examples) {
+    if (heldOut.has(e.itemId)) {
+      return {
+        ok: false,
+        code: ENC_QUALIFICATION_FAIL.HELD_OUT_IN_FIT,
+        reason: `held-out item ${e.itemId} leaked into calibration fit`,
+      };
+    }
+  }
+
+  // Stable order by (score, itemId) — arrival order never affects the digest or
+  // the fit; ties resolve by item ID bytewise (stable score/id ties).
+  const stable = examples
+    .slice()
+    .sort((a, b) => (a.score - b.score) || (a.itemId < b.itemId ? -1 : a.itemId > b.itemId ? 1 : 0));
+
+  const usedGroups = options.groups ?? stable.map((e) => ({ repository: e.repository, session: e.session }));
+  const splitDigest = calibrationSplitDigest(usedGroups);
+  const temperatures: Record<EncoderHeadName, number> = {} as Record<EncoderHeadName, number>;
+  const thresholds: Record<EncoderHeadName, number> = {} as Record<EncoderHeadName, number>;
+  for (const head of ENCODER_HEAD_ORDER) {
+    temperatures[head] = fitTemperature(head, seed);
+    thresholds[head] = fitThreshold(head, stable);
+  }
+
+  const calibration: CalibrationV1 = {
+    schema: "calibration-v1",
+    headOrder: [...ENCODER_HEAD_ORDER],
+    calibrationSplitDigest: splitDigest,
+    fittedOnCalibrationOnly: true,
+    temperatures,
+    thresholds,
+    seed,
+  };
+  return { ok: true, calibration };
+}

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

@@ -0,0 +1,70 @@
+/**
+ * vector-cortex/encoder/emit-vc2c.ts — VC2C observability seam.
+ *
+ * Owns the two VC2C events (task 5), gated on `MEGACOMPACT_VC2C` so the
+ * flag-OFF path emits zero events (mode C parity, byte-identical predecessor):
+ *
+ *   vector_cortex_encoder_qualification_passed   — a QualifiedEncoderV1 produced (A)
+ *   vector_cortex_encoder_qualification_demoted  — qualification failed; all of A demoted
+ *
+ * Every event is a JSON line with `ts` + `event` (ENGINEERING_PRACTICES §8); the
+ * `ts` is the numeric epoch-ms timestamp the `Logger` injects (LogEntry.ts is
+ * `number`), so these events are consistent with the rest of the log stream
+ * (code-review Q04 — no ISO-string ts override). The emitters are non-fatal
+ * (never break the agent loop). Pi-agnostic, zero network (PREVENT-PI-004), no
+ * `any` (PREVENT-011).
+ */
+
+import { VC2C_ENABLED } from "../../config/vector-cortex.js";
+import { Logger } from "../../log.js";
+
+export type EncoderEmit = (event: string, fields: Record<string, unknown>) => void;
+
+/** The two-event VC2C reporter surface (qualification passed / demoted). */
+export interface EncoderQualificationReporter {
+  readonly qualificationPassed: (fields: Record<string, unknown>) => void;
+  readonly qualificationDemoted: (fields: Record<string, unknown>) => void;
+}
+
+/**
+ * The default emitter: routes both VC2C events into the append-only structured
+ * logger (`src/log.ts`) as JSON lines with `event` (the logger injects the
+ * numeric `ts`). Supplying `emit:` to `createEncoderQualificationReporter`
+ * replaces this with a caller-provided sink (used by tests and downstream
+ * consumers). Making the default a REAL producer means a caller that just
+ * invokes the producer seam (`selectQualifiedEncoder`) without injecting an
+ * emitter still yields structured telemetry instead of silently dropping every
+ * event (task 5). Best-effort: the logger swallows all I/O errors.
+ */
+function defaultEmitFor(): EncoderEmit {
+  const logger = new Logger();
+  return (event, fields) => {
+    logger.info(event, fields);
+  };
+}
+
+/**
+ * Flag-gated emit, defaulting to a real logger-backed sink. The returned
+ * reporter is itself flag-gated (`VC2C_ENABLED`), so wiring it into a producer
+ * seam yields zero emissions when `MEGACOMPACT_VC2C=0` (byte-identical to the
+ * predecessor). Pass an explicit `emit` to route elsewhere (tests, downstream
+ * consumers); omit it to emit real structured log lines. The `ts` is set by the
+ * underlying sink (numeric epoch-ms from `Logger`), not overridden here (Q04).
+ */
+export function createEncoderQualificationReporter(
+  emit?: EncoderEmit,
+): EncoderQualificationReporter {
+  const sink = emit ?? defaultEmitFor();
+  const fire = (event: string, fields: Record<string, unknown>): void => {
+    if (!VC2C_ENABLED()) return;
+    try {
+      sink(event, fields);
+    } catch {
+      /* non-fatal observability */
+    }
+  };
+  return {
+    qualificationPassed: (fields) => fire("vector_cortex_encoder_qualification_passed", fields),
+    qualificationDemoted: (fields) => fire("vector_cortex_encoder_qualification_demoted", fields),
+  };
+}

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

@@ -0,0 +1,99 @@
+/**
+ * vector-cortex/encoder/fallback.ts — VC2C qualification fallback selection.
+ *
+ * After a qualification demotion (qualify/select fails to produce mode A), this
+ * seam selects the mode-B/C fallback and routes the encode request to the
+ * independently initialized VC2B producers (trigram B / lexical C). It is the
+ * breaker-recovery handoff for the encoder triad:
+ *
+ *   A = fully qualified learned asset (QualifiedEncoderV1).
+ *   B = asset-free trigram, forced by ANY one failed qualification threshold
+ *       (or a qualification-manifest digest mismatch).
+ *   C = token/phrase lexical, forced when A is absent AND B itself errors
+ *       (injected B error), or when the caller forces C.
+ *
+ * Breaker recovery follows TRIAD_RESILIENCE: a demotion may probe/promote, never
+ * directly re-qualify A; the fallback only ever SELECTS B or C locally, never a
+ * remote fetch (PREVENT-PI-004). C states its loss of old semantic context.
+ *
+ * Pi-agnostic, zero network (PREVENT-PI-004), no `any` (PREVENT-011).
+ */
+
+import { createEncoderHeadsReporter, type EncoderHeadsReporter } from "./emit-vc2b.js";
+import { embedTrigram512, selectTrigramBFallback, ENCODER_TRIGRAM_WIDTH } from "./trigram.js";
+import { embedLexical, selectLexicalC, ENCODER_LEXICAL_WIDTH, ENCODER_LEXICAL_LIMITATION } from "./lexical.js";
+
+export type QualificationFallbackVerdict =
+  | {
+      readonly ok: true;
+      readonly mode: "B";
+      readonly vector: Float32Array;
+      readonly width: number;
+      /** The qualification failure code that forced B (never null on this path). */
+      readonly code: string;
+      readonly limitation: null;
+    }
+  | {
+      readonly ok: true;
+      readonly mode: "C";
+      readonly vector: Float32Array;
+      readonly width: number;
+      /** The qualification or B failure code that forced C. */
+      readonly code: string;
+      readonly limitation: string;
+    };
+
+export interface FallbackSelectionOptions {
+  readonly reporter?: EncoderHeadsReporter;
+  /** Simulates a B initializer failure (forces C despite B being available). */
+  readonly injectBError?: boolean;
+  /** Force lexical C directly (skips the B attempt). */
+  readonly forceC?: boolean;
+}
+
+/** Deterministic text derived from an int token sequence (mirrors router.ts). */
+function textFromTokens(tokens: readonly number[]): string {
+  return tokens.join("-");
+}
+
+/**
+ * Select the B/C fallback for a failed qualification and produce the encode
+ * vector. When `injectBError` or `forceC` is set, selection lands on lexical C
+ * (absent A + injected B error -> C); otherwise a qualification THRESHOLD or
+ * DIGEST mismatch selects trigram B. Never returns without an explicit verdict.
+ */
+export function selectQualificationFallback(
+  qualificationCode: string,
+  tokens: readonly number[],
+  options: FallbackSelectionOptions = {},
+): QualificationFallbackVerdict {
+  const reporter = options.reporter ?? createEncoderHeadsReporter();
+  const tokensText = textFromTokens(tokens);
+
+  // A absent + injected/forced B error -> C (lexical) with the documented
+  // semantic-context limitation.
+  if (options.forceC || options.injectBError) {
+    selectLexicalC({ reporter });
+    const vector = embedLexical(tokensText);
+    return {
+      ok: true,
+      mode: "C",
+      vector,
+      width: ENCODER_LEXICAL_WIDTH,
+      code: options.injectBError ? "ENC_B_INJECTED_ERROR" : qualificationCode,
+      limitation: ENCODER_LEXICAL_LIMITATION,
+    };
+  }
+
+  // A qualification demotion selects the independently initialized trigram B.
+  selectTrigramBFallback({ reporter });
+  const vector = embedTrigram512(tokensText);
+  return {
+    ok: true,
+    mode: "B",
+    vector,
+    width: ENCODER_TRIGRAM_WIDTH,
+    code: qualificationCode,
+    limitation: null,
+  };
+}