@namzu/sdk 38.2.1 → 40.0.0

package/src/runtime/query/callback-inference.ts

@@ -0,0 +1,94 @@
+import { z } from 'zod'
+import { StreamTextAccumulator } from '../../provider/stream-text.js'
+import { type TokenUsage, mergeTokenUsage } from '../../types/common/index.js'
+import { createSystemMessage, createUserMessage } from '../../types/message/index.js'
+import type { PreparationTextRequest, PreparationTextResult } from '../../types/run/prepare-step.js'
+import type { IterationContext } from './iteration/phases/context.js'
+
+const requestSchema = z
+	.object({
+		system: z.string().min(1).max(12_000),
+		prompt: z.string().min(1).max(12_000),
+		maxTokens: z.number().int().min(1).max(1024).default(256),
+		timeoutMs: z.number().int().min(1).max(10_000).default(10_000),
+	})
+	.strict()
+
+/** The provider already owns retry, fallback, cancellation and budget admission. */
+export function createCallbackInference(
+	ctx: IterationContext,
+	model: string,
+	phase: 'preparation' | 'review',
+) {
+	const label = phase === 'preparation' ? 'Preparation' : 'Review'
+	const owner = phase === 'preparation' ? 'preparation stage' : 'answer reviewer'
+	const lifetime = new AbortController()
+	let used = false
+	return {
+		close: () => lifetime.abort(new Error(`The ${owner} has ended.`)),
+		async generateText(request: PreparationTextRequest): Promise<PreparationTextResult> {
+			lifetime.signal.throwIfAborted()
+			ctx.abortController.signal.throwIfAborted()
+			request.signal?.throwIfAborted()
+			const { signal: requestedSignal, ...fields } = request
+			const input = requestSchema.parse(fields)
+			if (input.system.length + input.prompt.length > 12_000)
+				throw new Error(`${label} inference input exceeds 12,000 characters.`)
+			if (used)
+				throw new Error(
+					`${phase === 'preparation' ? 'A' : 'An'} ${owner} may make only one inference call.`,
+				)
+			used = true
+			const deadline = new AbortController()
+			const timer = setTimeout(
+				() => deadline.abort(new Error(`${label} inference timed out.`)),
+				input.timeoutMs,
+			)
+			const signal = AbortSignal.any([
+				ctx.abortController.signal,
+				lifetime.signal,
+				deadline.signal,
+				...(requestedSignal ? [requestedSignal] : []),
+			])
+			const requested = ctx.servingMember?.() ?? { index: 0, providerId: ctx.provider.id }
+			const route = () => {
+				const member = ctx.servingMember?.() ?? requested
+				return {
+					providerId: member.providerId,
+					model: member.model ?? model,
+					chainIndex: member.index,
+				}
+			}
+			const text = new StreamTextAccumulator()
+			let invalidOutput: string | undefined
+			let usage: TokenUsage | undefined
+			try {
+				for await (const chunk of ctx.provider.chatStream({
+					model,
+					providerRoute: route(),
+					messages: [createSystemMessage(input.system), createUserMessage(input.prompt)],
+					maxTokens: input.maxTokens,
+					...(ctx.runConfig.effort ? { effort: ctx.runConfig.effort } : {}),
+					signal,
+				})) {
+					if (chunk.usage) usage = usage ? mergeTokenUsage(usage, chunk.usage) : { ...chunk.usage }
+					if (chunk.error) throw new Error(chunk.error)
+					signal.throwIfAborted()
+					if (chunk.delta.toolCalls?.length) invalidOutput = `${label} inference cannot call tools.`
+					if (!invalidOutput) {
+						text.push(chunk)
+						if (text.characters > 8192)
+							invalidOutput = `${label} inference output exceeds 8,192 characters.`
+					}
+				}
+				signal.throwIfAborted()
+				if (!usage) throw new Error(`${label} inference ended without usage.`)
+				if (invalidOutput) throw new Error(invalidOutput)
+				return { text: text.text, usage, servedBy: route() }
+			} finally {
+				clearTimeout(timer)
+				if (usage) ctx.runMgr.accumulateUsage(usage, route())
+			}
+		},
+	}
+}

package/src/runtime/query/checkpoint.ts

@@ -214,6 +214,8 @@ export class CheckpointManager {
 	private workingStateSource?: () => WorkingStateSnapshot | undefined
 	private latestUserMessageSource?: () => UserMessage | undefined
 	private restoredUserMessage?: UserMessage
+	private answerReviewAttemptsSource?: () => number
+	private restoredAnswerAttempts = 0
 	private structuredReviewAttemptsSource?: () => number
 	private restoredReviewAttempts = 0
 	private nativeStructuredAttemptsSource?: () => number
@@ -298,6 +300,13 @@ export class CheckpointManager {
 		return this.restoredUserMessage
 	}
 
+	setAnswerReviewAttemptsSource(source: () => number): void {
+		this.answerReviewAttemptsSource = source
+	}
+	get restoredAnswerReviewAttempts(): number {
+		return this.restoredAnswerAttempts
+	}
+
 	setNativeStructuredAttemptsSource(source: () => number): void {
 		this.nativeStructuredAttemptsSource = source
 	}
@@ -344,6 +353,7 @@ export class CheckpointManager {
 			runCreatedAt: this.runCreatedAt,
 			iteration,
 			messages: [...runMgr.messages],
+			answerReviewAttempts: this.answerReviewAttemptsSource?.() ?? this.restoredAnswerAttempts,
 			nativeStructuredAttempts:
 				this.nativeStructuredAttemptsSource?.() ?? this.restoredNativeAttempts,
 			structuredReviewAttempts:
@@ -539,6 +549,10 @@ export class CheckpointManager {
 		// its origin's age. A guard that no input can trip would have read as
 		// protection and been none.
 		this.runCreatedAt ??= checkpoint.runCreatedAt
+		const answerAttempts = checkpoint.answerReviewAttempts ?? 0
+		if (!Number.isSafeInteger(answerAttempts) || answerAttempts < 0)
+			throw new Error('Checkpoint answerReviewAttempts must be a nonnegative safe integer')
+		this.restoredAnswerAttempts = answerAttempts
 		const nativeAttempts = checkpoint.nativeStructuredAttempts ?? 0
 		if (!Number.isSafeInteger(nativeAttempts) || nativeAttempts < 0)
 			throw new Error('Invalid nativeStructuredAttempts in checkpoint')

package/src/runtime/query/events.ts

@@ -11,6 +11,7 @@ import { type PersistedRunEvent, isEphemeralEvent } from '../../types/run/events
 import type { RunEvent } from '../../types/run/index.js'
 import type { ReadRunEventsOptions } from '../../types/run/store.js'
 import type { TaskEvent, TaskStore } from '../../types/task/index.js'
+import { awaitWithAbort } from '../../utils/await-with-abort.js'
 import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
 import { type Logger, resolveLogger } from '../../utils/logger.js'
 
@@ -78,6 +79,27 @@ export class EventTranslator {
 		return this.withTranscriptLock(() => this.runMgr.getRunStore().readEvents(options))
 	}
 
+	captureRunEvidence(
+		maxReadBytes?: number,
+		signal?: AbortSignal,
+	): Promise<import('../../store/evidence/types.js').RunTextEvidenceSource | undefined> {
+		const capture = this.withTranscriptLock(async () => {
+			signal?.throwIfAborted()
+			const run = this.runMgr.getRun()
+			if (run.status !== 'running')
+				throw new Error('Evidence capture requires the active invocation.')
+			const { tenantId, projectId, sessionId, runId } = this.runMgr.getRunScope()
+			const source = await this.runMgr
+				.getRunStore()
+				.captureTextEvidence?.({ tenantId, projectId, sessionId, runId }, maxReadBytes, signal)
+			signal?.throwIfAborted()
+			if (this.runMgr.getRun().status !== 'running')
+				throw new Error('Evidence capture requires the active invocation.')
+			return source
+		})
+		return awaitWithAbort(capture, signal)
+	}
+
 	setGeneration(fence: FencingToken | undefined): void {
 		this.generation = fence
 	}

package/src/runtime/query/executor.ts

@@ -43,12 +43,16 @@ import type {
 	ToolCallRepairReason,
 } from '../../types/tool/repair.js'
 import { abortReasonText } from '../../utils/abort.js'
+import { awaitWithAbort } from '../../utils/await-with-abort.js'
 import { type BackoffPolicy, backoffWithJitter, sleep } from '../../utils/backoff.js'
 import { toErrorMessage } from '../../utils/error.js'
 import { generateToolCallId } from '../../utils/id.js'
 import type { Logger } from '../../utils/logger.js'
 import { compressShellOutput } from '../../utils/shell-compress.js'
 import { type BackgroundJobRegistry, type JobProcess, bindOwner } from '../jobs/registry.js'
+import { describeVisibleFileEvidence } from './file-evidence-context.js'
+import { seedObservationLedger } from './file-evidence-seed.js'
+import { skippedToolResultText } from './plugin-hooks.js'
 import type { ToolResultObservation } from './project-instructions.js'
 import { ToolCallBudget, assertMaxToolCalls } from './tool-call-budget.js'
 import {
@@ -332,6 +336,16 @@ export interface ToolExecutorConfig {
 	 * session and stops them itself when the session ends.
 	 */
 	backgroundJobOwner?: string
+	/**
+	 * Where `wait_for_job` records that the model is waiting on a job.
+	 *
+	 * A callback rather than the recorder itself: the executor's part is to
+	 * hand the tools a bound ref, and what the run does with the intent —
+	 * hold itself open for the job — is the iteration loop's business. Absent
+	 * means the bound ref has no `markAwaited` at all, so a host that wires no
+	 * recorder gets no hold rather than a marking call that goes nowhere.
+	 */
+	onJobAwaited?: (id: string) => void
 
 	/**
 	 * Where the `skill` tool reads from.
@@ -376,6 +390,8 @@ export interface ToolExecutorConfig {
 	 * {@link DEFAULT_MAX_TOOL_OUTPUT_CHARS}; set `0` to disable.
 	 */
 	maxToolOutputChars?: number
+	/** See QueryParams.retainedToolPreviewChars; applies to the recorded host output. */
+	retainedToolPreviewChars?: number
 
 	/**
 	 * Cap on the RICH channel of a single tool result, in base64
@@ -401,7 +417,8 @@ export interface ToolExecutorConfig {
 	 * with `read`/`grep`. Absent ⇒ over-budget output is middle-elided and
 	 * the overflow is lost.
 	 */
-	toolOutputDir?: string
+	captureRunEvidence?: ToolContext['captureRunEvidence']
+	toolOutputDir?: string | (() => string | undefined)
 	/**
 	 * Last chance to fix a tool call the model got wrong, before the error
 	 * reaches it. See {@link RepairToolCall}.
@@ -491,6 +508,12 @@ export function deniedToolOutput(toolName: string, reason: string): string {
 }
 
 export class ToolExecutor {
+	private outputDirectory(): string | undefined {
+		return typeof this.config.toolOutputDir === 'function'
+			? this.config.toolOutputDir()
+			: this.config.toolOutputDir
+	}
+
 	private config: ToolExecutorConfig
 	private activityStore: ActivityStore
 	private emitEvent: EmitEvent
@@ -503,6 +526,8 @@ export class ToolExecutor {
 	/** Set per turn by the orchestrator; see {@link setStepAllowedTools}. */
 	private stepAllowedTools?: readonly string[]
 	private readonly fileReadTracker: FileReadTracker
+	/** A ledger is rebuilt from history at most once; a second pass would re-append its chains. */
+	private fileObservationsSeeded = false
 
 	constructor(
 		config: ToolExecutorConfig,
@@ -536,6 +561,49 @@ export class ToolExecutor {
 		this.config = { ...this.config, sandbox }
 	}
 
+	/**
+	 * Rebuild this run's observation ledger from history a resume restored.
+	 *
+	 * Once, and only from a history that has already been repaired — the ledger
+	 * has to describe what the model is about to be shown, not what was
+	 * checkpointed before the repair removed an abandoned call. `sandboxed` is
+	 * passed rather than read off this executor's config because a resumed run
+	 * restores its history before it acquires a sandbox, so the config does not
+	 * know yet what the run's tool paths will be keyed on.
+	 *
+	 * Awaited, and the only filesystem work anywhere in this feature: the seed
+	 * has to write its entries under the keys the mutation tools will look them
+	 * up under, which on a host means resolving each path through its symlinks
+	 * the way `write` and `edit` do. No file's content is read.
+	 */
+	async seedFileObservations(messages: readonly Message[], sandboxed: boolean): Promise<void> {
+		if (this.fileObservationsSeeded) return
+		this.fileObservationsSeeded = true
+		const report = await seedObservationLedger(messages, this.fileReadTracker, {
+			workingDirectory: this.config.workingDirectory,
+			...(this.config.additionalDirectories
+				? { additionalDirectories: this.config.additionalDirectories }
+				: {}),
+			sandboxed,
+		})
+		this.log.info('Rebuilt the file observation ledger from restored history', {
+			[NAMZU.RUN_ID]: this.config.runId,
+			'namzu.files.witnessed': report.pathsWitnessed,
+			'namzu.files.seen': report.pathsSeen,
+			'namzu.files.replayed_units': report.unitsReplayed,
+		})
+	}
+
+	/** Request-only evidence from the same ledger used by mutation admission. No filesystem I/O. */
+	describeFileEvidence(messages: readonly Message[]): string | undefined {
+		return describeVisibleFileEvidence(
+			messages,
+			this.fileReadTracker,
+			this.config.workingDirectory,
+			this.config.sandbox !== undefined,
+		)
+	}
+
 	/**
 	 * Span that this executor's tool spans should hang off — the current
 	 * iteration. Re-set each turn by the orchestrator, because a tool span
@@ -1175,7 +1243,8 @@ export class ToolExecutor {
 			toolUseId: nestedId,
 			output: rawOutput,
 			maxChars: this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS,
-			spillDir: this.config.toolOutputDir,
+			retainedPreviewChars: this.config.retainedToolPreviewChars,
+			spillDir: this.outputDirectory(),
 			onError: (message) =>
 				this.log.warn('Failed to spill oversized nested tool output', {
 					[NAMZU.RUN_ID]: this.config.runId,
@@ -1206,6 +1275,7 @@ export class ToolExecutor {
 			outputLength: budgeted.originalLength,
 			...(budgeted.truncated ? { outputTruncated: true } : {}),
 			...(budgeted.spillPath ? { outputSpillPath: budgeted.spillPath } : {}),
+			...(budgeted.spillIntegrity ? { outputSpillIntegrity: budgeted.spillIntegrity } : {}),
 			...(via ? { via } : {}),
 		})
 		recordObservation({
@@ -1253,6 +1323,7 @@ export class ToolExecutor {
 				workingDirectory: this.config.workingDirectory,
 			},
 			invocationState: this.config.invocationState,
+			captureRunEvidence: this.config.captureRunEvidence,
 			toolRegistry: this.config.tools,
 			// The step's list wins where it has one; the run's is the default.
 			// Same precedence the request already uses when it decides which
@@ -1318,6 +1389,7 @@ export class ToolExecutor {
 												) as JobProcess,
 										}
 									: {}),
+								...(this.config.onJobAwaited ? { onAwaited: this.config.onJobAwaited } : {}),
 							},
 						),
 					}
@@ -1628,8 +1700,8 @@ export class ToolExecutor {
 			: formatFailedToolOutput(result.output, result.error)
 
 		const postOverride = post.override
-		let output =
-			postOverride?.output ?? (result.success ? this.maybeCompress(toolName, rawOutput) : rawOutput)
+		let output = postOverride?.output ?? rawOutput
+		const preview = !postOverride && result.success ? this.maybeCompress(toolName, output) : output
 		let selectedContent = postOverride?.isError
 			? undefined
 			: (postOverride?.content ?? result.content)
@@ -1655,16 +1727,22 @@ export class ToolExecutor {
 			toolName,
 			toolUseId: toolCall.id,
 			output,
+			preview,
 			maxChars: maxToolOutputChars,
-			spillDir: this.config.toolOutputDir,
+			retainedPreviewChars: this.config.retainedToolPreviewChars,
+			spillDir: this.outputDirectory(),
 			onError: (message) =>
-				this.log.warn('Failed to spill oversized tool output', {
+				this.log.warn('Failed to retain original tool output', {
 					[NAMZU.RUN_ID]: this.config.runId,
 					[GENAI.TOOL_NAME]: toolName,
 					'exception.message': message,
 				}),
 		})
-		if (budgeted.truncated) {
+		if (
+			budgeted.truncated &&
+			maxToolOutputChars > 0 &&
+			budgeted.originalLength > maxToolOutputChars
+		) {
 			this.log.warn('Tool output exceeded the model-visible budget', {
 				[NAMZU.RUN_ID]: this.config.runId,
 				[GENAI.TOOL_NAME]: toolName,
@@ -1736,6 +1814,7 @@ export class ToolExecutor {
 			outputLength: budgeted.originalLength,
 			...(budgeted.truncated ? { outputTruncated: true } : {}),
 			...(budgeted.spillPath ? { outputSpillPath: budgeted.spillPath } : {}),
+			...(budgeted.spillIntegrity ? { outputSpillIntegrity: budgeted.spillIntegrity } : {}),
 		})
 		recordObservation({
 			runId: this.config.runId,
@@ -1864,9 +1943,20 @@ export class ToolExecutor {
 				}
 			}
 
+			const inheritedCapture = toolContext.captureRunEvidence
+			const scopedCapture: ToolContext['captureRunEvidence'] = inheritedCapture
+				? async (maxReadBytes, signal) => {
+						const combined = signal
+							? AbortSignal.any([controller.signal, signal])
+							: controller.signal
+						combined.throwIfAborted()
+						return awaitWithAbort(inheritedCapture(maxReadBytes, combined), combined)
+					}
+				: undefined
 			const context = {
 				...toolContext,
 				abortSignal: controller.signal,
+				...(scopedCapture ? { captureRunEvidence: scopedCapture } : {}),
 				...(scopedDispatch ? { dispatchTool: scopedDispatch } : {}),
 			}
 			const execution = prepared
@@ -2223,7 +2313,7 @@ export class ToolExecutor {
 					return {
 						kind: 'skip',
 						input: currentInput,
-						output: `Tool ${toolName} skipped by plugin: ${result.reason}`,
+						output: skippedToolResultText(toolName, result.reason),
 					}
 				case 'error':
 					return {
@@ -2686,8 +2776,8 @@ export class ToolExecutor {
 						...(notice ? { notice } : {}),
 						// A tool may return different host and model text. They must
 						// never compete for the same exclusive spill filename.
-						spillDir: this.config.toolOutputDir
-							? join(this.config.toolOutputDir, 'content')
+						spillDir: this.outputDirectory()
+							? join(this.outputDirectory() as string, 'content')
 							: undefined,
 						onError: (message) =>
 							this.log.warn('Failed to spill oversized model tool content', {

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

@@ -0,0 +1,209 @@
+import { fingerprintContent } from '../../tools/builtins/content-fingerprint.js'
+import { ReadFileTool } from '../../tools/builtins/read-file.js'
+import type { Message } from '../../types/message/index.js'
+import type { FileReadTracker } from '../../types/tool/index.js'
+import {
+	MAX_EDIT_CALLS,
+	MAX_PATH_UNITS,
+	MAX_WITNESSED_PATHS,
+	type ReplayBudget,
+	type VisibleHistory,
+	createReplayBudget,
+	indexVisibleHistory,
+	knownStale,
+	lexicalFileKeys,
+	replayHop,
+	spend,
+	visibleCall,
+	visibleEdit,
+	visibleWrite,
+} from './file-evidence-replay.js'
+
+/**
+ * Receipt text a read entry may point at.
+ *
+ * The same class of bound as the one on a write call's arguments, and set to
+ * the same number for the same reason: past it the text is not read at all. A
+ * bigger file is simply not admitted this way — the model re-reads it, which is
+ * what it does today.
+ */
+const MAX_RECEIPT_UNITS = 32_000
+
+interface FileEvidence {
+	readonly path: string
+	/** Absent on the write-rooted entries; `'read'` on a body that is a receipt. */
+	readonly kind?: 'read'
+	readonly bodyInCall: string
+	readonly editsInCalls?: readonly string[]
+	readonly observedFingerprint: string
+}
+
+/** Join visible call bodies, successful receipts and this executor's observation ledger. */
+export function describeVisibleFileEvidence(
+	messages: readonly Message[],
+	tracker: FileReadTracker,
+	workingDirectory: string,
+	sandboxed: boolean,
+): string | undefined {
+	// Execution-owned witnesses survive transparent wrappers; a name alone proves nothing.
+	if (!tracker.writeCallId || !tracker.fingerprint) return
+	// Lexical, as this projection has always looked entries up: a spelling that
+	// does not resolve to the tool's canonical key finds nothing and the path is
+	// simply not admitted. Writing the ledger is the side that has to key the
+	// way the tools do — see `file-evidence-seed.ts`.
+	const history = indexVisibleHistory(messages, lexicalFileKeys(workingDirectory, sandboxed))
+	const budget = createReplayBudget()
+	const files = new Map<string, FileEvidence>()
+	for (const [id, call] of history.calls) {
+		const name = call?.function.name
+		if (name !== 'write' && name !== 'edit' && name !== 'read') continue
+		try {
+			const admitted =
+				name === 'write'
+					? writeEvidence(id, tracker, history)
+					: name === 'edit'
+						? chainEvidence(id, tracker, history, budget)
+						: readEvidence(id, tracker, history)
+			if (!admitted) continue
+			// A write-rooted entry outranks a read of the same file: it names a
+			// body the model composed itself, and edits can be replayed onto it.
+			// The ledger already withholds a read witness where one survives; this
+			// keeps a read that ran BEFORE the write from taking the path back.
+			const held = files.get(admitted.key)
+			if (admitted.evidence.kind === 'read' && held && held.kind !== 'read') continue
+			files.delete(admitted.key)
+			files.set(admitted.key, admitted.evidence)
+			if (files.size > MAX_WITNESSED_PATHS) files.delete(files.keys().next().value as string)
+		} catch {
+			// Malformed retained inputs or a custom tracker cannot establish evidence.
+		}
+	}
+	if (files.size === 0) return
+	return `Visible file evidence (this request only): each entry's current body is the complete body in the named successful write call, with the edit calls in editsInCalls — when present — applied in that order. An entry marked kind:"read" instead names a successful read call whose own receipt shows the file WHOLE, rendered with every line behind its own N<tab> prefix; that receipt is the body, and such an entry never carries editsInCalls. This runtime performed that reconstruction and checked it against its own file observation; it is not a derivation left to you. Reuse the body for a targeted edit; a read solely to recall it is unnecessary. This is NOT a fresh disk check, and after a resume the observation behind an entry may itself have been rebuilt from this conversation's own earlier calls rather than made while this process ran. Built-in edit/write still compare the disk body at mutation admission and refuse observed drift; on refusal inspect the current file and replan. Missing entries establish nothing.\n${JSON.stringify([...files.values()])}`
+}
+
+/** A full body that arrived whole in one call and is still the file's body. */
+function writeEvidence(
+	id: string,
+	tracker: FileReadTracker,
+	history: VisibleHistory,
+): { key: string; evidence: FileEvidence } | undefined {
+	const written = visibleWrite(history, id)
+	if (!written || knownStale(tracker, written.key)) return
+	const fingerprint = fingerprintContent(written.body)
+	if (
+		tracker.writeCallId?.(written.key) !== id ||
+		tracker.fingerprint?.(written.key) !== fingerprint
+	)
+		return
+	return {
+		key: written.key,
+		evidence: {
+			path: written.path,
+			bodyInCall: id,
+			observedFingerprint: fingerprint,
+		},
+	}
+}
+
+/**
+ * A full body plus the visible edits since, replayed and then checked.
+ *
+ * Only the chain's TIP establishes the path: a middle hop is validated as part
+ * of the walk below, and admitting one on its own would claim the file stops
+ * at an edit later calls have already moved past. The replay runs the same
+ * apply core the tool ran at mutation time, over call arguments that are
+ * already in the conversation — no filesystem read, and the result is compared
+ * to the ledger's disk-derived fingerprint, never written into it.
+ */
+function chainEvidence(
+	id: string,
+	tracker: FileReadTracker,
+	history: VisibleHistory,
+	budget: ReplayBudget,
+): { key: string; evidence: FileEvidence } | undefined {
+	const tip = visibleEdit(history, id)
+	if (!tip || knownStale(tracker, tip.key)) return
+	const key = tip.key
+	const chain = tracker.editChain?.(key)
+	const observed = tracker.fingerprint?.(key)
+	if (!chain || observed === undefined || chain.editCallIds.at(-1) !== id) return
+	// The call bound before the walk, the unit bound before each operation it
+	// pays for. Neither is measured by doing the work it exists to refuse.
+	if (chain.editCallIds.length > MAX_EDIT_CALLS) return
+	const rootId = chain.rootWriteCallId
+	const root = visibleWrite(history, rootId)
+	// A root naming a different file is an ambiguity, not a base: the ledger
+	// and the visible call disagree about what was written where.
+	if (!root || root.key !== key) return
+	let content = root.body
+	if (!spend(budget, content.length)) return
+	for (const editId of chain.editCallIds) {
+		const hop = editId === id ? tip : visibleEdit(history, editId)
+		if (!hop || hop.key !== key) return
+		// Each of this hop's operations is measured against the body it is about
+		// to be applied to, charged, and only then applied — so a hop over the
+		// ceiling is refused before it is built rather than after, and one that
+		// fits is never turned away for a ceiling that guessed high. A hop the
+		// budget refuses, or one whose anchors no longer match, reconstructs
+		// nothing and withholds the whole path.
+		const replayed = replayHop(content, hop.input, budget)
+		if (replayed === undefined) return
+		content = replayed
+	}
+	if (fingerprintContent(content) !== observed) return
+	return {
+		key,
+		evidence: {
+			path: root.path,
+			bodyInCall: rootId,
+			editsInCalls: [...chain.editCallIds],
+			observedFingerprint: observed,
+		},
+	}
+}
+
+/**
+ * A body the model can still see because a read of the whole file put it there.
+ *
+ * Structurally unlike the two above, and deliberately so. They name a body the
+ * model itself composed, in arguments this projection can parse and replay; this
+ * names a RESULT, and the only thing anyone is allowed to do with it is compare
+ * it. The tool fingerprinted the exact string it emitted, and the entry is
+ * admitted only while the receipt still fingerprints to that — so a receipt the
+ * output budget elided or spilled, one compaction cleared, or one changed in any
+ * other way withholds the path rather than pointing the model at a body that is
+ * no longer in front of it. Nothing here undoes the line numbering to recover
+ * text: the numbering is what makes the comparison conclusive, not an encoding
+ * to be reversed.
+ *
+ * No chain, ever. A read roots nothing, so an entry here is the file as that one
+ * call showed it, and the ledger drops the witness the moment an edit lands.
+ */
+function readEvidence(
+	id: string,
+	tracker: FileReadTracker,
+	history: VisibleHistory,
+): { key: string; evidence: FileEvidence } | undefined {
+	if (!tracker.readWitness) return
+	const call = visibleCall(history, id, 'read')
+	const shown = history.results.get(id)?.content
+	if (!call || typeof shown !== 'string' || shown.length > MAX_RECEIPT_UNITS) return
+	const input = ReadFileTool.inputSchema.safeParse(JSON.parse(call.function.arguments))
+	if (!input.success || input.data.path.length > MAX_PATH_UNITS) return
+	const key = history.keyOf(input.data.path)
+	if (key === undefined || knownStale(tracker, key)) return
+	const witness = tracker.readWitness(key)
+	const observed = tracker.fingerprint?.(key)
+	if (!witness || witness.callId !== id || observed === undefined) return
+	if (fingerprintContent(shown) !== witness.renderedFingerprint) return
+	return {
+		key,
+		evidence: {
+			path: input.data.path,
+			kind: 'read',
+			bodyInCall: id,
+			observedFingerprint: observed,
+		},
+	}
+}