pi-mega-compact 0.17.1 → 0.18.1

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

@@ -0,0 +1,75 @@
+/**
+ * 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, } 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) {
+    const bytes = Buffer.from(text, "utf8");
+    if (bytes.length === 0)
+        return [];
+    const out = [];
+    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) {
+    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 = {}) {
+    const reporter = options.reporter ?? createEncoderHeadsReporter();
+    const selection = { ok: true, mode: "B", dim: ENCODER_TRIGRAM_WIDTH, width: ENCODER_TRIGRAM_WIDTH };
+    reporter.fallbackSelected({ mode: selection.mode, dim: selection.dim, width: selection.width });
+    return selection;
+}
+export { l2Normalize };

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

@@ -0,0 +1,138 @@
+/**
+ * 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).
+ */
+/** Supported matrix from MODEL_ASSET.md §qualification. */
+export const ENCODER_SUPPORTED_PLATFORMS = [
+    "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;
+/** 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",
+};
+/** The 8 registered VC2A conformance IDs (task 1: "register ENC-001..008"). */
+export const ENC_IDS = [
+    "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",
+];
+/** The ordered per-head output dimensions: semantic 384, dependency 128,
+ *  contradiction 128, cacheStability 64, payloadRouting 32 (VC2B task 2). */
+export const ENCODER_HEAD_DIMS = {
+    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 = 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 = {
+    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;
+/** The 16 registered VC2B conformance IDs (task 1: "register ENC-009..016"). */
+export const ENC2B_IDS = [
+    "ENC-009",
+    "ENC-010",
+    "ENC-011",
+    "ENC-012",
+    "ENC-013",
+    "ENC-014",
+    "ENC-015",
+    "ENC-016",
+];

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

@@ -0,0 +1,142 @@
+/**
+ * vector-cortex/encoder/asset.ts — VC2A asset verification (task 2).
+ *
+ * Verifies a ModelManifestV1 before any allocation: SHA-256 the ONNX and
+ * tokenizer against the manifest digests, require opset 17, batch exactly 1 and
+ * maximum 512 tokens, and confirm the current platform is in the supported
+ * matrix. On ANY of these the caller demotes to mode B (asset-free trigram) —
+ * never a remote fetch (PREVENT-PI-004). A truncated/unreadable asset during
+ * the digest read demotes with ENC_ASSET_UNREADABLE.
+ *
+ * Pi-agnostic. Filesystem reads only, zero network (PREVENT-PI-004).
+ */
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { ENC_FAIL, ENCODER_BATCH, ENCODER_MAX_TOKENS, ENCODER_OPSET, ENCODER_SUPPORTED_PLATFORMS, } from "./types.js";
+/** True when `p` is a single basename: non-empty, no path separators, no "..",
+ *  no leading dot-segment traversal. Keeps manifest-controlled asset paths
+ *  confined to the asset directory (no path-traversal via join()). */
+function isBasename(p) {
+    if (!p || p.length === 0 || p.includes("/") || p.includes("\\"))
+        return false;
+    if (p === "." || p === "..")
+        return false;
+    return true;
+}
+/** Digest the on-disk bytes of one asset file; "" on unreadable (truncated). */
+function digestFile(path) {
+    try {
+        const buf = readFileSync(path);
+        return createHash("sha256").update(buf).digest("hex");
+    }
+    catch {
+        // Truncated / unreadable during the digest read -> ENC_ASSET_UNREADABLE.
+        return null;
+    }
+}
+/**
+ * Detect the current platform (MODEL_ASSET supported matrix). Unrecognized
+ * hosts return null so verification demotes to mode B (unsupported platform).
+ */
+export function detectPlatform(host = process.platform, arch = process.arch) {
+    if (!host || !arch)
+        return null;
+    // Normalize "win32"/"win32"/"linux"/"darwin" + "x64"/"arm64".
+    const plat = host === "win32" ? "win32" : host === "darwin" ? "darwin" : host === "linux" ? "linux" : "";
+    const a = arch === "x64" ? "x64" : arch === "arm64" ? "arm64" : "";
+    if (!plat || !a)
+        return null;
+    const candidate = `${plat}-${a}`;
+    return ENCODER_SUPPORTED_PLATFORMS.includes(candidate)
+        ? candidate
+        : null;
+}
+function isManifest(m) {
+    const o = m;
+    return (!!o &&
+        typeof o === "object" &&
+        o.schema === "model-manifest-v1" &&
+        typeof o.opset === "number" &&
+        typeof o.batch === "number" &&
+        typeof o.maxTokens === "number" &&
+        typeof o.platform === "string" &&
+        !!o.onnx &&
+        !!o.tokenizer &&
+        typeof o.onnx.path === "string" &&
+        typeof o.onnx.sha256 === "string" &&
+        typeof o.tokenizer.path === "string" &&
+        typeof o.tokenizer.sha256 === "string");
+}
+/**
+ * Verify the asset manifest + digest + constraints BEFORE allocation.
+ *
+ *   - manifest parse/shape failure      -> ENC_MANIFEST_INVALID -> mode B
+ *   - unsupported platform              -> ENC_PLATFORM_UNSUPPORTED -> mode B
+ *   - opset != 17                       -> ENC_OPSET_INVALID -> mode B
+ *   - batch != 1                        -> ENC_BATCH_INVALID -> mode B
+ *   - maxTokens > 512                   -> ENC_TOKENS_EXCEEDED -> mode B
+ *   - on-disk digest != manifest digest -> ENC_DIGEST_MISMATCH (one-byte mutation)
+ *   - unreadable/truncated file         -> ENC_ASSET_UNREADABLE
+ *
+ * Returns ok only when EVERY constraint passes and both files hash to the
+ * declared digests (the "only batch1/max512 verified assets reach inference"
+ * invariant). The ok result surfaces the verified manifest's `maxTokens`
+ * (<= 512) so the runtime can enforce the per-manifest token capacity at
+ * inference (Q03), not just the global 512 ceiling.
+ */
+export function verifyEncoderAsset(assetDir, manifest, platform = detectPlatform()) {
+    if (typeof manifest !== "object" || manifest === null || !isManifest(manifest)) {
+        return { ok: false, code: ENC_FAIL.MANIFEST_INVALID };
+    }
+    if (!platform)
+        return { ok: false, code: ENC_FAIL.PLATFORM_UNSUPPORTED };
+    // The manifest's declared platform must match the runtime host (per-platform
+    // asset pinning): a bundle cross-shipped to the wrong arch is not qualified.
+    if (manifest.platform !== platform)
+        return { ok: false, code: ENC_FAIL.PLATFORM_UNSUPPORTED };
+    if (manifest.opset !== ENCODER_OPSET)
+        return { ok: false, code: ENC_FAIL.OPSET_INVALID };
+    if (manifest.batch !== ENCODER_BATCH)
+        return { ok: false, code: ENC_FAIL.BATCH_INVALID };
+    if (manifest.maxTokens > ENCODER_MAX_TOKENS)
+        return { ok: false, code: ENC_FAIL.TOKENS_EXCEEDED };
+    // Constrain asset paths to basenames (no separators / no '..') so a forged
+    // manifest cannot read digests from arbitrary paths off the asset dir.
+    if (!isBasename(manifest.onnx.path) || !isBasename(manifest.tokenizer.path)) {
+        return { ok: false, code: ENC_FAIL.MANIFEST_INVALID };
+    }
+    const onnxPath = join(assetDir, manifest.onnx.path);
+    const onnxDigest = digestFile(onnxPath);
+    if (onnxDigest === null)
+        return { ok: false, code: ENC_FAIL.ASSET_UNREADABLE };
+    if (onnxDigest !== manifest.onnx.sha256)
+        return { ok: false, code: ENC_FAIL.DIGEST_MISMATCH };
+    const tokPath = join(assetDir, manifest.tokenizer.path);
+    const tokDigest = digestFile(tokPath);
+    if (tokDigest === null)
+        return { ok: false, code: ENC_FAIL.ASSET_UNREADABLE };
+    if (tokDigest !== manifest.tokenizer.sha256)
+        return { ok: false, code: ENC_FAIL.DIGEST_MISMATCH };
+    let embeddedBytes = 0;
+    try {
+        embeddedBytes = statSync(onnxPath).size + statSync(tokPath).size;
+    }
+    catch {
+        return { ok: false, code: ENC_FAIL.ASSET_UNREADABLE };
+    }
+    return { ok: true, embeddedBytes, maxTokens: manifest.maxTokens, onnxDigest, tokenizerDigest: tokDigest };
+}
+/**
+ * Read + shape-check a committed ModelManifestV1 from an asset directory.
+ * Returns the parsed manifest or null when the file is absent/malformed.
+ */
+export function readEncoderManifest(assetDir) {
+    try {
+        const raw = JSON.parse(readFileSync(join(assetDir, "manifest.json"), "utf8"));
+        return isManifest(raw) ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,63 @@
+/**
+ * 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";
+/** A flag-gated no-op reporter (zero emissions, structural no-op). */
+export const NOOP_VC2B_REPORTER = {
+    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) {
+    const logger = new Logger(logPath === undefined ? {} : { path: logPath });
+    return (event, fields) => {
+        logger.info(event, fields);
+    };
+}
+/**
+ * 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, opts = {}) {
+    const sink = emit ?? defaultEmitFor(opts.logPath);
+    const fire = (event, fields) => {
+        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/dist/vector-cortex/encoder/emit.js

@@ -0,0 +1,42 @@
+/**
+ * vector-cortex/encoder/emit.ts — VC2A observability seam.
+ *
+ * Emits the two VC2A structured events, gated on `MEGACOMPACT_VC2A` (mode C
+ * parity: flag OFF => zero emissions). Every event is a JSON line with `ts` +
+ * `event` (ENGINEERING_PRACTICES §8); the emitters are never fatal on consumer
+ * failure (non-fatal observability, never breaks the agent loop).
+ *
+ *   vector_cortex_encoder_asset_verified   — a qualified manifest+digest load
+ *   vector_cortex_encoder_runtime_demoted  — a demotion to mode B or C
+ *
+ * No network, no side effects beyond the supplied emit callback
+ * (PREVENT-PI-004 / PREVENT-011).
+ */
+import { VC2A_ENABLED } from "../../config/vector-cortex.js";
+/** A flag-gated no-op reporter (zero emissions, default when none injected). */
+export const NOOP_ENCODER_REPORTER = {
+    assetVerified: () => { },
+    runtimeDemoted: () => { },
+};
+/**
+ * Flag-gated emit: no-op when VC2A is off or no emitter is supplied. The
+ * returned reporter is itself flag-gated (`VC2A_ENABLED`), so wiring it into a
+ * runtime seam yields zero emissions when `MEGACOMPACT_VC2A=0` (byte-identical
+ * to the predecessor).
+ */
+export function createEncoderReporter(emit) {
+    const fire = (event, fields) => {
+        if (!VC2A_ENABLED())
+            return;
+        try {
+            emit?.(event, { ...fields, ts: new Date().toISOString() });
+        }
+        catch {
+            /* non-fatal observability */
+        }
+    };
+    return {
+        assetVerified: (fields) => fire("vector_cortex_encoder_asset_verified", fields),
+        runtimeDemoted: (fields) => fire("vector_cortex_encoder_runtime_demoted", fields),
+    };
+}

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

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