pi-mega-compact 0.18.0 → 0.19.0

package/extensions/dashboard-server/routes-vector-cortex.ts

@@ -17,11 +17,16 @@
 
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteContext } from "./routes-core.js";
-import { VC0A_ENABLED, VC0C_ENABLED, VC1B_ENABLED } from "../../src/config.js";
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { VC0A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC2C_ENABLED } from "../../src/config.js";
 import { readEvalRows } from "../../src/vector-cortex/eval/persist.js";
 import { summarizeEvalRows } from "../../src/vector-cortex/eval/reader.js";
 import { createVectorCortexSafety } from "../mega-runtime/vector-cortex-safety.js";
 import { createLedgerStore } from "../../src/vector-cortex/ledger/store.js";
+import { readEncoderManifest, verifyEncoderAsset, detectPlatform } from "../../src/vector-cortex/encoder/asset.js";
 import type {
   VectorCortexEvaluationSummary,
   VectorCortexHealthCard,
@@ -65,6 +70,102 @@ function sendJson(res: ServerResponse, status: number, body: unknown): void {
   res.end(JSON.stringify(body));
 }
 
+/** Resolve the committed encoder-v1 asset dir by walking up to the repo root. */
+function encoderAssetDir(): string | null {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  const rel = join("assets", "vector-cortex", "encoder-v1");
+  for (let i = 0; i < 8; i++) {
+    const candidate = join(dir, rel);
+    try {
+      // guardrails-allow PREVENT-PI-004: local asset filesystem read (loopback)
+      readFileSync(join(candidate, "manifest.json"));
+      return candidate;
+    } catch {
+      /* keep walking */
+    }
+    const next = dirname(dir);
+    if (next === dir) break;
+    dir = next;
+  }
+  return null;
+}
+
+/**
+ * VC2C encoder health facts (task 5): the SHA-256 of the committed qualified
+ * manifest (asset digest) and the encoder triad mode. Reader-only aggregate
+ * (digest prefix, no bytes). Gated on MEGACOMPACT_VC2C: when the flag is OFF
+ * (rollback), the card reports mode C with an absent digest — consistent with
+ * the rest of the card, whose enabled/mode fields reflect active (flag-gated)
+ * state. When ON: "A" when the committed asset verifies on this host, "B" when
+ * present but not verified (demotion), "C" when absent.
+ *
+ * The verification hashes the full ONNX + tokenizer bytes, which is expensive
+ * on a periodically-polled endpoint as the shipped asset grows. The result is
+ * memoized against a cheap key (manifest bytes + file sizes/mtimes + platform);
+ * any on-disk mutation invalidates the key, so the cache never goes stale while
+ * avoiding the repeated large-file hashing. A failed digest read returns null
+ * (an absent digest), never a misleading zero-sentinel.
+ */
+type EncoderHealthFacts = { assetDigest: string | null; mode: "A" | "B" | "C" };
+
+interface HealthFactCache {
+  key: string;
+  facts: EncoderHealthFacts;
+}
+
+let healthCache: HealthFactCache | null = null;
+
+/** Stable cache key: manifest bytes + (size,mtime) of the asset files + platform. */
+function healthFactCacheKey(dir: string, manifestPath: string): string | null {
+  const platform = detectPlatform();
+  if (!platform) return null;
+  const parts: string[] = [platform];
+  try {
+    for (const p of [manifestPath, join(dir, "model.onnx"), join(dir, "tokenizer.json")]) {
+      const s = statSync(p);
+      parts.push(`${s.size}:${s.mtimeMs}`);
+    }
+    // guardrails-allow PREVENT-PI-004: local manifest filesystem read (loopback)
+    parts.push(createHash("sha256").update(readFileSync(manifestPath)).digest("hex"));
+  } catch {
+    return null;
+  }
+  return parts.join("|");
+}
+
+function computeEncoderHealthFacts(dir: string): EncoderHealthFacts | null {
+  const manifest = readEncoderManifest(dir);
+  if (manifest === null) return { assetDigest: null, mode: "C" };
+  const manifestPath = join(dir, "manifest.json");
+  const key = healthFactCacheKey(dir, manifestPath);
+  if (key === null) return null;
+  if (healthCache !== null && healthCache.key === key) return healthCache.facts;
+  let digest: string;
+  try {
+    // guardrails-allow PREVENT-PI-004: local manifest filesystem read (loopback)
+    digest = createHash("sha256").update(readFileSync(manifestPath)).digest("hex");
+  } catch {
+    return { assetDigest: null, mode: "B" };
+  }
+  const verify = verifyEncoderAsset(dir, manifest, detectPlatform());
+  const facts: EncoderHealthFacts = { assetDigest: digest, mode: verify.ok ? "A" : "B" };
+  healthCache = { key, facts };
+  return facts;
+}
+
+function encoderHealthFacts(): EncoderHealthFacts {
+  if (!VC2C_ENABLED()) {
+    // Rollback: MEGACOMPACT_VC2C=0 selects C — report the inactive (flag-gated)
+    // mode with no asset digest rather than an on-disk-computed A/B.
+    return { assetDigest: null, mode: "C" };
+  }
+  const dir = encoderAssetDir();
+  if (dir === null) return { assetDigest: null, mode: "C" };
+  const facts = computeEncoderHealthFacts(dir);
+  if (facts === null) return { assetDigest: null, mode: "C" };
+  return facts;
+}
+
 /** Reader-only aggregate GET /api/vector-cortex/evaluation. */
 export function handleVectorCortexEvaluation(
   req: IncomingMessage,
@@ -133,6 +234,8 @@ export function handleVectorCortexHealth(
   const safety = enabled ? createVectorCortexSafety({ stateDir: ctx.stateDir }) : null;
   const card = safety ? safety.health() : null;
 
+  const enc = encoderHealthFacts();
+
   const fallback: VectorCortexHealthCard = {
     enabled: false,
     mode: "C",
@@ -152,6 +255,8 @@ export function handleVectorCortexHealth(
     updatedAt: new Date().toISOString(),
     aggregate: "CLOSED_A",
     stateSource: "ephemeral",
+    encoderAssetDigest: enc.assetDigest,
+    encoderMode: enc.mode,
   };
   if (!card) {
     sendJson(res, 200, fallback);
@@ -191,6 +296,8 @@ export function handleVectorCortexHealth(
     updatedAt: new Date().toISOString(),
     aggregate,
     stateSource: card.stateSource,
+    encoderAssetDigest: enc.assetDigest,
+    encoderMode: enc.mode,
   };
   sendJson(res, 200, body);
   return true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",
@@ -27,6 +27,7 @@
     "extensions",
     "extensions/dashboard-client/dist",
     "src",
+    "assets/vector-cortex/encoder-v1",
     "README.md",
     "LICENSE",
     "!dist/**/*.test.js",

package/src/config/vector-cortex.ts

@@ -80,6 +80,26 @@ export const VC1C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC1C");
  */
 export const VC2A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC2A");
 
+/**
+ * VC2B — multi-head encoder (VectorSetV1 / HeadCalibrationDraft).
+ * Default ON. `MEGACOMPACT_VC2B=0` disables and is byte-identical to the
+ * predecessor (the encoder emits no per-head vectors and no fallback-selected
+ * event; the trigram/lexical paths themselves are unchanged and are the
+ * predecessor's mode-B/C producers). The real consumers are the encoder-heads
+ * emit seam and the multi-head encoder producers (heads/trigram/lexical).
+ */
+export const VC2B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC2B");
+
+/**
+ * VC2C — encoder qualification + calibration (QualifiedEncoderV1 / CalibrationV1).
+ * Default ON. `MEGACOMPACT_VC2C=0` disables and is byte-identical to the
+ * predecessor (mode C: no qualification manifest is read or selected, the
+ * calibrate/select/fallback seams are idle, zero `vector_cortex_encoder_qualification_*`
+ * emissions; the trigram/lexical paths are unchanged). The real consumers are
+ * the encoder-qualification emit seam and the calibrate/select seams.
+ */
+export const VC2C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC2C");
+
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/src/config.ts

@@ -158,6 +158,8 @@ export {
   VC1B_ENABLED,
   VC1C_ENABLED,
   VC2A_ENABLED,
+  VC2B_ENABLED,
+  VC2C_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

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-vc2b.ts

@@ -0,0 +1,82 @@
+/**
+ * vector-cortex/encoder/emit-vc2b.ts — VC2B observability seam.
+ *
+ * Owns the two VC2B events (task 5), gated on `MEGACOMPACT_VC2B` so the
+ * flag-OFF path emits zero events (mode C parity, byte-identical predecessor):
+ *
+ *   vector_cortex_encoder_heads_emitted      — a multi-head VectorSetV1 produced
+ *   vector_cortex_encoder_fallback_selected  — a mode B/C fallback selected
+ *
+ * No dashboard or API change is necessary for this internal sprint (task 5).
+ * Every event is a JSON line with `ts` + `event` (ENGINEERING_PRACTICES §8); the
+ * emitters are non-fatal (never break the agent loop). Pi-agnostic, zero network
+ * (PREVENT-PI-004), no `any` (PREVENT-011).
+ */
+
+import { VC2B_ENABLED } from "../../config/vector-cortex.js";
+import { Logger } from "../../log.js";
+
+export type EncoderEmit = (event: string, fields: Record<string, unknown>) => void;
+
+/** The two-event VC2B reporter surface. */
+export interface EncoderHeadsReporter {
+  readonly headsEmitted: (fields: Record<string, unknown>) => void;
+  readonly fallbackSelected: (fields: Record<string, unknown>) => void;
+}
+
+/** A flag-gated no-op reporter (zero emissions, structural no-op). */
+export const NOOP_VC2B_REPORTER: EncoderHeadsReporter = {
+  headsEmitted: () => {},
+  fallbackSelected: () => {},
+};
+
+/**
+ * The default emitter: routes both VC2B events into the append-only structured
+ * logger (`src/log.ts`) as JSON lines with `ts` + `event`. Supplying `emit:` to
+ * `createEncoderHeadsReporter` 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 (`encodeOrFallback`, `encodeVectorSet`,
+ * `selectTrigramBFallback`, `selectLexicalC`) without injecting an emitter still
+ * yields structured telemetry instead of silently dropping every event (task 5,
+ * code-review Q01). Best-effort: the logger swallows all I/O errors.
+ */
+function defaultEmitFor(logPath: string | undefined): EncoderEmit {
+  const logger = new Logger(logPath === undefined ? {} : { path: logPath });
+  return (event, fields) => {
+    logger.info(event, fields);
+  };
+}
+
+/** Options for the default logger-backed sink (used when no `emit` is injected). */
+export interface EncoderHeadsEmitOptions {
+  /** Where the default structured sink writes (defaults to the global log path). */
+  readonly logPath?: string;
+}
+
+/**
+ * Flag-gated emit, defaulting to a real logger-backed sink. The returned
+ * reporter is itself flag-gated (`VC2B_ENABLED`), so wiring it into a producer
+ * seam yields zero emissions when `MEGACOMPACT_VC2B=0` (byte-identical to the
+ * predecessor). Pass an explicit `emit` to route elsewhere (tests, downstream
+ * consumers); omit it to emit real structured log lines (Q01: the default is a
+ * live producer, not a silent no-op). `opts.logPath` only redirects the default
+ * sink and is ignored when `emit` is supplied.
+ */
+export function createEncoderHeadsReporter(
+  emit?: EncoderEmit,
+  opts: EncoderHeadsEmitOptions = {},
+): EncoderHeadsReporter {
+  const sink = emit ?? defaultEmitFor(opts.logPath);
+  const fire = (event: string, fields: Record<string, unknown>): void => {
+    if (!VC2B_ENABLED()) return;
+    try {
+      sink(event, { ...fields, ts: new Date().toISOString() });
+    } catch {
+      /* non-fatal observability */
+    }
+  };
+  return {
+    headsEmitted: (fields) => fire("vector_cortex_encoder_heads_emitted", fields),
+    fallbackSelected: (fields) => fire("vector_cortex_encoder_fallback_selected", fields),
+  };
+}

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,
+  };
+}