dsh-switchman 1.8.1 → 1.9.0

package/host/context-trim/metrics.js

@@ -0,0 +1,104 @@
+/** dsh-switchman context-trim stream metrics.
+ *
+ * Meter duality (design §8): trim thresholds run on VIEW-estimated tokens
+ * (buildView output, the meter the fold logic controls), while the
+ * watermark keeps its STORED-token meter — the two signals are kept
+ * separate on purpose. This module wraps the llm/stream result generator
+ * so every provider response is sampled for usage (input/cached/output)
+ * without ever breaking the stream: sampling errors are swallowed, the
+ * chunk always flows through untouched.
+ */
+
+/** Extract usage fields from a stream chunk. Returns
+ * { inputTokens, cachedTokens, outputTokens } or null when the chunk
+ * carries none. Defensive field walk — providers shape usage differently
+ * (usage.input_tokens, usage.prompt_tokens, cached_tokens,
+ * cache_read_input_tokens, ...). */
+export function extractUsage(chunk) {
+	if (chunk === null || typeof chunk !== "object") return null;
+	const candidates = [chunk.usage, chunk.metadata?.usage, chunk.response?.usage];
+	for (const usage of candidates) {
+		if (usage === null || typeof usage !== "object") continue;
+		const input = usage.input_tokens ?? usage.prompt_tokens ?? usage.inputTokens;
+		const cached = usage.cache_read_input_tokens ?? usage.cached_tokens ?? usage.cachedTokens ?? usage.prompt_tokens_details?.cached_tokens;
+		const output = usage.output_tokens ?? usage.completion_tokens ?? usage.outputTokens;
+		if (!Number.isFinite(input) && !Number.isFinite(cached) && !Number.isFinite(output)) continue;
+		return {
+			inputTokens: Number.isFinite(input) ? input : null,
+			cachedTokens: Number.isFinite(cached) ? cached : null,
+			outputTokens: Number.isFinite(output) ? output : null,
+		};
+	}
+	return null;
+}
+
+/** Per-session metrics store. */
+export function createMetrics() {
+	const sessions = new Map(); // sessionId -> record
+
+	function recordOf(sessionId) {
+		let record = sessions.get(sessionId);
+		if (record === undefined) {
+			record = {
+				lastInputTokens: null,
+				cachedTokens: null,
+				outputTokens: null,
+				viewTokens: null, // view estimate noted by the listener pre-request
+				lastModel: null, // { provider, model } of the last stream
+				lastStreamAt: 0,
+				totalStreams: 0,
+			};
+		}
+		sessions.delete(sessionId); // drop first so re-insert refreshes recency order
+		sessions.set(sessionId, record);
+		// Prune: keep only the 50 most recently active sessions (bounded memory).
+		if (sessions.size > 50) {
+			const oldest = sessions.keys().next().value;
+			if (oldest !== undefined && oldest !== sessionId) sessions.delete(oldest);
+		}
+		return record;
+	}
+
+	return {
+		/** Note the outbound-view estimate + model before/around a request. */
+		noteView(sessionId, viewTokens, model) {
+			const record = recordOf(sessionId);
+			if (Number.isFinite(viewTokens)) record.viewTokens = Math.round(viewTokens);
+			if (model !== null && typeof model === "object") record.lastModel = { provider: model.provider ?? null, model: model.model ?? null };
+			record.lastStreamAt = Date.now();
+			record.totalStreams += 1;
+			return record;
+		},
+		/** Merge a usage sample (from extractUsage) into the record. */
+		recordUsage(sessionId, usage) {
+			if (usage === null) return null;
+			const record = recordOf(sessionId);
+			if (usage.inputTokens !== null) record.lastInputTokens = usage.inputTokens;
+			if (usage.cachedTokens !== null) record.cachedTokens = usage.cachedTokens;
+			if (usage.outputTokens !== null) record.outputTokens = usage.outputTokens;
+			return record;
+		},
+		/** Record of one session (or null when never streamed). */
+		of(sessionId) {
+			return sessions.get(sessionId) ?? null;
+		},
+	};
+}
+
+/** Wrap a stream result so each chunk flows through a (failing-open)
+ * sampler before being yielded. Returns the original value untouched when
+ * it is not an async iterable (non-stream fallbacks must pass through). */
+export function wrapStreamForMetrics(result, onChunk) {
+	if (result === null || typeof result !== "object" || typeof result[Symbol.asyncIterator] !== "function") return result;
+	async function* sampled() {
+		for await (const chunk of result) {
+			try {
+				onChunk(chunk);
+			} catch {
+				/* sampling must never break the stream */
+			}
+			yield chunk;
+		}
+	}
+	return sampled();
+}

package/host/context-trim/state.js

@@ -0,0 +1,241 @@
+/** dsh-switchman context-trim fold ledger store (host side).
+ *
+ * One ledger per session: the ordered list of fold blocks plus fold
+ * metadata (last fold's view-token estimate for the growth gate, fold
+ * timestamps for the hourly cadence cap). Ledgers persist as one JSON
+ * file per session under <dshHome>/.dsh-switchman/state/trim/ (or an
+ * explicit state dir) — atomic tmp+rename writes, corrupt files reset the
+ * ledger (fail-open: trimming must never brick a session over its own
+ * bookkeeping).
+ *
+ * commitFold validates a new block against the CURRENT messages snapshot
+ * (the posMap: refs -> indices) before it enters the ledger — ref range
+ * must be locatable, segment-aligned, disjoint from every existing block,
+ * and strictly monotonic (behind or inside the existing frontier is
+ * rejected). Without a posMap (ctx_trim_fold against a stale capture) only
+ * structural checks and exact-duplicate guards apply.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { dshHome } from "../lib/dsh-home.js";
+import { estimateTokensOf, refPositions } from "./view.js";
+
+/** Current ledger file format version. */
+export const LEDGER_VERSION = 1;
+
+/** Filenames are session-id-derived; keep them filesystem-safe. */
+function sanitizeSessionId(sessionId) {
+	const raw = typeof sessionId === "string" && sessionId !== "" ? sessionId : "default";
+	// Percent-encode % and path separators FIRST so the mapping is injective
+	// ("a/b" and "a_b" must never share one ledger file).
+	const safe = Array.from(raw, (ch) => (ch === "%" ? "%25" : ch === "/" ? "%2F" : ch === "\\" ? "%5C" : ch)).join("").slice(0, 128);
+	return safe === "" ? "default" : safe;
+}
+
+/** Empty ledger for one session. frontier = ref of the newest folded
+ * message (the fold boundary); it only ever advances (monotonic). */
+export function emptyLedger(sessionId) {
+	return {
+		version: LEDGER_VERSION,
+		sessionId,
+		blocks: [],
+		frontier: null,
+		lastFoldViewTokens: 0,
+		lastFoldLowTokens: 0,
+		lastFoldAt: 0,
+		foldsThisHour: [],
+		// Fork-state inheritance marker (fork.js): set only when this ledger
+		// was cloned from a parent session — one inheritance per child.
+		inheritedFrom: null,
+		inheritedAt: 0,
+	};
+}
+
+/** Structural validation of a candidate block (refRange/count/summary).
+ * Returns the normalized block or null. */
+export function normalizeBlock(candidate, now) {
+	if (candidate === null || typeof candidate !== "object") return null;
+	const firstId = candidate.refRange?.firstId;
+	const lastId = candidate.refRange?.lastId;
+	if (typeof firstId !== "string" || firstId === "" || typeof lastId !== "string" || lastId === "") return null;
+	const summary = typeof candidate.summary === "string" ? candidate.summary.trim() : "";
+	if (summary === "") return null;
+	const count = Number.isInteger(candidate.count) && candidate.count > 0 ? candidate.count : 0;
+	if (count <= 0) return null;
+	const approxTokens = Number.isFinite(candidate.approxTokens) && candidate.approxTokens > 0 ? Math.round(candidate.approxTokens) : count;
+	const kind = candidate.kind === "mechanical" ? "mechanical" : "summary";
+	const tier = candidate.tier === "emergency" || candidate.tier === "pressure" || candidate.tier === "growth" || candidate.tier === "model" ? candidate.tier : "model";
+	return {
+		id: typeof candidate.id === "string" && candidate.id !== "" ? candidate.id : `b${now}`,
+		kind,
+		tier,
+		refRange: { firstId, lastId },
+		count,
+		approxTokens,
+		summary,
+		createdAt: now,
+	};
+}
+
+/** Create the ledger store. options: { stateDir?, warn? }. stateDir wins
+ * over the dshHome default; warn receives soft failures. */
+export function createStore(options = {}) {
+	const warn = typeof options.warn === "function" ? options.warn : () => {};
+	const stateDir = options.stateDir ?? join(dshHome(), ".dsh-switchman", "state", "trim");
+	const ledgers = new Map(); // sessionId -> ledger (loaded lazily)
+
+	function fileFor(sessionId) {
+		return join(stateDir, `${sanitizeSessionId(sessionId)}.json`);
+	}
+
+	/** Load one ledger (cached). Corrupt or unreadable files reset the
+	 * ledger and are moved aside (best effort) for forensics. */
+	function ledgerOf(sessionId) {
+		const cached = ledgers.get(sessionId);
+		if (cached !== undefined) return cached;
+		let ledger = emptyLedger(sessionId);
+		const file = fileFor(sessionId);
+		try {
+			if (existsSync(file)) {
+				const parsed = JSON.parse(readFileSync(file, "utf8"));
+				if (parsed !== null && typeof parsed === "object" && Array.isArray(parsed.blocks) && parsed.version === LEDGER_VERSION) {
+					ledger = {
+						version: LEDGER_VERSION,
+						sessionId,
+						blocks: parsed.blocks,
+						frontier: typeof parsed.frontier === "string" ? parsed.frontier : null,
+						lastFoldViewTokens: Number.isFinite(parsed.lastFoldViewTokens) ? parsed.lastFoldViewTokens : 0,
+						lastFoldLowTokens: Number.isFinite(parsed.lastFoldLowTokens) ? parsed.lastFoldLowTokens : 0,
+						lastFoldAt: Number.isFinite(parsed.lastFoldAt) ? parsed.lastFoldAt : 0,
+						foldsThisHour: Array.isArray(parsed.foldsThisHour) ? parsed.foldsThisHour.filter((ts) => Number.isFinite(ts)) : [],
+						inheritedFrom: typeof parsed.inheritedFrom === "string" ? parsed.inheritedFrom : null,
+						inheritedAt: Number.isFinite(parsed.inheritedAt) ? parsed.inheritedAt : 0,
+					};
+				} else {
+					warn(`[context-trim] ledger for ${sanitizeSessionId(sessionId)} has an unknown format — resetting`);
+					try {
+						renameSync(file, `${file}.corrupt`);
+					} catch {
+						/* best effort */
+					}
+				}
+			}
+		} catch (error) {
+			warn(`[context-trim] ledger load failed (${error?.message ?? error}) — resetting`);
+			ledger = emptyLedger(sessionId);
+			try {
+				renameSync(file, `${file}.corrupt`);
+			} catch {
+				/* best effort */
+			}
+		}
+		ledgers.set(sessionId, ledger);
+		return ledger;
+	}
+
+	/** Persist one ledger atomically (tmp + rename). */
+	function persist(ledger) {
+		try {
+			mkdirSync(stateDir, { recursive: true });
+			const file = fileFor(ledger.sessionId);
+			const tmp = `${file}.tmp`;
+			writeFileSync(tmp, JSON.stringify(ledger));
+			renameSync(tmp, file);
+			return true;
+		} catch (error) {
+			warn(`[context-trim] ledger persist failed (${error?.message ?? error})`);
+			return false;
+		}
+	}
+
+	/** Commit a fold block. posMap (refs -> indices of the CURRENT capture)
+	 * enables full validation; returns { ok, ledger, block } or
+	 * { ok: false, reason }. Memory only — persist() separately. */
+	function commitFold(sessionId, candidate, posMap = null, now = Date.now()) {
+		const block = normalizeBlock(candidate, now);
+		if (block === null) return { ok: false, reason: "invalid-block" };
+		const ledger = ledgerOf(sessionId);
+		// exact-duplicate guard (same range already folded)
+		for (const existing of ledger.blocks) {
+			if (existing.refRange.firstId === block.refRange.firstId && existing.refRange.lastId === block.refRange.lastId) {
+				return { ok: false, reason: "duplicate-range" };
+			}
+		}
+		if (posMap !== null) {
+			const positions = posMap instanceof Map ? posMap : refPositions(posMap);
+			const firstList = positions.get(block.refRange.firstId);
+			const lastList = positions.get(block.refRange.lastId);
+			if (firstList === undefined || lastList === undefined) return { ok: false, reason: "refs-not-found" };
+			// Content-addressed refs collide for duplicate messages, so one ref
+			// may map to many positions. Anchor the pair on block.count and
+			// search occurrences instead of trusting list extremes.
+			let firstIdx = -1;
+			let lastIdx = -1;
+			for (const start of firstList) {
+				const end = start + block.count - 1;
+				if (lastList.includes(end)) {
+					firstIdx = start;
+					lastIdx = end;
+					break;
+				}
+			}
+			if (firstIdx < 0) return { ok: false, reason: "count-mismatch" };
+			// monotonicity: the new range must sit strictly behind the
+			// frontier range and be disjoint from every existing block.
+			for (const existing of ledger.blocks) {
+				const eFirst = positions.get(existing.refRange.firstId);
+				const eLast = positions.get(existing.refRange.lastId);
+				if (eFirst === undefined || eLast === undefined) continue; // stale block outside this capture
+				const eStart = eFirst[0];
+				const eEnd = eLast[eLast.length - 1];
+				if (firstIdx <= eEnd && eStart <= lastIdx) return { ok: false, reason: "overlaps-existing-fold" };
+			}
+		}
+		ledger.blocks.push(block);
+		ledger.frontier = block.refRange.lastId;
+		ledger.lastFoldAt = now;
+		ledger.foldsThisHour = ledger.foldsThisHour.filter((ts) => now - ts < 3_600_000);
+		ledger.foldsThisHour.push(now);
+		ledgers.set(sessionId, ledger);
+		return { ok: true, ledger, block };
+	}
+
+	/** Adopt a fully-built ledger as one session's ledger (fork-state
+	 * inheritance, fork.js resolveInheritance). One-shot: refused when the
+	 * session already carries fold blocks or an inheritance marker — real
+	 * state is never overwritten. Caches AND persists; returns true when
+	 * adopted. */
+	function adoptLedger(sessionId, ledger) {
+		const current = ledgerOf(sessionId);
+		if ((Array.isArray(current.blocks) && current.blocks.length > 0) || current.inheritedFrom !== null) return false;
+		if (ledger === null || typeof ledger !== "object" || ledger.sessionId !== sessionId) return false;
+		ledgers.set(sessionId, ledger);
+		return persist(ledger);
+	}
+
+	/** Record the view-token estimate captured at the last fold (growth-gate
+	 * baseline) and persist. */
+	function recordFoldBaseline(sessionId, viewTokens, lowTokens) {
+		const ledger = ledgerOf(sessionId);
+		if (Number.isFinite(viewTokens) && viewTokens > 0) ledger.lastFoldViewTokens = Math.round(viewTokens);
+		if (Number.isFinite(lowTokens) && lowTokens > 0) ledger.lastFoldLowTokens = Math.round(lowTokens);
+		persist(ledger);
+		return ledger;
+	}
+
+	return { ledgerOf, commitFold, recordFoldBaseline, adoptLedger, persist, stateDir };
+}
+
+/** Test/inspection helper: estimated tokens of a ledger's folds. */
+export function ledgerFoldedTokens(messages, ledger) {
+	const positions = refPositions(messages);
+	let total = 0;
+	for (const block of ledger?.blocks ?? []) {
+		const firstList = positions.get(block.refRange?.firstId);
+		const lastList = positions.get(block.refRange?.lastId);
+		if (firstList === undefined || lastList === undefined) continue;
+		total += estimateTokensOf(messages, firstList[0], lastList[lastList.length - 1]);
+	}
+	return total;
+}

package/host/context-trim/summarizer.js

@@ -0,0 +1,179 @@
+/** dsh-switchman context-trim summarizer.
+ *
+ * Produces the summary text for one fold block, two ways:
+ *
+ * - summarizeWithModel — the L3 path (design §5): a side-model call via
+ *   llm.prepareCall + call.stream (receiver-bound on the llm service, the
+ *   same waterfall pattern intent classification uses). Guarded by a hard
+ *   deadline (AbortController); ANY failure (timeout, error chunk, empty
+ *   output) returns null and the caller skips the fold cycle — fail-open.
+ * - mechanicalSummary — the deterministic fallback used by the emergency
+ *   tier: structural heads of each message, no model round trip.
+ *
+ * The summary prompt carries the bili compression rules: message refs and
+ * file paths verbatim, decisions WITH rationale, exact values, open
+ * objectives carry forward, verbose logs drop.
+ */
+
+import { randomUUID } from "node:crypto";
+
+/** Default side-model summary deadline. Large increments legitimately
+ * take a while; the emergency tier does not wait on this path at all. */
+export const SUMMARY_TIMEOUT_MS = 120_000;
+
+/** Material cap: beyond this the render keeps head+tail and marks the cut
+ * (a 1M-token material would burn the side-model call for no fidelity). */
+export const MAX_MATERIAL_CHARS = 400_000;
+
+/** System prompt for the side-model summarizer. English per repo docs
+ * style; the OUTPUT language follows the summarized material. */
+export const SUMMARY_SYSTEM_PROMPT = [
+	"You compress one contiguous range of a coding-agent conversation into ONE self-contained plain-text summary that will replace that range permanently.",
+	"",
+	"KEEP VERBATIM:",
+	"- Full file paths with line numbers (lib/hooks.ts:347) — never bare filenames.",
+	"- Function/class/type signatures and the critical code line that encodes a finding.",
+	"- Error messages and stack-trace key lines (exact text).",
+	"- Exact values: versions, config keys, thresholds, magic numbers.",
+	"- Decisions WITH their rationale (the because is load-bearing).",
+	"- Open objectives, unresolved TODOs, and open questions, each tagged with its message ref.",
+	"",
+	"DROP (keep one line of lesson for failures): verbose logs once the error line is captured, repeated file reads, dead-end exploration details, back-and-forth discussion once the outcome is recorded.",
+	"",
+	"FORMAT:",
+	"- Dense bullets, short thematic headers; no narrative prose.",
+	"- Reference messages as [m<ref>] using the refs in the material.",
+	"- Write the summary in the same language as the material.",
+	"- Output ONLY the summary text.",
+].join("\n");
+
+/** Render the fold material for one message range: labeled, ref-stamped
+ * blocks. Deterministic (same slice, same bytes) — refs come from refOf so
+ * id-less messages stay stable across re-sends. */
+export function renderMaterial(messages, startIdx, endIdx, refOf) {
+	const parts = [];
+	let chars = 0;
+	let truncated = false;
+	for (let i = startIdx; i <= endIdx; i++) {
+		const message = messages[i];
+		const ref = refOf(message, i);
+		const role = typeof message?.role === "string" ? message.role : "unknown";
+		let text;
+		const content = message?.content;
+		if (typeof content === "string") text = content;
+		else if (Array.isArray(content)) {
+			const chunks = [];
+			for (const block of content) {
+				if (block !== null && typeof block === "object" && typeof block.text === "string") chunks.push(block.text);
+				else {
+					try {
+						chunks.push(JSON.stringify(block ?? null));
+					} catch {
+						chunks.push("[unserializable]");
+					}
+				}
+			}
+			text = chunks.join("\n");
+		} else {
+			try {
+				text = JSON.stringify(message ?? null);
+			} catch {
+				text = "[unserializable]";
+			}
+		}
+		if (Array.isArray(message?.tool_calls) && message.tool_calls.length > 0) {
+			try {
+				text += `\n[tool_calls] ${JSON.stringify(message.tool_calls)}`;
+			} catch {
+				/* keep the base text */
+			}
+		}
+		const head = `--- [m${ref}] (${role}) ---\n`;
+		const body = `${text}\n\n`;
+		if (chars + head.length + body.length > MAX_MATERIAL_CHARS) {
+			truncated = true;
+			break;
+		}
+		parts.push(head + body);
+		chars += head.length + body.length;
+	}
+	if (truncated) parts.push(`--- [...material truncated after ${chars} chars; ${endIdx - startIdx + 1 - (parts.length - 1)} messages dropped from this render...] ---\n`);
+	return parts.join("");
+}
+
+/** Emergency-tier mechanical summary: deterministic structural heads (no
+ * model call). One line per message: ref, role, first line (capped). */
+export function mechanicalSummary(messages, startIdx, endIdx, refOf) {
+	const lines = [`Mechanical fold of ${endIdx - startIdx + 1} messages (emergency tier; no model summary available).`, ""];
+	for (let i = startIdx; i <= endIdx; i++) {
+		const message = messages[i];
+		const ref = refOf(message, i);
+		const role = typeof message?.role === "string" ? message.role : "unknown";
+		const content = message?.content;
+		let firstLine = "";
+		if (typeof content === "string") firstLine = content;
+		else if (Array.isArray(content)) {
+			for (const block of content) {
+				if (block !== null && typeof block === "object" && typeof block.text === "string" && block.text.trim() !== "") {
+					firstLine = block.text;
+					break;
+				}
+			}
+		}
+		const line = firstLine.replace(/\s+/gu, " ").trim().slice(0, 160);
+		lines.push(`- [m${ref}] (${role}) ${line === "" ? "(no text content)" : line}`);
+	}
+	lines.push("", "Open objectives and exact details are NOT preserved by this mechanical fold; the next model-driven fold will supersede it.");
+	return lines.join("\n");
+}
+
+/** Side-model summary. llm: the dsh llm service (receiver-bound methods);
+ * route: { provider, model } | null (null → caller skips); materialText:
+ * renderMaterial output; deadlineMs: hard budget. Returns the summary
+ * text, or null on ANY failure (caller skips the fold cycle). */
+export async function summarizeWithModel(llm, route, materialText, options = {}) {
+	const fail = typeof options.onFail === "function" ? options.onFail : null;
+	if (route === null || route === undefined) { fail?.("no-route"); return null; }
+	if (typeof llm?.prepareCall !== "function") { fail?.("no-prepare-call"); return null; }
+	const deadlineMs = Number.isFinite(options.deadlineMs) && options.deadlineMs > 0 ? options.deadlineMs : SUMMARY_TIMEOUT_MS;
+	const maxTokens = Number.isFinite(options.maxTokens) && options.maxTokens > 0 ? options.maxTokens : 8_192;
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(new Error("trim summary deadline")), deadlineMs);
+	try {
+		const call = await llm.prepareCall(
+			{ provider: route.provider, model: route.model, maxTokens },
+			controller.signal,
+			(controls) => controls,
+		);
+		let text = "";
+			let finishKind = null;
+		// stream options MUST carry the prepared call config — the adapter
+		// dispatch binds credentials/routing from it (same waterfall shape as
+		// the intent classifier; dropping it fails prepare-time integrity).
+		// system rides as a top-level option and the user message carries a
+		// source tag, exactly like the intent classifier's proven shape.
+		const streamOptions = {
+			...call.config,
+			system: SUMMARY_SYSTEM_PROMPT,
+			messages: [
+				{ id: randomUUID(), role: "user", content: [{ type: "text", text: materialText }], source: { kind: "dsh-switchman-trim-summary" } },
+			],
+			signal: controller.signal,
+		};
+		for await (const chunk of call.stream(streamOptions)) {
+			if (chunk?.type === "text-delta" && typeof chunk.text === "string") text += chunk.text;
+			else if (chunk?.type === "finish") {
+				finishKind = chunk.kind ?? null;
+				if (chunk.kind === "error" || chunk.kind === "aborted") { fail?.(`stream-${chunk.kind}`); return null; }
+			}
+		}
+		const summary = text.trim();
+		if (summary === "") { fail?.(`empty-output finish=${finishKind ?? "none"}`); return null; }
+		return summary;
+	} catch (error) {
+		fail?.(`error: ${error?.message ?? error}`);
+		return null;
+	} finally {
+		clearTimeout(timer);
+	}
+}

package/host/context-trim/trigger.js

@@ -0,0 +1,122 @@
+/** dsh-switchman context-trim trigger tiers (pure decision logic).
+ *
+ * The trigger half of the port (design §4/§5): decides whether a fold
+ * should run NOW. Called only at idle boundaries (agent/status idle) —
+ * never inside llm/stream, never while a fold for the same session is in
+ * flight. Three tiers, checked emergency-first:
+ *
+ * - emergency  : view usage >= trimEmergencyPercent of the context window.
+ *                Forced MECHANICAL fold (no side-model round trip — at 95%
+ *                the session cannot afford the latency or the failure).
+ * - pressure   : view usage >= trimPressurePercent. Side-model fold.
+ * - growth     : growth since the last fold's post-fold low (the anchor
+ *                that keeps the gate armed after folds committing at high
+ *                view points) > trimGrowthTokens AND the contiguous
+ *                compressible increment >= trimIncrementTokens. The
+ *                primary, cache-friendly gate (the bili heuristic).
+ *
+ * Side-model folds are additionally throttled by trimMaxFoldsPerHour and a
+ * hard minimum interval between folds; emergency folds have their own
+ * cooldown so a stuck-at-95% session folds at most once per window.
+ * Everything is derived from measured inputs — no clock, no host access —
+ * which keeps the decision unit-testable (golden thresholds).
+ */
+
+import { estimateTokensOf, refPositions, segmentBounds } from "./view.js";
+
+/** Hard minimum wall-clock interval between side-model folds. */
+export const FOLD_MIN_INTERVAL_MS = 60_000;
+
+/** Minimum interval between emergency (mechanical) folds. */
+export const EMERGENCY_COOLDOWN_MS = 90_000;
+
+/** The foldable span of a captured messages array for one ledger: from the
+ * first segment boundary strictly after the frontier to the last segment
+ * end that still clears the protected tail. Returns { startIdx, endIdx }
+ * or null when nothing is foldable (empty history, everything folded, or
+ * protected tail covers it all). */
+export function computeFoldableRange(messages, ledger, protectedTail) {
+	if (!Array.isArray(messages) || messages.length === 0) return null;
+	const tail = Number.isInteger(protectedTail) && protectedTail > 0 ? protectedTail : 0;
+	const tailStart = messages.length - tail;
+	if (tailStart <= 0) return null;
+	// first candidate segment start: strictly after the frontier message
+	let startFrom = 0;
+	if (typeof ledger?.frontier === "string" && ledger.frontier !== "") {
+		const positions = refPositions(messages);
+		const list = positions.get(ledger.frontier);
+		if (list !== undefined && list.length > 0) startFrom = list[list.length - 1] + 1;
+	}
+	let best = null;
+	for (const [start, end] of segmentBounds(messages)) {
+		if (start < startFrom) continue; // behind the frontier
+		if (end >= tailStart) break; // segment would cut into the protected tail
+		if (best === null) best = { startIdx: start, endIdx: end };
+		else best.endIdx = end; // extend the contiguous span
+	}
+	return best;
+}
+
+/** Evaluate the trigger. input: {
+ *   foldable: { startIdx, endIdx } | null,  // computeFoldableRange result
+ *   messages,        // captured raw messages (increment measurement)
+ *   viewTokens,      // outbound-view token estimate of the current history
+ *   windowTokens,    // context window size, or null when unknown
+ *   thresholds: { growthTokens, incrementTokens, pressurePercent, emergencyPercent, maxFoldsPerHour },
+ *   now, lastFoldAt, foldsThisHour, lastEmergencyAt,
+ * }.
+ * Returns { action: "none"|"fold"|"emergency", tier, reason, startIdx, endIdx, incrementTokens }. */
+export function evaluateTrigger(input) {
+	const none = { action: "none", tier: null, reason: "", startIdx: -1, endIdx: -1, incrementTokens: 0 };
+	const foldable = input?.foldable ?? null;
+	if (foldable === null) return { ...none, reason: "nothing-foldable" };
+	const { startIdx, endIdx } = foldable;
+	const thresholds = input?.thresholds ?? {};
+	const now = Number.isFinite(input?.now) ? input.now : Date.now();
+	const incrementTokens = estimateTokensOf(input?.messages ?? [], startIdx, endIdx);
+	if (incrementTokens < 1) return { ...none, reason: "empty-increment" };
+
+	// Tier c — emergency: window pressure, mechanical, cooldown-gated.
+	const windowTokens = Number.isFinite(input?.windowTokens) && input.windowTokens > 0 ? input.windowTokens : null;
+	const emergencyPercent = Number.isFinite(thresholds.emergencyPercent) && thresholds.emergencyPercent > 0 ? thresholds.emergencyPercent : 95;
+	if (windowTokens !== null) {
+		const usagePct = (input.viewTokens / windowTokens) * 100;
+		if (usagePct >= emergencyPercent) {
+			const lastEmergencyAt = Number.isFinite(input?.lastEmergencyAt) ? input.lastEmergencyAt : 0;
+			if (now - lastEmergencyAt < EMERGENCY_COOLDOWN_MS) return { ...none, reason: "emergency-cooldown" };
+			return { action: "emergency", tier: "emergency", reason: `usage ${usagePct.toFixed(1)}% >= ${emergencyPercent}%`, startIdx, endIdx, incrementTokens };
+		}
+	}
+
+	// Side-model folds (pressure + growth) share the cadence gates.
+	const lastFoldAt = Number.isFinite(input?.lastFoldAt) ? input.lastFoldAt : 0;
+	const hourly = Array.isArray(input?.foldsThisHour) ? input.foldsThisHour.filter((ts) => now - ts < 3_600_000).length : 0;
+	const maxFoldsPerHour = Number.isInteger(thresholds.maxFoldsPerHour) && thresholds.maxFoldsPerHour > 0 ? thresholds.maxFoldsPerHour : 6;
+	if (hourly >= maxFoldsPerHour) return { ...none, reason: "hourly-cap" };
+	if (now - lastFoldAt < FOLD_MIN_INTERVAL_MS) return { ...none, reason: "min-interval" };
+
+	// Tier b — pressure: soft window threshold, side-model.
+	const pressurePercent = Number.isFinite(thresholds.pressurePercent) && thresholds.pressurePercent > 0 ? thresholds.pressurePercent : 60;
+	if (windowTokens !== null) {
+		const usagePct = (input.viewTokens / windowTokens) * 100;
+		if (usagePct >= pressurePercent) {
+			return { action: "fold", tier: "pressure", reason: `usage ${usagePct.toFixed(1)}% >= ${pressurePercent}%`, startIdx, endIdx, incrementTokens };
+		}
+	}
+
+	// Tier a — growth gate: the primary cache-friendly heuristic.
+	const growthTokens = Number.isFinite(thresholds.growthTokens) && thresholds.growthTokens > 0 ? thresholds.growthTokens : 22_500;
+	const incrementGate = Number.isFinite(thresholds.incrementTokens) && thresholds.incrementTokens > 0 ? thresholds.incrementTokens : 50_000;
+	// Growth anchor: the post-fold low when known (keeps the gate armed
+	// after folds that commit at high view points), else the pre-fold
+	// view for ledgers written before lastFoldLowTokens existed.
+	const anchor = Number.isFinite(input?.ledger?.lastFoldLowTokens) && input.ledger.lastFoldLowTokens > 0
+		? input.ledger.lastFoldLowTokens
+		: Number.isFinite(input?.ledger?.lastFoldViewTokens) ? input.ledger.lastFoldViewTokens : 0;
+	const growth = input.viewTokens - anchor;
+	if (growth > growthTokens && incrementTokens >= incrementGate) {
+		return { action: "fold", tier: "growth", reason: `growth ~${Math.round(growth)} > ${growthTokens} and increment ~${incrementTokens} >= ${incrementGate}`, startIdx, endIdx, incrementTokens };
+	}
+
+	return { ...none, reason: "below-thresholds" };
+}