pi-mega-compact 0.17.1 → 0.18.1

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

@@ -0,0 +1,283 @@
+/**
+ * vector-cortex/encoder/runtime.ts — VC2A EncoderRuntime (task 3).
+ *
+ * Allocates (prepares an inference session) ONLY after manifest verification;
+ * rejects any non (batch 1, tokens <= maxTokens, <=512) input with
+ * ENC_SHAPE_INVALID; caps the encoder's MARGINAL footprint at 150 MiB
+ * (ENC_RSS_BUDGET_EXCEEDED -> mode B); and yields a deterministic mode-A
+ * inference over the verified asset (the trained weights are substituted in
+ * VC2C — the contract, shape gating and budgets all land here).
+ *
+ * MEMORY BUDGET (Q01/Q02): the 150 MiB cap measures the encoder's INCREMENTAL
+ * footprint — an in-process allocation counter (`selfAllocated`) plus any
+ * externally staged asset working set (`host.allocatedBytes()`) — NOT the
+ * whole-process RSS. In a live pi extension the process baseline (node:sqlite
+ * DatabaseSync + dashboard + loaded context) routinely exceeds 150 MiB, so an
+ * absolute-RSS cap would permanently demote a qualified asset to mode B and
+ * make mode A unreachable in production. Bounding the marginal footprint keeps
+ * mode A reachable while still enforcing the budget. `selfAllocated` models a
+ * single REUSABLE 384-float projection buffer (first inference allocates it,
+ * every later inference reuses it), so it is capped at `SEMANTIC_BUFFER_BYTES`
+ * — the marginal footprint can never grow without bound (Q01), and a long-lived
+ * runtime cannot drift over budget from healthy operation. The check runs
+ * BEFORE the allocation on both the load and the inference path
+ * (cap-before-allocation, task 3), and an over-budget inference demotes the
+ * runtime to mode B just as an over-budget load does (consistent demotion per
+ * ENC_FAIL.RSS_BUDGET_EXCEEDED).
+ *
+ * TOKEN CAPACITY (Q03): the per-manifest `maxTokens` (<= 512) is stored at load
+ * and enforced at inference — an input longer than the verified manifest's
+ * declared capacity is rejected with ENC_SHAPE_INVALID, honoring the model
+ * contract rather than a global 512 ceiling.
+ *
+ * FLAG GATING (Q04): the default factory consults `MEGACOMPACT_VC2A`; when the
+ * flag is OFF the runtime is fixed at mode C (rollback, byte-identical to the
+ * predecessor — no asset is read or verified). `forcedMode: "C"` is the
+ * explicit override for the same rollback path.
+ *
+ * Triad: A = qualified local ONNX (verified); B = asset-free trigram (forced by
+ * a missing/unsupported/digest-bad asset, no remote fetch); C = lexical forced
+ * when A verification fails AND B initialization itself fails. Demotions always
+ * select B/C locally and never attempt a network fetch (PREVENT-PI-004).
+ *
+ * Pi-agnostic. No `any` (PREVENT-011). Emits the two VC2A events via the
+ * reporter (non-fatal).
+ */
+
+import {
+  detectPlatform,
+  readEncoderManifest,
+  verifyEncoderAsset,
+  type AssetVerifyResult,
+} from "./asset.js";
+import { createEncoderReporter, type EncoderReporter } from "./emit.js";
+import { VC2A_ENABLED } from "../../config/vector-cortex.js";
+import {
+  ENC_FAIL,
+  ENCODER_MAX_TOKENS,
+  ENCODER_RSS_BUDGET_BYTES,
+  ENCODER_SEMANTIC_WIDTH,
+  type EncoderInferResult,
+  type EncoderInput,
+  type EncoderLoadResult,
+  type EncoderMode,
+  type EncoderRuntime,
+} from "./types.js";
+
+/** Bytes a single encoder-owned projection buffer commits to the marginal
+ *  footprint (Float32Array, 4 bytes per element). */
+const SEMANTIC_BUFFER_BYTES = ENCODER_SEMANTIC_WIDTH * 4;
+
+/** Injectable seam for allocation accounting + allocator + clock so tests can
+ *  drive failures deterministically. Allocation accounting is the encoder's
+ *  MARGINAL footprint (Q01) — NOT whole-process RSS. */
+export interface RuntimeHost {
+  /** External bytes already committed to the encoder's incremental working set
+   *  (e.g. an ONNX session buffer staged outside this runtime). Default 0. */
+  readonly allocatedBytes: () => number;
+  readonly allocatorFails: () => boolean;
+  readonly nowMs: () => number;
+}
+
+const DEFAULT_HOST: RuntimeHost = {
+  allocatedBytes: () => 0,
+  allocatorFails: () => false,
+  nowMs: () => Date.now(),
+};
+
+export interface CreateEncoderRuntimeOptions {
+  readonly reporter?: EncoderReporter;
+  readonly host?: Partial<RuntimeHost>;
+  /** Force the rollback path: load() always returns mode C without verifying
+   *  any asset (byte-identical to the pre-triad derived pointer). A/B forcing
+   *  is intentionally not offered — those are reached by verification outcome,
+   *  not by fiat. When omitted, the flag defaults gating applies (Q04):
+   *  `MEGACOMPACT_VC2A=0` fixes the runtime at mode C automatically. */
+  readonly forcedMode?: "C";
+  /** Override the platform detector (tests / cross-platform demotion). */
+  readonly platform?: () => ReturnType<typeof detectPlatform>;
+}
+
+function mergeHost(partial?: Partial<RuntimeHost>): RuntimeHost {
+  return { ...DEFAULT_HOST, ...partial };
+}
+
+/** A deterministic seeded projection so the mode-A inference path is testable
+ *  end-to-end without onnxruntime (real weights + execution are VC2C). */
+function projectSemantic(seed: number, n: number): Float32Array {
+  const out = new Float32Array(n);
+  let state = (seed >>> 0) ^ 0x9e3779b9;
+  let sum = 0;
+  for (let i = 0; i < n; i++) {
+    state = (state * 1664525 + 1013904223) >>> 0;
+    out[i] = (state / 4294967296) * 2 - 1;
+    sum += out[i]! * out[i]!;
+  }
+  const norm = Math.sqrt(sum) || 1;
+  for (let i = 0; i < n; i++) out[i] = out[i]! / norm;
+  return out;
+}
+
+/** Deterministic token seed derived from the verified asset bytes count. */
+function seedFromBytes(embeddedBytes: number): number {
+  return (embeddedBytes * 2654435761) >>> 0;
+}
+
+function modeLabel(mode: EncoderMode): string {
+  return mode === "A" ? "qualified-onnx" : mode === "B" ? "trigram" : "lexical";
+}
+
+export function createEncoderRuntime(
+  options: CreateEncoderRuntimeOptions = {},
+): EncoderRuntime {
+  const reporter = options.reporter ?? createEncoderReporter();
+  const host = mergeHost(options.host);
+  const forced = options.forcedMode;
+  const plat = options.platform ?? detectPlatform;
+
+  // Q04: rollback contract — MEGACOMPACT_VC2A=0 selects mode C (byte-identical
+  // to the predecessor: no asset read/verify, no learned infer). An explicit
+  // forcedMode "C" takes precedence; otherwise the flag gates the default.
+  const rolledBack = forced === "C" || !VC2A_ENABLED();
+  let mode: EncoderMode = rolledBack ? "C" : "C";
+  let embeddedBytes = 0;
+  let verified = false;
+  /** Per-manifest token capacity (<= 512) from the verified asset; enforced at
+   *  inference (Q03). Defaults to the global ceiling before a load. */
+  let maxTokens = ENCODER_MAX_TOKENS;
+  /** Bytes this runtime itself has allocated. This models a SINGLE reusable
+   *  384-float projection buffer: the first inference allocates it (1536
+   *  bytes), every later inference reuses it, so the counter is capped at
+   *  `SEMANTIC_BUFFER_BYTES` and never grows without bound (Q01). Combined
+   *  with `host.allocatedBytes()` it drives the 150 MiB marginal budget (Q02),
+   *  never whole-process RSS. */
+  let selfAllocated = 0;
+
+  /** The encoder's marginal working-set footprint, in bytes. */
+  const footprint = (): number => selfAllocated + host.allocatedBytes();
+
+  const demoteTo = (rmode: "B" | "C", code: string): void => {
+    mode = rmode;
+    verified = false;
+    reporter.runtimeDemoted({ reason: code, mode: rmode, platform: plat()?.toString() ?? "unsupported" });
+  };
+
+  const runtime: EncoderRuntime = {
+    schema: "encoder-runtime-v1",
+    // Live getter so `mode` always reflects the latest load/demote outcome
+    // (a plain property would freeze at its construction-time value forever).
+    get mode(): EncoderMode {
+      return mode;
+    },
+    load(assetDir: string): EncoderLoadResult {
+      if (rolledBack) {
+        // Rollback path (forcedMode "C" or MEGACOMPACT_VC2A=0): mode C restores
+        // the prior derived pointer; no asset is read or verified; no emission.
+        // Q04: report the rollback with its own code, not MANIFEST_INVALID, so a
+        // correctly-shaped, digest-correct asset is not mis-read as corrupted.
+        mode = "C";
+        verified = false;
+        return { ok: false, mode: "C", code: ENC_FAIL.ROLLBACK };
+      }
+      // Attempt A: verify the local qualified ONNX asset (never a remote fetch).
+      const manifest = readEncoderManifest(assetDir);
+      let verify: AssetVerifyResult;
+      if (manifest === null) {
+        verify = { ok: false, code: ENC_FAIL.MANIFEST_INVALID };
+      } else {
+        verify = verifyEncoderAsset(assetDir, manifest, plat());
+      }
+
+      if (!verify.ok) {
+        // A failed -> B, unless B init itself fails (allocator) -> C.
+        if (host.allocatorFails()) {
+          demoteTo("C", ENC_FAIL.ASSET_UNREADABLE);
+          return { ok: false, mode: "C", code: ENC_FAIL.ASSET_UNREADABLE };
+        }
+        demoteTo("B", verify.code);
+        return { ok: false, mode: "B", code: verify.code };
+      }
+
+      // Allocate only after verification (task 3). Simulate allocator failure.
+      if (host.allocatorFails()) {
+        demoteTo("B", ENC_FAIL.ASSET_UNREADABLE);
+        return { ok: false, mode: "B", code: ENC_FAIL.ASSET_UNREADABLE };
+      }
+
+      // Cap the encoder's MARGINAL footprint at 150 MiB (task 3, Q01). This
+      // bounds the encoder's incremental allocation, so a healthy process with
+      // a large baseline RSS still reaches mode A.
+      if (footprint() > ENCODER_RSS_BUDGET_BYTES) {
+        demoteTo("B", ENC_FAIL.RSS_BUDGET_EXCEEDED);
+        return { ok: false, mode: "B", code: ENC_FAIL.RSS_BUDGET_EXCEEDED };
+      }
+
+      embeddedBytes = verify.embeddedBytes;
+      // Q03: record the verified manifest's token capacity so inference can
+      // enforce the model's declared maximum, not just the global 512 ceiling.
+      maxTokens = verify.maxTokens;
+      verified = true;
+      mode = "A";
+      reporter.assetVerified({
+        mode: "A",
+        embeddedBytes: verify.embeddedBytes,
+        onnxDigest: verify.onnxDigest.slice(0, 12),
+      });
+      return {
+        ok: true,
+        mode: "A",
+        embeddedBytes: verify.embeddedBytes,
+        rssBytes: footprint(),
+        sessionId: `enc-${seedFromBytes(verify.embeddedBytes).toString(16)}`,
+      };
+    },
+    infer(input: EncoderInput): EncoderInferResult {
+      if (!verified || mode !== "A") {
+        // Only batch1/max512 verified assets reach inference (mode B/C do not).
+        return {
+          ok: false,
+          code: ENC_FAIL.SHAPE_INVALID,
+          shapeError: "no verified learned asset; mode is " + modeLabel(mode),
+        };
+      }
+      if (!input || !Array.isArray(input.tokens)) {
+        return { ok: false, code: ENC_FAIL.SHAPE_INVALID, shapeError: "missing tokens array" };
+      }
+      const n = input.tokens.length;
+      // Q03: enforce the per-manifest maxTokens (<= global 512 ceiling), so an
+      // over-cap request against a low-cap verified asset is rejected rather
+      // than silently exceeding the model's declared capacity.
+      if (n < 1 || n > maxTokens) {
+        return {
+          ok: false,
+          code: ENC_FAIL.SHAPE_INVALID,
+          shapeError: `token count ${n} outside 1..${maxTokens} (manifest cap)`,
+        };
+      }
+      // Q03: cap-before-allocation on the inference path too. Check the
+      // marginal footprint BEFORE allocating the projection buffer; an
+      // over-budget inference demotes to mode B consistently with load() (the
+      // ENC_FAIL.RSS_BUDGET_EXCEEDED model: "measured RSS over 150 MiB -> B"),
+      // so a subsequent infer no longer attempts allocation in a stale mode A.
+      if (footprint() > ENCODER_RSS_BUDGET_BYTES) {
+        demoteTo("B", ENC_FAIL.RSS_BUDGET_EXCEEDED);
+        return {
+          ok: false,
+          code: ENC_FAIL.RSS_BUDGET_EXCEEDED,
+          shapeError: "encoder footprint over budget during inference",
+        };
+      }
+      const start = host.nowMs();
+      // Batch is always 1 (single request); shape is (1, n) for n in 1..maxTokens.
+      const semantic = projectSemantic(seedFromBytes(embeddedBytes) ^ n, ENCODER_SEMANTIC_WIDTH);
+      // Q01: the projection buffer is a single reusable 384-float array; the
+      // marginal footprint is a fixed SEMANTIC_BUFFER_BYTES once it exists, so
+      // selfAllocated is SET (never accumulated) — bounded regardless of how
+      // many inferences run on a long-lived runtime.
+      selfAllocated = SEMANTIC_BUFFER_BYTES;
+      const latencyMs = host.nowMs() - start;
+      return { ok: true, semantic, rssBytes: footprint(), latencyMs, shapeError: null };
+    },
+  };
+  return runtime;
+}

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

@@ -0,0 +1,85 @@
+/**
+ * vector-cortex/encoder/trigram.ts — VC2B mode B: asset-free trigram encoder.
+ *
+ * Trigram B is a deterministic, asset-free (no learned model, no manifest, no
+ * calibration) 512-dim fixed feature encoding of a token/phrase sequence. It is
+ * the mode-B fallback selected when the learned asset (mode A) is removed,
+ * missing, unsupported, or digest-bad — and it never imports the learned asset
+ * or learned calibration (task 4). It derives directly from textual authority:
+ * the same document hashed via its byte-level trigrams yields the same 512-dim
+ * vector regardless of the asset state.
+ *
+ * Width is fixed at `ENCODER_TRIGRAM_WIDTH = 512` (VC2B task 4 "trigram B at 512
+ * dimensions"). The vector is L2-normalized; a zero-norm (empty) input maps to
+ * the all-zero vector, matching the heads convention of the VectorSet.
+ *
+ * Failure-triad independence: B's algorithm/index is distinct from A (learned
+ * projections) and C (token/phrase lexical) — it is a deterministic hashed
+ * n-gram bag-of-hashes, computed purely in-process with no external asset.
+ *
+ * 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 trigram B (VC2B task 4). */
+export const ENCODER_TRIGRAM_WIDTH = 512;
+
+/** Tokenize a phrase into byte-level trigrams (3-byte sliding windows). For a
+ *  short phrase with fewer than 3 bytes we still emit the available shingles. */
+function trigrams(text: string): string[] {
+  const bytes = Buffer.from(text, "utf8");
+  if (bytes.length === 0) return [];
+  const out: string[] = [];
+  const n = bytes.length;
+  // `Math.max(1, n - 2)` already emits a single whole-string shingle for 1- and
+  // 2-byte phrases (slice(0,3) covers the whole buffer), so there is NO separate
+  // short-phrase block — adding one would hash the same shingle twice (Q05).
+  for (let i = 0; i < Math.max(1, n - 2); i++) {
+    const chunk = bytes.slice(i, i + 3);
+    out.push(chunk.toString("hex"));
+  }
+  return out;
+}
+
+/**
+ * Encode a phrase into a 512-dim L2-normalized trigram vector (all-zero on
+ * empty input). Deterministic: the same text always yields the same vector
+ * (repeat drift == 0) — no asset, no calibration, no network.
+ */
+export function embedTrigram512(text: string): Float32Array {
+  const width = ENCODER_TRIGRAM_WIDTH;
+  const out = new Float32Array(width);
+  // Feistel-style double hashing of each trigram into a bucket index + weight.
+  for (const tg of trigrams(text)) {
+    const h1 = createHash("sha256").update(tg).digest();
+    const bucket = h1.readUInt32BE(0) % width;
+    const weight = (h1.readUInt32BE(4) / 4294967295) * 2 - 1;
+    out[bucket] += weight;
+  }
+  return l2Normalize(out);
+}
+
+/**
+ * The 512-dim vector is produced even when the learned asset is absent: this is
+ * the mode-B selection point. Returns `{ ok: true, dim, width }` always — there
+ * is no asset to consult (task 4 + ENC-FALLBACK-003). Selecting mode B also
+ * emits `vector_cortex_encoder_fallback_selected` via the flag-gated reporter
+ * (task 5) — the production seam that makes the fallback event live in the
+ * runtime, not dead test-only wiring.
+ */
+export function selectTrigramBFallback(
+  options: { readonly reporter?: EncoderHeadsReporter } = {},
+): { ok: true; dim: number; width: number; mode: "B" } {
+  const reporter = options.reporter ?? createEncoderHeadsReporter();
+  const selection = { ok: true as const, mode: "B" as const, dim: ENCODER_TRIGRAM_WIDTH, width: ENCODER_TRIGRAM_WIDTH };
+  reporter.fallbackSelected({ mode: selection.mode, dim: selection.dim, width: selection.width });
+  return selection;
+}
+
+export { l2Normalize };

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

@@ -0,0 +1,275 @@
+/**
+ * vector-cortex/encoder/types.ts — VC2A contract (ModelManifestV1 /
+ * EncoderRuntime).
+ *
+ * The offline encoder runtime owns the learned-asset path (triad mode A: a
+ * qualified local ONNX). MODEL_ASSET.md is the normative target. This
+ * sprint (VC2A) ships the manifest + verification + shaped-inference contract;
+ * the trained weights are packaged in VC2C (MODEL_ASSET: "package.json changes
+ * occur only in VC2C"), but the verification, digest-before-load, platform
+ * demotion, shape rejection and RSS/latency budget all land here so a later
+ * sprint only substitutes real weights.
+ *
+ * Contract-first (ENGINEERING_PRACTICES §3): this types file is the reviewed
+ * gate; implementations import from it; consumers import only types + factory.
+ *
+ * Pi-agnostic and dependency-free (PREVENT-PI-004 — local assets only, the
+ * runtime never fetches). No `any` (PREVENT-011).
+ */
+
+/** The normative encoder pool; a tokenizer must be digest-covered. */
+export type EncoderPlatform =
+  | "linux-x64"
+  | "linux-arm64"
+  | "darwin-x64"
+  | "darwin-arm64"
+  | "win32-x64";
+
+/** Supported matrix from MODEL_ASSET.md §qualification. */
+export const ENCODER_SUPPORTED_PLATFORMS: readonly EncoderPlatform[] = [
+  "linux-x64",
+  "linux-arm64",
+  "darwin-x64",
+  "darwin-arm64",
+  "win32-x64",
+];
+
+/** ONNX opset required by the normative v1 target (opset 17). */
+export const ENCODER_OPSET = 17;
+/** Batch must be exactly 1 (single-request inference). */
+export const ENCODER_BATCH = 1;
+/** Maximum accepted token count (WordPiece, deterministic truncation). */
+export const ENCODER_MAX_TOKENS = 512;
+/** Caps the encoder's MARGINAL footprint (bytes) at 150 MiB (MODEL_ASSET
+ *  §qualification). The budget bounds the encoder's own incremental allocation
+ *  (a reusable projection buffer + any externally staged asset working set),
+ *  NOT the whole-process RSS — in a live pi extension the process baseline
+ *  routinely exceeds 150 MiB, so measuring absolute RSS would make mode A
+ *  unreachable in production. This is the "RSS" figure the acceptance metric
+ *  and ENC_FAIL.RSS_BUDGET_EXCEEDED refer to: it is the encoder's marginal
+ *  footprint, never the process RSS (code-review Q01/Q02). */
+export const ENCODER_RSS_BUDGET_BYTES = 150 * 1024 * 1024;
+/** p95 inference budget in milliseconds (MODEL_ASSET §qualification). */
+export const ENCODER_LATENCY_P95_MS = 40;
+/** Semantic projection head width (MODEL_ASSET: 384 float32 L2-normalized). */
+export const ENCODER_SEMANTIC_WIDTH = 384;
+
+/** A digest-pinned asset file declared in the manifest. */
+export interface ManifestAssetFile {
+  readonly path: string;
+  readonly sha256: string;
+  readonly bytes: number;
+}
+
+/** The five independent projection heads (MODEL_ASSET §decision record). */
+export interface EncoderHeads {
+  readonly semantic: number;
+  readonly dependency: number;
+  readonly contradiction: number;
+  readonly cacheStability: number;
+  readonly payloadRouting: number;
+}
+
+/**
+ * ModelManifestV1 — the digest/opset/platform/input/output contract for the
+ * offline encoder asset. Every byte of the ONNX + tokenizer is covered by a
+ * SHA-256 recorded here; verification hashes the files BEFORE load.
+ */
+export interface ModelManifestV1 {
+  readonly schema: "model-manifest-v1";
+  readonly modelVersion: string;
+  readonly opset: number;
+  readonly batch: number;
+  readonly maxTokens: number;
+  readonly platform: EncoderPlatform;
+  readonly hiddenWidth: number;
+  readonly semanticWidth: number;
+  readonly heads: EncoderHeads;
+  readonly onnx: ManifestAssetFile;
+  readonly tokenizer: ManifestAssetFile;
+  readonly totalBytes: number;
+  readonly trainingManifestDigest: string;
+}
+
+/** Result of loading the encoder runtime (mode A qualified load). */
+export type EncoderLoadResult =
+  | { ok: true; mode: "A"; embeddedBytes: number; rssBytes: number; sessionId: string }
+  | { ok: false; mode: "B" | "C"; code: string };
+
+/** A single shaped inference request: batch 1, max 512 tokens. */
+export interface EncoderInput {
+  readonly tokens: readonly number[];
+}
+
+/** Result of a single inference (mode A only; mode B/C do not infer). */
+export type EncoderInferResult =
+  | { ok: true; semantic: Float32Array; rssBytes: number; latencyMs: number; shapeError: null }
+  | { ok: false; code: string; shapeError: string };
+
+/**
+ * EncoderRuntime — allocate only after manifest verification; infer only for a
+ * verified, qualified asset. `mode` is "A" when the local qualified ONNX is
+ * active; "B" when an unsupported platform / missing asset / digest mismatch
+ * demoted to the asset-free trigram (no remote fetch); "C" when both A and B
+ * initialization failed (lexical fallback).
+ */
+export interface EncoderRuntime {
+  readonly schema: "encoder-runtime-v1";
+  readonly mode: EncoderMode;
+  load(assetDir: string): EncoderLoadResult;
+  infer(input: EncoderInput): EncoderInferResult;
+}
+
+export type EncoderMode = "A" | "B" | "C";
+
+/** Exact VC2A failure codes (returned, never thrown across the boundary). */
+export const ENC_FAIL = {
+  /** opset != 17. */
+  OPSET_INVALID: "ENC_OPSET_INVALID",
+  /** batch != 1. */
+  BATCH_INVALID: "ENC_BATCH_INVALID",
+  /** maxTokens > 512. */
+  TOKENS_EXCEEDED: "ENC_TOKENS_EXCEEDED",
+  /** input token count > declared maxTokens / 512, or not batch 1. */
+  SHAPE_INVALID: "ENC_SHAPE_INVALID",
+  /** asset file unreadable (truncated during digest read, allocator failure). */
+  ASSET_UNREADABLE: "ENC_ASSET_UNREADABLE",
+  /** on-disk digest does not match the manifest (one-byte mutation). */
+  DIGEST_MISMATCH: "ENC_DIGEST_MISMATCH",
+  /** platform not in the supported matrix (selects trigram B). */
+  PLATFORM_UNSUPPORTED: "ENC_PLATFORM_UNSUPPORTED",
+  /** manifest missing/invalid (selects trigram B). */
+  MANIFEST_INVALID: "ENC_MANIFEST_INVALID",
+  /** encoder MARGINAL footprint over the 150 MiB budget (selects trigram B).
+   *  This is the encoder's own incremental allocation (a reusable projection
+   *  buffer + any externally staged asset working set), NOT whole-process RSS
+   *  — see ENCODER_RSS_BUDGET_BYTES. */
+  RSS_BUDGET_EXCEEDED: "ENC_RSS_BUDGET_EXCEEDED",
+  /** mode C forced by the rollback path (MEGACOMPACT_VC2A=0 / forcedMode "C").
+   *  Distinct from MANIFEST_INVALID so a non-corrupt, correctly-shaped asset
+   *  present on disk is not mis-reported as "manifest invalid" when the runtime
+   *  is simply rolled back to the predecessor path (code-review Q04). */
+  ROLLBACK: "ENC_ROLLBACK_ACTIVE",
+} as const;
+
+/** The 8 registered VC2A conformance IDs (task 1: "register ENC-001..008"). */
+export const ENC_IDS: readonly string[] = [
+  "ENC-001",
+  "ENC-002",
+  "ENC-003",
+  "ENC-004",
+  "ENC-005",
+  "ENC-006",
+  "ENC-007",
+  "ENC-008",
+];
+
+// ---------------------------------------------------------------------------
+// VC2B — multi-head encoder (VectorSetV1 / HeadCalibrationDraft).
+// ---------------------------------------------------------------------------
+
+/** The five independent projection heads in STABLE order (MODEL_ASSET
+ *  §decision record; VC2B task 2 "stable order"). The array order is the
+ *  normative ordering consumed by consumers: semantic, dependency,
+ *  contradiction, cache-stability, payload-routing. */
+export const ENCODER_HEAD_ORDER = [
+  "semantic",
+  "dependency",
+  "contradiction",
+  "cacheStability",
+  "payloadRouting",
+] as const;
+
+/** Five head names (stable, matching ENCODER_HEAD_ORDER). */
+export type EncoderHeadName = (typeof ENCODER_HEAD_ORDER)[number];
+
+/** The ordered per-head output dimensions: semantic 384, dependency 128,
+ *  contradiction 128, cacheStability 64, payloadRouting 32 (VC2B task 2). */
+export const ENCODER_HEAD_DIMS: Readonly<Record<EncoderHeadName, number>> = {
+  semantic: 384,
+  dependency: 128,
+  contradiction: 128,
+  cacheStability: 64,
+  payloadRouting: 32,
+};
+
+/** Ordered dimension list matching ENCODER_HEAD_ORDER (384/128/128/64/32). */
+export const ENCODER_HEAD_DIM_ORDER: readonly number[] = ENCODER_HEAD_ORDER.map(
+  (h) => ENCODER_HEAD_DIMS[h],
+);
+
+/**
+ * Weighted training losses per head (MODEL_ASSET §data/losses/calibration):
+ * semantic .35, dependency .20, contradiction .20, cache .15, payload .10.
+ * These are normative (VC2B task 3: "losses exactly .35/.20/.20/.15/.10").
+ */
+export const ENCODER_HEAD_LOSS_WEIGHTS: Readonly<Record<EncoderHeadName, number>> = {
+  semantic: 0.35,
+  dependency: 0.2,
+  contradiction: 0.2,
+  cacheStability: 0.15,
+  payloadRouting: 0.1,
+};
+
+/** Sum of the five loss weights must be exactly 1.0 (asserted in tests). */
+export const ENCODER_HEAD_LOSS_SUM = 1.0;
+
+/** Deterministic seed shared by Python/NumPy training and ONNX export (VC2B
+ *  task 3: "seed ... at 1729"). */
+export const ENCODER_SEED = 1729;
+
+/**
+ * A single produced per-head vector. `head` names the head (stable order),
+ * `dim` is that head's declared dimension, `values` is the L2-normalized
+ * Float32Array (all-zero when the raw projection had zero norm — VC2B task 2).
+ */
+export interface HeadVector {
+  readonly head: EncoderHeadName;
+  readonly dim: number;
+  readonly values: Float32Array;
+}
+
+/**
+ * VectorSetV1 — the produced multi-head encoded vectors for one input slice,
+ * in STABLE order (semantic → payloadRouting). This is the VC2B-owned contract
+ * handed to VC3A ("VC3A receives qualified VectorSet or explicit B/C mode").
+ */
+export interface VectorSetV1 {
+  readonly schema: "vector-set-v1";
+  readonly inputTokens: readonly number[];
+  readonly heads: readonly HeadVector[];
+  /** True when every head was L2-normalized (or all-zero on zero norm). */
+  readonly normalized: boolean;
+}
+
+/**
+ * HeadCalibrationDraft — the VC2B-owned calibration draft produced BEFORE
+ * training/export logic (task 1). Calibration is FITTED on the calibration
+ * split only in VC2C (CalibrationV1); this draft records the frozen per-head
+ * losses, seed, dimension order, and the corpus/split digests that training
+ * must reproduce (task 3).
+ */
+export interface HeadCalibrationDraft {
+  readonly schema: "head-calibration-draft-v1";
+  readonly headOrder: readonly EncoderHeadName[];
+  readonly dims: Readonly<Record<EncoderHeadName, number>>;
+  readonly losses: Readonly<Record<EncoderHeadName, number>>;
+  readonly seed: number;
+  /** SHA-256 of the training corpus manifest (task 3, persisted). */
+  readonly corpusDigest: string;
+  /** SHA-256 of the split assignment (train/calibration/test) by
+   *  repository+session group (EVALUATION.md §corpus). */
+  readonly splitDigest: string;
+}
+
+/** The 16 registered VC2B conformance IDs (task 1: "register ENC-009..016"). */
+export const ENC2B_IDS: readonly string[] = [
+  "ENC-009",
+  "ENC-010",
+  "ENC-011",
+  "ENC-012",
+  "ENC-013",
+  "ENC-014",
+  "ENC-015",
+  "ENC-016",
+];