@iowarp/clio-coder 0.3.2 → 0.3.4

package/src/domains/context/working-set/payload.ts

@@ -0,0 +1,152 @@
+/**
+ * Readers for the two message payload shapes the working set acts on:
+ * `tool_result` (whose body is replaced by a marker) and `assistant` (whose
+ * thinking blocks are dropped).
+ *
+ * These deliberately mirror the private helpers in
+ * `src/domains/session/compaction/mask-observations.ts`. That module is the
+ * destructive stage this layer replaces and it goes away once the legacy path
+ * is retired, so the working set carries its own copy rather than importing
+ * from a module scheduled for deletion. The shapes themselves are not this
+ * layer's invention: `turn-persistence.ts` writes
+ * `{ toolCallId, toolName, result, isError, resultSummary }`, and `result` is
+ * whatever the tool returned, usually `{ content: [...], details: {...} }`.
+ */
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+export interface ToolResultPayload {
+	/** The payload object itself, or a synthetic wrapper when the payload is a bare value. */
+	obj: Record<string, unknown>;
+	/** The tool's own result value, wherever the payload put it. */
+	result: unknown;
+	toolName: string;
+}
+
+export function toolResultPayload(payload: unknown): ToolResultPayload {
+	const obj = isRecord(payload) ? payload : { result: payload };
+	const result = obj.result ?? obj.output ?? obj.out ?? obj.content ?? payload;
+	const toolName =
+		(typeof obj.toolName === "string" && obj.toolName) ||
+		(typeof obj.name === "string" && obj.name) ||
+		(typeof obj.tool === "string" && obj.tool) ||
+		"tool";
+	return { obj, result, toolName };
+}
+
+function textFromContent(content: unknown): string {
+	if (!Array.isArray(content)) return "";
+	const parts: string[] = [];
+	for (const block of content) {
+		if (!isRecord(block)) continue;
+		if (block.type === "text" && typeof block.text === "string") parts.push(block.text);
+	}
+	return parts.join("");
+}
+
+function stringifyBody(value: unknown): string {
+	if (value === undefined || value === null) return "";
+	if (typeof value === "string") return value;
+	try {
+		return JSON.stringify(value) ?? "";
+	} catch {
+		return String(value);
+	}
+}
+
+/** The displayed body of a tool result: content text first, then the legacy single-field shapes. */
+export function toolResultText(result: unknown): string {
+	if (typeof result === "string") return result;
+	if (!isRecord(result)) return stringifyBody(result);
+	const contentText = textFromContent(result.content);
+	if (contentText.length > 0) return contentText;
+	if (typeof result.text === "string") return result.text;
+	if (typeof result.output === "string") return result.output;
+	if (typeof result.message === "string") return result.message;
+	return stringifyBody(result);
+}
+
+/**
+ * Estimated tokens of the body the marker would replace: the text the model
+ * reads, not the payload JSON. `details`, `resultSummary`, and the observation
+ * envelope never reach the model, so a floor measured on the whole payload
+ * would let a two-byte result with a fat envelope through and buy a marker
+ * longer than the body it replaced.
+ */
+export function toolResultBodyTokens(payload: unknown): number {
+	return Math.ceil(toolResultText(toolResultPayload(payload).result).length / 4);
+}
+
+function nestedRecord(parent: Record<string, unknown> | null, key: string): Record<string, unknown> | null {
+	if (parent === null) return null;
+	const value = parent[key];
+	return isRecord(value) ? value : null;
+}
+
+function stringField(record: Record<string, unknown> | null, key: string): string | undefined {
+	if (record === null) return undefined;
+	const value = record[key];
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+/**
+ * Scratch path holding the complete output, when the tool spilled one. Checked
+ * in the same order `toolResultSummary` writes it: the OBSERVE envelope, then
+ * bash-style result shaping, then the persisted summary that mirrors both.
+ */
+export function offloadPathOf(payload: ToolResultPayload): string | undefined {
+	const details = nestedRecord(isRecord(payload.result) ? payload.result : null, "details");
+	return (
+		stringField(nestedRecord(details, "resultDisposition"), "offloadPath") ??
+		stringField(nestedRecord(details, "observation"), "offloadPath") ??
+		stringField(nestedRecord(details, "resultSize"), "offloadPath") ??
+		stringField(nestedRecord(payload.obj, "resultSummary"), "offloadPath")
+	);
+}
+
+/**
+ * The one file this result was about, when the tool named exactly one.
+ * `edit`, `write`, and `artifact` record `details.paths`; a result naming
+ * several is left without a path rather than picking one arbitrarily. Read
+ * results carry no `paths`, so the marker falls back to the call's own
+ * argument (`callPathsByToolCallId` in path-index.ts).
+ */
+export function primaryPathOf(payload: ToolResultPayload): string | undefined {
+	const details = nestedRecord(isRecord(payload.result) ? payload.result : null, "details");
+	const paths = details?.paths;
+	if (!Array.isArray(paths) || paths.length !== 1) return undefined;
+	const first = paths[0];
+	return typeof first === "string" && first.length > 0 ? first : undefined;
+}
+
+function isThinkingBlock(block: unknown): boolean {
+	return isRecord(block) && block.type === "thinking";
+}
+
+/** Both shapes the ledger holds reasoning in: `thinking` content blocks and the payload-level string. */
+export function hasThinking(payload: unknown): boolean {
+	const obj = isRecord(payload) ? payload : null;
+	if (obj === null) return false;
+	if (Array.isArray(obj.content) && obj.content.some(isThinkingBlock)) return true;
+	return typeof obj.thinking === "string" && obj.thinking.length > 0;
+}
+
+export function withoutThinkingBlocks(content: unknown): unknown[] | undefined {
+	if (!Array.isArray(content)) return undefined;
+	return content.filter((block) => !isThinkingBlock(block));
+}
+
+/**
+ * True when an earlier destructive compaction run already replaced this body.
+ * Such a result has no body left to evict, and re-marking it would spend a
+ * marker on a marker. Mirrors `alreadyCompacted()` in mask-observations.ts.
+ */
+export function hasLegacyCompactionMarker(payload: unknown): boolean {
+	if (!isRecord(payload)) return false;
+	if (isRecord(payload.contextCompaction)) return true;
+	if (isRecord(nestedRecord(payload, "resultSummary")?.contextCompaction)) return true;
+	const result = payload.result ?? payload.output ?? payload.out;
+	return isRecord(nestedRecord(isRecord(result) ? result : null, "details")?.contextCompaction);
+}

package/src/domains/context/working-set/policies/age-horizon.ts

@@ -0,0 +1,55 @@
+/**
+ * `age-horizon`: today's selection, recorded instead of destroyed.
+ *
+ * The rule is exactly what `maskStaleObservations` applied before this layer
+ * existed. Every tool-result body older than the protected recent-turn horizon
+ * leaves the working set, and every assistant message older than the horizon
+ * loses its thinking blocks. Same turn-start definition, same cutoff, same
+ * skip conditions. The difference is that the bodies stay in the ledger and
+ * come back with `context(scope="recall", ref=...)`.
+ *
+ * It shipped as the default for one slice so the ledger could stop being
+ * rewritten without changing what the model saw; `structural-v1` is the default
+ * now and this policy stays as the recorded form of the old selection. It has
+ * no target stop on purpose: everything beyond the horizon leaves in one event,
+ * as the mask did, and `pressure.target` is ignored.
+ *
+ * Age is not a quality signal, which is the whole reason `structural-v1`
+ * exists: a file read twenty turns ago and never touched since is more useful
+ * than a directory listing from two turns ago. Nothing here scores candidates
+ * by size or recency beyond that ordering; the only token input is the
+ * `minEvictableTokens` floor, which protects low-yield bodies from churn.
+ */
+
+import type { EvictionCandidate, PolicyInput, WorkingSetPolicy } from "../contract.js";
+import { protectionCutoffIndex } from "../horizon.js";
+import { hasLegacyCompactionMarker, hasThinking, toolResultBodyTokens } from "../payload.js";
+
+export const ageHorizonPolicy: WorkingSetPolicy = {
+	id: "age-horizon",
+	select(input: PolicyInput): ReadonlyArray<EvictionCandidate> {
+		const { entries, view, settings } = input;
+		const cutoff = protectionCutoffIndex(entries, settings.protectLastTurns);
+		const candidates: EvictionCandidate[] = [];
+		// Newest-safe-first: the entry closest to the protection horizon is the
+		// least likely to be re-read, and a caller that stops early has then
+		// evicted the oldest nothing and the newest something.
+		for (let i = cutoff - 1; i >= 0; i -= 1) {
+			const entry = entries[i];
+			if (entry === undefined || entry.kind !== "message") continue;
+			if (view.evicted.has(entry.turnId)) continue;
+			if (entry.role === "tool_result") {
+				if (hasLegacyCompactionMarker(entry.payload)) continue;
+				if (toolResultBodyTokens(entry.payload) < settings.minEvictableTokens) continue;
+				candidates.push({ ref: { entry: entry.turnId }, reason: "age_horizon" });
+				continue;
+			}
+			// Thinking has no size floor: dropping it costs no marker, so even a
+			// short stretch of reasoning is free to remove.
+			if (entry.role === "assistant" && hasThinking(entry.payload)) {
+				candidates.push({ ref: { entry: entry.turnId }, reason: "thinking_turn_closed" });
+			}
+		}
+		return candidates;
+	},
+};

package/src/domains/context/working-set/policies/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Policy registry. One id in, one pure policy out, so the live engine and the
+ * replay-lite runner resolve the same object from the same settings value and
+ * cannot drift into running different selections.
+ *
+ * `structural-v1` is the default; the replay tables under
+ * benchmarks/results/context-replay/ put it ahead of `age-horizon` on
+ * retention and ahead of the random control on precision. `age-horizon` stays
+ * resolvable as the exact pre-layer selection.
+ */
+
+import type { WorkingSetPolicy, WorkingSetPolicyId } from "../contract.js";
+import { ageHorizonPolicy } from "./age-horizon.js";
+import { structuralPolicy } from "./structural.js";
+
+export { ageHorizonPolicy, structuralPolicy };
+
+export function resolveWorkingSetPolicy(id: WorkingSetPolicyId): WorkingSetPolicy {
+	if (id === "age-horizon") return ageHorizonPolicy;
+	return structuralPolicy;
+}

package/src/domains/context/working-set/policies/structural.ts

@@ -0,0 +1,160 @@
+/**
+ * `structural-v1`: evict what the session has structurally finished with.
+ *
+ * The age rule asks how old a result is. This one asks what happened to it
+ * since: was the file rewritten, did a later read cover the same lines, did the
+ * failure get resolved, has the listing been walked. Those are facts the ledger
+ * already records, and they are the facts a human would use to decide what is
+ * still worth carrying. Age is the last rung, not the first, and it only runs
+ * when the structural rungs did not free enough.
+ *
+ * Rule order is the policy. Each rung emits candidates newest-first, every
+ * candidate passes `isProtected`, and no unit is claimed twice, so a read that
+ * is both stale and superseded is evicted for the reason that came first and
+ * carries the ref that explains it. Rungs 1 to 5 are unconditional: redundant
+ * content is free to drop, whatever the pressure. Rung 6 is the only one that
+ * looks at token counts, and it stops the moment the projection reaches
+ * `target`.
+ *
+ * Deterministic by construction: the index is a pure function of the entries,
+ * every loop runs in index order, and nothing here reads a clock, a size
+ * ranking, or a recency score.
+ */
+
+import type { EvictionCandidate, EvictionReason, PolicyInput, WorkingSetPolicy } from "../contract.js";
+import { tokensFreedByEviction } from "../engine.js";
+import { protectionCutoffIndex } from "../horizon.js";
+import { buildPathIndex, callPathsByToolCallId, covers, type PathIndex, type PathObservation } from "../path-index.js";
+import { hasThinking } from "../payload.js";
+import { findLaterSuccess, isProtected } from "../protect.js";
+
+/** Ops that observe content rather than change it. */
+const READ_CLASS = new Set<PathObservation["op"]>(["read", "grep", "find", "ls", "code_nav"]);
+const MUTATING = new Set<PathObservation["op"]>(["write", "edit"]);
+
+/**
+ * The mutation that invalidated this observation: the first successful one
+ * after it. A failed edit (`oldText not found`, permission denied) changed
+ * nothing, and the read it was aimed at is exactly what the model needs to fix
+ * the edit.
+ */
+function firstMutationAfter(observation: PathObservation, index: PathIndex): PathObservation | null {
+	for (const other of index.byPath.get(observation.path) ?? []) {
+		if (other.entryIndex > observation.entryIndex && MUTATING.has(other.op) && !other.isError) return other;
+	}
+	return null;
+}
+
+/** The most recent later read of the same file that covers this one's lines. */
+function lastCoveringRead(observation: PathObservation, index: PathIndex): PathObservation | null {
+	let found: PathObservation | null = null;
+	for (const other of index.byPath.get(observation.path) ?? []) {
+		if (other.entryIndex <= observation.entryIndex || other.op !== "read" || other.isError) continue;
+		if (covers(other.range, observation.range)) found = other;
+	}
+	return found;
+}
+
+/** Every surfaced path went on to be read. A path nobody read is an unread path. */
+function isListingConsumed(observation: PathObservation, index: PathIndex): boolean {
+	if (observation.surfaced.length === 0) return false;
+	for (const path of observation.surfaced) {
+		const readLater = (index.byPath.get(path) ?? []).some(
+			(other) => other.op === "read" && !other.isError && other.entryIndex > observation.entryIndex,
+		);
+		if (!readLater) return false;
+	}
+	return true;
+}
+
+export const structuralPolicy: WorkingSetPolicy = {
+	id: "structural-v1",
+	select(input: PolicyInput): ReadonlyArray<EvictionCandidate> {
+		const { entries, view, settings, pressure, estimateTokens } = input;
+		const index = buildPathIndex(entries, { cwd: input.cwd });
+		const callPaths = callPathsByToolCallId(entries);
+		const cutoffIndex = protectionCutoffIndex(entries, settings.protectLastTurns);
+		const candidates: EvictionCandidate[] = [];
+		const claimed = new Set<string>();
+		let freed = 0;
+
+		const entryIndexOf = new Map<string, number>();
+		for (let i = 0; i < entries.length; i += 1) {
+			const entry = entries[i];
+			if (entry !== undefined) entryIndexOf.set(entry.turnId, i);
+		}
+
+		const emit = (turnId: string, reason: EvictionReason, by?: string): boolean => {
+			if (claimed.has(turnId) || view.evicted.has(turnId)) return false;
+			const entryIndex = entryIndexOf.get(turnId);
+			if (entryIndex === undefined) return false;
+			const entry = entries[entryIndex];
+			if (entry === undefined) return false;
+			if (isProtected(entry, { entryIndex, cutoffIndex, input, index })) return false;
+			const candidate: EvictionCandidate = { ref: { entry: turnId }, reason, ...(by === undefined ? {} : { by }) };
+			claimed.add(turnId);
+			candidates.push(candidate);
+			freed += tokensFreedByEviction(estimateTokens, entry, candidate, callPaths);
+			return true;
+		};
+
+		// Newest-first within every rung, for the cost reason in charter 4.6:
+		// evicting the youngest safe unit keeps the cold region after the
+		// eviction point small, so the turn that pays for the event pays least.
+		const newestFirst = [...index.observations].reverse();
+
+		// 1. The file changed under it. Whatever the body said is now a claim
+		//    about a file that no longer exists in that form.
+		for (const observation of newestFirst) {
+			if (!READ_CLASS.has(observation.op) || observation.path.length === 0) continue;
+			const mutation = firstMutationAfter(observation, index);
+			if (mutation !== null) emit(observation.ref.entry, "stale_after_mutation", mutation.ref.entry);
+		}
+
+		// 2. The agent asked for the same lines again. It already decided this
+		//    content was worth re-fetching, and the newer copy is the live one.
+		for (const observation of newestFirst) {
+			if (observation.op !== "read" || observation.path.length === 0) continue;
+			const superseding = lastCoveringRead(observation, index);
+			if (superseding !== null) emit(observation.ref.entry, "superseded_read", superseding.ref.entry);
+		}
+
+		// 3. The failure was resolved. The marker keeps its first line, because
+		//    a failure that happened is evidence even once it is fixed.
+		for (const observation of newestFirst) {
+			if (!observation.isError) continue;
+			const success = findLaterSuccess(observation, index);
+			if (success !== null) emit(observation.ref.entry, "failure_resolved", success.ref.entry);
+		}
+
+		// 4. The listing has been walked. One surfaced path still unread and it
+		//    stays: that is the path the agent comes back to.
+		for (const observation of newestFirst) {
+			if (isListingConsumed(observation, index)) emit(observation.ref.entry, "listing_consumed");
+		}
+
+		// 5. Reasoning from a closed turn, the same rule age-horizon applies.
+		for (let i = cutoffIndex - 1; i >= 0; i -= 1) {
+			const entry = entries[i];
+			if (entry?.kind !== "message" || entry.role !== "assistant") continue;
+			if (hasThinking(entry.payload)) emit(entry.turnId, "thinking_turn_closed");
+		}
+
+		// 6. Age, and only under pressure. Everything above is redundancy the
+		//    session can lose for free; this rung loses content that is still
+		//    good, so it runs only when the projection is still over threshold
+		//    and stops the moment it reaches target.
+		const window = pressure.contextWindow;
+		if (window <= 0) return candidates;
+		let projected = pressure.tokens - freed;
+		if (projected <= pressure.threshold * window) return candidates;
+		const targetTokens = pressure.target * window;
+		for (let i = cutoffIndex - 1; i >= 0 && projected > targetTokens; i -= 1) {
+			const entry = entries[i];
+			if (entry?.kind !== "message" || entry.role !== "tool_result") continue;
+			const before = freed;
+			if (emit(entry.turnId, "age_horizon")) projected -= freed - before;
+		}
+		return candidates;
+	},
+};

package/src/domains/context/working-set/project.ts

@@ -0,0 +1,132 @@
+/**
+ * Apply a `WorkingSetView` to a ledger slice as an in-memory projection.
+ *
+ * This is the whole point of the layer: the ledger keeps every byte the tools
+ * produced, and the model sees a narrower view of it. Nothing here writes, and
+ * nothing here decides what leaves; `fold.ts` says what is out and this module
+ * renders that decision onto the entries the replay builder consumes.
+ *
+ * Pure and idempotent. Projecting an already-projected slice reproduces it
+ * byte for byte, because the marker comes from the ledger entry rather than
+ * from the body being replaced. Entries the view does not name are returned by
+ * reference, and a named entry is a shallow copy with a new payload: nothing
+ * below the payload is ever mutated, so a deep clone of the body about to be
+ * replaced would only cost the pricing loop the body's size.
+ *
+ * Callers may pass raw ledger entries: only entries whose `turnId` is a key in
+ * `view.evicted` change, and the view was already narrowed to the active path
+ * by the fold, so an eviction recorded on an abandoned branch cannot reach a
+ * live one (issue #94).
+ */
+
+import type { MessageEntry, SessionEntry } from "../../session/entries.js";
+import type { EvictedState, WorkingSetView } from "./contract.js";
+import { hasThinking, isRecord, toolResultPayload, withoutThinkingBlocks } from "./payload.js";
+
+/**
+ * Replace the observation body with its marker. Tool pairing (`toolCallId`,
+ * `toolName`) and `details` survive untouched, so replay still matches the
+ * result to its call and the renderer still knows what the call was; only the
+ * text the model reads changes. The `workingSet` stamp on `details` is how a
+ * reader tells a marker from a genuinely tiny tool result.
+ */
+function projectToolResult(entry: MessageEntry, state: EvictedState): MessageEntry {
+	const next = { ...entry };
+	const { obj, result } = toolResultPayload(next.payload);
+	const details = isRecord(result) && isRecord(result.details) ? result.details : {};
+	next.payload = {
+		...obj,
+		result: {
+			content: [{ type: "text", text: state.marker }],
+			details: {
+				...details,
+				workingSet: { evicted: true, reason: state.reason, ref: entry.turnId },
+			},
+		},
+		output: undefined,
+		out: undefined,
+		content: undefined,
+	};
+	return next;
+}
+
+/**
+ * Drop reasoning from a closed turn. No marker replaces it: thinking is
+ * model-internal, the Anthropic API discards it after every turn anyway, and a
+ * marker would spend tokens to say that something the model cannot act on is
+ * gone. Both persisted shapes go: `thinking` content blocks and the
+ * payload-level string the local engine adapters write.
+ *
+ * A turn that was nothing but reasoning keeps it. Projected, it would reach
+ * the provider as an assistant message with no content, or vanish from the
+ * replay and leave two user messages adjacent; either is worse than the
+ * tokens. `planEviction` then prices such a turn at zero and records nothing.
+ */
+function projectAssistant(entry: MessageEntry): MessageEntry {
+	const obj = isRecord(entry.payload) ? entry.payload : null;
+	if (obj === null || !hasThinking(obj)) return entry;
+	const content = withoutThinkingBlocks(obj.content);
+	if (!hasVisibleContent(obj, content)) return entry;
+	const next = { ...entry };
+	next.payload = {
+		...obj,
+		...(content !== undefined ? { content } : {}),
+		thinking: undefined,
+	};
+	return next;
+}
+
+/** What the replay builder would still send: a payload-level text or at least one surviving block. */
+function hasVisibleContent(obj: Record<string, unknown>, content: unknown[] | undefined): boolean {
+	if (typeof obj.text === "string" && obj.text.length > 0) return true;
+	return content !== undefined && content.length > 0;
+}
+
+/**
+ * Usage recorded before the projection existed described a longer prompt than
+ * the model will now receive. `calculateContextTokens` anchors on the newest
+ * assistant usage it trusts, so leaving those anchors in place would report the
+ * pre-eviction size forever and the pressure estimator would never see the
+ * space the eviction freed. Mirrors `invalidateUsage()` in
+ * mask-observations.ts, bounded to the entries that precede the event.
+ */
+function invalidateUsage(entry: SessionEntry): SessionEntry {
+	if (entry.kind !== "message" || entry.role !== "assistant") return entry;
+	const obj = isRecord(entry.payload) ? entry.payload : null;
+	if (obj === null || obj.contextUsageInvalidated === true) return entry;
+	const next = { ...entry };
+	next.payload = { ...obj, contextUsageInvalidated: true };
+	return next;
+}
+
+/**
+ * Index of the newest eviction event within this slice. An event the slice does
+ * not contain (a caller that truncated before it) is treated as later than
+ * everything here: every usage anchor in the slice predates the projection.
+ */
+function eventIndex(entries: ReadonlyArray<SessionEntry>, lastEvictionTurnId: string | null): number {
+	if (lastEvictionTurnId === null) return entries.length;
+	const index = entries.findIndex((entry) => entry.turnId === lastEvictionTurnId);
+	return index < 0 ? entries.length : index;
+}
+
+export function projectWorkingSet(entries: ReadonlyArray<SessionEntry>, view: WorkingSetView): SessionEntry[] {
+	if (view.evicted.size === 0 && view.evictionEvents === 0) return [...entries];
+	const cutoff = view.evictionEvents > 0 ? eventIndex(entries, view.lastEvictionTurnId) : -1;
+	const out: SessionEntry[] = [];
+	for (let index = 0; index < entries.length; index += 1) {
+		const entry = entries[index];
+		if (entry === undefined) continue;
+		let next = entry;
+		if (entry.kind === "message") {
+			const state = view.evicted.get(entry.turnId);
+			if (state !== undefined) {
+				if (entry.role === "tool_result") next = projectToolResult(entry, state);
+				else if (entry.role === "assistant") next = projectAssistant(entry);
+			}
+		}
+		if (index < cutoff) next = invalidateUsage(next);
+		out.push(next);
+	}
+	return out;
+}

package/src/domains/context/working-set/protect.ts

@@ -0,0 +1,109 @@
+/**
+ * Protection predicates: what the working set never gives up, whatever a rule
+ * concludes.
+ *
+ * These run before every rule and are absolute. A policy is allowed to be
+ * wrong about relevance (that is what the replay table measures); it is not
+ * allowed to drop the operator's words, the last few turns of work, a failure
+ * nobody has resolved, or a mutation the current turn is still standing on.
+ * Charter 4.5 lists them; this module is that list, and `structural.ts` calls
+ * it on every candidate rather than reimplementing any of it.
+ *
+ * Pure over the entry, the index, and the policy input.
+ */
+
+import type { SessionEntry } from "../../session/entries.js";
+import type { PolicyInput } from "./contract.js";
+import type { PathIndex, PathObservation } from "./path-index.js";
+import { hasLegacyCompactionMarker, isRecord, toolResultBodyTokens } from "./payload.js";
+
+export interface ProtectionContext {
+	entryIndex: number;
+	/** First entry of the protected recent window, from `protectionCutoffIndex`. */
+	cutoffIndex: number;
+	input: PolicyInput;
+	index: PathIndex;
+}
+
+/** Ops whose identity is the file they touched, so a retry on the same path counts as the same call. */
+const PATH_IDENTIFIED_OPS = new Set(["read", "grep", "find"]);
+
+function isBlockedResult(payload: unknown): boolean {
+	if (!isRecord(payload)) return false;
+	// The registry's admission verdict, persisted by turn-persistence. A call
+	// the safety rails refused is a decision the session made, not an
+	// observation it can re-fetch.
+	return payload.outcome === "blocked" || typeof payload.blockReason === "string";
+}
+
+function isErrorResult(payload: unknown): boolean {
+	if (!isRecord(payload)) return false;
+	return payload.isError === true || payload.error === true;
+}
+
+/**
+ * The later call that resolved this failure: same tool with byte-identical
+ * arguments, or, for the path-identified ops, the same file by any route. Null
+ * when nothing after it succeeded, which is what keeps the failure protected.
+ * A refused call is not a success: the safety rails returned a verdict, not
+ * the observation the failure was trying to make.
+ *
+ * Shared with `structural.ts` rung 3 on purpose: the rule that evicts a
+ * resolved failure and the predicate that protects an unresolved one must
+ * answer the same question, or a failure could be both.
+ */
+export function findLaterSuccess(observation: PathObservation, index: PathIndex): PathObservation | null {
+	for (const candidate of index.observations) {
+		if (candidate.entryIndex <= observation.entryIndex || candidate.isError || candidate.isBlocked) continue;
+		if (candidate.toolName === observation.toolName && observation.argsKey.length > 0) {
+			if (candidate.argsKey === observation.argsKey) return candidate;
+		}
+		if (
+			PATH_IDENTIFIED_OPS.has(observation.op) &&
+			candidate.op === observation.op &&
+			observation.path.length > 0 &&
+			candidate.path === observation.path
+		) {
+			return candidate;
+		}
+	}
+	return null;
+}
+
+/** A write or edit the turn in flight is still standing on. */
+function isActiveTurnMutation(observation: PathObservation, index: PathIndex): boolean {
+	if (observation.op !== "write" && observation.op !== "edit") return false;
+	return observation.turnIndex >= index.turnCount;
+}
+
+export function isProtected(entry: SessionEntry, ctx: ProtectionContext): boolean {
+	// Only two things ever leave the working set: a tool result's body and an
+	// assistant turn's thinking. Everything else (operator words, summaries,
+	// skill activations, ledgers, worker runs, bash executions) is the session's
+	// own record of itself.
+	if (entry.kind !== "message") return true;
+	if (entry.role !== "tool_result" && entry.role !== "assistant") return true;
+
+	// The recent window is untouchable for both kinds.
+	if (ctx.entryIndex >= ctx.cutoffIndex) return true;
+	if (entry.role === "assistant") return false;
+
+	// The floor protects low-yield bodies from churn. The engine separately
+	// rejects any candidate whose marker would free zero or negative tokens, so
+	// this setting may stay above the literal marker break-even point. The floor
+	// is the body's size, not the payload's: details never reach the model.
+	if (toolResultBodyTokens(entry.payload) < ctx.input.settings.minEvictableTokens) return true;
+	// A body the legacy destructive stage already replaced has nothing left to evict.
+	if (hasLegacyCompactionMarker(entry.payload)) return true;
+	if (isBlockedResult(entry.payload)) return true;
+
+	const observation = ctx.index.byRef.get(entry.turnId);
+	// No observation means no way to ask whether a failure was resolved, so an
+	// unindexed failure stays. Everything else unindexed is an ordinary result
+	// the age rung may still take under pressure.
+	if (observation === undefined) return isErrorResult(entry.payload);
+
+	if (isActiveTurnMutation(observation, ctx.index)) return true;
+	if (observation.isError && findLaterSuccess(observation, ctx.index) === null) return true;
+	return false;
+}