pi-mega-compact 0.17.1 → 0.18.0

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

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

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

@@ -0,0 +1,85 @@
+/**
+ * vector-cortex/encoder/types.ts — VC2A contract (ModelManifestV1 /
+ * EncoderRuntime).
+ *
+ * The offline encoder runtime owns the learned-asset path (triad mode A: a
+ * qualified local ONNX). MODEL_ASSET.md is the normative target. This
+ * sprint (VC2A) ships the manifest + verification + shaped-inference contract;
+ * the trained weights are packaged in VC2C (MODEL_ASSET: "package.json changes
+ * occur only in VC2C"), but the verification, digest-before-load, platform
+ * demotion, shape rejection and RSS/latency budget all land here so a later
+ * sprint only substitutes real weights.
+ *
+ * Contract-first (ENGINEERING_PRACTICES §3): this types file is the reviewed
+ * gate; implementations import from it; consumers import only types + factory.
+ *
+ * Pi-agnostic and dependency-free (PREVENT-PI-004 — local assets only, the
+ * runtime never fetches). No `any` (PREVENT-011).
+ */
+/** Supported matrix from MODEL_ASSET.md §qualification. */
+export const ENCODER_SUPPORTED_PLATFORMS = [
+    "linux-x64",
+    "linux-arm64",
+    "darwin-x64",
+    "darwin-arm64",
+    "win32-x64",
+];
+/** ONNX opset required by the normative v1 target (opset 17). */
+export const ENCODER_OPSET = 17;
+/** Batch must be exactly 1 (single-request inference). */
+export const ENCODER_BATCH = 1;
+/** Maximum accepted token count (WordPiece, deterministic truncation). */
+export const ENCODER_MAX_TOKENS = 512;
+/** Caps the encoder's MARGINAL footprint (bytes) at 150 MiB (MODEL_ASSET
+ *  §qualification). The budget bounds the encoder's own incremental allocation
+ *  (a reusable projection buffer + any externally staged asset working set),
+ *  NOT the whole-process RSS — in a live pi extension the process baseline
+ *  routinely exceeds 150 MiB, so measuring absolute RSS would make mode A
+ *  unreachable in production. This is the "RSS" figure the acceptance metric
+ *  and ENC_FAIL.RSS_BUDGET_EXCEEDED refer to: it is the encoder's marginal
+ *  footprint, never the process RSS (code-review Q01/Q02). */
+export const ENCODER_RSS_BUDGET_BYTES = 150 * 1024 * 1024;
+/** p95 inference budget in milliseconds (MODEL_ASSET §qualification). */
+export const ENCODER_LATENCY_P95_MS = 40;
+/** Semantic projection head width (MODEL_ASSET: 384 float32 L2-normalized). */
+export const ENCODER_SEMANTIC_WIDTH = 384;
+/** Exact VC2A failure codes (returned, never thrown across the boundary). */
+export const ENC_FAIL = {
+    /** opset != 17. */
+    OPSET_INVALID: "ENC_OPSET_INVALID",
+    /** batch != 1. */
+    BATCH_INVALID: "ENC_BATCH_INVALID",
+    /** maxTokens > 512. */
+    TOKENS_EXCEEDED: "ENC_TOKENS_EXCEEDED",
+    /** input token count > declared maxTokens / 512, or not batch 1. */
+    SHAPE_INVALID: "ENC_SHAPE_INVALID",
+    /** asset file unreadable (truncated during digest read, allocator failure). */
+    ASSET_UNREADABLE: "ENC_ASSET_UNREADABLE",
+    /** on-disk digest does not match the manifest (one-byte mutation). */
+    DIGEST_MISMATCH: "ENC_DIGEST_MISMATCH",
+    /** platform not in the supported matrix (selects trigram B). */
+    PLATFORM_UNSUPPORTED: "ENC_PLATFORM_UNSUPPORTED",
+    /** manifest missing/invalid (selects trigram B). */
+    MANIFEST_INVALID: "ENC_MANIFEST_INVALID",
+    /** encoder MARGINAL footprint over the 150 MiB budget (selects trigram B).
+     *  This is the encoder's own incremental allocation (a reusable projection
+     *  buffer + any externally staged asset working set), NOT whole-process RSS
+     *  — see ENCODER_RSS_BUDGET_BYTES. */
+    RSS_BUDGET_EXCEEDED: "ENC_RSS_BUDGET_EXCEEDED",
+    /** mode C forced by the rollback path (MEGACOMPACT_VC2A=0 / forcedMode "C").
+     *  Distinct from MANIFEST_INVALID so a non-corrupt, correctly-shaped asset
+     *  present on disk is not mis-reported as "manifest invalid" when the runtime
+     *  is simply rolled back to the predecessor path (code-review Q04). */
+    ROLLBACK: "ENC_ROLLBACK_ACTIVE",
+};
+/** The 8 registered VC2A conformance IDs (task 1: "register ENC-001..008"). */
+export const ENC_IDS = [
+    "ENC-001",
+    "ENC-002",
+    "ENC-003",
+    "ENC-004",
+    "ENC-005",
+    "ENC-006",
+    "ENC-007",
+    "ENC-008",
+];

package/extensions/dashboard-server/routes-rag-settings-helpers.ts

@@ -311,6 +311,12 @@ export const SETTINGS: ReadonlyArray<{
 				"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,
+			),
 		],
 	},
 	{

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

@@ -0,0 +1,93 @@
+/**
+ * context-handler/dbMirrorAppend.ts — DB-mirror append + VC1B ledger append.
+ *
+ * Extracted from context-handler.ts (delegate-shell split). Appends incoming
+ * messages to raw_transcript (S27) + conversation_thread/tool_results (P2.2),
+ * then appends canonical messages to the v2 vector-cortex ledger (VC1B S1).
+ * All best-effort + non-fatal — a failure never breaks the agent loop
+ * (PREVENT-PI-004: zero network, local SQLite only).
+ */
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { openStore } from "../../../src/store/sqlite.js";
+import { appendMirrorMessages } from "../mirror-append.js";
+import { appendMessagesToLedger } from "../../mega-runtime/vector-cortex-ledger.js";
+import { epochIdFor } from "../../../src/mirror/epoch.js";
+import type { MegaRuntime } from "../../mega-runtime.js";
+import type { MegaConfig } from "../../mega-config.js";
+import { messageContentText } from "./messageText.js";
+
+/**
+ * Append incoming messages to the DB mirror (raw_transcript + thread/tool
+ * tables) and the v2 ledger. Gated on config.dbMirror for the mirror; the VC1B
+ * ledger append is flag-gated inside appendMessagesToLedger (flag-OFF opens no
+ * DB, byte-identical to the predecessor). Non-fatal end-to-end.
+ */
+export function appendMirrorAndLedger(
+	runtime: MegaRuntime,
+	config: MegaConfig,
+	messages: AgentMessage[],
+): void {
+	// 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) 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) });
+		}
+	}
+
+	// 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) });
+	}
+}

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

@@ -0,0 +1,101 @@
+/**
+ * context-handler/gateCheck.ts — S29 fast-gate threshold evaluation.
+ *
+ * Extracted from context-handler.ts (delegate-shell split). Drives 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. Returns a
+ * discriminated union: either "return" (a tailed view to hand back to pi) or
+ * "proceed" with the resolved per-model threshold for the live-trim tail cap.
+ */
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import {
+	resolveModelThreshold,
+	DEFAULT_SAFETY_MARGIN_PCT,
+	DEFAULT_FIRE_POINT_PCT,
+} from "../../../src/store/sqlite.js";
+import { autoCompactCheck } from "../../../src/compact.js";
+import type { MegaRuntime } from "../../mega-runtime.js";
+import type { MegaConfig } from "../../mega-config.js";
+
+/** Tail-injection closure shape produced by buildTailResult (tailResult.ts). */
+export type TailResultFn = (
+	msgs?: readonly AgentMessage[],
+) => { messages: AgentMessage[] } | undefined;
+
+/** Outcome of the fast-gate evaluation. */
+export type GateOutcome =
+	| { kind: "return"; view: { messages: AgentMessage[] } | undefined }
+	| {
+			kind: "proceed";
+			perModelThreshold: { safetyMarginPct: number; firePointPct: number };
+	  };
+
+/**
+ * Evaluate whether the current context warrants compaction. Returns a tailed
+ * view ("return") when the gate does not pass, or "proceed" with the resolved
+ * per-model threshold (reused by the live-trim token-budget tail cap).
+ */
+export function evaluateGate(
+	runtime: MegaRuntime,
+	config: MegaConfig,
+	opts: {
+		pct: number | null | undefined;
+		currentTokens: number;
+		tailResult: TailResultFn;
+	},
+): GateOutcome {
+	const pct = opts.pct;
+	const currentTokens = opts.currentTokens;
+	const tailResult = opts.tailResult;
+
+	// 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: `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 { kind: "return", view: tailResult() ?? undefined };
+		}
+		const check = autoCompactCheck(currentTokens, runtime.effectiveThreshold); // SERVER-STYLE CONFIRM (local)
+		if (!check.shouldCompact) {
+			runtime.diagCtxNoCompact++;
+			return { kind: "return", view: tailResult() ?? undefined };
+		}
+		gatePassed = true;
+	}
+	if (!gatePassed) {
+		runtime.diagCtxFastGate++;
+		return { kind: "return", view: tailResult() ?? undefined };
+	}
+	return { kind: "proceed", perModelThreshold };
+}