@namzu/sdk 43.0.0 → 44.1.0

package/src/store/evidence/index-page.ts

@@ -1,21 +1,10 @@
-import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
-import { link, mkdir, rename, unlink, writeFile } from 'node:fs/promises'
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto'
 import type { FileHandle } from 'node:fs/promises'
-import { dirname, join } from 'node:path'
 import { z } from 'zod'
-import { compactionArchiveSchema } from './compaction-archive.js'
 import type { CompactedToolMetadata } from './compaction-provenance.js'
 import { compactedTexts } from './compaction-text.js'
 import { digest, textFilter, tokenFilter } from './format.js'
-import {
-	type EvidenceBudget,
-	EvidencePageLimit,
-	RECORD_BYTES,
-	decode,
-	noLinks,
-	readBytes,
-	readSmall,
-} from './io.js'
+import { type EvidenceBudget, RECORD_BYTES, decode, readBytes } from './io.js'
 
 const integer = z.number().int().nonnegative().safe()
 export const entrySchema = z.object({
@@ -23,6 +12,8 @@ export const entrySchema = z.object({
 	length: integer.max(RECORD_BYTES),
 	sha256: z.string().regex(/^[a-f0-9]{64}$/),
 	seq: integer,
+	/** The turn the record belongs to; absent for a record outside any turn. */
+	turnId: z.string().uuid().optional(),
 	source: z.enum([
 		'tool_completed',
 		'message_completed',
@@ -51,64 +42,31 @@ export const positionSchema = z.object({
 	textIndex: integer.default(0),
 })
 export type IndexPosition = z.infer<typeof positionSchema>
-const pageSchema = z.object({
-	start: positionSchema,
-	entries: z.array(entrySchema).max(64),
-	next: positionSchema.nullable(),
-	records: integer.max(64),
-})
-export type IndexPage = z.infer<typeof pageSchema>
+export interface IndexPage {
+	start: IndexPosition
+	entries: IndexEntry[]
+	next: IndexPosition | null
+	records: number
+}
 
+/** Seals addresses and cursors to one scope and one state of the source. */
 export interface EvidenceSeal {
 	pack(value: unknown): string
 	unpack(value: string): unknown
-	dir: string
 }
 
-export async function evidenceSeal(
-	root: string,
-	scopeKey: string,
-	sourceKey: string,
-	budget: EvidenceBudget,
-): Promise<EvidenceSeal> {
-	try {
-		await noLinks(root)
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
-		await noLinks(dirname(root))
-		try {
-			await mkdir(root, { mode: 0o700 })
-		} catch (error) {
-			if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
-		}
-		await noLinks(root)
-	}
-	const dir = join(root, scopeKey)
-	await mkdir(dir, { mode: 0o700, recursive: true })
-	await noLinks(dir)
-	const keyPath = join(dir, 'key')
-	let key: Buffer
-	try {
-		key = await readSmall(keyPath, budget, 32)
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
-		const candidate = `${keyPath}.${randomBytes(8).toString('hex')}.tmp`
-		await writeFile(candidate, randomBytes(32), { flag: 'wx', mode: 0o600 })
-		try {
-			try {
-				await link(candidate, keyPath)
-			} catch (error) {
-				if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
-			}
-		} finally {
-			await unlink(candidate)
-		}
-		key = await readSmall(keyPath, budget, 32)
-	}
-	if (key.length !== 32) throw new Error('Incomplete evidence index key.')
+/**
+ * The seal of one session log. Its key is derived from the log's first
+ * record, so an address or cursor stays valid across a restart while the
+ * source is unchanged, and never validates against another session.
+ */
+export function evidenceSeal(sessionStart: Uint8Array, sourceKey: string): EvidenceSeal {
+	const key = createHash('sha256')
+		.update('namzu-session-evidence-v1\n')
+		.update(sessionStart)
+		.digest()
 	const mac = (value: string) => createHmac('sha256', key).update(`${sourceKey}\n${value}`).digest()
 	return {
-		dir,
 		pack(value) {
 			const body = Buffer.from(JSON.stringify(value)).toString('base64url')
 			return `${body}.${mac(body).toString('base64url')}`
@@ -125,93 +83,70 @@ export async function evidenceSeal(
 }
 
 export function toolEntry(
-	event: Record<string, unknown>,
+	record: Record<string, unknown>,
 	offset: number,
 	bytes: Buffer,
 ): IndexEntry | null {
-	if (event.type !== 'tool_completed') return null
+	if (record.type !== 'tool_completed') return null
 	if (
-		typeof event.result !== 'string' ||
-		typeof event.isError !== 'boolean' ||
-		typeof event.toolName !== 'string' ||
-		typeof event.toolUseId !== 'string'
+		typeof record.result !== 'string' ||
+		typeof record.isError !== 'boolean' ||
+		typeof record.toolName !== 'string' ||
+		typeof record.toolUseId !== 'string'
 	)
 		throw new Error('Malformed tool evidence.')
 	return entrySchema.parse({
 		offset,
 		length: bytes.length,
 		sha256: digest(bytes),
-		seq: event.seq,
+		seq: record.seq,
+		...(typeof record.turnId === 'string' ? { turnId: record.turnId } : {}),
 		source: 'tool_completed',
 		part: 0,
-		toolName: event.toolName,
-		toolUseId: event.toolUseId,
-		isError: event.isError,
-		truncated: event.outputTruncated === true,
-		...(typeof event.outputSpillIntegrity === 'string'
-			? { spill: event.outputSpillIntegrity }
+		toolName: record.toolName,
+		toolUseId: record.toolUseId,
+		isError: record.isError,
+		truncated: record.outputTruncated === true,
+		...(typeof record.outputSpillIntegrity === 'string'
+			? { spill: record.outputSpillIntegrity }
 			: {}),
-		filter: textFilter(event.result),
-		tokenFilter: tokenFilter(event.result),
+		filter: textFilter(record.result),
+		tokenFilter: tokenFilter(record.result),
 	})
 }
 
-/** Validate all textual parts before publishing any part of a record. */
-export function eventTexts(
-	event: Record<string, unknown>,
+/** Validate all textual parts of a record before publishing any part of it. */
+export function recordTexts(
+	record: Record<string, unknown>,
 ): ({ source: string; text: string } & CompactedToolMetadata)[] {
-	if (event.type === 'compaction_archive') {
-		return compactionArchiveSchema.parse(event).archive.parts.map((part) => ({
-			source: `compaction_shed:${part.role === 'system' && part.summary ? 'summary' : part.role}`,
-			text: '',
-			...(part.role === 'tool' ? { toolName: part.toolName, isError: part.isError } : {}),
-		}))
+	if (record.type === 'tool_completed') {
+		if (typeof record.result !== 'string') throw new Error('Invalid tool text.')
+		return [{ source: 'tool_completed', text: record.result }]
 	}
-	if (event.type === 'tool_completed') {
-		if (typeof event.result !== 'string') throw new Error('Invalid tool text.')
-		return [{ source: 'tool_completed', text: event.result }]
+	if (record.type === 'message_completed') {
+		if (record.content === undefined) return []
+		if (typeof record.content !== 'string') throw new Error('Invalid message text.')
+		return [{ source: 'message_completed', text: record.content }]
 	}
-	if (event.type === 'message_completed') {
-		if (event.content === undefined) return []
-		if (typeof event.content !== 'string') throw new Error('Invalid message text.')
-		return [{ source: 'message_completed', text: event.content }]
-	}
-	if (event.type !== 'compaction_shed') return []
-	return compactedTexts(event.messages).map(({ role, summary, ...part }) => ({
+	if (record.type !== 'compaction_shed') return []
+	return compactedTexts(record.messages).map(({ role, summary, ...part }) => ({
 		source: `compaction_shed:${summary ? 'summary' : role}`,
 		...part,
 	}))
 }
 
-/** Each cache page indexes at most 64 records, 64 textual parts and 4 MiB of input. */
+/**
+ * Index the text of at most 64 records (64 textual parts, 4 MiB of input)
+ * from `start`. Every record must belong to the session and continue the
+ * log's seq; the first must be `session_started`.
+ */
 export async function indexPage(
 	handle: FileHandle,
 	size: number,
-	runId: string,
+	sessionId: string,
 	start: IndexPosition,
-	seal: EvidenceSeal,
-	sourceKey: string,
 	budget: EvidenceBudget,
 ): Promise<{ page: IndexPage; cacheHit: boolean }> {
-	const path = join(
-		seal.dir,
-		`${digest(`${sourceKey}:${start.offset}:${start.seq}:${start.textIndex}:summary-provenance-v1:${process.version}:${process.versions.v8}:${process.versions.unicode}`)}.page`,
-	)
-	try {
-		const cached = await readSmall(path, budget, 512 * 1024)
-		const page = pageSchema.parse(seal.unpack(decode(cached)))
-		if (
-			page.start.offset !== start.offset ||
-			page.start.seq !== start.seq ||
-			page.start.textIndex !== start.textIndex
-		)
-			throw new Error('Index page position mismatch.')
-		return { page, cacheHit: true }
-	} catch (error) {
-		budget.signal?.throwIfAborted()
-		if (error instanceof EvidencePageLimit) throw error
-		// The cache is disposable. A missing, damaged or incompatible page is rebuilt.
-	}
 	let offset = start.offset
 	let seq = start.seq
 	let textIndex = start.textIndex
@@ -224,7 +159,7 @@ export async function indexPage(
 		let newline = buffered.indexOf(10)
 		while (newline < 0) {
 			if (buffered.length >= RECORD_BYTES || readOffset >= size)
-				throw new Error('Oversized or torn transcript record; history is incomplete.')
+				throw new Error('Oversized or torn session log record; history is incomplete.')
 			const count = Math.min(65_536, size - readOffset, RECORD_BYTES - buffered.length)
 			if (readOffset - start.offset + count > RECORD_BYTES && records > 0) break
 			buffered = Buffer.concat([buffered, await readBytes(handle, readOffset, count, budget)])
@@ -233,41 +168,37 @@ export async function indexPage(
 		}
 		if (newline < 0) break
 		const raw = buffered.subarray(0, newline + 1)
-		const event = JSON.parse(decode(raw)) as Record<string, unknown>
+		const record = JSON.parse(decode(raw)) as Record<string, unknown>
 		if (
-			event.runId !== runId ||
-			event.seq !== seq + 1 ||
-			typeof event.type !== 'string' ||
-			(offset === 0 && event.type !== 'run_started')
+			record.sessionId !== sessionId ||
+			record.seq !== seq + 1 ||
+			typeof record.type !== 'string' ||
+			(offset === 0 && record.type !== 'session_started')
 		)
-			throw new Error('Transcript identity or event sequence is invalid.')
-		const parts = eventTexts(event)
-		const archive =
-			event.type === 'compaction_archive' ? compactionArchiveSchema.parse(event) : undefined
+			throw new Error('Session log identity or record sequence is invalid.')
+		const parts = recordTexts(record)
 		if (textIndex > parts.length) throw new Error('Invalid textual part position.')
 		const hash = digest(raw)
-		const tool = toolEntry(event, offset, raw)
+		const tool = toolEntry(record, offset, raw)
 		records++
 		while (textIndex < parts.length && entries.length < 64) {
 			const part = parts[textIndex]
 			if (!part) throw new Error('Invalid textual part.')
-			const archivedPart = archive?.archive.parts[textIndex]
-			if (archive && !archivedPart) throw new Error('Missing archived text part.')
 			entries.push(
 				tool ??
 					entrySchema.parse({
 						offset,
 						length: raw.length,
 						sha256: hash,
-						seq: event.seq,
+						seq: record.seq,
+						...(typeof record.turnId === 'string' ? { turnId: record.turnId } : {}),
 						source: part.source,
 						toolName: part.toolName,
 						isError: part.isError,
 						part: textIndex,
 						truncated: false,
-						...(archivedPart ? { spill: archivedPart.manifest } : {}),
 						filter: textFilter(part.text),
-						tokenFilter: archivedPart ? undefined : tokenFilter(part.text),
+						tokenFilter: tokenFilter(part.text),
 					}),
 			)
 			textIndex++
@@ -284,9 +215,5 @@ export async function indexPage(
 		records,
 		next: offset < size ? { offset, seq, textIndex } : null,
 	}
-	const temp = `${path}.${randomBytes(8).toString('hex')}.tmp`
-	budget.signal?.throwIfAborted()
-	await writeFile(temp, seal.pack(page), { flag: 'wx', mode: 0o600 })
-	await rename(temp, path)
 	return { page, cacheHit: false }
 }

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

@@ -3,7 +3,6 @@ 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,
@@ -11,7 +10,7 @@ import {
 	mayContain,
 	mayContainToken,
 } from './format.js'
-import { type IndexEntry, entrySchema, eventTexts } from './index-page.js'
+import { type IndexEntry, entrySchema, recordTexts } from './index-page.js'
 import {
 	type EvidenceBudget,
 	decode,
@@ -21,7 +20,7 @@ import {
 	stamp,
 	utf8Page,
 } from './io.js'
-import type { RunEvidenceScope, RunTextEvidenceReadResult } from './types.js'
+import type { SessionEvidenceScope, SessionTextEvidenceReadResult } from './types.js'
 
 const integer = z.number().int().nonnegative().safe()
 export const textPointerSchema = entrySchema.pick({
@@ -73,15 +72,14 @@ interface TextRecord {
 	sha256: string
 	seq: number
 	event: Record<string, unknown>
-	parts: ReturnType<typeof eventTexts>
-	archive?: z.infer<typeof compactionArchiveSchema>
+	parts: ReturnType<typeof recordTexts>
 }
 
 /** One authenticated record per operation, never shared between calls or sources. */
 export function createTextSourceReader(
 	handle: FileHandle,
-	runDir: string,
-	runId: string,
+	sessionDir: string,
+	sessionId: string,
 	budget: EvidenceBudget,
 ): (pointer: z.infer<typeof textPointerSchema>, verifiedRecord?: Buffer) => Promise<TextSource> {
 	let saved: TextRecord | undefined
@@ -99,7 +97,7 @@ export function createTextSourceReader(
 			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)
+			if (event.sessionId !== sessionId || event.seq !== pointer.seq)
 				throw new Error('Recorded text identity changed.')
 			saved = {
 				offset: pointer.offset,
@@ -107,28 +105,28 @@ export function createTextSourceReader(
 				sha256: pointer.sha256,
 				seq: pointer.seq,
 				event,
-				parts: eventTexts(event),
-				archive:
-					event.type === 'compaction_archive' ? compactionArchiveSchema.parse(event) : undefined,
+				parts: recordTexts(event),
 			}
 		}
-		return sourceText(pointer, runDir, budget, saved)
+		return sourceText(pointer, sessionDir, budget, saved)
 	}
 }
 
 async function sourceText(
 	pointer: z.infer<typeof textPointerSchema>,
-	runDir: string,
+	sessionDir: string,
 	budget: EvidenceBudget,
-	{ event, parts, archive }: TextRecord,
+	{ event, parts }: 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 recordedAt = evidenceRecordedAt(
+		typeof event.ts === 'string' ? Date.parse(event.ts) : undefined,
+	)
 	const entry = entrySchema.parse({
 		...pointer,
+		...(typeof event.turnId === 'string' ? { turnId: event.turnId } : {}),
 		source: part.source,
 		...(tool
 			? {
@@ -139,7 +137,6 @@ async function sourceText(
 				}
 			: { toolName: part.toolName, isError: part.isError }),
 		truncated: tool && event.outputTruncated === true,
-		...(archivedPart ? { spill: archivedPart.manifest } : {}),
 		filter: '',
 	})
 
@@ -147,7 +144,7 @@ async function sourceText(
 		const bytes = Buffer.from(part.text, 'utf8')
 		return {
 			entry,
-			recordedAt: evidenceRecordedAt(event.timestamp),
+			recordedAt,
 			bytes: bytes.length,
 			chars: part.text.length,
 			retained: entry.truncated ? 'preview' : 'full',
@@ -156,13 +153,11 @@ async function sourceText(
 			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`)
-	}
+	// Never follow a model/provider-controlled spill path from the record: the
+	// retained output of a tool call is at `<session-id>/tool-results/`, named
+	// by the digest of its tool-use id.
+	if (!entry.toolUseId) throw new Error('Retained output has no tool identity.')
+	const path = join(sessionDir, 'tool-results', `${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)))
@@ -170,7 +165,7 @@ async function sourceText(
 		throw new Error('Incomplete retained output manifest.')
 	return {
 		entry,
-		recordedAt: evidenceRecordedAt(event.timestamp),
+		recordedAt,
 		bytes: manifest.bytes,
 		chars: manifest.chars,
 		retained: 'full',
@@ -242,10 +237,10 @@ async function sourceText(
 
 export async function readTextPage(
 	source: TextSource,
-	scope: RunEvidenceScope,
+	scope: SessionEvidenceScope,
 	offset: number,
 	budget: EvidenceBudget,
-): Promise<RunTextEvidenceReadResult> {
+): Promise<SessionTextEvidenceReadResult> {
 	const entry = source.entry
 	if (offset > source.bytes) throw new Error('Offset exceeds retained text.')
 	const chunk = entry.spill

package/src/store/evidence/types.ts

@@ -1,32 +1,31 @@
-/** @experimental An explicitly authorized invocation. No directory discovery. */
-export interface RunEvidenceScope {
+/** @experimental An explicitly authorized session, or one turn of it. No directory discovery. */
+export interface SessionEvidenceScope {
 	readonly tenantId: string
 	readonly projectId: string
 	readonly sessionId: string
-	readonly runId: string
+	/** Narrow to one turn. Absent: every turn of the session. */
+	readonly turnId?: string
 }
 
-/** @experimental Cache and run directories must be private and host-owned. */
-export interface DiskRunEvidenceOptions {
-	readonly scope: RunEvidenceScope
-	readonly runDir: string
-	readonly indexDir: string
+/** @experimental The session log must be private and host-owned. */
+export interface SessionEvidenceSourceOptions {
+	readonly scope: SessionEvidenceScope
+	/** The session log (`<session-id>.jsonl`). */
+	readonly logPath: 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.
+	 * Readers default to a session with no active turn. Snapshot mode also
+	 * reads a session whose turn is still running, checking the log head
+	 * before and after every operation. Appends invalidate continuations and
+	 * addresses. Results over an active turn remain incomplete even at the
+	 * snapshot end.
 	 */
 	readonly consistency?: 'closed' | 'snapshot'
 }
 
 /** @experimental Literal search; empty query browses tool records. */
-export interface RunEvidenceSearchOptions {
+export interface SessionEvidenceSearchOptions {
 	/** 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.
 	 */
@@ -63,7 +62,7 @@ export interface RunEvidenceSearchOptions {
 }
 
 /** @experimental Opaque addresses remain usable after restart while the source is unchanged. */
-export interface RunEvidenceMatch {
+export interface SessionEvidenceMatch {
 	readonly address: string
 	readonly seq: number
 	/** Stored event wall-clock Unix milliseconds; absent/invalid/zero stamps remain unknown.
@@ -83,9 +82,9 @@ export interface RunEvidenceMatch {
 }
 
 /** @experimental An empty bounded page does not imply absence. Follow nextCursor. */
-export interface RunEvidenceSearchResult {
-	readonly scope: RunEvidenceScope
-	readonly matches: readonly RunEvidenceMatch[]
+export interface SessionEvidenceSearchResult {
+	readonly scope: SessionEvidenceScope
+	readonly matches: readonly SessionEvidenceMatch[]
 	readonly nextCursor: string | null
 	readonly scannedBytes: number
 	readonly indexedRecords: number
@@ -97,7 +96,7 @@ export interface RunEvidenceSearchResult {
 }
 
 /** @experimental Byte offsets refer to UTF-8 retained text, not the current workspace file. */
-export interface RunEvidenceReadOptions {
+export interface SessionEvidenceReadOptions {
 	readonly address: string
 	readonly byteOffset?: number
 	/** Optional per-call ceiling, 1–8 MiB, capped by the source's own ceiling. */
@@ -105,10 +104,10 @@ export interface RunEvidenceReadOptions {
 }
 
 /** @experimental Full means retained text, not binary blocks or proof an action succeeded. */
-export interface RunEvidenceReadResult {
-	readonly scope: RunEvidenceScope
+export interface SessionEvidenceReadResult {
+	readonly scope: SessionEvidenceScope
 	readonly seq: number
-	/** Same stored-event wall-clock semantics as RunEvidenceMatch.recordedAt. */
+	/** Same stored-event wall-clock semantics as SessionEvidenceMatch.recordedAt. */
 	readonly recordedAt?: number
 	readonly toolName: string
 	readonly isError: boolean
@@ -120,16 +119,22 @@ export interface RunEvidenceReadResult {
 	readonly scannedBytes: number
 }
 
-/** @experimental Retrieval only: never re-executes a tool or resumes a run. */
-export interface RunEvidenceSource {
-	readonly scope: RunEvidenceScope
+/** @experimental Retrieval only: never re-executes a tool or resumes a turn. */
+export interface SessionEvidenceSource {
+	readonly scope: SessionEvidenceScope
 	readonly supportsTermRefinement?: boolean
-	search(options?: RunEvidenceSearchOptions, signal?: AbortSignal): Promise<RunEvidenceSearchResult>
-	read(options: RunEvidenceReadOptions, signal?: AbortSignal): Promise<RunEvidenceReadResult>
+	search(
+		options?: SessionEvidenceSearchOptions,
+		signal?: AbortSignal,
+	): Promise<SessionEvidenceSearchResult>
+	read(
+		options: SessionEvidenceReadOptions,
+		signal?: AbortSignal,
+	): Promise<SessionEvidenceReadResult>
 }
 
 /** @experimental Textual event parts, including assistant output and shed conversation messages. */
-export interface RunTextEvidenceSearchOptions extends RunEvidenceSearchOptions {
+export interface SessionTextEvidenceSearchOptions extends SessionEvidenceSearchOptions {
 	/** Omit explicitly marked derived summaries. Default false; bound into cursors. Exact reads remain available. */
 	readonly excludeDerivedSummaries?: boolean
 	readonly seq?: number
@@ -138,7 +143,8 @@ export interface RunTextEvidenceSearchOptions extends RunEvidenceSearchOptions {
 }
 
 /** @experimental Event identity is durable; byteOffset starts a bounded excerpt in the retained text. */
-export interface RunTextEvidenceMatch extends Omit<RunEvidenceMatch, 'toolName' | 'isError'> {
+export interface SessionTextEvidenceMatch
+	extends Omit<SessionEvidenceMatch, 'toolName' | 'isError'> {
 	readonly source: string
 	readonly part: number
 	readonly toolName?: string
@@ -148,15 +154,16 @@ export interface RunTextEvidenceMatch extends Omit<RunEvidenceMatch, 'toolName'
 }
 
 /** @experimental Search includes messages and tool text, never binary or private reasoning blocks. */
-export interface RunTextEvidenceSearchResult extends Omit<RunEvidenceSearchResult, 'matches'> {
-	readonly matches: readonly RunTextEvidenceMatch[]
+export interface SessionTextEvidenceSearchResult
+	extends Omit<SessionEvidenceSearchResult, 'matches'> {
+	readonly matches: readonly SessionTextEvidenceMatch[]
 	/** 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'> {
+export interface SessionTextEvidenceReadResult
+	extends Omit<SessionEvidenceReadResult, 'toolName' | 'isError'> {
 	readonly source: string
 	readonly part: number
 	readonly toolName?: string
@@ -165,13 +172,16 @@ export interface RunTextEvidenceReadResult
 	readonly totalChars?: number
 }
 
-/** @experimental Scope-bound, bounded text retrieval across an invocation's event stream. */
-export interface RunTextEvidenceSource {
-	readonly scope: RunEvidenceScope
+/** @experimental Scope-bound, bounded text retrieval across a session log. */
+export interface SessionTextEvidenceSource {
+	readonly scope: SessionEvidenceScope
 	readonly supportsTermRefinement?: boolean
 	search(
-		options?: RunTextEvidenceSearchOptions,
+		options?: SessionTextEvidenceSearchOptions,
+		signal?: AbortSignal,
+	): Promise<SessionTextEvidenceSearchResult>
+	read(
+		options: SessionEvidenceReadOptions,
 		signal?: AbortSignal,
-	): Promise<RunTextEvidenceSearchResult>
-	read(options: RunEvidenceReadOptions, signal?: AbortSignal): Promise<RunTextEvidenceReadResult>
+	): Promise<SessionTextEvidenceReadResult>
 }