pi-mega-compact 0.18.1 → 0.19.0

package/dist/src/vector-cortex/encoder/select.js

@@ -0,0 +1,172 @@
+/**
+ * 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, } from "./types.js";
+import { createEncoderQualificationReporter, } from "./emit-vc2c.js";
+/** Canonical digest over a CalibrationV1's stable identity (split digest, heads,
+ *  temps, thresholds, seed) — the "qualification manifest digest". */
+export function qualificationManifestDigest(calibration) {
+    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, m) {
+    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) {
+    return (m.reconstruction.votesOk &&
+        m.reconstruction.dependencyClosureRecall >= EVALUATION_THRESHOLDS.reconstruction.dependencyClosureRecall &&
+        m.reconstruction.taskSuccessNonInferior);
+}
+function assetPasses(a, failed) {
+    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, options = {}) {
+    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 = [];
+    assetPasses(candidate.asset, failed);
+    const heads = ["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 = {
+        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 };
+}

package/dist/src/vector-cortex/encoder/types.js

@@ -136,3 +136,34 @@ export const ENC2B_IDS = [
     "ENC-015",
     "ENC-016",
 ];
+/** 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 },
+};
+/** 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",
+};
+/** The 4 registered VC2C conformance IDs (task 1: "register ENC-017..020"). */
+export const ENC2C_IDS = [
+    "ENC-017",
+    "ENC-018",
+    "ENC-019",
+    "ENC-020",
+];

package/dist/vector-cortex/encoder/calibrate.js

@@ -0,0 +1,174 @@
+/**
+ * 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, } from "./types.js";
+/** Canonical digests of a sorted stable representation (order-invariant). */
+function digestStrings(values) {
+    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) {
+    return `${g.repository.length}:${g.repository}${g.session.length}:${g.session}`;
+}
+export function calibrationSplitDigest(groups) {
+    const rendered = new Set();
+    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) {
+    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, seed) {
+    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, examples) {
+    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, options = {}) {
+    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 = {};
+    const thresholds = {};
+    for (const head of ENCODER_HEAD_ORDER) {
+        temperatures[head] = fitTemperature(head, seed);
+        thresholds[head] = fitThreshold(head, stable);
+    }
+    const calibration = {
+        schema: "calibration-v1",
+        headOrder: [...ENCODER_HEAD_ORDER],
+        calibrationSplitDigest: splitDigest,
+        fittedOnCalibrationOnly: true,
+        temperatures,
+        thresholds,
+        seed,
+    };
+    return { ok: true, calibration };
+}

package/dist/vector-cortex/encoder/emit-vc2c.js

@@ -0,0 +1,59 @@
+/**
+ * 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";
+/**
+ * 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() {
+    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) {
+    const sink = emit ?? defaultEmitFor();
+    const fire = (event, fields) => {
+        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/dist/vector-cortex/encoder/fallback.js

@@ -0,0 +1,62 @@
+/**
+ * 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 } 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";
+/** Deterministic text derived from an int token sequence (mirrors router.ts). */
+function textFromTokens(tokens) {
+    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, tokens, options = {}) {
+    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,
+    };
+}

package/dist/vector-cortex/encoder/select.js

@@ -0,0 +1,172 @@
+/**
+ * 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, } from "./types.js";
+import { createEncoderQualificationReporter, } from "./emit-vc2c.js";
+/** Canonical digest over a CalibrationV1's stable identity (split digest, heads,
+ *  temps, thresholds, seed) — the "qualification manifest digest". */
+export function qualificationManifestDigest(calibration) {
+    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, m) {
+    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) {
+    return (m.reconstruction.votesOk &&
+        m.reconstruction.dependencyClosureRecall >= EVALUATION_THRESHOLDS.reconstruction.dependencyClosureRecall &&
+        m.reconstruction.taskSuccessNonInferior);
+}
+function assetPasses(a, failed) {
+    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, options = {}) {
+    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 = [];
+    assetPasses(candidate.asset, failed);
+    const heads = ["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 = {
+        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 };
+}