pi-mega-compact 0.18.0 → 0.19.0

package/assets/vector-cortex/encoder-v1/manifest.json

@@ -0,0 +1 @@
+{"batch":1,"heads":{"cacheStability":64,"contradiction":128,"dependency":128,"payloadRouting":32,"semantic":384},"hiddenWidth":384,"maxTokens":512,"modelVersion":"encoder-v1-placeholder","onnx":{"bytes":42,"path":"model.onnx","sha256":"01cbed8b0b301609542ff8c392c3e7d927b0d848ac53a768dfffd33bfe6005ff"},"opset":17,"platform":"linux-x64","schema":"model-manifest-v1","semanticWidth":384,"tokenizer":{"bytes":8518,"path":"tokenizer.json","sha256":"ada18e5c4dfcb5c369c05f4ffc10bc40298ce707e78f16135c6d33019f6db8cd"},"totalBytes":8560,"trainingManifestDigest":"e9b2550dbb79141af84440dda65ca21d3509904b2c09a89316145137a5b5e3de"}

package/assets/vector-cortex/encoder-v1/model-card.json

@@ -0,0 +1 @@
+{"accepted":"local offline deterministic projection over verified asset (V1); trained weights + evaluation land in VC2B/VC2C","comparison":[{"candidate":"MiniLM-class transformer","latencyMs":8,"license":"permissive","offlineNode":"no (native addon)","quality":"high","sizeMB":120},{"candidate":"small BERT","latencyMs":10,"license":"permissive","offlineNode":"partial","quality":"high","sizeMB":110},{"candidate":"bag/subword baseline","latencyMs":1,"license":"permissive","offlineNode":"yes","quality":"medium","sizeMB":4}],"note":"placeholder asset — replaced by the VC2C export pipeline","reprintPermission":true,"schema":"model-card-v1"}

package/assets/vector-cortex/encoder-v1/tokenizer.json

@@ -0,0 +1 @@
+{"maxTokens":512,"schema":"wordpiece-tokenizer-v1","specialTokens":{"cls":2,"mask":4,"pad":0,"sep":3,"unk":1},"truncation":{"keepFirst":128,"keepLast":384},"vocab":[["[PAD]",0],["[UNK]",1],["[CLS]",2],["[SEP]",3],["[MASK]",4],["##tok0",5],["##tok1",6],["##tok2",7],["##tok3",8],["##tok4",9],["##tok5",10],["##tok6",11],["##tok7",12],["##tok8",13],["##tok9",14],["##tok10",15],["##tok11",16],["##tok12",17],["##tok13",18],["##tok14",19],["##tok15",20],["##tok16",21],["##tok17",22],["##tok18",23],["##tok19",24],["##tok20",25],["##tok21",26],["##tok22",27],["##tok23",28],["##tok24",29],["##tok25",30],["##tok26",31],["##tok27",32],["##tok28",33],["##tok29",34],["##tok30",35],["##tok31",36],["##tok32",37],["##tok33",38],["##tok34",39],["##tok35",40],["##tok36",41],["##tok37",42],["##tok38",43],["##tok39",44],["##tok40",45],["##tok41",46],["##tok42",47],["##tok43",48],["##tok44",49],["##tok45",50],["##tok46",51],["##tok47",52],["##tok48",53],["##tok49",54],["##tok50",55],["##tok51",56],["##tok52",57],["##tok53",58],["##tok54",59],["##tok55",60],["##tok56",61],["##tok57",62],["##tok58",63],["##tok59",64],["##tok60",65],["##tok61",66],["##tok62",67],["##tok63",68],["##tok64",69],["##tok65",70],["##tok66",71],["##tok67",72],["##tok68",73],["##tok69",74],["##tok70",75],["##tok71",76],["##tok72",77],["##tok73",78],["##tok74",79],["##tok75",80],["##tok76",81],["##tok77",82],["##tok78",83],["##tok79",84],["##tok80",85],["##tok81",86],["##tok82",87],["##tok83",88],["##tok84",89],["##tok85",90],["##tok86",91],["##tok87",92],["##tok88",93],["##tok89",94],["##tok90",95],["##tok91",96],["##tok92",97],["##tok93",98],["##tok94",99],["##tok95",100],["##tok96",101],["##tok97",102],["##tok98",103],["##tok99",104],["##tok100",105],["##tok101",106],["##tok102",107],["##tok103",108],["##tok104",109],["##tok105",110],["##tok106",111],["##tok107",112],["##tok108",113],["##tok109",114],["##tok110",115],["##tok111",116],["##tok112",117],["##tok113",118],["##tok114",119],["##tok115",120],["##tok116",121],["##tok117",122],["##tok118",123],["##tok119",124],["##tok120",125],["##tok121",126],["##tok122",127],["##tok123",128],["##tok124",129],["##tok125",130],["##tok126",131],["##tok127",132],["##tok128",133],["##tok129",134],["##tok130",135],["##tok131",136],["##tok132",137],["##tok133",138],["##tok134",139],["##tok135",140],["##tok136",141],["##tok137",142],["##tok138",143],["##tok139",144],["##tok140",145],["##tok141",146],["##tok142",147],["##tok143",148],["##tok144",149],["##tok145",150],["##tok146",151],["##tok147",152],["##tok148",153],["##tok149",154],["##tok150",155],["##tok151",156],["##tok152",157],["##tok153",158],["##tok154",159],["##tok155",160],["##tok156",161],["##tok157",162],["##tok158",163],["##tok159",164],["##tok160",165],["##tok161",166],["##tok162",167],["##tok163",168],["##tok164",169],["##tok165",170],["##tok166",171],["##tok167",172],["##tok168",173],["##tok169",174],["##tok170",175],["##tok171",176],["##tok172",177],["##tok173",178],["##tok174",179],["##tok175",180],["##tok176",181],["##tok177",182],["##tok178",183],["##tok179",184],["##tok180",185],["##tok181",186],["##tok182",187],["##tok183",188],["##tok184",189],["##tok185",190],["##tok186",191],["##tok187",192],["##tok188",193],["##tok189",194],["##tok190",195],["##tok191",196],["##tok192",197],["##tok193",198],["##tok194",199],["##tok195",200],["##tok196",201],["##tok197",202],["##tok198",203],["##tok199",204],["##tok200",205],["##tok201",206],["##tok202",207],["##tok203",208],["##tok204",209],["##tok205",210],["##tok206",211],["##tok207",212],["##tok208",213],["##tok209",214],["##tok210",215],["##tok211",216],["##tok212",217],["##tok213",218],["##tok214",219],["##tok215",220],["##tok216",221],["##tok217",222],["##tok218",223],["##tok219",224],["##tok220",225],["##tok221",226],["##tok222",227],["##tok223",228],["##tok224",229],["##tok225",230],["##tok226",231],["##tok227",232],["##tok228",233],["##tok229",234],["##tok230",235],["##tok231",236],["##tok232",237],["##tok233",238],["##tok234",239],["##tok235",240],["##tok236",241],["##tok237",242],["##tok238",243],["##tok239",244],["##tok240",245],["##tok241",246],["##tok242",247],["##tok243",248],["##tok244",249],["##tok245",250],["##tok246",251],["##tok247",252],["##tok248",253],["##tok249",254],["##tok250",255],["##tok251",256],["##tok252",257],["##tok253",258],["##tok254",259],["##tok255",260],["##tok256",261],["##tok257",262],["##tok258",263],["##tok259",264],["##tok260",265],["##tok261",266],["##tok262",267],["##tok263",268],["##tok264",269],["##tok265",270],["##tok266",271],["##tok267",272],["##tok268",273],["##tok269",274],["##tok270",275],["##tok271",276],["##tok272",277],["##tok273",278],["##tok274",279],["##tok275",280],["##tok276",281],["##tok277",282],["##tok278",283],["##tok279",284],["##tok280",285],["##tok281",286],["##tok282",287],["##tok283",288],["##tok284",289],["##tok285",290],["##tok286",291],["##tok287",292],["##tok288",293],["##tok289",294],["##tok290",295],["##tok291",296],["##tok292",297],["##tok293",298],["##tok294",299],["##tok295",300],["##tok296",301],["##tok297",302],["##tok298",303],["##tok299",304],["##tok300",305],["##tok301",306],["##tok302",307],["##tok303",308],["##tok304",309],["##tok305",310],["##tok306",311],["##tok307",312],["##tok308",313],["##tok309",314],["##tok310",315],["##tok311",316],["##tok312",317],["##tok313",318],["##tok314",319],["##tok315",320],["##tok316",321],["##tok317",322],["##tok318",323],["##tok319",324],["##tok320",325],["##tok321",326],["##tok322",327],["##tok323",328],["##tok324",329],["##tok325",330],["##tok326",331],["##tok327",332],["##tok328",333],["##tok329",334],["##tok330",335],["##tok331",336],["##tok332",337],["##tok333",338],["##tok334",339],["##tok335",340],["##tok336",341],["##tok337",342],["##tok338",343],["##tok339",344],["##tok340",345],["##tok341",346],["##tok342",347],["##tok343",348],["##tok344",349],["##tok345",350],["##tok346",351],["##tok347",352],["##tok348",353],["##tok349",354],["##tok350",355],["##tok351",356],["##tok352",357],["##tok353",358],["##tok354",359],["##tok355",360],["##tok356",361],["##tok357",362],["##tok358",363],["##tok359",364],["##tok360",365],["##tok361",366],["##tok362",367],["##tok363",368],["##tok364",369],["##tok365",370],["##tok366",371],["##tok367",372],["##tok368",373],["##tok369",374],["##tok370",375],["##tok371",376],["##tok372",377],["##tok373",378],["##tok374",379],["##tok375",380],["##tok376",381],["##tok377",382],["##tok378",383],["##tok379",384],["##tok380",385],["##tok381",386],["##tok382",387],["##tok383",388],["##tok384",389],["##tok385",390],["##tok386",391],["##tok387",392],["##tok388",393],["##tok389",394],["##tok390",395],["##tok391",396],["##tok392",397],["##tok393",398],["##tok394",399],["##tok395",400],["##tok396",401],["##tok397",402],["##tok398",403],["##tok399",404],["##tok400",405],["##tok401",406],["##tok402",407],["##tok403",408],["##tok404",409],["##tok405",410],["##tok406",411],["##tok407",412],["##tok408",413],["##tok409",414],["##tok410",415],["##tok411",416],["##tok412",417],["##tok413",418],["##tok414",419],["##tok415",420],["##tok416",421],["##tok417",422],["##tok418",423],["##tok419",424],["##tok420",425],["##tok421",426],["##tok422",427],["##tok423",428],["##tok424",429],["##tok425",430],["##tok426",431],["##tok427",432],["##tok428",433],["##tok429",434],["##tok430",435],["##tok431",436],["##tok432",437],["##tok433",438],["##tok434",439],["##tok435",440],["##tok436",441],["##tok437",442],["##tok438",443],["##tok439",444],["##tok440",445],["##tok441",446],["##tok442",447],["##tok443",448],["##tok444",449],["##tok445",450],["##tok446",451],["##tok447",452],["##tok448",453],["##tok449",454],["##tok450",455],["##tok451",456],["##tok452",457],["##tok453",458],["##tok454",459],["##tok455",460],["##tok456",461],["##tok457",462],["##tok458",463],["##tok459",464],["##tok460",465],["##tok461",466],["##tok462",467],["##tok463",468],["##tok464",469],["##tok465",470],["##tok466",471],["##tok467",472],["##tok468",473],["##tok469",474],["##tok470",475],["##tok471",476],["##tok472",477],["##tok473",478],["##tok474",479],["##tok475",480],["##tok476",481],["##tok477",482],["##tok478",483],["##tok479",484],["##tok480",485],["##tok481",486],["##tok482",487],["##tok483",488],["##tok484",489],["##tok485",490],["##tok486",491],["##tok487",492],["##tok488",493],["##tok489",494],["##tok490",495],["##tok491",496],["##tok492",497],["##tok493",498],["##tok494",499],["##tok495",500],["##tok496",501],["##tok497",502],["##tok498",503],["##tok499",504]]}

package/dist/config/vector-cortex.js

@@ -73,6 +73,24 @@ 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");
+/**
+ * VC2C — encoder qualification + calibration (QualifiedEncoderV1 / CalibrationV1).
+ * Default ON. `MEGACOMPACT_VC2C=0` disables and is byte-identical to the
+ * predecessor (mode C: no qualification manifest is read or selected, the
+ * calibrate/select/fallback seams are idle, zero `vector_cortex_encoder_qualification_*`
+ * emissions; the trigram/lexical paths are unchanged). The real consumers are
+ * the encoder-qualification emit seam and the calibrate/select seams.
+ */
+export const VC2C_ENABLED = () => sprintFlag("MEGACOMPACT_VC2C");
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/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, VC2C_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,8 @@ 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),
+            boolDirect("MEGACOMPACT_VC2C", "VC2C Encoder Qualification + Calibration", "QualifiedEncoderV1/CalibrationV1: calibration fit on the calibration split only (held-out labels prohibited) + atomic selection across MODEL_ASSET and per-head EVALUATION thresholds (any field failure demotes all of A). OFF = mode C, no qualification/calibration selection, byte-identical predecessor.", true),
         ],
     },
     {

package/dist/extensions/dashboard-server/routes-vector-cortex.js

@@ -14,11 +14,16 @@
  * Guardrails: PREVENT-PI-004 (local filesystem read only), PREVENT-011 (no
  * `any`), reader-only aggregate (never payloads/prompts/ledger — EVAL-REDACT-002).
  */
-import { VC0A_ENABLED, VC0C_ENABLED, VC1B_ENABLED } from "../../src/config.js";
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { VC0A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC2C_ENABLED } from "../../src/config.js";
 import { readEvalRows } from "../../src/vector-cortex/eval/persist.js";
 import { summarizeEvalRows } from "../../src/vector-cortex/eval/reader.js";
 import { createVectorCortexSafety } from "../mega-runtime/vector-cortex-safety.js";
 import { createLedgerStore } from "../../src/vector-cortex/ledger/store.js";
+import { readEncoderManifest, verifyEncoderAsset, detectPlatform } from "../../src/vector-cortex/encoder/asset.js";
 /** Admin capability: an actor-supplied subsystem selector for breaker reset. */
 function readJsonBody(req, cb) {
     let body = "";
@@ -50,6 +55,84 @@ function sendJson(res, status, body) {
     res.writeHead(status, { "Content-Type": "application/json" });
     res.end(JSON.stringify(body));
 }
+/** Resolve the committed encoder-v1 asset dir by walking up to the repo root. */
+function encoderAssetDir() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    const rel = join("assets", "vector-cortex", "encoder-v1");
+    for (let i = 0; i < 8; i++) {
+        const candidate = join(dir, rel);
+        try {
+            // guardrails-allow PREVENT-PI-004: local asset filesystem read (loopback)
+            readFileSync(join(candidate, "manifest.json"));
+            return candidate;
+        }
+        catch {
+            /* keep walking */
+        }
+        const next = dirname(dir);
+        if (next === dir)
+            break;
+        dir = next;
+    }
+    return null;
+}
+let healthCache = null;
+/** Stable cache key: manifest bytes + (size,mtime) of the asset files + platform. */
+function healthFactCacheKey(dir, manifestPath) {
+    const platform = detectPlatform();
+    if (!platform)
+        return null;
+    const parts = [platform];
+    try {
+        for (const p of [manifestPath, join(dir, "model.onnx"), join(dir, "tokenizer.json")]) {
+            const s = statSync(p);
+            parts.push(`${s.size}:${s.mtimeMs}`);
+        }
+        // guardrails-allow PREVENT-PI-004: local manifest filesystem read (loopback)
+        parts.push(createHash("sha256").update(readFileSync(manifestPath)).digest("hex"));
+    }
+    catch {
+        return null;
+    }
+    return parts.join("|");
+}
+function computeEncoderHealthFacts(dir) {
+    const manifest = readEncoderManifest(dir);
+    if (manifest === null)
+        return { assetDigest: null, mode: "C" };
+    const manifestPath = join(dir, "manifest.json");
+    const key = healthFactCacheKey(dir, manifestPath);
+    if (key === null)
+        return null;
+    if (healthCache !== null && healthCache.key === key)
+        return healthCache.facts;
+    let digest;
+    try {
+        // guardrails-allow PREVENT-PI-004: local manifest filesystem read (loopback)
+        digest = createHash("sha256").update(readFileSync(manifestPath)).digest("hex");
+    }
+    catch {
+        return { assetDigest: null, mode: "B" };
+    }
+    const verify = verifyEncoderAsset(dir, manifest, detectPlatform());
+    const facts = { assetDigest: digest, mode: verify.ok ? "A" : "B" };
+    healthCache = { key, facts };
+    return facts;
+}
+function encoderHealthFacts() {
+    if (!VC2C_ENABLED()) {
+        // Rollback: MEGACOMPACT_VC2C=0 selects C — report the inactive (flag-gated)
+        // mode with no asset digest rather than an on-disk-computed A/B.
+        return { assetDigest: null, mode: "C" };
+    }
+    const dir = encoderAssetDir();
+    if (dir === null)
+        return { assetDigest: null, mode: "C" };
+    const facts = computeEncoderHealthFacts(dir);
+    if (facts === null)
+        return { assetDigest: null, mode: "C" };
+    return facts;
+}
 /** Reader-only aggregate GET /api/vector-cortex/evaluation. */
 export function handleVectorCortexEvaluation(req, res, ctx) {
     const url = req.url ?? "";
@@ -107,6 +190,7 @@ export function handleVectorCortexHealth(req, res, ctx) {
     const enabled = VC0C_ENABLED();
     const safety = enabled ? createVectorCortexSafety({ stateDir: ctx.stateDir }) : null;
     const card = safety ? safety.health() : null;
+    const enc = encoderHealthFacts();
     const fallback = {
         enabled: false,
         mode: "C",
@@ -126,6 +210,8 @@ export function handleVectorCortexHealth(req, res, ctx) {
         updatedAt: new Date().toISOString(),
         aggregate: "CLOSED_A",
         stateSource: "ephemeral",
+        encoderAssetDigest: enc.assetDigest,
+        encoderMode: enc.mode,
     };
     if (!card) {
         sendJson(res, 200, fallback);
@@ -161,6 +247,8 @@ export function handleVectorCortexHealth(req, res, ctx) {
         updatedAt: new Date().toISOString(),
         aggregate,
         stateSource: card.stateSource,
+        encoderAssetDigest: enc.assetDigest,
+        encoderMode: enc.mode,
     };
     sendJson(res, 200, body);
     return 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,24 @@ 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");
+/**
+ * VC2C — encoder qualification + calibration (QualifiedEncoderV1 / CalibrationV1).
+ * Default ON. `MEGACOMPACT_VC2C=0` disables and is byte-identical to the
+ * predecessor (mode C: no qualification manifest is read or selected, the
+ * calibrate/select/fallback seams are idle, zero `vector_cortex_encoder_qualification_*`
+ * emissions; the trigram/lexical paths are unchanged). The real consumers are
+ * the encoder-qualification emit seam and the calibrate/select seams.
+ */
+export const VC2C_ENABLED = () => sprintFlag("MEGACOMPACT_VC2C");
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/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, VC2C_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/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/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),
+    };
+}