@namzu/sdk 38.2.1 → 40.0.0

package/src/store/evidence/source-text.ts

@@ -0,0 +1,285 @@
+import { lstat } from 'node:fs/promises'
+import type { FileHandle } from 'node:fs/promises'
+import { join } from 'node:path'
+import { z } from 'zod'
+import { evidenceRecordedAt } from '../../utils/evidence-time.js'
+import { compactionArchiveSchema, compactionPartPath } from './compaction-archive.js'
+import {
+	EVIDENCE_CHUNK_BYTES,
+	SEARCH_OVERLAP_BYTES,
+	digest,
+	mayContain,
+	mayContainToken,
+} from './format.js'
+import { type IndexEntry, entrySchema, eventTexts } from './index-page.js'
+import {
+	type EvidenceBudget,
+	decode,
+	openEvidence,
+	readBytes,
+	readSmall,
+	stamp,
+	utf8Page,
+} from './io.js'
+import type { RunEvidenceScope, RunTextEvidenceReadResult } from './types.js'
+
+const integer = z.number().int().nonnegative().safe()
+export const textPointerSchema = entrySchema.pick({
+	offset: true,
+	length: true,
+	sha256: true,
+	seq: true,
+	part: true,
+})
+const manifestSchema = z.object({
+	version: z.literal(1),
+	bytes: integer,
+	chars: integer.optional(),
+	chunkBytes: z.literal(EVIDENCE_CHUNK_BYTES),
+	chunks: z
+		.array(
+			z.object({
+				sha256: z.string().regex(/^[a-f0-9]{64}$/),
+				filter: z.string().max(1400),
+				tokenFilter: z.string().max(1400).optional(),
+				characterOffset: integer.optional(),
+			}),
+		)
+		.max(4096),
+})
+
+export interface TextSource {
+	entry: IndexEntry
+	recordedAt?: number
+	bytes: number
+	chars?: number
+	retained: 'full' | 'preview'
+	chunks: number
+	mayMatch(
+		chunk: number,
+		query: string,
+		matchMode?: 'literal' | 'token',
+		caseSensitive?: boolean,
+	): boolean
+	window(
+		chunk: number,
+		preceding?: boolean,
+	): Promise<{ bytes: Buffer; offset: number; characterOffset?: number; searchFrom?: number }>
+}
+
+interface TextRecord {
+	offset: number
+	length: number
+	sha256: string
+	seq: number
+	event: Record<string, unknown>
+	parts: ReturnType<typeof eventTexts>
+	archive?: z.infer<typeof compactionArchiveSchema>
+}
+
+/** One authenticated record per operation, never shared between calls or sources. */
+export function createTextSourceReader(
+	handle: FileHandle,
+	runDir: string,
+	runId: string,
+	budget: EvidenceBudget,
+): (pointer: z.infer<typeof textPointerSchema>, verifiedRecord?: Buffer) => Promise<TextSource> {
+	let saved: TextRecord | undefined
+	return async (pointer, verifiedRecord) => {
+		budget.signal?.throwIfAborted()
+		if (
+			!saved ||
+			saved.offset !== pointer.offset ||
+			saved.length !== pointer.length ||
+			saved.sha256 !== pointer.sha256 ||
+			saved.seq !== pointer.seq
+		) {
+			const raw =
+				verifiedRecord ?? (await readBytes(handle, pointer.offset, pointer.length, budget))
+			if (raw.length !== pointer.length || digest(raw) !== pointer.sha256)
+				throw new Error('Recorded tool evidence changed.')
+			const event = JSON.parse(decode(raw)) as Record<string, unknown>
+			if (event.runId !== runId || event.seq !== pointer.seq)
+				throw new Error('Recorded text identity changed.')
+			saved = {
+				offset: pointer.offset,
+				length: pointer.length,
+				sha256: pointer.sha256,
+				seq: pointer.seq,
+				event,
+				parts: eventTexts(event),
+				archive:
+					event.type === 'compaction_archive' ? compactionArchiveSchema.parse(event) : undefined,
+			}
+		}
+		return sourceText(pointer, runDir, budget, saved)
+	}
+}
+
+async function sourceText(
+	pointer: z.infer<typeof textPointerSchema>,
+	runDir: string,
+	budget: EvidenceBudget,
+	{ event, parts, archive }: TextRecord,
+): Promise<TextSource> {
+	const part = parts[pointer.part]
+	if (!part) throw new Error('Recorded text part is unavailable.')
+	const tool = event.type === 'tool_completed'
+	const archivedPart = archive?.archive.parts[pointer.part]
+	if (archive && !archivedPart) throw new Error('Missing archived text part.')
+	const entry = entrySchema.parse({
+		...pointer,
+		source: part.source,
+		...(tool
+			? {
+					toolName: z.string().parse(event.toolName),
+					toolUseId: z.string().parse(event.toolUseId),
+					isError: z.boolean().parse(event.isError),
+					spill: event.outputSpillIntegrity,
+				}
+			: { toolName: part.toolName, isError: part.isError }),
+		truncated: tool && event.outputTruncated === true,
+		...(archivedPart ? { spill: archivedPart.manifest } : {}),
+		filter: '',
+	})
+
+	if (!entry.spill) {
+		const bytes = Buffer.from(part.text, 'utf8')
+		return {
+			entry,
+			recordedAt: evidenceRecordedAt(event.timestamp),
+			bytes: bytes.length,
+			chars: part.text.length,
+			retained: entry.truncated ? 'preview' : 'full',
+			chunks: 1,
+			mayMatch: () => true,
+			window: async () => ({ bytes, offset: 0, characterOffset: 0 }),
+		}
+	}
+	// Never follow a model/provider-controlled spill path from the event.
+	let path: string
+	if (archive) path = compactionPartPath(runDir, archive.archive.id, pointer.part)
+	else {
+		if (!entry.toolUseId) throw new Error('Retained output has no tool identity.')
+		path = join(runDir, 'tool-output', `${digest(entry.toolUseId)}.txt`)
+	}
+	const rawManifest = await readSmall(`${path}.manifest.json`, budget)
+	if (digest(rawManifest) !== entry.spill) throw new Error('Retained output manifest changed.')
+	const manifest = manifestSchema.parse(JSON.parse(decode(rawManifest)))
+	if (manifest.chunks.length !== Math.ceil(manifest.bytes / EVIDENCE_CHUNK_BYTES))
+		throw new Error('Incomplete retained output manifest.')
+	return {
+		entry,
+		recordedAt: evidenceRecordedAt(event.timestamp),
+		bytes: manifest.bytes,
+		chars: manifest.chars,
+		retained: 'full',
+		chunks: Math.max(1, manifest.chunks.length),
+		mayMatch: (chunk, query, matchMode = 'literal', caseSensitive = true) => {
+			const part = manifest.chunks[chunk]
+			if (!part) return query === ''
+			if (matchMode === 'token')
+				return (
+					mayContainToken(part.tokenFilter, query) &&
+					(!caseSensitive || mayContain(part.filter, query))
+				)
+			return !caseSensitive || mayContain(part.filter, query)
+		},
+		async window(chunk, preceding = false) {
+			const file = await openEvidence(path)
+			try {
+				const before = await file.stat()
+				if (before.size !== manifest.bytes) throw new Error('Retained output size changed.')
+				const pieces: Buffer[] = []
+				// A token boundary needs the previous code point. Authenticate its
+				// entire chunk and charge that read; never trust an unverified byte.
+				const first = preceding && chunk > 0 ? chunk - 1 : chunk
+				for (let index = first; index < Math.min(chunk + 2, manifest.chunks.length); index++) {
+					const bytes = await readBytes(
+						file,
+						index * EVIDENCE_CHUNK_BYTES,
+						Math.min(EVIDENCE_CHUNK_BYTES, manifest.bytes - index * EVIDENCE_CHUNK_BYTES),
+						budget,
+					)
+					if (digest(bytes) !== manifest.chunks[index]?.sha256)
+						throw new Error('Retained output bytes changed.')
+					pieces.push(bytes)
+				}
+				if (
+					stamp(before) !== stamp(await file.stat()) ||
+					stamp(before) !== stamp(await lstat(path))
+				)
+					throw new Error('Retained output changed during read.')
+				const all = Buffer.concat(pieces)
+				const ownedStart = (chunk - first) * EVIDENCE_CHUNK_BYTES
+				let contentStart = ownedStart
+				while (contentStart < all.length && ((all[contentStart] ?? 0) & 0xc0) === 0x80)
+					contentStart++
+				let start = contentStart
+				if (preceding && chunk > 0) {
+					start--
+					while (start > 0 && ((all[start] ?? 0) & 0xc0) === 0x80) start--
+				}
+				const prefixChars = decode(all.subarray(start, contentStart)).length
+				const characterOffset =
+					manifest.chunks[chunk]?.characterOffset ?? (chunk === 0 ? 0 : undefined)
+				return {
+					bytes: utf8Page(
+						all.subarray(start),
+						ownedStart + EVIDENCE_CHUNK_BYTES + SEARCH_OVERLAP_BYTES - start,
+					),
+					offset: first * EVIDENCE_CHUNK_BYTES + start,
+					characterOffset:
+						characterOffset === undefined ? undefined : characterOffset - prefixChars,
+					searchFrom: prefixChars,
+				}
+			} finally {
+				await file.close()
+			}
+		},
+	}
+}
+
+export async function readTextPage(
+	source: TextSource,
+	scope: RunEvidenceScope,
+	offset: number,
+	budget: EvidenceBudget,
+): Promise<RunTextEvidenceReadResult> {
+	const entry = source.entry
+	if (offset > source.bytes) throw new Error('Offset exceeds retained text.')
+	const chunk = entry.spill
+		? Math.min(Math.floor(offset / EVIDENCE_CHUNK_BYTES), source.chunks - 1)
+		: 0
+	const window = await source.window(chunk)
+	if (offset < window.offset) throw new Error('Offset splits a UTF-8 character.')
+	const bytes = window.bytes.subarray(offset - window.offset)
+	let text = decode(utf8Page(bytes, 24_000))
+	if (text.length > 6000) {
+		let end = 6000
+		if (/[\uDC00-\uDFFF]/.test(text[end] ?? '')) end--
+		text = text.slice(0, end)
+	}
+	const next = offset + Buffer.byteLength(text)
+	if (next === offset && offset < source.bytes) throw new Error('Text page did not advance.')
+	return {
+		scope,
+		recordedAt: source.recordedAt,
+		seq: entry.seq,
+		source: entry.source,
+		part: entry.part,
+		characterOffset:
+			window.characterOffset === undefined
+				? undefined
+				: window.characterOffset + decode(window.bytes.subarray(0, offset - window.offset)).length,
+		totalChars: source.chars,
+		toolName: entry.toolName,
+		isError: entry.isError,
+		retained: source.retained,
+		text,
+		byteOffset: offset,
+		nextByteOffset: next < source.bytes ? next : null,
+		totalBytes: source.bytes,
+		scannedBytes: budget.bytes,
+	}
+}

package/src/store/evidence/types.ts

@@ -0,0 +1,177 @@
+/** @experimental An explicitly authorized invocation. No directory discovery. */
+export interface RunEvidenceScope {
+	readonly tenantId: string
+	readonly projectId: string
+	readonly sessionId: string
+	readonly runId: string
+}
+
+/** @experimental Cache and run directories must be private and host-owned. */
+export interface DiskRunEvidenceOptions {
+	readonly scope: RunEvidenceScope
+	readonly runDir: string
+	readonly indexDir: string
+	/** Optional smaller I/O ceiling per operation, in bytes (1–8 MiB). */
+	readonly maxReadBytes?: number
+	/**
+	 * Disk readers default to closed runs. Snapshot mode also reads explicitly
+	 * scoped nonterminal runs, checking file/metadata stamps before and after
+	 * every operation. It neither claims a writer is dead nor resumes it.
+	 * Appends or metadata changes invalidate continuations and addresses.
+	 * Nonterminal search results remain incomplete even at the snapshot end.
+	 * An incomplete final JSONL fragment is excluded without changing the file;
+	 * the backward boundary scan is capped at one record (4 MiB) and billed.
+	 */
+	readonly consistency?: 'closed' | 'snapshot'
+}
+
+/** @experimental Literal search; empty query browses tool records. */
+export interface RunEvidenceSearchOptions {
+	/** Optional per-call ceiling, 1–8 MiB. Cannot raise the source's own ceiling.
+	 * Not part of search identity; a continuation may use a different allowance.
+	 */
+	readonly maxReadBytes?: number
+	readonly query?: string
+	/**
+	 * Find passages matching any of 1–16 nonblank literal terms (up to 256 UTF-16
+	 * units each) in the same bounded scan. Mutually exclusive with query, even
+	 * an empty query. Exact duplicate terms and their order do not matter.
+	 * This is candidate discovery, not relevance ranking or natural-language parsing.
+	 */
+	readonly terms?: readonly string[]
+	/** With a cursor and its original token terms, continue at that position using
+	 * a strict nonempty subset. Requires supportsTermRefinement. The returned
+	 * cursor is bound to the subset; the original cursor remains usable.
+	 */
+	readonly refineTerms?: readonly string[]
+	/**
+	 * Defaults to literal substring matching. Token mode accepts only single
+	 * Unicode letter/number/underscore tokens and matches complete tokens.
+	 * Case-insensitive tokens use toLowerCase(), as bounded evidence ranking does.
+	 * Empty-query browsing and phrases require literal mode. Bound into cursors.
+	 */
+	readonly matchMode?: 'literal' | 'token'
+	/** Defaults to true. False uses the selected mode's case rules (see matchMode). */
+	readonly caseSensitive?: boolean
+	/**
+	 * Omit successful results from these exact tool names during search. At most
+	 * 16 names, each 1–256 UTF-16 units. Errors and unknown provenance remain.
+	 * Bound into cursors; exact reads are unchanged. Default: exclude nothing.
+	 */
+	readonly excludeSuccessfulTools?: readonly string[]
+	readonly cursor?: string
+}
+
+/** @experimental Opaque addresses remain usable after restart while the source is unchanged. */
+export interface RunEvidenceMatch {
+	readonly address: string
+	readonly seq: number
+	/** Stored event wall-clock Unix milliseconds; absent/invalid/zero stamps remain unknown.
+	 * This dates archive recording, not the facts in its text. Clocks can differ or move backwards.
+	 */
+	readonly recordedAt?: number
+	readonly toolName: string
+	readonly isError: boolean
+	readonly retained: 'full' | 'preview'
+	readonly excerpt: string
+	/** True only when the excerpt contains the whole full-retained text part.
+	 * False includes partial text and retained previews; absent is unknown.
+	 * This says nothing about other parts, scan completeness or source truth.
+	 */
+	readonly excerptComplete?: boolean
+	readonly byteOffset: number
+}
+
+/** @experimental An empty bounded page does not imply absence. Follow nextCursor. */
+export interface RunEvidenceSearchResult {
+	readonly scope: RunEvidenceScope
+	readonly matches: readonly RunEvidenceMatch[]
+	readonly nextCursor: string | null
+	readonly scannedBytes: number
+	readonly indexedRecords: number
+	readonly cacheHit: boolean
+	readonly incomplete: boolean
+	readonly unavailable: readonly string[]
+	/** Successful tool-result visits omitted by this page's filter; not unique facts. */
+	readonly excludedToolResults?: number
+}
+
+/** @experimental Byte offsets refer to UTF-8 retained text, not the current workspace file. */
+export interface RunEvidenceReadOptions {
+	readonly address: string
+	readonly byteOffset?: number
+	/** Optional per-call ceiling, 1–8 MiB, capped by the source's own ceiling. */
+	readonly maxReadBytes?: number
+}
+
+/** @experimental Full means retained text, not binary blocks or proof an action succeeded. */
+export interface RunEvidenceReadResult {
+	readonly scope: RunEvidenceScope
+	readonly seq: number
+	/** Same stored-event wall-clock semantics as RunEvidenceMatch.recordedAt. */
+	readonly recordedAt?: number
+	readonly toolName: string
+	readonly isError: boolean
+	readonly retained: 'full' | 'preview'
+	readonly text: string
+	readonly byteOffset: number
+	readonly nextByteOffset: number | null
+	readonly totalBytes: number
+	readonly scannedBytes: number
+}
+
+/** @experimental Retrieval only: never re-executes a tool or resumes a run. */
+export interface RunEvidenceSource {
+	readonly scope: RunEvidenceScope
+	readonly supportsTermRefinement?: boolean
+	search(options?: RunEvidenceSearchOptions, signal?: AbortSignal): Promise<RunEvidenceSearchResult>
+	read(options: RunEvidenceReadOptions, signal?: AbortSignal): Promise<RunEvidenceReadResult>
+}
+
+/** @experimental Textual event parts, including assistant output and shed conversation messages. */
+export interface RunTextEvidenceSearchOptions extends RunEvidenceSearchOptions {
+	/** Omit explicitly marked derived summaries. Default false; bound into cursors. Exact reads remain available. */
+	readonly excludeDerivedSummaries?: boolean
+	readonly seq?: number
+	readonly part?: number
+	readonly limit?: number
+}
+
+/** @experimental Event identity is durable; byteOffset starts a bounded excerpt in the retained text. */
+export interface RunTextEvidenceMatch extends Omit<RunEvidenceMatch, 'toolName' | 'isError'> {
+	readonly source: string
+	readonly part: number
+	readonly toolName?: string
+	readonly isError?: boolean
+	/** UTF-16 position, when the authenticated source includes a character index. */
+	readonly characterOffset?: number
+}
+
+/** @experimental Search includes messages and tool text, never binary or private reasoning blocks. */
+export interface RunTextEvidenceSearchResult extends Omit<RunEvidenceSearchResult, 'matches'> {
+	readonly matches: readonly RunTextEvidenceMatch[]
+	/** Derived-summary part visits deliberately skipped, not unique facts or matched passages. */
+	readonly excludedSummaries?: number
+}
+
+/** @experimental Character counts are UTF-16 units; absent counts must not be inferred from bytes. */
+export interface RunTextEvidenceReadResult
+	extends Omit<RunEvidenceReadResult, 'toolName' | 'isError'> {
+	readonly source: string
+	readonly part: number
+	readonly toolName?: string
+	readonly isError?: boolean
+	readonly characterOffset?: number
+	readonly totalChars?: number
+}
+
+/** @experimental Scope-bound, bounded text retrieval across an invocation's event stream. */
+export interface RunTextEvidenceSource {
+	readonly scope: RunEvidenceScope
+	readonly supportsTermRefinement?: boolean
+	search(
+		options?: RunTextEvidenceSearchOptions,
+		signal?: AbortSignal,
+	): Promise<RunTextEvidenceSearchResult>
+	read(options: RunEvidenceReadOptions, signal?: AbortSignal): Promise<RunTextEvidenceReadResult>
+}

package/src/store/memory/disk.ts

@@ -149,6 +149,8 @@ function assertMemoryContent(value: unknown, expectedId: MemoryId): asserts valu
 
 export interface DiskMemoryStoreConfig {
 	baseDir: string
+	/** Exact memory directory; defaults to `baseDir/memory`. Hosts can partition by workspace. */
+	directory?: string
 	logger?: Logger
 	/** Maximum wait for another process's operation; default 10 seconds. Never breaks stale locks. */
 	lockTimeoutMs?: number
@@ -168,7 +170,8 @@ export class DiskMemoryStore implements MemoryStore {
 	private readonly indexRecords = new DiskRecordStore<unknown>(SCHEMA)
 
 	constructor(config: DiskMemoryStoreConfig) {
-		this.baseDir = join(config.baseDir, 'memory')
+		this.baseDir =
+			config.directory === undefined ? join(config.baseDir, 'memory') : resolve(config.directory)
 		this.log = resolveLogger(config.logger).child({ [SCOPE_ATTRIBUTE]: 'store/memory/disk' })
 		this.lockTimeoutMs = config.lockTimeoutMs ?? DEFAULT_MEMORY_LOCK_TIMEOUT_MS
 		validateMemoryLockTimeout(this.lockTimeoutMs)

package/src/store/run/disk.ts

@@ -1,4 +1,5 @@
-import { appendFile, mkdir, readFile, readdir, unlink } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+import { appendFile, mkdir, readFile, readdir, stat, unlink } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js'
 import type { Message } from '../../types/message/index.js'
@@ -16,10 +17,22 @@ import type {
 	RunStore,
 } from '../../types/run/store.js'
 import { atomicWriteFile } from '../../utils/atomic-write.js'
+import { awaitWithAbort } from '../../utils/await-with-abort.js'
 import { asCheckpointId, asRunId } from '../../utils/id.js'
 import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
 import { type Logger, resolveLogger } from '../../utils/logger.js'
+import { restoreCompactionRecord, retainCompactionRecord } from '../evidence/compaction-archive.js'
+import { digest } from '../evidence/format.js'
+import { createLinkedRunTextEvidenceSource } from '../evidence/linked.js'
+import {
+	type RecordPointer,
+	hasEvidenceText,
+	recordPointerSchema,
+	transcriptTail,
+} from '../evidence/record-chain.js'
+import type { RunEvidenceScope, RunTextEvidenceSource } from '../evidence/types.js'
 import { defineSchema, migrate, stamp } from '../schema.js'
+import { readToolExecutionsIn } from './tool-executions.js'
 
 /**
  * This store's on-disk format, versioned as a unit — which is how a
@@ -48,9 +61,22 @@ const CHECKPOINT_SCHEMA = defineSchema({
 export type { CompletedToolRecord }
 
 export class RunDiskStore implements RunStore {
+	async readToolExecutions(ids: readonly string[], signal?: AbortSignal) {
+		return readToolExecutionsIn(
+			join(this.requireInit(), 'transcript.jsonl'),
+			this.boundRunId!,
+			ids,
+			signal,
+		)
+	}
 	private baseDir: string
 	private runDir: string | null = null
 	private log: Logger
+	private eventLock: Promise<void> = Promise.resolve()
+	private evidenceTip: RecordPointer | undefined
+	private evidenceTextTip: RecordPointer | null | undefined
+	private evidenceEpoch = randomUUID()
+	private boundRunId: string | undefined
 	private indexLock: Promise<void> = Promise.resolve()
 
 	constructor(config: RunStoreConfig) {
@@ -76,19 +102,94 @@ export class RunDiskStore implements RunStore {
 		await mkdir(this.runDir, { recursive: true })
 		await healTornTranscript(this.runDir)
 		await healTornAuditTrail(this.runDir)
+		this.boundRunId = runId
+		this.evidenceEpoch = randomUUID()
+		const tail = await transcriptTail(join(this.runDir, 'transcript.jsonl'), runId)
+		this.evidenceTip = tail?.tip
+		this.evidenceTextTip = tail?.textTip
 		this.log.info('Run directory created', { 'namzu.run.dir': this.runDir })
 		return this.runDir
 	}
 
-	async appendEvent(event: RunEvent): Promise<void> {
-		const dir = this.requireInit()
+	private withEventLock<T>(operation: () => Promise<T>): Promise<T> {
+		const next = this.eventLock.then(operation)
+		this.eventLock = next.then(
+			() => {},
+			() => {},
+		)
+		return next
+	}
 
-		const line = `${JSON.stringify({
-			...event,
-			timestamp: Date.now(),
-		})}\n`
+	async appendEvent(event: RunEvent): Promise<void> {
+		return this.withEventLock(async () => {
+			const storedEvent = await retainCompactionRecord(event, this.requireInit())
+			const path = join(this.requireInit(), 'transcript.jsonl')
+			const before = await stat(path).catch((error: NodeJS.ErrnoException) => {
+				if (error.code === 'ENOENT') return { size: 0 }
+				throw error
+			})
+			const previous = this.evidenceTip
+			const linked =
+				event.runId === this.boundRunId &&
+				previous &&
+				previous.offset + previous.length === before.size &&
+				previous.seq + 1 === event.seq
+			const previousTextRecord = linked
+				? this.evidenceTextTip
+				: before.size === 0 && event.seq === 1 && event.type === 'run_started'
+					? null
+					: undefined
+			const line = Buffer.from(
+				`${JSON.stringify({
+					...storedEvent,
+					timestamp: Date.now(),
+					previousRecord: linked ? previous : null,
+					previousTextRecord,
+				})}\n`,
+			)
+			await appendFile(path, line)
+			const pointer = recordPointerSchema.safeParse({
+				offset: before.size,
+				length: line.length,
+				sha256: digest(line),
+				seq: event.seq,
+			})
+			this.evidenceTip =
+				event.runId === this.boundRunId && pointer.success ? pointer.data : undefined
+			// Include chain boundaries as well as text. This prevents a later skip
+			// from hiding an incomplete history or a malformed content record.
+			this.evidenceTextTip = this.evidenceTip
+				? !linked || hasEvidenceText(JSON.parse(line.toString('utf8')))
+					? this.evidenceTip
+					: previousTextRecord
+				: undefined
+		})
+	}
 
-		await appendFile(join(dir, 'transcript.jsonl'), line, 'utf-8')
+	/** Capture a writer-owned, immutable read boundary between complete appends. */
+	async captureTextEvidence(
+		scope: RunEvidenceScope,
+		maxReadBytes?: number,
+		signal?: AbortSignal,
+	): Promise<RunTextEvidenceSource | undefined> {
+		signal?.throwIfAborted()
+		const capture = this.withEventLock(async () => {
+			signal?.throwIfAborted()
+			if (scope.runId !== this.boundRunId)
+				throw new Error('Evidence capture does not own this run.')
+			if (!this.evidenceTip) return undefined
+			const runDir = this.requireInit()
+			const before = await stat(join(runDir, 'transcript.jsonl'))
+			signal?.throwIfAborted()
+			const tip = { ...this.evidenceTip }
+			if (before.size < tip.offset + tip.length)
+				throw new Error('Evidence transcript was shortened.')
+			return createLinkedRunTextEvidenceSource(
+				{ scope, runDir, indexDir: join(runDir, 'evidence-index'), maxReadBytes },
+				{ tip, identity: `${before.dev}:${before.ino}`, epoch: this.evidenceEpoch },
+			)
+		})
+		return awaitWithAbort(capture, signal)
 	}
 
 	async readEvents(options?: ReadRunEventsOptions): Promise<readonly PersistedRunEvent[]> {
@@ -461,6 +562,7 @@ export async function readRunEventsIn(
 		}
 		previousSeq = seq
 		if (seq <= sinceSeq) continue
+		parsed = await restoreCompactionRecord(parsed, runDir)
 
 		events.push({
 			...parsed,

package/src/store/run/memory.ts

@@ -7,6 +7,7 @@ import type {
 	RunMessageSnapshot,
 	RunStore,
 } from '../../types/run/store.js'
+import { ToolExecutionCollector } from './tool-executions.js'
 
 /**
  * Process-local {@link RunStore}: a run's evidence with no filesystem.
@@ -23,6 +24,15 @@ import type {
  * environments with no writable filesystem at all.
  */
 export class InMemoryRunStore implements RunStore {
+	async readToolExecutions(ids: readonly string[], signal?: AbortSignal) {
+		signal?.throwIfAborted()
+		const collector = new ToolExecutionCollector(this.requireInit(), ids)
+		for (const event of this.events) {
+			signal?.throwIfAborted()
+			collector.accept(event)
+		}
+		return collector.finish()
+	}
 	private runId: string | null = null
 	private parentRunId: string | undefined
 	private meta: Run | null = null