@namzu/sdk 38.2.1 → 40.0.0

package/src/store/evidence/linked.ts

@@ -0,0 +1,365 @@
+import { lstat } from 'node:fs/promises'
+import type { FileHandle } from 'node:fs/promises'
+import { join } from 'node:path'
+import { z } from 'zod'
+import { EVIDENCE_CHUNK_BYTES, digest } from './format.js'
+import { type EvidenceSeal, eventTexts, evidenceSeal } from './index-page.js'
+import {
+	type EvidenceBudget,
+	EvidencePageLimit,
+	PAGE_BYTES,
+	decode,
+	openEvidence,
+	readBytes,
+	readSmall,
+} from './io.js'
+import { passageMatcher, passagesInWindow } from './passages.js'
+import { type RecordPointer, recordPointerSchema, recordPredecessors } from './record-chain.js'
+import { evidenceSearchInput, evidenceTermsSchema } from './search-input.js'
+import {
+	evidenceExclusionsKey,
+	evidenceExclusionsSchema,
+	excludesSuccessfulTool,
+} from './selection.js'
+import { createTextSourceReader, readTextPage, textPointerSchema } from './source-text.js'
+import type {
+	DiskRunEvidenceOptions,
+	RunEvidenceReadOptions,
+	RunTextEvidenceMatch,
+	RunTextEvidenceSearchOptions,
+	RunTextEvidenceSource,
+} from './types.js'
+
+const integer = z.number().int().nonnegative().safe()
+const scopeSchema = z
+	.object({
+		tenantId: z.string().uuid(),
+		projectId: z.string().uuid(),
+		sessionId: z.string().uuid(),
+		runId: z.string().uuid(),
+	})
+	.strict()
+const cursorSchema = z.object({
+	kind: z.enum(['linked-search', 'linked-search-terms', 'linked-search-tokens']),
+	query: z.string().max(256),
+	termsKey: z
+		.string()
+		.regex(/^[a-f0-9]{64}$/)
+		.optional(),
+	caseSensitive: z.boolean().default(true),
+	matchMode: z.enum(['literal', 'token']).default('literal'),
+	exclusionsKey: z
+		.string()
+		.regex(/^[a-f0-9]{64}$/)
+		.optional(),
+	seq: integer.optional(),
+	part: integer.optional(),
+	next: recordPointerSchema.nullable(),
+	textIndex: integer,
+	chunk: integer,
+	within: integer.default(0),
+})
+const addressSchema = z.object({ kind: z.literal('linked-text'), entry: textPointerSchema })
+
+/** Internal: only the durable writer can supply this anchor. Never accept it from a tool input. */
+export function createLinkedRunTextEvidenceSource(
+	options: DiskRunEvidenceOptions,
+	anchor: { tip: RecordPointer; identity: string; epoch: string },
+): RunTextEvidenceSource {
+	const scope = Object.freeze(scopeSchema.parse(options.scope))
+	const runDir = options.runDir
+	const tip = recordPointerSchema.parse(anchor.tip)
+	const ceiling = tip.offset + tip.length
+	const scopeKey = digest(JSON.stringify(scope))
+	const sourceKey = digest(`linked-v1:${scopeKey}:${anchor.identity}:${anchor.epoch}`)
+	const maxReadBytes = integer
+		.min(1024 * 1024)
+		.max(PAGE_BYTES)
+		.parse(options.maxReadBytes ?? PAGE_BYTES)
+	const inBoundary = (pointer: RecordPointer) => {
+		if (pointer.seq > tip.seq || pointer.offset + pointer.length > ceiling)
+			throw new Error('Evidence address exceeds the captured boundary.')
+	}
+	async function access<T extends { scannedBytes: number }>(
+		signal: AbortSignal | undefined,
+		requestedBytes: number | undefined,
+		action: (handle: FileHandle, seal: EvidenceSeal, budget: EvidenceBudget) => Promise<T>,
+	): Promise<T> {
+		const limit = Math.min(maxReadBytes, requestedBytes ?? maxReadBytes)
+		const budget: EvidenceBudget = { bytes: 0, limit, signal }
+		signal?.throwIfAborted()
+		const verifyOwner = async () => {
+			const metadata = JSON.parse(
+				decode(await readSmall(join(runDir, 'run.json'), budget, 512 * 1024)),
+			)
+			if (
+				metadata.id !== scope.runId ||
+				JSON.stringify(scopeSchema.parse(metadata.metadata?.scope)) !== JSON.stringify(scope)
+			)
+				throw new Error('Evidence run does not belong to the authorized scope.')
+		}
+		await verifyOwner()
+		// Reserve a final ownership check; counters/status may change while this run works.
+		budget.limit = limit - 512 * 1024
+
+		const path = join(options.runDir, 'transcript.jsonl')
+		const handle = await openEvidence(path)
+		const check = (stat: { dev: number; ino: number; size: number }) => {
+			if (`${stat.dev}:${stat.ino}` !== anchor.identity || stat.size < ceiling)
+				throw new Error('Captured transcript was replaced or shortened.')
+		}
+		try {
+			check(await handle.stat())
+			const seal = await evidenceSeal(options.indexDir, scopeKey, sourceKey, budget)
+			const result = await action(handle, seal, budget)
+			signal?.throwIfAborted()
+			check(await handle.stat())
+			check(await lstat(path))
+			budget.limit = limit
+			await verifyOwner()
+			return { ...result, scannedBytes: budget.bytes }
+		} finally {
+			await handle.close()
+		}
+	}
+	return Object.freeze({
+		scope,
+		async search(options: RunTextEvidenceSearchOptions = {}, signal?: AbortSignal) {
+			const input = z
+				.object({
+					maxReadBytes: integer
+						.min(1024 * 1024)
+						.max(PAGE_BYTES)
+						.optional(),
+					query: z.string().max(256).optional(),
+					terms: evidenceTermsSchema,
+					caseSensitive: z.boolean().default(true),
+					matchMode: z.enum(['literal', 'token']).default('literal'),
+					excludeSuccessfulTools: evidenceExclusionsSchema,
+					excludeDerivedSummaries: z.boolean().default(false),
+					cursor: z.string().max(4096).optional(),
+					seq: integer.positive().optional(),
+					part: integer.optional(),
+					limit: integer.min(1).max(4).default(4),
+				})
+				.strict()
+				.parse(options)
+			if (input.part !== undefined && input.seq === undefined)
+				throw new Error('Part requires an event sequence.')
+			const { query, terms, termsKey, browse } = evidenceSearchInput(input)
+			const exclusionsKey = evidenceExclusionsKey(
+				input.excludeSuccessfulTools,
+				input.excludeDerivedSummaries,
+			)
+			const kind =
+				input.matchMode === 'token'
+					? ('linked-search-tokens' as const)
+					: terms
+						? ('linked-search-terms' as const)
+						: ('linked-search' as const)
+			return access(signal, input.maxReadBytes, async (handle, seal, budget) => {
+				const readSource = createTextSourceReader(handle, runDir, scope.runId, budget)
+				const cursor = input.cursor
+					? cursorSchema.parse(seal.unpack(input.cursor))
+					: {
+							kind,
+							query,
+							termsKey,
+							exclusionsKey,
+							seq: input.seq,
+							part: input.part,
+							next: tip as RecordPointer | null,
+							textIndex: 0,
+							chunk: 0,
+							within: 0,
+							caseSensitive: input.caseSensitive,
+							matchMode: input.matchMode,
+						}
+				if (
+					cursor.kind !== kind ||
+					cursor.query !== query ||
+					cursor.termsKey !== termsKey ||
+					cursor.exclusionsKey !== exclusionsKey ||
+					cursor.caseSensitive !== input.caseSensitive ||
+					cursor.matchMode !== input.matchMode ||
+					cursor.seq !== input.seq ||
+					cursor.part !== input.part
+				)
+					throw new Error('Search cursor query changed.')
+				const matchPassage = passageMatcher(terms ?? query, input.caseSensitive, input.matchMode)
+				const matches: RunTextEvidenceMatch[] = []
+				const unavailable: string[] = []
+				let records = 0
+				let parts = 0
+				let chunks = 0
+				let incomplete = false
+				let excludedToolResults = 0
+				let excludedSummaries = 0
+				while (
+					cursor.next &&
+					records < 64 &&
+					parts < 64 &&
+					chunks < 64 &&
+					matches.length < input.limit
+				) {
+					const pointer = cursor.next
+					inBoundary(pointer)
+					if (input.seq !== undefined && pointer.seq < input.seq) {
+						cursor.next = null
+						break
+					}
+					let raw: Buffer
+					try {
+						raw = await readBytes(handle, pointer.offset, pointer.length, budget)
+					} catch (error) {
+						if (error instanceof EvidencePageLimit) {
+							if (records === 0) throw new Error('Recorded text exceeds the available page budget.')
+							break
+						}
+						throw error
+					}
+					if (digest(raw) !== pointer.sha256)
+						throw new Error('Recorded text integrity chain changed.')
+					const event = JSON.parse(decode(raw))
+					if (event.runId !== scope.runId || event.seq !== pointer.seq)
+						throw new Error('Recorded text identity changed.')
+					records++
+					const links = recordPredecessors(event, pointer)
+					incomplete ||= links.incomplete
+					const texts =
+						input.seq === undefined || input.seq === pointer.seq ? eventTexts(event) : []
+					while (
+						cursor.textIndex < texts.length &&
+						parts < 64 &&
+						chunks < 64 &&
+						matches.length < input.limit
+					) {
+						const part = cursor.textIndex
+						if (input.part !== undefined && part !== input.part) {
+							cursor.textIndex++
+							continue
+						}
+						parts++
+						try {
+							const derived =
+								input.excludeDerivedSummaries && texts[part]?.source === 'compaction_shed:summary'
+							if (
+								derived ||
+								excludesSuccessfulTool(
+									event.type === 'tool_completed' && typeof event.toolUseId === 'string'
+										? event
+										: (texts[part] ?? {}),
+									input.excludeSuccessfulTools,
+								)
+							) {
+								if (derived) excludedSummaries++
+								else excludedToolResults++
+								cursor.textIndex++
+								cursor.chunk = 0
+								cursor.within = 0
+								continue
+							}
+							const source = await readSource({ ...pointer, part }, raw)
+							if (source.retained === 'preview') incomplete = true
+							while (cursor.chunk < source.chunks && chunks < 64 && matches.length < input.limit) {
+								signal?.throwIfAborted()
+								chunks++
+								if (
+									(terms ?? [query]).some((term) =>
+										source.mayMatch(cursor.chunk, term, input.matchMode, input.caseSensitive),
+									)
+								) {
+									const window = await source.window(cursor.chunk, input.matchMode === 'token')
+									const text = decode(window.bytes)
+									const page = passagesInWindow(
+										text,
+										Math.max(cursor.within, window.searchFrom ?? 0),
+										matchPassage,
+										input.limit - matches.length,
+										source.entry.spill
+											? (cursor.chunk + 1) * EVIDENCE_CHUNK_BYTES - window.offset
+											: undefined,
+									)
+									cursor.within = page.next
+									for (const { start, end } of page.passages) {
+										const excerpt = text.slice(start, end)
+										const byteOffset = window.offset + Buffer.byteLength(text.slice(0, start))
+										matches.push({
+											address: seal.pack({ kind: 'linked-text', entry: { ...pointer, part } }),
+											seq: pointer.seq,
+											recordedAt: source.recordedAt,
+											source: source.entry.source,
+											part,
+											toolName: source.entry.toolName,
+											isError: source.entry.isError,
+											retained: source.retained,
+											excerpt,
+											excerptComplete:
+												source.retained === 'full' &&
+												byteOffset === 0 &&
+												Buffer.byteLength(excerpt) === source.bytes,
+											byteOffset,
+											characterOffset:
+												window.characterOffset === undefined
+													? undefined
+													: window.characterOffset + start,
+										})
+									}
+									if (cursor.within < text.length) break
+								}
+								cursor.within = 0
+								cursor.chunk++
+								if (browse) cursor.chunk = source.chunks
+							}
+							if (cursor.chunk < source.chunks) break
+						} catch (error) {
+							signal?.throwIfAborted()
+							if (error instanceof EvidencePageLimit && (records > 1 || parts > 1 || chunks > 1))
+								break
+							unavailable.push(`Text record ${pointer.seq}/${part} is unavailable or changed.`)
+						}
+						cursor.textIndex++
+						cursor.chunk = 0
+						cursor.within = 0
+					}
+					if (cursor.textIndex < texts.length) break
+					cursor.next = links.next
+					cursor.textIndex = 0
+					cursor.chunk = 0
+					cursor.within = 0
+				}
+				return {
+					scope,
+					matches,
+					nextCursor: cursor.next ? seal.pack(cursor) : null,
+					scannedBytes: budget.bytes,
+					indexedRecords: records,
+					cacheHit: false,
+					incomplete: incomplete || unavailable.length > 0,
+					unavailable,
+					...(excludedToolResults ? { excludedToolResults } : {}),
+					...(excludedSummaries ? { excludedSummaries } : {}),
+				}
+			})
+		},
+		async read(options: RunEvidenceReadOptions, signal?: AbortSignal) {
+			const input = z
+				.object({
+					address: z.string().max(8192),
+					byteOffset: integer.default(0),
+					maxReadBytes: integer
+						.min(1024 * 1024)
+						.max(PAGE_BYTES)
+						.optional(),
+				})
+				.strict()
+				.parse(options)
+			return access(signal, input.maxReadBytes, async (handle, seal, budget) => {
+				const pointer = addressSchema.parse(seal.unpack(input.address)).entry
+				inBoundary(pointer)
+				const source = await createTextSourceReader(handle, runDir, scope.runId, budget)(pointer)
+				return readTextPage(source, scope, input.byteOffset, budget)
+			})
+		},
+	})
+}

package/src/store/evidence/passages.ts

@@ -0,0 +1,88 @@
+import { evidenceTokenMatcher } from '../../utils/evidence-tokens.js'
+
+/** An exact excerpt; matching never rewrites the text or its UTF-16 positions. */
+export interface EvidencePassage {
+	hit: number
+	start: number
+	end: number
+	next: number
+}
+
+/** Exact substring or token matching, without caller-selected regex operators. */
+export function passageMatcher(
+	query: string | readonly string[],
+	caseSensitive: boolean,
+	matchMode: 'literal' | 'token' = 'literal',
+) {
+	const terms = typeof query === 'string' ? [query] : query
+	const tokenMatch = matchMode === 'token' ? evidenceTokenMatcher(terms, caseSensitive) : undefined
+	const expression =
+		caseSensitive && typeof query === 'string'
+			? undefined
+			: new RegExp(
+					terms.map((term) => term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|'),
+					caseSensitive ? 'g' : 'giu',
+				)
+	const maxLength = Math.max(...terms.map((term) => term.length))
+	const find = (text: string, from: number) => {
+		if (tokenMatch) return tokenMatch(text, from)
+		if (expression) {
+			expression.lastIndex = from
+			const match = expression.exec(text)
+			return match ? { index: match.index, length: match[0].length } : undefined
+		}
+		const index = text.indexOf(terms[0] ?? '', from)
+		return index < 0 ? undefined : { index, length: terms[0]?.length ?? 0 }
+	}
+	return (text: string, from: number): EvidencePassage | undefined => {
+		const hit = find(text, from)?.index ?? -1
+		if (hit < 0 || (from >= text.length && query !== '')) return undefined
+		let start = Math.max(0, hit - 120)
+		if (start > 0 && /[\uDC00-\uDFFF]/.test(text[start] ?? '')) start--
+		let end = Math.min(text.length, start + 512)
+		if (end < text.length && /[\uDC00-\uDFFF]/.test(text[end] ?? '')) end--
+		// Nearby hits already fully shown by this excerpt need no second copy.
+		// A match crossing its end still deserves a complete later excerpt.
+		let next =
+			end === text.length || query === '' ? text.length : Math.max(hit + 1, end - maxLength + 1)
+		if (typeof query !== 'string' && end < text.length) {
+			// Different term lengths share one excerpt. Skip fully visible short
+			// matches, but keep the earliest long match that crosses its boundary.
+			let at = next
+			next = end
+			while (at < end) {
+				const crossing = find(text, at)
+				if (!crossing || crossing.index >= end) break
+				if (crossing.index + crossing.length > end) {
+					next = crossing.index
+					break
+				}
+				at = crossing.index + 1
+				if (/[\uDC00-\uDFFF]/.test(text[at] ?? '')) at++
+			}
+		}
+		if (/[\uDC00-\uDFFF]/.test(text[next] ?? '')) next++
+		return { hit, start, end, next }
+	}
+}
+
+/** Overlap bytes support boundary matches; starts in those bytes belong to the next window. */
+export function passagesInWindow(
+	text: string,
+	from: number,
+	match: ReturnType<typeof passageMatcher>,
+	limit: number,
+	ownedBytes = Number.POSITIVE_INFINITY,
+): { passages: EvidencePassage[]; next: number } {
+	const passages: EvidencePassage[] = []
+	let next = from
+	while (passages.length < limit) {
+		const passage = match(text, next)
+		if (!passage || Buffer.byteLength(text.slice(0, passage.hit)) >= ownedBytes)
+			return { passages, next: text.length }
+		passages.push(passage)
+		next = passage.next
+		if (next >= text.length) break
+	}
+	return { passages, next }
+}

package/src/store/evidence/record-chain.ts

@@ -0,0 +1,108 @@
+import type { FileHandle } from 'node:fs/promises'
+import { z } from 'zod'
+import { digest } from './format.js'
+import { eventTexts } from './index-page.js'
+import { RECORD_BYTES, decode, openEvidence, readBytes } from './io.js'
+
+const integer = z.number().int().nonnegative().safe()
+export const recordPointerSchema = z.object({
+	offset: integer,
+	length: integer.positive().max(RECORD_BYTES),
+	sha256: z.string().regex(/^[a-f0-9]{64}$/),
+	seq: integer.positive(),
+})
+export type RecordPointer = z.infer<typeof recordPointerSchema>
+
+/** Malformed content must still be visited and rejected by the reader. */
+export function hasEvidenceText(event: Record<string, unknown>): boolean {
+	try {
+		return eventTexts(event).length > 0
+	} catch {
+		return true
+	}
+}
+
+/** Validate links even when a text-only traversal skips intervening operational records. */
+export function recordPredecessors(event: Record<string, unknown>, pointer: RecordPointer) {
+	let previous: RecordPointer | null = null
+	let incomplete = false
+	if (event.previousRecord != null) {
+		previous = recordPointerSchema.parse(event.previousRecord)
+		if (previous.offset + previous.length !== pointer.offset || previous.seq + 1 !== pointer.seq)
+			throw new Error('Invalid text integrity chain.')
+	} else if (pointer.seq === 1) {
+		if (pointer.offset !== 0 || event.type !== 'run_started')
+			throw new Error('Invalid transcript start.')
+	} else {
+		incomplete = true
+	}
+	let next = previous
+	if (Object.hasOwn(event, 'previousTextRecord')) {
+		next = recordPointerSchema.nullable().parse(event.previousTextRecord)
+		if (
+			(next === null && previous !== null) ||
+			(next !== null &&
+				(previous === null ||
+					next.seq >= pointer.seq ||
+					next.offset + next.length > pointer.offset ||
+					(next.seq === previous.seq &&
+						(next.offset !== previous.offset ||
+							next.length !== previous.length ||
+							next.sha256 !== previous.sha256))))
+		)
+			throw new Error('Invalid text predecessor link.')
+	}
+	return { previous, next, incomplete }
+}
+
+/** Bootstrap only the last complete record, never load a growing log to capture a boundary. */
+export async function transcriptTail(
+	path: string,
+	runId: string,
+): Promise<{ tip: RecordPointer; textTip?: RecordPointer | null } | undefined> {
+	let handle: FileHandle
+	try {
+		handle = await openEvidence(path)
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined
+		throw error
+	}
+	try {
+		const stat = await handle.stat()
+		if (!stat.size) return undefined
+		const offset = Math.max(0, stat.size - RECORD_BYTES)
+		const tail = await readBytes(handle, offset, stat.size - offset, { bytes: 0 })
+		if (tail.at(-1) !== 10) return undefined
+		const start = tail.lastIndexOf(10, tail.length - 2) + 1
+		if (start === 0 && offset !== 0) return undefined
+		const raw = tail.subarray(start)
+		let event: Record<string, unknown> | null
+		try {
+			event = JSON.parse(decode(raw))
+		} catch {
+			return undefined
+		}
+		if (event?.runId !== runId) return undefined
+		const pointer = recordPointerSchema.safeParse({
+			offset: offset + start,
+			length: raw.length,
+			sha256: digest(raw),
+			seq: event.seq,
+		})
+		if (!pointer.success) return undefined
+		const tip = pointer.data
+		// Starts, gaps and malformed records remain traversal barriers. They may
+		// never disappear behind a later text link after reopening the writer.
+		let textTip: RecordPointer | null | undefined = tip
+		try {
+			const links = recordPredecessors(event, tip)
+			if (!hasEvidenceText(event) && links.previous !== null)
+				textTip = Object.hasOwn(event, 'previousTextRecord') ? links.next : undefined
+		} catch {
+			// Keep the tail itself; retrieval will reject its malformed links.
+		}
+		return { tip, textTip }
+	} finally {
+		await handle.close()
+	}
+}

package/src/store/evidence/search-input.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod'
+import { evidenceTokenKey, isEvidenceToken } from '../../utils/evidence-tokens.js'
+import { digest } from './format.js'
+
+export const evidenceTermsSchema = z
+	.array(
+		z
+			.string()
+			.min(1)
+			.max(256)
+			.refine((text) => text.trim().length > 0),
+	)
+	.min(1)
+	.max(16)
+	.optional()
+
+/** Canonical membership binds continuations without putting long term lists in cursors. */
+export function evidenceSearchInput(input: {
+	query?: string
+	terms?: string[]
+	matchMode?: 'literal' | 'token'
+}) {
+	if (input.terms && input.query !== undefined)
+		throw new Error('Supply either a literal query or literal terms, not both.')
+	const terms = input.terms
+		? [...new Set(input.terms)].sort((a, b) => b.length - a.length || (a < b ? -1 : a > b ? 1 : 0))
+		: undefined
+	if (input.matchMode === 'token' && !(terms ?? [input.query ?? '']).every(isEvidenceToken))
+		throw new Error('Token search requires nonempty letter/number/underscore tokens.')
+	return {
+		query: input.query ?? '',
+		terms,
+		termsKey: terms ? digest(JSON.stringify(terms)) : undefined,
+		browse: !terms && !input.query,
+	}
+}
+
+/** Refinement only narrows matching; it never resets scope, filters or position. */
+export function evidenceTermRefinement(
+	input: {
+		terms?: readonly string[]
+		cursor?: string
+		matchMode?: string
+		caseSensitive?: boolean
+	},
+	refined: readonly string[],
+): string[] {
+	const terms = evidenceTermsSchema.parse(refined)
+	if (
+		!input.cursor ||
+		input.matchMode !== 'token' ||
+		!input.terms ||
+		!terms?.every(isEvidenceToken)
+	)
+		throw new Error('Term refinement requires a token cursor and its original terms.')
+	const key = (term: string) => evidenceTokenKey(term, input.caseSensitive ?? true)
+	const original = new Set(input.terms.map(key))
+	const subset = new Set(terms.map(key))
+	if (subset.size >= original.size || [...subset].some((term) => !original.has(term)))
+		throw new Error('Term refinement must be a strict nonempty subset of the original terms.')
+	return terms
+}

package/src/store/evidence/selection.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod'
+import { digest } from './format.js'
+
+/** Host-selected search exclusion, never an authorization rule or inferred provenance. */
+export const evidenceExclusionsSchema = z
+	.array(z.string().min(1).max(256))
+	.max(16)
+	.default([])
+	.transform((names) => [...new Set(names)].sort())
+
+export function evidenceExclusionsKey(
+	names: readonly string[],
+	excludeDerivedSummaries = false,
+): string | undefined {
+	if (excludeDerivedSummaries)
+		return digest(JSON.stringify({ tools: names, derivedSummaries: true }))
+	return names.length ? digest(JSON.stringify(names)) : undefined
+}
+
+export function excludesSuccessfulTool(
+	entry: { toolName?: string; isError?: boolean },
+	names: readonly string[],
+): boolean {
+	return entry.isError === false && entry.toolName !== undefined && names.includes(entry.toolName)
+}

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

@@ -0,0 +1,36 @@
+/** Producer category derived from an evidence source tag, never from its prose. */
+export type EvidenceRecordKind =
+	| 'assistant_message'
+	| 'tool_result'
+	| 'user_message'
+	| 'derived_summary'
+	| 'system_message'
+	| 'unknown'
+
+/**
+ * Classify an already authenticated host source tag. This function performs no
+ * authentication and grants no authority, freshness or factual correctness.
+ * Custom labels stay unknown; do not pass labels parsed from quoted content.
+ */
+export function classifyEvidenceSource(source: string): EvidenceRecordKind {
+	switch (source) {
+		case 'message_completed':
+		case 'compaction_shed:assistant':
+			return 'assistant_message'
+		case 'tool_completed':
+		case 'compaction_shed:tool':
+			return 'tool_result'
+		case 'compaction_shed:user':
+			return 'user_message'
+		case 'compaction_shed:summary':
+			return 'derived_summary'
+		case 'compaction_shed:system':
+			return 'system_message'
+		default:
+			return 'unknown'
+	}
+}
+
+/** Shared model-facing interpretation for hosts projecting recorded evidence. */
+export const EVIDENCE_RECORD_GUIDANCE =
+	'Producer kinds do not establish truth or independence. assistant_message is a prior model claim, not proof of observed state or successful action. Attribute it as a claim unless supported by the original observation; tool results may themselves quote claims.'