@namzu/sdk 39.0.0 → 40.0.0

package/src/runtime/query/file-evidence-replay.ts

@@ -0,0 +1,776 @@
+import { resolve } from 'node:path'
+import { isClearedToolResult } from '../../compaction/tool-result-editing.js'
+import { replayEditCallWithin } from '../../tools/builtins/edit-apply.js'
+import { EditTool } from '../../tools/builtins/edit.js'
+import { ReadFileTool } from '../../tools/builtins/read-file.js'
+import {
+	type ReadWindowRequest,
+	renderNumberedRead,
+	resolveReadWindow,
+} from '../../tools/builtins/read-render.js'
+import { WriteFileTool } from '../../tools/builtins/write-file.js'
+import type { Message, ToolCall } from '../../types/message/index.js'
+import type { FileReadTracker } from '../../types/tool/index.js'
+import { isSkippedToolResult } from './plugin-hooks.js'
+
+/**
+ * Reconstructing a file's body from calls the conversation can still see.
+ *
+ * One module because two callers need the same answer and must not each have
+ * their own idea of it: the derived work context asks "is this ledger entry's
+ * body one the model can rebuild from what is in front of it?", and the resume
+ * seed asks "which of these ledger entries can be rebuilt at all?". A
+ * predicate that admitted a hop in one and refused it in the other would mean
+ * a path referenced as evidence that the ledger never witnessed, or the
+ * reverse. Everything below is a function of the messages, the ledger and the
+ * bounds — there is no filesystem access anywhere in this file.
+ */
+
+/**
+ * Edit CALLS one chain may carry before the path is withheld.
+ *
+ * On calls rather than replacements because the bound is on replay work, and
+ * an `edits: [...]` batch is one pass over the content however many hunks it
+ * holds. Eight is generous for the shape this exists for — a file written and
+ * then refined within a turn — and short enough that the whole request's
+ * replay stays a rounding error beside the model call it rides on.
+ */
+export const MAX_EDIT_CALLS = 8
+
+/**
+ * Content a replay may materialise across every path in one pass.
+ *
+ * Counted cumulatively in UTF-16 units — the measure the caps below and the
+ * step-context budget already use — and charged for the write body each chain
+ * starts from as well as every body an edit builds on top of it, because those
+ * are the strings actually built. Each operation is measured exactly against
+ * the content it is about to be applied to and refused before it is built, so
+ * a pass whose history is full of long chains it is going to refuse anyway
+ * cannot make itself slow proving that. A refusal is charged nothing: the body
+ * was never built, and the paths after it keep their room.
+ */
+export const MAX_REPLAYED_UNITS = 256 * 1024
+
+/**
+ * Arguments longer than a real tool call carries; past this the call is not
+ * read AS EVIDENCE.
+ *
+ * A bound on what may be BELIEVED, and on nothing else. The path such a call
+ * declares is still read, under no bound at all — see {@link declaredPath} —
+ * because a write too long to quote back is still a write that happened, and a
+ * pass that could not say WHICH file it happened to would have to abandon every
+ * other path in the conversation to stay honest.
+ */
+const MAX_ARGUMENT_UNITS = 32_000
+
+/** Call ids longer than any provider mints. */
+const MAX_CALL_ID_UNITS = 256
+
+/**
+ * Path lengths a `write` entry may go out with.
+ *
+ * Exported because `file-evidence-context.ts` puts the same bound on the
+ * spelling a `read` entry emits — a read is the other thing that puts a path
+ * in the work-context message, and the constant belongs to this module.
+ */
+export const MAX_PATH_UNITS = 512
+
+/**
+ * Arguments this module will not read as JSON at all, at any bound.
+ *
+ * {@link MAX_ARGUMENT_UNITS} governs what may be BELIEVED about a call, and
+ * deliberately leaves attribution unbounded so that one large `write` cannot
+ * cost a conversation every other witness in it. Unbounded is still not free:
+ * `JSON.parse` over a multi-megabyte body is real work, and it was being done
+ * up to three times for one call — once to collect the paths, once to key the
+ * mutation, once to read the call as evidence. Two of those are gone: the
+ * attribution answer is now memoised for the whole pass (see
+ * {@link PathAttributions}), and the evidence read never reaches a call past
+ * the far smaller bound above. What is left is this ceiling on the single
+ * remaining parse.
+ *
+ * About a megabyte, some thirty times the evidence bound, because the rule is
+ * that an oversize-but-ORDINARY write stays attributable — a generated file, a
+ * bundled config, a long document — while the pathological input is refused. A
+ * call past it is attributable to nothing, and the walk treats it exactly as
+ * it treats one that names no `path`: there is no key to withdraw, so the
+ * whole pass is abandoned and the conversation keeps the empty ledger a resume
+ * has always started from.
+ */
+const MAX_ATTRIBUTION_UNITS = 1024 * 1024
+
+/**
+ * One pass's answer to "which file did this call touch", memoised.
+ *
+ * Keyed on the call OBJECT rather than on its id: an id claimed by two calls
+ * is an ambiguity this module refuses to settle by position, and settling it
+ * by cache hit instead would be the same mistake wearing a different hat. A
+ * `WeakMap` because the entries are worth exactly as long as the transcript
+ * they describe, and the value is the declared path or `null` for a call that
+ * declares none — `undefined` means only "not asked yet".
+ */
+export type PathAttributions = WeakMap<ToolCall, string | null>
+
+export function createPathAttributions(): PathAttributions {
+	return new WeakMap()
+}
+
+/**
+ * A call's arguments as JSON, or `undefined` for arguments this module will
+ * not read.
+ *
+ * Every `JSON.parse` of a tool call in this file goes through here, so the
+ * ceiling is one rule rather than one rule per reader, and malformed input is
+ * a value the callers test rather than an exception they have to be wrapped
+ * against.
+ */
+function parseArguments(call: ToolCall): unknown {
+	if (call.function.arguments.length > MAX_ATTRIBUTION_UNITS) return undefined
+	try {
+		return JSON.parse(call.function.arguments)
+	} catch {
+		return undefined
+	}
+}
+
+/**
+ * The ledger key a tool-call path belongs to, or `undefined` for a path this
+ * pass may not key at all.
+ *
+ * A resolver rather than a working directory, because the two callers do not
+ * key alike and must not be made to. The projection READS a ledger the tools
+ * wrote and looks entries up lexically, as it always has: a spelling that does
+ * not match the tool's canonical key simply finds nothing. A seed WRITES that
+ * ledger, so its keys have to be the ones the tools will come looking for —
+ * which means resolving a path the way `write` and `edit` resolve it, through
+ * every symlink, and that is filesystem work nothing in this module is allowed
+ * to do. So the caller resolves first and hands the answers in.
+ */
+export type FileKeyResolver = (path: string) => string | undefined
+
+/**
+ * The lexical key space: the path resolved against the working directory, or
+ * the path as written when the tools address a sandbox.
+ *
+ * What a reader of the ledger uses. Not what a writer of it may use: see
+ * {@link FileKeyResolver}.
+ */
+export function lexicalFileKeys(workingDirectory: string, sandboxed: boolean): FileKeyResolver {
+	return (path: string) => (sandboxed ? path : resolve(workingDirectory, path))
+}
+
+/** The calls and receipts of one conversation, indexed by call id. */
+export interface VisibleHistory {
+	/** `null` where an id was claimed by more than one assistant call. */
+	readonly calls: ReadonlyMap<string, ToolCall | null>
+	/** `null` where an id was answered more than once. */
+	readonly results: ReadonlyMap<string, Message | null>
+	/** The ledger key a tool-call path resolves to. */
+	readonly keyOf: FileKeyResolver
+}
+
+/**
+ * Index a transcript once, so every lookup below is a map hit.
+ *
+ * An id claimed twice, or answered twice, indexes to `null` rather than to
+ * whichever message came last: two calls wearing one id is an ambiguity, and
+ * resolving it by position would let the second silently vouch for the first.
+ */
+export function indexVisibleHistory(
+	messages: readonly Message[],
+	keyOf: FileKeyResolver,
+): VisibleHistory {
+	const calls = new Map<string, ToolCall | null>()
+	const results = new Map<string, Message | null>()
+	for (const message of messages) {
+		if (message.role === 'assistant') {
+			for (const call of message.toolCalls ?? []) {
+				calls.set(call.id, calls.has(call.id) ? null : call)
+			}
+		} else if (message.role === 'tool') {
+			results.set(message.toolCallId, results.has(message.toolCallId) ? null : message)
+		}
+	}
+	return { calls, results, keyOf }
+}
+
+/**
+ * Every path a replay of this history might have to key, in the order the
+ * calls arrived.
+ *
+ * For a caller that has to resolve them before the replay can run, and only
+ * for that: nothing here decides anything about a path. Empty when the history
+ * holds no `write` and no `edit` call at all, because a claim is only ever made
+ * by a mutation — a conversation that only read files reconstructs nothing, and
+ * resolving its reads would be filesystem work with no possible result.
+ *
+ * Every mutation the walk can ATTRIBUTE has to appear here, the ones it will
+ * refuse to reconstruct included. This used to drop a call whose arguments ran
+ * past the evidence bound, so the walk reached it holding no key for its path,
+ * read that as a mutation it could not attribute, and abandoned the seeding
+ * entirely: one thirty-kilobyte `write` anywhere in a conversation erased every
+ * witness in it. The bounds belong to what may be believed; the path is read
+ * here out of the same field the walk reads it from, under no bound at all.
+ */
+export function collectObservedPaths(
+	messages: readonly Message[],
+	attributions: PathAttributions = createPathAttributions(),
+): readonly string[] {
+	const paths = new Set<string>()
+	let mutated = false
+	for (const message of messages) {
+		if (message.role !== 'assistant') continue
+		for (const call of message.toolCalls ?? []) {
+			const name = call.function.name
+			if (name !== 'write' && name !== 'edit' && name !== 'read') continue
+			if (name !== 'read') mutated = true
+			const path = declaredPath(call, attributions)
+			if (path !== undefined) paths.add(path)
+		}
+	}
+	return mutated ? [...paths] : []
+}
+
+/**
+ * The `path` argument a tool call declares, whatever else its input holds.
+ *
+ * The one attribution rule, used both to collect the paths a pass must resolve
+ * and to key each mutation as the walk reaches it — one function, so the two
+ * can never disagree about which file a call touched, which is the disagreement
+ * that turns an ordinary large write into a total loss.
+ *
+ * The recorded arguments and nothing else. A receipt names the path too, but it
+ * names it inside a sentence a path may itself contain, in a spelling that
+ * differs between the host and sandbox branches, and compaction clears receipts
+ * while it never clears a call. A call the provider stream cut off mid-JSON
+ * carries `{}` here: `function.arguments` is normalized to that and the raw
+ * buffer moves to `metadata.partialArguments`, which is what the model was
+ * saying rather than what ran — a `repairToolCall` hook may have rewritten the
+ * arguments before execution. So a truncated call is attributable to nothing,
+ * and the walk treats it as such. So is a call whose arguments run past
+ * {@link MAX_ATTRIBUTION_UNITS}, which this does not read at all.
+ *
+ * Answered once per pass and remembered. The path collection and the walk ask
+ * the same question of the same calls, and a `write` carries a whole file body
+ * in the string being parsed to answer it.
+ */
+function declaredPath(call: ToolCall, attributions: PathAttributions): string | undefined {
+	const remembered = attributions.get(call)
+	if (remembered !== undefined) return remembered ?? undefined
+	const parsed = parseArguments(call)
+	const declared =
+		typeof parsed === 'object' && parsed !== null ? (parsed as { path?: unknown }).path : undefined
+	const path = typeof declared === 'string' && declared.length > 0 ? declared : null
+	attributions.set(call, path)
+	return path ?? undefined
+}
+
+/**
+ * The visibility every hop must pass, write or edit, root or tip.
+ *
+ * One function because a middle hop is not a lesser claim than the last one.
+ * A chain whose second edit was cleared by compaction, or came back an error,
+ * or arrived truncated, reconstructs nothing at all — so the whole path is
+ * withheld rather than emitted as the part still visible, which would name a
+ * body the model cannot rebuild.
+ *
+ * A call a `pre_tool_use` hook SKIPPED is the one refusal that does not arrive
+ * as an error. The hook declined the call; nothing failed, so the receipt is a
+ * plain success carrying the sentence `plugin-hooks.ts` writes for it, and
+ * reading that as a `write` would hand back a body the tool was never allowed
+ * to put on disk — a fingerprint for a file that still holds whatever it held
+ * before, and a spurious drift refusal on the next edit. Recognised through
+ * the same function that writes the sentence, so the two cannot drift apart.
+ */
+export function visibleCall(
+	history: VisibleHistory,
+	id: string,
+	name: 'write' | 'edit' | 'read',
+): ToolCall | undefined {
+	const call = history.calls.get(id)
+	const receipt = history.results.get(id)
+	if (
+		!call ||
+		call.function.name !== name ||
+		call.metadata?.inputTruncated ||
+		call.function.arguments.length > MAX_ARGUMENT_UNITS ||
+		id.length > MAX_CALL_ID_UNITS ||
+		!receipt ||
+		receipt.role !== 'tool' ||
+		receipt.isError ||
+		typeof receipt.content !== 'string' ||
+		isClearedToolResult(receipt.content) ||
+		isSkippedToolResult(name, receipt.content)
+	)
+		return undefined
+	return call
+}
+
+/** A full body that arrived whole in one visible call. */
+export function visibleWrite(
+	history: VisibleHistory,
+	id: string,
+): { readonly path: string; readonly key: string; readonly body: string } | undefined {
+	const call = visibleCall(history, id, 'write')
+	if (!call) return
+	const input = WriteFileTool.inputSchema.safeParse(parseArguments(call))
+	if (!input.success || input.data.path.length > MAX_PATH_UNITS) return
+	const body = input.data.content ?? input.data.newStr
+	if (typeof body !== 'string') return
+	const key = history.keyOf(input.data.path)
+	if (key === undefined) return
+	return { path: input.data.path, key, body }
+}
+
+/**
+ * One visible edit call's arguments, ready to replay.
+ *
+ * No length bound on the path here, unlike the write above. A write's path is
+ * the spelling an entry goes out with; an edit is held to the KEY it resolves
+ * to, which its chain's root has already been bounded on.
+ */
+export function visibleEdit(
+	history: VisibleHistory,
+	id: string,
+): { readonly key: string; readonly input: unknown } | undefined {
+	const call = visibleCall(history, id, 'edit')
+	if (!call) return
+	const input = EditTool.inputSchema.safeParse(parseArguments(call))
+	if (!input.success) return
+	const key = history.keyOf(input.data.path)
+	if (key === undefined) return
+	return { key, input: input.data }
+}
+
+/** Room left for content this pass may still materialise. */
+export interface ReplayBudget {
+	remaining: number
+}
+
+export function createReplayBudget(units: number = MAX_REPLAYED_UNITS): ReplayBudget {
+	return { remaining: units }
+}
+
+/**
+ * Charge one body against the pass's replay allowance.
+ *
+ * Checked before it is taken, so a refusal costs nothing. Deducting first and
+ * reporting afterwards left the allowance negative, and one oversized path
+ * then refused every admissible path behind it in the same pass.
+ */
+export function spend(budget: ReplayBudget, units: number): boolean {
+	if (units > budget.remaining) return false
+	budget.remaining -= units
+	return true
+}
+
+/**
+ * Replay one edit call onto the body in hand, within what the budget has left.
+ *
+ * `undefined` for a hop the budget turns away and for one that no longer
+ * applies, because both mean the same thing to every caller here: this path
+ * reconstructs nothing. The charge is settled either way — what the attempt
+ * built, it built — and for a hop refused at its first operation that charge
+ * is zero.
+ */
+export function replayHop(
+	content: string,
+	input: unknown,
+	budget: ReplayBudget,
+): string | undefined {
+	const replay = replayEditCallWithin(content, input, budget.remaining)
+	budget.remaining = Math.max(budget.remaining - replay.charged, 0)
+	return replay.outcome === 'replayed' ? replay.content : undefined
+}
+
+/**
+ * Whether a refused mutation has reported this path stale since the ledger
+ * last observed it.
+ *
+ * That refusal read the real file to make its comparison, so the ledger knows
+ * its body is behind disk without a consumer here touching the filesystem.
+ * The reconstruction would still be a body the model can rebuild — but not the
+ * FILE's body, which is what an entry claims. Withheld until a real
+ * observation re-baselines the ledger, which is also what clears the flag.
+ */
+export function knownStale(tracker: FileReadTracker, key: string): boolean {
+	return tracker.driftObserved?.(key) === true
+}
+
+/**
+ * Paths one pass may hold a reconstructed body for at a time.
+ *
+ * The projection emits at most this many entries and keeps the most recent, so
+ * a pass that tracked more would be doing work whose result is discarded.
+ */
+export const MAX_WITNESSED_PATHS = 6
+
+/** What one pass of {@link replayObservationLedger} established. */
+export interface LedgerReplayReport {
+	/** Paths whose body was reconstructed exactly, with a fingerprint and a witness. */
+	readonly pathsWitnessed: number
+	/**
+	 * Paths the conversation demonstrably mutated but whose body could not be
+	 * rebuilt. Nothing is written to the ledger for these; see {@link commit}.
+	 */
+	readonly pathsSeen: number
+	/**
+	 * Content materialised, in UTF-16 units. Never above
+	 * {@link MAX_REPLAYED_UNITS}, and non-zero even for a pass that established
+	 * nothing: it reports the work done, not the work kept.
+	 */
+	readonly unitsReplayed: number
+}
+
+/**
+ * One path's state part-way through a walk of the transcript.
+ *
+ * `content` is a body this pass can rebuild and is still holding; `seen` is a
+ * path the conversation mutated whose current body it cannot rebuild. `seen`
+ * exists so that an edit cannot stack onto a body something unseen has already
+ * replaced; it reaches the ledger as nothing at all.
+ */
+type Claim =
+	| { readonly kind: 'content'; body: string; readonly steps: LedgerStep[] }
+	| { readonly kind: 'seen' }
+
+/** A call to make against the ledger once the whole walk has stood up. */
+type LedgerStep =
+	| { readonly kind: 'write'; readonly body: string; readonly callId: string }
+	| { readonly kind: 'edit'; readonly content: string; readonly callId: string }
+
+/**
+ * Rebuild an observation ledger from a conversation's own history.
+ *
+ * The ledger is process state. A resumed conversation gets a fresh empty one,
+ * and until something reads a file again the runtime knows nothing about files
+ * this conversation wrote in full — so the projection admits nothing and the
+ * model re-reads a body already in front of it, every time a session is picked
+ * back up.
+ *
+ * What is reconstructable here is exactly what the projection would admit, by
+ * the same predicates and the same bounded replay, because both go through the
+ * functions above. A `write` whose call and successful receipt are both intact
+ * hands back its body and its witness; the edits on top of it are replayed
+ * hop by hop and extend the chain. Anything else about a path the conversation
+ * mutated — a receipt compaction cleared, a call the transcript never answered,
+ * a mutation it refused, one a `pre_tool_use` hook skipped before it ever ran,
+ * a hop that no longer applies, a body past the bounds, a call too long to
+ * quote back — withdraws whatever this pass was holding for that path and
+ * writes NOTHING for it.
+ *
+ * Content-backed observations only, and that is the whole of what a resume
+ * restores. A path in the ledger with no fingerprint is a path `write` lets
+ * through unread: the read-before-overwrite refusal is `hasRead`, and the drift
+ * comparison it guards needs a body to compare. Seeding membership alone would
+ * therefore admit a full overwrite of a file that changed while the session was
+ * closed, with nothing checked — weaker than the empty ledger a resume used to
+ * start from, which refuses that overwrite outright. So a path this pass cannot
+ * rebuild is left exactly as that empty ledger leaves it, and the first real
+ * read re-establishes it.
+ *
+ * Two things this deliberately does not do. It never reads the filesystem: a
+ * fingerprint restored here is a claim derived from history, and the built-in
+ * mutation checks still compare it against the real file before anything is
+ * written — so a file changed while the session was closed is refused exactly
+ * as it is today, and the refusal's drift flag withdraws the entry. And it
+ * never recovers a body from a `read` receipt by undoing the line numbering: a
+ * read's rendering is compared, whole, against a body this pass already holds,
+ * and a read that cannot be matched that way withdraws the body rather than
+ * supplying one.
+ *
+ * That first guarantee is the reason `keyOf` is a parameter. Everything written
+ * here has to land on the key the mutation tools will look it up under, and on
+ * a host those keys are canonical — `write` and `edit` follow every symlink
+ * before they touch the ledger. Keying a seed lexically instead writes entries
+ * into a key space the tools never read: the projection would then match a
+ * fingerprint this pass had just written to it, and the drift refusal that is
+ * supposed to withdraw the claim would land somewhere else and never reach it.
+ * So the caller resolves the paths the way the tools do — see
+ * `file-evidence-seed.ts` — and a path it could not resolve gets no key, which
+ * makes the mutation that named it unattributable and stops the pass.
+ */
+export function replayObservationLedger(
+	messages: readonly Message[],
+	tracker: FileReadTracker,
+	keyOf: FileKeyResolver,
+	attributions: PathAttributions = createPathAttributions(),
+): LedgerReplayReport {
+	const history = indexVisibleHistory(messages, keyOf)
+	const budget = createReplayBudget()
+	const claims = new Map<string, Claim>()
+	// The keys currently holding a body, newest last — the projection's own
+	// order, so the paths this keeps are the paths it would emit.
+	const withBody = new Set<string>()
+
+	for (const message of messages) {
+		if (message.role !== 'assistant') continue
+		for (const call of message.toolCalls ?? []) {
+			const name = call.function.name
+			if (name !== 'write' && name !== 'edit' && name !== 'read') continue
+			const receipt = history.results.get(call.id)
+			// Two receipts wearing one call id hide which of them this call got.
+			// On a mutation that is the ambiguity below, arriving from the other
+			// side. On a READ it is no smaller: the receipt that was hidden could
+			// be the one showing a body this walk is holding to be something else,
+			// and skipping the read past would keep a claim that very observation
+			// withdrew. Both get the same answer.
+			if (receipt === null) return commit(tracker, new Map(), budget)
+			const answered = receipt !== undefined && receipt.role === 'tool' && !receipt.isError
+			if (name === 'read') {
+				// A read that never came back, or came back refused, saw no body: it
+				// can neither confirm what this pass holds nor contradict it. And a
+				// read changes no file, so a claim left standing across one is still a
+				// claim about the same bytes.
+				if (answered) observeRead(history, call, claims, withBody, budget)
+				continue
+			}
+			// One id claimed by two calls hides which of them ran. On a path this
+			// pass is not holding that is merely invisible, but a mutation could
+			// have replaced a body claimed somewhere else in this walk, and there
+			// is no way to tell where — so the pass establishes nothing at all
+			// rather than carry a body something unseen may have moved past.
+			if (history.calls.get(call.id) === null) return commit(tracker, new Map(), budget)
+			// Attribution before outcome, for every mutation the walk reaches. A call
+			// the transcript never answered — the unknown-outcome result the kernel's
+			// own repair writes for one included — is precisely the call whose effect
+			// on the file nobody knows: the process may have died with the write half
+			// made. And a refusal is a tool's own report about this path, a drift
+			// refusal above all, which read the disk and found the body this ledger
+			// holds is not the body there. Carrying a claim through either would have
+			// the first resumed request tell the model a file holds a body the
+			// transcript itself says nobody can vouch for, so each withdraws the path
+			// it names — and only that path. A mutation attributable to no path at all
+			// is still the one thing that stops the pass, because then there is no
+			// path to withdraw.
+			const key = mutatedKey(history, call, attributions)
+			if (key === undefined) return commit(tracker, new Map(), budget)
+			const claim: Claim = answered
+				? mutate(history, call, name, key, claims.get(key), budget)
+				: { kind: 'seen' }
+			claims.set(key, claim)
+			withBody.delete(key)
+			if (claim.kind === 'content') withBody.add(key)
+			// Oldest body first, matching what the projection keeps. An evicted
+			// path is one this pass stops vouching for: it was mutated here, and
+			// what it holds is past what the pass can carry, so it reaches the
+			// ledger as the nothing every unrebuilt path reaches it as.
+			if (withBody.size > MAX_WITNESSED_PATHS) {
+				const oldest = withBody.values().next().value as string
+				withBody.delete(oldest)
+				// Setting an existing key leaves it where it is, so the order the
+				// ledger is written in stays the order the calls arrived in.
+				claims.set(oldest, { kind: 'seen' })
+			}
+		}
+	}
+
+	return commit(tracker, claims, budget)
+}
+
+/** Apply a walk's surviving claims to the ledger, in the order they were made. */
+function commit(
+	tracker: FileReadTracker,
+	claims: ReadonlyMap<string, Claim>,
+	budget: ReplayBudget,
+): LedgerReplayReport {
+	let pathsWitnessed = 0
+	let pathsSeen = 0
+	for (const [key, claim] of claims) {
+		if (claim.kind === 'seen') {
+			// Nothing. Not even membership: `hasRead` is the read-before-overwrite
+			// refusal, and granting it without a fingerprint would let a full
+			// overwrite of this path through with no body to compare — over a file
+			// that may have moved while the session was closed. The claim was
+			// carried through the walk so that no edit stacked onto a body
+			// something unseen had replaced; having done that, it is dropped.
+			pathsSeen++
+			continue
+		}
+		for (const step of claim.steps) {
+			if (step.kind === 'write') {
+				tracker.recordRead(key, step.body, step.callId)
+			} else if (tracker.recordEdit) {
+				tracker.recordEdit(key, step.content, step.callId)
+			} else {
+				// The same fallback the `edit` tool takes against a tracker without
+				// the method: the observation advances and no chain is built.
+				tracker.recordRead(key, step.content)
+			}
+		}
+		pathsWitnessed++
+	}
+	return { pathsWitnessed, pathsSeen, unitsReplayed: MAX_REPLAYED_UNITS - budget.remaining }
+}
+
+/** Fold one successful mutation into the path's claim. */
+function mutate(
+	history: VisibleHistory,
+	call: ToolCall,
+	name: 'write' | 'edit',
+	key: string,
+	claim: Claim | undefined,
+	budget: ReplayBudget,
+): Claim {
+	if (name === 'write') {
+		const written = visibleWrite(history, call.id)
+		// A write nothing may quote back is still a write that HAPPENED, and the
+		// path it happened to is known: arguments past the evidence bound, a call
+		// the stream truncated, a path longer than an entry goes out with, a key
+		// the call and the ledger disagree about. Each of those withdraws the
+		// body and keeps the walk going — what was on this path is now unknown,
+		// which is a statement about one path rather than a reason to stop. A
+		// call a hook SKIPPED lands here too, from the other direction: that one
+		// never ran, so the file holds whatever it held before and this pass
+		// cannot say what that was either.
+		if (!written || written.key !== key) return { kind: 'seen' }
+		if (!spend(budget, written.body.length)) return { kind: 'seen' }
+		// A full body replaces everything under it, chain included.
+		return {
+			kind: 'content',
+			body: written.body,
+			steps: [{ kind: 'write', body: written.body, callId: call.id }],
+		}
+	}
+	// An edit onto a body this pass is not holding cannot be replayed onto
+	// anything, and one onto a chain already at its bound stops being followed.
+	if (!claim || claim.kind !== 'content') return { kind: 'seen' }
+	if (claim.steps.length > MAX_EDIT_CALLS) return { kind: 'seen' }
+	const hop = visibleEdit(history, call.id)
+	if (!hop || hop.key !== key) return { kind: 'seen' }
+	const replayed = replayHop(claim.body, hop.input, budget)
+	if (replayed === undefined) return { kind: 'seen' }
+	claim.body = replayed
+	claim.steps.push({ kind: 'edit', content: replayed, callId: call.id })
+	return claim
+}
+
+/**
+ * Confirm or withdraw a body this pass holds, from a `read` that observed it.
+ *
+ * A read changes no file, so on its own it establishes nothing: a partial read
+ * shows a window, and a body cannot be recovered from the rendering without
+ * stripping the line numbers back off — which would be inventing a file from
+ * text that was formatted for a reader, and is exactly what the ledger's
+ * contract forbids. What a read CAN do is settle whether a body already
+ * reconstructed here is the one the read saw. The rendering is produced
+ * forwards, from the body in hand through the read tool's own renderer, and
+ * compared whole.
+ *
+ * Equality is conclusive because of the numbering. Every line of a rendering
+ * goes out behind its own `${n}\t`, so one rendering belongs to exactly one
+ * body and window; and the partial-view notice carries no such prefix on its
+ * lines, so a rendering that covers a whole file cannot be equal to one that
+ * was cut short. A read this cannot match leaves the path known and its body
+ * withdrawn — the honest answer, and the one the drift check then re-derives
+ * from disk.
+ */
+function observeRead(
+	history: VisibleHistory,
+	call: ToolCall,
+	claims: Map<string, Claim>,
+	withBody: Set<string>,
+	budget: ReplayBudget,
+): void {
+	const read = readWindow(history, call)
+	if (!read) return
+	const claim = claims.get(read.key)
+	if (!claim || claim.kind !== 'content') return
+	const shown = history.results.get(call.id)?.content
+	if (visibleCall(history, call.id, 'read') && typeof shown === 'string') {
+		// A whole-file rendering is the body plus a number on every line, so one
+		// shorter than the body it would render cannot be equal to it. The cheap
+		// half of the comparison, taken before anything is measured.
+		const units =
+			shown.length < claim.body.length ? undefined : wholeFileRenderUnits(claim.body, read.window)
+		// The rendering is content this pass materialises, so it is charged like
+		// every other body — and charged for what it will actually come to,
+		// worked out from the body and the window while the string does not exist
+		// yet. Charging the RECEIPT's length was charging one number and building
+		// another: a receipt that had been rewritten short could have the pass
+		// build a rendering the ceiling had never been asked about.
+		if (units !== undefined && spend(budget, units)) {
+			const rendered = renderNumberedRead(claim.body, read.window)
+			if (!rendered.partial && rendered.output === shown) return
+		}
+	}
+	claims.set(read.key, { kind: 'seen' })
+	// Off the held list as well as out of the claim. A withdrawn path is one
+	// this pass is no longer carrying a body for, so counting it against the
+	// eviction bound would have a later mutation evict a path that IS still
+	// holding one — the pass would then write fewer witnesses than the
+	// projection can emit, and the one it dropped was admissible.
+	withBody.delete(read.key)
+}
+
+/**
+ * What `read` would return for this whole body, in UTF-16 units, without
+ * building it — and `undefined` for a window that would leave a line out.
+ *
+ * The rendering puts `${n}\t` in front of every line and joins them back with
+ * the newlines the body already carries, so its length is the body's, plus one
+ * tab per line, plus the digits of the numbers `1..lines`. A windowed read
+ * renumbers from its offset and carries the PARTIAL notice, and can never equal
+ * a whole body's rendering — so it is refused here rather than built and
+ * compared, which is also what makes the figure above exact.
+ */
+function wholeFileRenderUnits(body: string, window: ReadWindowRequest): number | undefined {
+	const lines = countLines(body)
+	const { start, end } = resolveReadWindow(window, lines)
+	if (start !== 0 || end < lines) return undefined
+	return body.length + lines + lineNumberUnits(lines)
+}
+
+/** Lines the way `String.split('\n')` counts them, without building the array. */
+function countLines(body: string): number {
+	let lines = 1
+	for (let at = body.indexOf('\n'); at !== -1; at = body.indexOf('\n', at + 1)) lines++
+	return lines
+}
+
+/** Units the line numbers `1..lines` occupy, counted by decade rather than one by one. */
+function lineNumberUnits(lines: number): number {
+	let units = 0
+	for (let width = 1, first = 1; first <= lines; width++, first *= 10)
+		units += (Math.min(lines, first * 10 - 1) - first + 1) * width
+	return units
+}
+
+/**
+ * The ledger key a mutation belongs to, whatever the transcript says came back
+ * — or `undefined` for one this pass cannot attribute to any file at all.
+ *
+ * Deliberately the declared path rather than the tool's own schema, and asked
+ * before the outcome is. A call that fails validation in some OTHER field, that
+ * is too long to read as evidence, that was never answered or that was refused
+ * still says which file it was aimed at, and a mutation that can be attributed
+ * can be honoured — as a content-changing observation nothing here can replay,
+ * which costs the path it names and no other. A key is exactly what withdrawing
+ * one path rather than the whole pass requires. `undefined` is kept for the two
+ * things that really are unattributable: a call naming no path, and a path this
+ * run may not reach, whose key the resolver therefore withheld. Those, and only
+ * those, stop the pass — a refused call included, because a refusal this pass
+ * cannot place is a refusal it cannot act on either.
+ */
+function mutatedKey(
+	history: VisibleHistory,
+	call: ToolCall,
+	attributions: PathAttributions,
+): string | undefined {
+	const path = declaredPath(call, attributions)
+	return path === undefined ? undefined : history.keyOf(path)
+}
+
+/** The path and window one `read` call asked for. */
+function readWindow(
+	history: VisibleHistory,
+	call: ToolCall,
+): { readonly key: string; readonly window: ReadWindowRequest } | undefined {
+	const input = ReadFileTool.inputSchema.safeParse(parseArguments(call))
+	if (!input.success) return undefined
+	const key = history.keyOf(input.data.path)
+	// A read this pass cannot key cannot contradict a claim either: the only
+	// claims it holds came from mutations, and a mutation whose path would
+	// not resolve stopped the pass before it made one.
+	return key === undefined ? undefined : { key, window: input.data }
+}