pi-mega-compact 0.18.0 → 0.18.1

package/dist/config/vector-cortex.js

@@ -73,6 +73,15 @@ export const VC1C_ENABLED = () => sprintFlag("MEGACOMPACT_VC1C");
  * encoder runtime's A/B/C selection.
  */
 export const VC2A_ENABLED = () => 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 = () => sprintFlag("MEGACOMPACT_VC2B");
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/dist/config.js

@@ -0,0 +1,117 @@
+/**
+ * config.ts — shared default paths/constants for the mega-compact engine.
+ *
+ * Kept tiny and dependency-free so both the extension entry and unit tests can
+ * import it without pulling in pi runtime types.
+ */
+import { join } from "node:path";
+import { homedir } from "node:os";
+/** Default on-disk location for checkpoints + session state. */
+export const STATE_DIR_DEFAULT = join(homedir(), ".pi", "agent", "extensions", "pi-mega-compact");
+/** Pi custom message / entry type used as the dedup sentinel. */
+export const MARKER_TYPE = "mega-compact-marker";
+/**
+ * Derive context-window pressure (0–1) from a usage percentage. Used to scale
+ * compression strength + keepFrom depth (Fix E): low pct = room to spare,
+ * high pct = near the limit. Deterministic; clamps to [0,1].
+ */
+export function pressureFromPct(pct) {
+    if (pct == null || Number.isNaN(pct))
+        return 0;
+    return pct < 0 ? 0 : pct > 100 ? 1 : pct / 100;
+}
+/**
+ * Map pressure → how many recent messages to preserve verbatim. Under low
+ * pressure we keep `preserveRecent`; under high pressure we compact deeper,
+ * down to `preserveRecentMin`. Never splits a tool pair / anchor floor — the
+ * boundary guard (computeDropRange) enforces that downstream.
+ */
+export function preserveRecentForPressure(pressure, preserveRecent, preserveRecentMin) {
+    const p = pressure < 0 ? 0 : pressure > 1 ? 1 : pressure;
+    const v = Math.round(preserveRecent - (preserveRecent - preserveRecentMin) * p);
+    // Floor of 1: even with preserveRecentMin=0 at full pressure, never compact
+    // ALL messages — the boundary guard (computeDropRange) needs ≥1 to anchor on.
+    return Math.max(1, preserveRecentMin, Math.min(preserveRecent, v));
+}
+/** Clamp a pressure ratio into [0, 1]. */
+function clamp01(p) {
+    if (!Number.isFinite(p))
+        return 0;
+    return p < 0 ? 0 : p > 1 ? 1 : p;
+}
+/**
+ * Pressure as a 0–1 ratio from live token usage relative to the compaction
+ * threshold. Cheaper + more direct than deriving from a usage percentage when
+ * we already have both numbers (the context handler does). Re-exports
+ * `pressureFromPct` covers the percentage-only path. (S24.)
+ */
+export function pressureRatio(currentTokens, thresholdTokens) {
+    if (!Number.isFinite(currentTokens) || currentTokens <= 0)
+        return 0;
+    const t = Number.isFinite(thresholdTokens) && thresholdTokens > 0 ? thresholdTokens : 0;
+    return clamp01(t > 0 ? currentTokens / t : 0);
+}
+/** Map a 0–1 pressure ratio to a discrete band. (S24.) */
+export function pressureBand(pressure) {
+    const p = clamp01(pressure);
+    if (p >= 1.0)
+        return "mega";
+    if (p >= 0.9)
+        return "ultra";
+    if (p >= 0.75)
+        return "high";
+    if (p >= 0.5)
+        return "medium";
+    return "low";
+}
+/**
+ * Memory auto-review cadence (in turns) for a given pressure band. As pressure
+ * climbs, the conversation is reviewed more often so durable memories keep pace
+ * with the faster context churn. Returns a divisor used as
+ * `turn % cadence === 0`. Always >= 1. (S24 — memory cadence tie-in.)
+ */
+export function memoryReviewCadence(band, baseInterval) {
+    const base = baseInterval >= 1 ? baseInterval : 1;
+    switch (band) {
+        case "mega": return Math.max(1, Math.round(base / 5));
+        case "ultra": return Math.max(1, Math.round(base / 3));
+        case "high": return Math.max(1, Math.round(base / 2));
+        case "medium": return Math.max(1, Math.round((base * 2) / 3));
+        case "low":
+        default: return base;
+    }
+}
+// ---------------------------------------------------------------------------
+// S57 RAG Suite feature flags — all default ON with graceful fallback; opt OUT
+// via MEGACOMPACT_<NAME>_DISABLED=true. Every feature degrades to existing
+// behavior on error (non-fatal, best-effort).
+// ---------------------------------------------------------------------------
+function ragFlag(name) {
+    const v = process.env[name];
+    if (v === undefined)
+        return false;
+    return v === "true" || v === "1";
+}
+function ragEnabled(name) {
+    return !ragFlag(name + "_DISABLED");
+}
+/** B1: Query reformulation (keyword expansion via embedding neighbors). */
+export const RAG_QUERY_REFORMULATION = () => ragEnabled("MEGACOMPACT_QUERY_REFORMULATION");
+/** B2: Tiered recall router (L0 cache → L1 FTS5 → L2 HNSW). */
+export const RAG_TIERED_ROUTER = () => ragEnabled("MEGACOMPACT_TIERED_ROUTER");
+/** B3: Recall quality metrics (precision/recall scoring + logging). */
+export const RAG_RECALL_METRICS = () => ragEnabled("MEGACOMPACT_RECALL_METRICS");
+/** B4: Memory graph traversal (dashboard-oriented). */
+export const RAG_MEMORY_GRAPH = () => ragEnabled("MEGACOMPACT_MEMORY_GRAPH");
+/** B5: HyDE — generate a hypothetical answer doc via LLM. Auto-ON when an
+ * HttpEmbedder is active (the LLM is configured for indexing); opt OUT with
+ * MEGACOMPACT_HYDE_DISABLED=true. TrigramEmbedder path is unaffected. */
+export const RAG_HYDE_ENABLED = () => ragEnabled("MEGACOMPACT_HYDE");
+/** Spec 1: vbrainstorm visual design migration for the dashboard. */
+export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
+// ---------------------------------------------------------------------------
+// Vector-cortex flags + breaker constants (VC0A+). Positive sprint flags,
+// default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
+// so root consumers share one source of truth.
+// ---------------------------------------------------------------------------
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";

package/dist/extensions/dashboard-server/routes-rag-settings-helpers.js

@@ -127,6 +127,8 @@ export const SETTINGS = [
             str("MEGACOMPACT_RAPTOR_MODEL", "RAPTOR Summary Model", "Ollama model for cluster summarization (empty = extractive)", ""),
             str("MEGACOMPACT_RAPTOR_URL", "RAPTOR Ollama URL", "Ollama endpoint for RAPTOR summarization", "http://127.0.0.1:11434"),
             num("MEGACOMPACT_EMBED_CACHE", "Embed Cache Size", "Embedding cache entries (0 = disabled)", 256, 0, 10000),
+            num("MEGACOMPACT_EMBEDDING_BATCH_TOKENS", "Embedding Batch Tokens", "Oversized-prompt chunking limit (tokens) for the BYO localhost embedder; text above this is chunked + mean-pooled", 2048, 64, 8192),
+            num("MEGACOMPACT_EMBEDDING_CHARS_PER_TOKEN", "Embedding Chars per Token", "Estimated characters per token used for embedder chunking size", 4, 1, 32),
         ],
     },
     {
@@ -139,6 +141,7 @@ export const SETTINGS = [
             boolDirect("MEGACOMPACT_VC0C", "VC0C Live Safety Envelope", "TriadResult/Breaker live circuit breaker (60s window, 20 attempts, 30s cooldown, 3 probes, 5min healthy residence) + durable spool before provider invocation; manual reset clears cooldown but never evidence. OFF = mode C, unchanged transcript, byte-identical.", true),
             boolDirect("MEGACOMPACT_VC1C", "VC1C Cross-Language Conformance v2", "FixtureManifestV2 canonical manifest validator + DowngradeReport deterministic downgrade export + MinHashV2 exact big-integer signatures and the M4 copy/validate/switch minhash-v2 migration (seed table frozen, cross-language byte-exact). OFF = mode C, v1 sync dedup scan unchanged, byte-identical.", true),
             boolDirect("MEGACOMPACT_VC2A", "VC2A Offline Model Runtime", "ModelManifestV1 digest-before-load ONNX runtime (opset17/batch1/max512) + asset-free trigram demotion. Asset path assets/vector-cortex/encoder-v1 is immutable/digest-pinned. OFF = mode C, byte-identical to predecessor.", true),
+            boolDirect("MEGACOMPACT_VC2B", "VC2B Multi-Head Encoder", "VectorSetV1 five L2-normalized heads (384/128/128/64/32) with head-calibration draft + asset-free trigram B (512d) and lexical C fallbacks, plus the per-head emit seam. OFF = mode C, no per-head vectors emitted, byte-identical predecessor.", true),
         ],
     },
     {

package/dist/log.js

@@ -0,0 +1,47 @@
+/**
+ * log.ts — tiny append-only structured logger.
+ *
+ * Writes one JSON object per line to a log file (default:
+ * ~/.pi/agent/extensions/mega-compact.log). Best-effort: logging never throws
+ * into the extension. Pi-agnostic and dependency-free so it can be unit-tested.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { STATE_DIR_DEFAULT } from "./config.js";
+/** Default log path lives alongside the state dir. */
+export function defaultLogPath() {
+    return join(STATE_DIR_DEFAULT, "mega-compact.log");
+}
+export class Logger {
+    path;
+    enabled;
+    /** Monotonic clock injected by the caller so the module stays deterministic. */
+    now;
+    constructor(opts = {}) {
+        this.path = opts.path ?? defaultLogPath();
+        this.enabled = opts.enabled ?? true;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    /** Append one structured line. Swallows all I/O errors. */
+    log(level, event, fields = {}) {
+        if (!this.enabled)
+            return;
+        const entry = { ts: this.now(), level, event, ...fields };
+        try {
+            mkdirSync(dirname(this.path), { recursive: true });
+            appendFileSync(this.path, `${JSON.stringify(entry)}\n`);
+        }
+        catch {
+            /* best-effort: never break the extension on a log failure */
+        }
+    }
+    info(event, fields) {
+        this.log("info", event, fields);
+    }
+    warn(event, fields) {
+        this.log("warn", event, fields);
+    }
+    error(event, fields) {
+        this.log("error", event, fields);
+    }
+}

package/dist/src/config/vector-cortex.js

@@ -73,6 +73,15 @@ export const VC1C_ENABLED = () => sprintFlag("MEGACOMPACT_VC1C");
  * encoder runtime's A/B/C selection.
  */
 export const VC2A_ENABLED = () => 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 = () => sprintFlag("MEGACOMPACT_VC2B");
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/dist/src/config.js

@@ -114,4 +114,4 @@ export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
 // default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
 // so root consumers share one source of truth.
 // ---------------------------------------------------------------------------
-export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";

package/dist/src/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/src/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 };

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

@@ -0,0 +1,104 @@
+/**
+ * vector-cortex/encoder/lexical.ts — VC2B mode C: token/phrase lexical encoder.
+ *
+ * Lexical C is a token/phrase lexical feature generator used when both mode A
+ * (learned asset) and mode B (trigram) are unavailable or fail. It is continuity,
+ * NOT semantic completeness: C operates on exact current tokens/phrases only and
+ * MUST state that it has lost old semantic context (task 4 + TRIAD_RESILIENCE.
+ * "C is continuity, not semantic completeness: it may omit old context and must
+ * report that limitation").
+ *
+ * C never imports the learned asset or learned calibration (task 4): it is a
+ * pure token/phrase lexical projection (token counts + phrase hashes) computed
+ * from the exact input. It is independently implemented from B (which hashes
+ * byte-level trigrams) — C works at the token/phrase level, B at the byte-ngram
+ * level, so the two share no algorithm.
+ *
+ * Authority outage freezes derived high-water: C never advances any derived
+ * frontier; it is purely a local reconstruction from the exact present tokens.
+ *
+ * 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 lexical C. */
+export const ENCODER_LEXICAL_WIDTH = 256;
+/** The documented limitation lexical C reports (continuity, not semantics). */
+export const ENCODER_LEXICAL_LIMITATION = "lexical C: token/phrase-level continuity only; old semantic context is omitted";
+export function tokenizeLexical(text) {
+    // Split into lowercase token/phrase units on non-alphanumeric boundaries.
+    return text.toLowerCase().split(/[^a-z0-9_]+/).filter((t) => t.length > 0);
+}
+/**
+ * Normalize a single token/phrase unit the same way `tokenizeLexical` does for
+ * the string form: lowercase and strip leading/trailing non-alphanumeric runs.
+ * Applied to array-form tokens so both accepted input forms of `embedLexical`
+ * hash identical conceptual content to identical buckets, regardless of how the
+ * caller chose to pass it (code-review Q03).
+ */
+function normalizeToken(tok) {
+    return tok.toLowerCase().split(/[^a-z0-9_]+/).join("");
+}
+/**
+ * Resolve either accepted input form to a normalized token sequence: the string
+ * form routes through `tokenizeLexical` (split on non-alphanumeric boundaries,
+ * fragmented tokens discarded); the array form applies the same per-token
+ * lowercase/strip normalization and drops tokens that normalize to empty. Both
+ * paths therefore agree on hash buckets for the same conceptual content.
+ */
+function resolveTokens(tokensOrText) {
+    if (typeof tokensOrText === "string")
+        return tokenizeLexical(tokensOrText);
+    const out = [];
+    for (const raw of tokensOrText) {
+        const norm = normalizeToken(raw);
+        if (norm.length > 0)
+            out.push(norm);
+    }
+    return out;
+}
+/**
+ * Encode a token/phrase sequence into a 256-dim L2-normalized lexical vector
+ * (all-zero on empty input). Features: exact token count + token id-hash sums +
+ * phrase-adjacency hashes. Deterministic (repeat drift == 0). Pure local compute.
+ */
+export function embedLexical(tokensOrText) {
+    const width = ENCODER_LEXICAL_WIDTH;
+    const out = new Float32Array(width);
+    const tokens = resolveTokens(tokensOrText);
+    for (let i = 0; i < tokens.length; i++) {
+        const tok = tokens[i];
+        const h = createHash("sha256").update(`t:${tok}`).digest();
+        const bucket = h.readUInt32BE(0) % width;
+        const weight = (h.readUInt32BE(4) / 4294967295) * 2 - 1;
+        out[bucket] += weight;
+        // Phrase adjacency: bigram hash blended in so semantic-free ordering matters.
+        if (i > 0) {
+            const pair = createHash("sha256").update(`p:${tokens[i - 1]}:${tok}`).digest();
+            const pb = pair.readUInt32BE(0) % width;
+            const pw = (pair.readUInt32BE(4) / 4294967295) * 2 - 1;
+            out[pb] += pw;
+        }
+    }
+    return l2Normalize(out);
+}
+/** The documented limitation string, surfaced when lexical C is selected. */
+export function selectLexicalC(options = {}) {
+    const reporter = options.reporter ?? createEncoderHeadsReporter();
+    const selection = {
+        ok: true,
+        mode: "C",
+        dim: ENCODER_LEXICAL_WIDTH,
+        width: ENCODER_LEXICAL_WIDTH,
+        limitation: ENCODER_LEXICAL_LIMITATION,
+    };
+    reporter.fallbackSelected({
+        mode: selection.mode,
+        dim: selection.dim,
+        width: selection.width,
+        limitation: selection.limitation,
+    });
+    return selection;
+}
+export { l2Normalize };

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

@@ -0,0 +1,115 @@
+/**
+ * vector-cortex/encoder/router.ts — VC2B encode-or-fallback router (S2).
+ *
+ * The single production seam that catches a real VC2A `load()` failure and
+ * hands off to the independently initialized VC2B fallbacks:
+ *
+ *   - mode A: the learned multi-head projection — an EncoderRuntime that
+ *     verifies+loads a local qualified ONNX (VC2A) plus `encodeVectorSet`
+ *     producing VectorSetV1, emitting `vector_cortex_encoder_heads_emitted`;
+ *   - when that `load()` fails for ANY reason (removed model ->
+ *     ENC_ASSET_UNREADABLE, digest mismatch -> ENC_DIGEST_MISMATCH, missing
+ *     manifest -> ENC_MANIFEST_INVALID, unsupported platform, RSS over budget,
+ *     ...) the router catches the real failure and selects the independently
+ *     initialized asset-free trigram B (`selectTrigramBFallback`) — or lexical C
+ *     when the runtime reports B-unavailable / the caller forces mode C. The
+ *     `vector_cortex_encoder_fallback_selected` event fires from the REAL
+ *     producer seam, not test wiring (task 5 + code-review S1).
+ *
+ * Best-effort and non-fatal: every branch returns an explicit verdict and never
+ * throws across the boundary into the agent loop. Flag-OFF parity: with
+ * `MEGACOMPACT_VC2B=0` the VC2B reporter is a no-op (zero emissions), and the
+ * mode-A path is governed by the VC2A runtime itself — the router only adds the
+ * fallback handoff and changes no producer bytes.
+ *
+ * Pi-agnostic, zero network (PREVENT-PI-004), no `any` (PREVENT-011).
+ */
+import { createEncoderRuntime } from "./runtime.js";
+import { encodeVectorSet } from "./heads.js";
+import { embedTrigram512, selectTrigramBFallback } from "./trigram.js";
+import { embedLexical, selectLexicalC } from "./lexical.js";
+import { createEncoderHeadsReporter } from "./emit-vc2b.js";
+import { ENC_FAIL, } from "./types.js";
+/** Deterministic text derived from an int token sequence so the asset-free
+ *  fallback producers operate on the same authority the learned path encoded. */
+function textFromTokens(tokens) {
+    return tokens.join("-");
+}
+/**
+ * Try to produce an encoding for an input token sequence. Mode A: verify+load
+ * the local learned asset via the EncoderRuntime; on a real `load()` failure
+ * (removed model, digest mismatch, missing manifest, ...) the router catches it
+ * and selects the independently initialized trigram B or lexical C, emitting
+ * `vector_cortex_encoder_fallback_selected` (and `heads_emitted` when A wins).
+ */
+export function encodeOrFallback(input, assetDir, options = {}) {
+    const reporter = options.reporter ?? createEncoderHeadsReporter();
+    const tokens = Array.isArray(input?.tokens) ? input.tokens : [];
+    const runtime = options.runtime ?? createEncoderRuntime();
+    // A caller that explicitly forces a fallback mode wins even over the empty-
+    // input degenerate case: the forced-mode contract must hold for ANY input, so
+    // handle forceFallback before the empty-input selection below (Q02). A forced
+    // B/C is NOT a rollback and NOT a demotion — it is an intentional selection
+    // for capacity/testing — so the verdict carries `code: null`, never
+    // ENC_FAIL.ROLLBACK, so a consumer that reads `verdict.code` as "what
+    // triggered the fallback" won't misread a deliberately forced mode as a
+    // rollback and take rollback-specific action (code-review Q04).
+    if (options.forceFallback !== undefined) {
+        if (options.forceFallback === "C") {
+            const sel = selectLexicalC({ reporter });
+            const vector = embedLexical(textFromTokens(tokens));
+            return { ok: true, mode: "C", vector, width: sel.width, limitation: sel.limitation, code: null };
+        }
+        const sel = selectTrigramBFallback({ reporter });
+        const vector = embedTrigram512(textFromTokens(tokens));
+        return { ok: true, mode: "B", vector, width: sel.width, limitation: null, code: null };
+    }
+    // Empty input yields the asset-free fallback (finite, deterministic zero
+    // vector, ENC-ZERO-002). This is legitimate degenerate behavior, NOT a shape
+    // failure, so the verdict carries no failure code (code === null) — a consumer
+    // that interprets `code` as "what went wrong" must not misread a valid all-zero
+    // B vector as a shape rejection (Q05). Only reached when no mode is forced, so
+    // a forced B/C is never subverted by empty tokens.
+    if (tokens.length === 0) {
+        const sel = selectTrigramBFallback({ reporter });
+        const vector = embedTrigram512("");
+        return { ok: true, mode: "B", vector, width: sel.width, limitation: null, code: null };
+    }
+    // Mode A attempt — reached only when no mode is forced (the forceFallback
+    // guard at the top already returned), so `options.forceFallback` is undefined here.
+    const loaded = runtime.load(assetDir);
+    if (!loaded.ok) {
+        return fallbackFromLoad(loaded, reporter, tokens);
+    }
+    // Q01/Q03: a qualified mode-A load is not enough — the verified per-manifest
+    // token capacity (maxTokens, <= global 512) must also be enforced before we
+    // produce a VectorSetV1. run inference over the input; an over-cap sequence
+    // (e.g. 100 tokens against a verified maxTokens=64 manifest) or an
+    // over-budget inference is rejected here and routed to the B/C fallback with
+    // the real failure code, rather than silently emitting an ok:true mode-A
+    // set whose inputTokens breach the model's declared capacity.
+    const inferred = runtime.infer({ tokens });
+    if (!inferred.ok) {
+        return fallbackFromLoad({ ok: false, mode: "B", code: inferred.code }, reporter, tokens);
+    }
+    const vectorSet = encodeVectorSet(tokens, { reporter, seed: options.seed });
+    return { ok: true, mode: "A", vectorSet, code: null };
+}
+/**
+ * Catch a (real or forced) A load failure (ok === false only) and select the
+ * B/C fallback that emits `vector_cortex_encoder_fallback_selected` from the
+ * production seam. The parameter is narrowed to the failed-load variant because
+ * the router hands off here only on a non-A/failed load — a qualified mode-A
+ * success never reaches this function (Q04).
+ */
+function fallbackFromLoad(loaded, reporter, tokens) {
+    if (loaded.mode === "C") {
+        const sel = selectLexicalC({ reporter });
+        const vector = embedLexical(textFromTokens(tokens));
+        return { ok: true, mode: "C", vector, width: sel.width, limitation: sel.limitation, code: loaded.code };
+    }
+    const sel = selectTrigramBFallback({ reporter });
+    const vector = embedTrigram512(textFromTokens(tokens));
+    return { ok: true, mode: "B", vector, width: sel.width, limitation: null, code: loaded.code };
+}
+export { ENC_FAIL };