pi-mega-compact 0.17.1 → 0.18.1

package/extensions/mega-events/context-handler.ts

@@ -2,45 +2,32 @@
  * mega-events/context-handler.ts — the context event handler (auto-trigger).
  *
  * Delegate-shell (extensions split): handles the live-trim compaction pipeline —
- * DB-mirror append, fast-gate threshold check, pipeline invocation, legacy
- * durable compact, and the live-trim message reconstruction that feeds pi's
- * transformContext. The extracted pieces live in ./context-handler/:
+ * DB-mirror append, fast-gate threshold check, replay/debounce, pipeline
+ * invocation, legacy durable compact, and the live-trim message reconstruction
+ * that feeds pi's transformContext. The extracted pieces live in ./context-handler/:
  *  - messageText.ts    (messageContentText — best-effort text extraction)
  *  - tailResult.ts     (buildTailResult — recall-tail injection factory)
  *  - afterCompact.ts   (persistEpochAndMaintain — epoch/wiki/seed/dedup writes)
+ *  - dbMirrorAppend.ts (appendMirrorAndLedger — mirror + VC1B ledger append)
+ *  - gateCheck.ts      (evaluateGate — S29 fast-gate threshold evaluation)
+ *  - pipelineRun.ts    (invokePipeline — adaptive-compression runCompact)
+ *  - liveTrim.ts       (buildLiveTrimView — S16 live-trim reconstruction + cap)
  */
 import type {
 	ExtensionAPI,
 	ExtensionContext,
 	ContextEvent,
 } from "@earendil-works/pi-coding-agent";
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import {
-	openStore,
-	resolveModelThreshold,
-	DEFAULT_SAFETY_MARGIN_PCT,
-	DEFAULT_FIRE_POINT_PCT,
-} from "../../src/store/sqlite.js";
-import { autoCompactCheck } from "../../src/compact.js";
-import {
-	estimateSessionTokens,
-	estimateBlockTokens,
-	estimateMessageTokens,
-} from "../../src/tokens.js";
+import { estimateSessionTokens } from "../../src/tokens.js";
 import type { MegaRuntime } from "../mega-runtime.js";
-import { runCompact, piCompactWouldNoop } from "../mega-pipeline.js";
-import {
-	pressureFromPct,
-	pressureRatio,
-	type MegaConfig,
-} from "../mega-config.js";
-import { appendMirrorMessages } from "./mirror-append.js";
-import { appendMessagesToLedger } from "../mega-runtime/vector-cortex-ledger.js";
-import { epochIdFor } from "../../src/mirror/epoch.js";
-import { computeLiveTrimCut, liveTrimSummaryMessage } from "../mega-trim.js";
-import { messageContentText } from "./context-handler/messageText.js";
+import { piCompactWouldNoop } from "../mega-pipeline.js";
+import type { MegaConfig } from "../mega-config.js";
 import { buildTailResult } from "./context-handler/tailResult.js";
 import { persistEpochAndMaintain } from "./context-handler/afterCompact.js";
+import { appendMirrorAndLedger } from "./context-handler/dbMirrorAppend.js";
+import { evaluateGate } from "./context-handler/gateCheck.js";
+import { invokePipeline } from "./context-handler/pipelineRun.js";
+import { buildLiveTrimView } from "./context-handler/liveTrim.js";
 
 /** Register the context event handler (live-trim auto-trigger). */
 export function registerContextHandler(
@@ -101,122 +88,14 @@ export function registerContextHandler(
 
 		const view = viewForFallback ?? runtime.engineView(messages);
 
-		// S27 DB-mirror: append incoming messages to raw_transcript.
-		// Runs BEFORE fast-gate so every message is captured, even if we
-		// don't compact this turn. Append is idempotent (content_hash PK).
-		// F3: high-water mark (mirror-append.ts) skips already-processed
-		// messages on subsequent events. On fork/rewind (shorter list or
-		// boundary hash mismatch) the mark is dropped, falling back to a
-		// full reprocess.
-		if (config.dbMirror) {
-			try {
-				const db = openStore(runtime.currentStateDir);
-				appendMirrorMessages(
-					db,
-					messages,
-					runtime.rt.sessionId,
-					epochIdFor(runtime.rt.sessionId),
-					runtime.currentTurn,
-				);
-				// P2.2: populate conversation_thread + tool_results tables for
-				// prompt-cache analytics and durable separation. The live-array
-				// separation (buildSeparatedPrompt / buildCacheOptimizedPrompt in
-				// tailResult above) is sufficient for the prompt-construction path;
-				// these DB writes persist the split for post-hoc analysis, dashboard
-				// queries, and future readers. Non-fatal — failure here never breaks
-				// the agent loop (PREVENT-PI-004: zero network, local SQLite only).
-				{
-					const sid = runtime.rt.sessionId;
-					const turn = runtime.currentTurn;
-					const now = Date.now();
-					const threadStmt = db.prepare(
-						"INSERT OR IGNORE INTO conversation_thread (conversation_id, role, content, turn_index, timestamp) VALUES (?, ?, ?, ?, ?)",
-					);
-					const toolStmt = db.prepare(
-						"INSERT OR IGNORE INTO tool_results (conversation_id, role, content, turn_index, timestamp) VALUES (?, ?, ?, ?, ?)",
-					);
-					for (const m of messages) {
-						const role = m.role;
-						const content = messageContentText(m);
-						if (role === "user" || role === "assistant") {
-							threadStmt.run(sid, role, content, turn, now);
-						} else if (role === "toolResult" || role === "bashExecution") {
-							toolStmt.run(sid, role, content, turn, now);
-						}
-					}
-				}
-			} catch (e) {
-				runtime.logger.warn("db-mirror-append-fail", { error: String(e) });
-			}
-		}
+		// S27 DB-mirror + VC1B ledger append. Runs BEFORE the fast-gate so every
+		// message is captured, even if we don't compact this turn. Non-fatal.
+		appendMirrorAndLedger(runtime, config, messages);
 
-		// VC1B (S1): canonical messages -> v2 ledger occurrences. Flag-OFF opens
-		// no DB (byte-identical predecessor); non-fatal. onFailure surfaces
-		// per-append rejections (e.g. EVT_SEQ_REGRESSION on rewind/fork) as
-		// structured warnings rather than swallowing them silently.
-		try {
-			appendMessagesToLedger(
-				runtime.currentStateDir,
-				runtime.rt.sessionId,
-				messages,
-				runtime.logger,
-			);
-		} catch (e) {
-			runtime.logger.warn("vc1b-ledger-append-fail", { error: String(e) });
-		}
-
-		// S52 / v0.16.1: per-model threshold override. The user can tune the
-		// fire point + safety margin PER MODEL (different providers' models range
-		// 8K-1M+ context, so one global tier % is wrong). Falls back to env/default
-		// when no override row exists. Computed once here + reused in the tail cap
-		// below; the lookup is a single SQLite PK hit (cheap; cached after the
-		// first read in a session).
-		const _modelIdForThreshold = runtime.currentModel?.modelId ?? null;
-		const _perModelThreshold = resolveModelThreshold(_modelIdForThreshold, {
-			safetyMarginFallback: DEFAULT_SAFETY_MARGIN_PCT,
-			firePointFallback:
-				config.tierPct != null
-					? Math.round(config.tierPct * 100)
-					: DEFAULT_FIRE_POINT_PCT,
-			stateDir: runtime.currentStateDir,
-		});
-		// S29 FAST GATE: drive the auto-trigger off the context % (the number the
-		// menu bar shows), NOT the token count — the model under-reports tokens,
-		// so a token-only gate misses the overshoot that causes max-output-tokens
-		// truncation. The fire point is the per-model override when present,
-		// otherwise the tier's percent threshold (tierPct) unless overridden by
-		// MEGACOMPACT_AUTO_PCT_TRIGGER. `custom` (absolute
-		// MEGACOMPACT_THRESHOLD_TOKENS, tierPct null) is an explicit opt-out of
-		// percent scaling — it keeps the token gate. When pct is unavailable
-		// (window unknown / a model that doesn't report percent) a tiered config
-		// falls back to the token gate (S27 boot-fallback guarantee) instead of
-		// skipping compaction — a percent-only gate would regress that.
-		let gatePassed = false;
-		if (config.tierPct != null && pct != null) {
-			// Per-model override is a % (10-90); tierPct is a fraction (0.1-1.0).
-			// Prefer the override; fall back to autoPctTrigger + tierPct.
-			const tierPctFraction = config.autoPctTrigger ?? config.tierPct;
-			const perModelFraction = _perModelThreshold.firePointPct / 100;
-			const firePct =
-				_modelIdForThreshold != null ? perModelFraction : tierPctFraction;
-			gatePassed = pct / 100 >= firePct;
-		} else {
-			// custom tier OR tiered-but-pct-unavailable → token gate (S27 fallback).
-			if (currentTokens < runtime.effectiveThreshold) {
-				runtime.diagCtxFastGate++;
-				return tailResult() ?? undefined;
-			}
-			const check = autoCompactCheck(currentTokens, runtime.effectiveThreshold); // SERVER-STYLE CONFIRM (local)
-			if (!check.shouldCompact) {
-				runtime.diagCtxNoCompact++;
-				return tailResult() ?? undefined;
-			}
-			gatePassed = true;
-		}
-		if (!gatePassed) {
-			runtime.diagCtxFastGate++;
-			return tailResult() ?? undefined;
-		}
+		// S29 FAST GATE: drive the auto-trigger off the context percent (see
+		// gateCheck.ts). Returns a tailed view when the gate does not pass.
+		const gate = evaluateGate(runtime, config, { pct, currentTokens, tailResult });
+		if (gate.kind === "return") return gate.view;
 
 		// D.2: Replay MUST be exempt from debounce — replay is free (no compute,
 		// no re-write) and prevents unnecessary KV-cache invalidation. Check
@@ -266,40 +145,20 @@ export function registerContextHandler(
 		}
 		runtime.debounceUntil = now + 2000;
 
-		// Adaptive compression (Fix E): scale compression strength + keepFrom depth
-		// with how close we are to the model context limit. Null-safe: when the
-		// token-fallback path ran (pct unavailable) use the token-basis pressure
-		// (the same basis the runtime `pressure` getter uses for custom/no-window).
-		const pressure =
-			pct != null
-				? pressureFromPct(pct)
-				: pressureRatio(currentTokens, runtime.effectiveThreshold);
-		const ran = runCompact(pi, runtime, config, ctx, messages, {
-			compressionPressure: pressure,
+		// Adaptive-compression pipeline invocation (see pipelineRun.ts). Returns a
+		// tailed view ("return") when compaction skipped; otherwise "proceed" with
+		// the result + pressure consumed by the live-trim stage below.
+		const pipeline = invokePipeline(pi, runtime, config, ctx, {
+			messages,
+			pct,
+			currentTokens,
+			tailResult,
 		});
-		// D.3: skip paths fall back to replay instead of returning empty.
-		// If runCompact skipped and we have a valid trimCache, replay it
-		// (free stability win) — otherwise defer to the next event.
-		if (ran.skipped) {
-			runtime.diagCtxRunSkipped++;
-			if (
-				runtime.trimCache &&
-				runtime.trimCache.checkpointId === runtime.rt.lastCheckpointId &&
-				runtime.trimCache.cut <= messages.length
-			) {
-				const recent = messages.slice(runtime.trimCache.cut); // guardrails-allow PREVENT-PI-002: cached `cut` was sanitized by computeLiveTrimCut (src/boundary.ts); replayed verbatim, transcript only grows within an epoch.
-				runtime.diagLiveTrimFires++;
-				runtime.diagLiveTrimReplays++;
-				runtime.snapshot(ctx);
-				const skipView = [{ ...runtime.trimCache.summaryAgentMsg }, ...recent];
-				return tailResult(skipView) ?? { messages: skipView };
-			}
-			return tailResult() ?? undefined;
-		}
+		if (pipeline.kind === "return") return pipeline.view;
 
 		// S27 DB-mirror: write checkpoint_epoch + stamp turn epochs + auto-wiki +
 		// topic seed + fire-and-forget dedup. Best-effort + non-fatal.
-		await persistEpochAndMaintain(runtime, config, ran);
+		await persistEpochAndMaintain(runtime, config, pipeline.ran);
 
 		// LEGACY path (rollback): v0.4.28 ctx.compact() + the no-op gate. The
 		// manual compact path aborts the in-flight turn — only used behind the flag.
@@ -351,180 +210,19 @@ export function registerContextHandler(
 		}
 
 		// S16 LIVE trim: collapse the compacted region to a summary + recent anchor.
-		// Non-destructive: pi keeps the real transcript; only this LLM call sees the
-		// trimmed window. We compute the cut on the engine view (pure, tested) then
-		// slice the ORIGINAL pi AgentMessage[] from that index (lossless alignment,
-		// mirroring dropCompactedRange) and prepend a user-role summary message.
-		// A build failure or unsafe cut returns nothing (no trim this call — the
-		// next context event retries). The anchor floor is read live from env (the
-		// config value is the cached default) so it can be tuned per-test / per-run
-		// without reloading the module.
-		try {
-			const anchorEnv = process.env.MEGACOMPACT_ANCHOR_USER_MESSAGES;
-			const anchorUserMessages =
-				anchorEnv != null &&
-				anchorEnv !== "" &&
-				Number.isFinite(Number(anchorEnv))
-					? Number(anchorEnv)
-					: config.anchorUserMessages;
-			const cut = computeLiveTrimCut(view, {
-				compactedFrom: ran.result.compactedFrom,
-				summary: ran.result.summary,
-				anchorUserMessages,
-				// CRITICAL-OVER ESCAPE HATCH: when context is at/over ~90% of the
-				// window, relief takes priority over the anchor floor. Without this,
-				// computeLiveTrimCut bails to null (can't satisfy the floor) and the
-				// model is fed a raw overflow that errors every turn — the
-				// "Already compacted" + overflow death-spiral (2026-08-01 incident).
-				// A thin anchor is recoverable; an overflowed session is not.
-				//
-				// CRITICAL: pct is null for OpenAI-compatible providers that don't
-				// report usage.percent (e.g. neuralwatt). Without the token-pressure
-				// fallback the hatch never armed → cut=null → raw overflow → 400
-				// "conversation too long even after compaction" (2026-08-03 incident
-				// on glm-5.2-short, 200K window). Now also fires on pressure >= 0.9
-				// (token-basis) so the hatch arms regardless of whether the provider
-				// reports pct.
-				criticalOver: (pct ?? 0) >= 90 || pressure >= 0.9,
-			});
-			if (cut === null) {
-				runtime.diagCtxCutNull++;
-				runtime.logger.info("live-trim-skip", {
-					sessionId: runtime.rt.sessionId,
-					compactedFrom: ran.result.compactedFrom,
-					viewLen: view.length,
-					anchorUserMessages,
-					criticalOver: (pct ?? 0) >= 90,
-				});
-				return tailResult() ?? undefined; // unsafe / below anchor floor — no trim this call
-			}
-			const summaryMsg = liveTrimSummaryMessage({
-				compactedFrom: ran.result.compactedFrom,
-				summary: ran.result.summary,
-				anchorUserMessages: config.anchorUserMessages,
-			});
-			// Synthesize a user-role AgentMessage carrying the compacted summary.
-			const summaryAgentMsg = {
-				role: "user" as const,
-				content: summaryMsg.text,
-				// v0.8.6: stable timestamp across the epoch (NOT Date.now()) so the
-				// summary message bytes — and thus the KV-cache prefix — don't drift
-				// on every replay within the same compaction epoch.
-				timestamp: runtime.rt.lastCompactAt ?? Date.now(),
-			} as unknown as AgentMessage;
-			const recentRaw = messages.slice(cut); // guardrails-allow PREVENT-PI-002: `cut` is the pre-sanitized `compactedFrom` produced by src/boundary.ts computeDropRange, so the preserved run begins on a toolPair-safe index.
-
-			// FIX 2 (2026-08-03 incident): TOKEN-BUDGET CAP on the live-trim view.
-			// Compaction fires at tier% of the window (140K for a 200K window),
-			// but a SINGLE turn can inject a huge tool output (file read, bash) that
-			// jumps context from 139K → 199K+ before the next gate fires. When that
-			// happens [summary + preserved tail] can STILL exceed the model window,
-			// and the provider rejects with 400 "conversation too long even after
-			// compaction". The anchor floor (PREVENT-PI-001) keeps ≥N user messages
-			// but has NO token cap, so a 2-message tail of two 80K bash outputs sails
-			// right past the window.
-			//
-			// Cap: when the model context window is known, reserve room for the
-			// summary + the model's max output tokens + a 10% safety margin, then
-			// drop oldest preserved messages from the front of `recentRaw` until the
-			// tail fits. Never drops below the FINAL message (always keep the latest
-			// turn so the agent can respond). This is a last-resort HARD cap — it
-			// only fires when the preserved tail alone is oversized, which is rare.
-			const ctxWindow = runtime.lastCtxWindow;
-			// Reuse the per-model threshold resolved at the gate (single lookup).
-			const modelThreshold = _perModelThreshold;
-			// Reserve room for output tokens. Use the model's reported max output
-			// when known; fall back to 10% of the window (scales with any model —
-			// 20K for a 200K window, 100K for a 1M window) so we never let the
-			// preserved tail eat the model's output budget when maxTokens is unknown.
-			const maxOutput =
-				runtime.currentModel?.maxTokens && runtime.currentModel.maxTokens > 0
-					? runtime.currentModel.maxTokens
-					: Math.ceil(ctxWindow * 0.1);
-			let recent = recentRaw;
-			if (ctxWindow > 0 && recentRaw.length > 1) {
-				const summaryTokens = estimateBlockTokens(summaryMsg.text);
-				// Reserve: summary + max output + per-model safety margin (0-20%).
-				const safetyMargin = Math.ceil(
-					ctxWindow * (modelThreshold.safetyMarginPct / 100),
-				);
-				const budget = ctxWindow - maxOutput - safetyMargin - summaryTokens;
-				if (budget > 0) {
-					// Walk recent from the front, dropping oldest first until the
-					// remaining tail fits. Use the AgentMessage→engine-text estimate via
-					// messageContentText (already imported) + estimateMessageTokens.
-					let tailTokens = 0;
-					for (let i = recentRaw.length - 1; i >= 0; i--) {
-						const m = recentRaw[i];
-						tailTokens += estimateMessageTokens({
-							text: messageContentText(m),
-						});
-						if (tailTokens > budget) {
-							// Keep from i+1 onward; but never fewer than the final message.
-							const startIdx = Math.min(i + 1, recentRaw.length - 1);
-							if (startIdx > 0) {
-								recent = recentRaw.slice(startIdx);
-								runtime.logger.warn("live-trim-tail-cap", {
-									sessionId: runtime.rt.sessionId,
-									dropped: startIdx,
-									tailTokens,
-									safetyMarginPct: modelThreshold.safetyMarginPct,
-									budget,
-									ctxWindow,
-								});
-							}
-							break;
-						}
-					}
-				}
-			}
-
-			// v0.8.6: cache the trim view so subsequent gated calls in this epoch
-			// replay it verbatim (stabilizing the KV-cache prefix) instead of
-			// regenerating a fresh summary + sentinel every fire.
-			runtime.trimCache = {
-				// v0.8.7: key the replay cache on the STABLE epoch signal
-				// (rt.lastCheckpointId) instead of ran.result.checkpointId, which is
-				// dedup-volatile: on a re-compact that dedups onto a DIFFERENT existing
-				// checkpoint, result.checkpointId is the matched id (engine.ts:188) while
-				// lastCheckpointId is only updated on a genuinely new checkpoint
-				// (compact.ts:100-104). Keying on result.checkpointId would make
-				// trimCache.checkpointId != rt.lastCheckpointId forever after that
-				// dedup fire, disabling replay for the rest of the epoch (the
-				// alternating cache-miss that 0.8.6 meant to fix). Prefer the stable
-				// signal; fall back to result.checkpointId then the epoch timestamp
-				// only for the no-checkpoint edge case.
-				checkpointId:
-					runtime.rt.lastCheckpointId ??
-					ran.result.checkpointId ??
-					`epoch-${runtime.rt.lastCompactAt ?? Date.now()}`,
-				cut,
-				summaryAgentMsg,
-				ctxPct: pct ?? null,
-				ctxTokens: currentTokens,
-			};
-			runtime.snapshot(ctx);
-			// DIAG (team-run relief): confirm the live trim actually fires + how big
-			// the window still is. The return is non-durable (per-LLM-call only), so
-			// this is the signal that the model is being fed a compacted view while
-			// the on-disk transcript + context meter keep growing.
-			runtime.diagLiveTrimFires++;
-			runtime.logger.info("live-trim", {
-				sessionId: runtime.rt.sessionId,
-				inputMsgs: messages.length,
-				outputMsgs: recent.length + 1,
-				compactedFrom: cut,
-				ctxPct: pct,
-				ctxTokens: usage?.tokens ?? null,
-			});
-			return (
-				tailResult([summaryAgentMsg, ...recent]) ?? {
-					messages: [summaryAgentMsg, ...recent],
-				}
-			);
-		} catch {
-			runtime.diagCtxThrown++;
-			return tailResult() ?? undefined; // non-fatal: no trim this call; the next context event retries
-		}
+		// See liveTrim.ts. Non-destructive: pi keeps the real transcript; only this
+		// LLM call sees the trimmed window. Returns undefined on unsafe cut/throw —
+		// the next context event retries.
+		return buildLiveTrimView(runtime, config, ctx, {
+			messages,
+			view,
+			pct,
+			currentTokens,
+			usageTokens: usage?.tokens,
+			pressure: pipeline.pressure,
+			ran: pipeline.ran,
+			perModelThreshold: gate.perModelThreshold,
+			tailResult,
+		});
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.17.1",
+  "version": "0.18.1",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",

package/src/config/vector-cortex.ts

@@ -69,6 +69,27 @@ export const VC0C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC0C");
  */
 export const VC1C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC1C");
 
+/**
+ * VC2A — offline model runtime and asset decision (ModelManifestV1 /
+ * EncoderRuntime).
+ * Default ON. `MEGACOMPACT_VC2A=0` disables and is byte-identical to the
+ * predecessor (mode C: no asset manifest is read/verified, the encoder runtime
+ * idles in mode C, zero `vector_cortex_encoder_*` emissions; the trigram/lexical
+ * paths are unchanged). The real consumers are the encoder emit seam and the
+ * encoder runtime's A/B/C selection.
+ */
+export const VC2A_ENABLED = (): boolean => 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 = (): boolean => 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/src/config.ts

@@ -157,6 +157,8 @@ export {
   VC0C_ENABLED,
   VC1B_ENABLED,
   VC1C_ENABLED,
+  VC2A_ENABLED,
+  VC2B_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

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

@@ -0,0 +1,155 @@
+/**
+ * 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,
+  type EncoderPlatform,
+  type ModelManifestV1,
+} from "./types.js";
+
+export type AssetVerifyResult =
+  | { ok: true; embeddedBytes: number; maxTokens: number; onnxDigest: string; tokenizerDigest: string }
+  | { ok: false; code: string };
+
+/** 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: string): boolean {
+  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: string): string | null {
+  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): EncoderPlatform | null {
+  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}` as EncoderPlatform;
+  return (ENCODER_SUPPORTED_PLATFORMS as readonly string[]).includes(candidate)
+    ? candidate
+    : null;
+}
+
+function isManifest(m: unknown): m is ModelManifestV1 {
+  const o = m as ModelManifestV1;
+  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: string,
+  manifest: unknown,
+  platform: EncoderPlatform | null = detectPlatform(),
+): AssetVerifyResult {
+  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: string): ModelManifestV1 | null {
+  try {
+    const raw = JSON.parse(readFileSync(join(assetDir, "manifest.json"), "utf8")) as unknown;
+    return isManifest(raw) ? raw : null;
+  } catch {
+    return null;
+  }
+}