@namzu/sdk 42.0.2 → 44.0.0

package/src/manager/index.ts

@@ -1,5 +1,4 @@
-export { RunPersistence } from './run/persistence.js'
-export { EmergencySaveManager } from './run/emergency.js'
+export { TurnRecorder } from './session/turn-recorder.js'
 
 export { ConnectorManager } from './connector/lifecycle.js'
 export type { ConnectorManagerConfig } from './connector/lifecycle.js'

package/src/manager/plan/lifecycle.ts

@@ -1,4 +1,4 @@
-import type { RunId } from '../../types/ids/index.js'
+import type { SessionId, TurnId } from '../../types/ids/index.js'
 import type {
 	Plan,
 	PlanApprovalRequest,
@@ -27,12 +27,12 @@ export type PlanEventListener = (event: PlanEvent) => void | Promise<void>
 export type PlanApprovalHandler = (request: PlanApprovalRequest) => Promise<PlanApprovalResponse>
 
 /**
- * The plan a run declares, and the gate a host approves it through.
+ * The plan a turn declares, and the gate a host approves it through.
  *
  * **The kernel deliberately drives only part of this class.** It builds a plan
  * (`approve_plan` calls `startGenerating` / `addStep` / `markReady`), gates it
  * (`iteration/phases/context.ts` calls `approve` and `startExecution`),
- * translates its events onto the run stream (`EventTranslator.wirePlanManager`),
+ * translates its events onto the session event stream (`EventTranslator.wirePlanManager`),
  * and settles it on failure (`runtime/query/result.ts` calls `failPlan`). It
  * never reports a step outcome and never settles a plan that succeeded.
  *
@@ -55,12 +55,16 @@ export type PlanApprovalHandler = (request: PlanApprovalRequest) => Promise<Plan
  */
 export class PlanManager {
 	private currentPlan: Plan | null = null
-	private runId: RunId
+	private readonly scope: { readonly sessionId: SessionId; readonly turnId: TurnId }
 	private listeners: PlanEventListener[] = []
 	private approvalHandler?: PlanApprovalHandler
 
-	constructor(runId: RunId, approvalHandler?: PlanApprovalHandler) {
-		this.runId = runId
+	/** `scope` is the turn the plan belongs to; every plan and approval request carries it. */
+	constructor(
+		scope: { readonly sessionId: SessionId; readonly turnId: TurnId },
+		approvalHandler?: PlanApprovalHandler,
+	) {
+		this.scope = { sessionId: scope.sessionId, turnId: scope.turnId }
 		this.approvalHandler = approvalHandler
 	}
 
@@ -102,8 +106,8 @@ export class PlanManager {
 	 * refuse, exposed so a caller can ask before it commits.
 	 *
 	 * The kernel settles a successful plan only when this is empty. It cannot
-	 * catch the refusal instead: a throw on the success path would turn a run
-	 * that worked into a run that crashed on its way out, which is a worse
+	 * catch the refusal instead: a throw on the success path would make a turn
+	 * that worked into one that crashed on its way out, which is a worse
 	 * version of the bug the refusal exists to prevent.
 	 */
 	get unreportedSteps(): readonly PlanStep[] {
@@ -114,7 +118,8 @@ export class PlanManager {
 	startGenerating(title: string): Plan {
 		const plan: Plan = {
 			id: generatePlanId(),
-			runId: this.runId,
+			sessionId: this.scope.sessionId,
+			turnId: this.scope.turnId,
 			status: 'generating',
 			title,
 			steps: [],
@@ -167,7 +172,8 @@ export class PlanManager {
 
 		const request: PlanApprovalRequest = {
 			planId: this.currentPlan.id,
-			runId: this.runId,
+			sessionId: this.scope.sessionId,
+			turnId: this.scope.turnId,
 			title: this.currentPlan.title,
 			steps: this.currentPlan.steps,
 			summary: this.currentPlan.summary,

package/src/manager/resident/consumption.ts

@@ -24,7 +24,9 @@ const settlementSchema = z.object({
 })
 const receiptSchema = z
 	.object({
-		runId: z.string().uuid(),
+		/** The resident step's turn: one receipt per turn, whose session holds its log. */
+		sessionId: z.string().uuid(),
+		turnId: z.string().uuid(),
 		/** Own usage includes retry and side-call spend; never add cache buckets again. */
 		ownTokens: count.nullable(),
 		treeTokens: count.nullable(),
@@ -74,7 +76,7 @@ export interface ResidentConsumptionOptions {
 export interface ResidentConsumptionAttempt extends ResidentAdmission {
 	readonly settlement: ResidentSettlement | null
 	readonly receipt: ResidentConsumptionReceipt | null
-	readonly receiptStatus: 'available' | 'missing' | 'invalid' | 'deferred' | 'duplicate-run'
+	readonly receiptStatus: 'available' | 'missing' | 'invalid' | 'deferred' | 'duplicate-turn'
 }
 
 /** @experimental An evidence projection, not a bill or an enforced spending cap. */
@@ -253,13 +255,13 @@ export async function inspectResidentConsumption(
 		})
 	}
 	// A copied root receipt must not authenticate two claims. Exclude BOTH records.
-	const runCounts = new Map<string, number>()
+	const turnCounts = new Map<string, number>()
 	for (const { receipt } of attempts)
 		if (receipt)
-			runCounts.set(uuidKey(receipt.runId), (runCounts.get(uuidKey(receipt.runId)) ?? 0) + 1)
+			turnCounts.set(uuidKey(receipt.turnId), (turnCounts.get(uuidKey(receipt.turnId)) ?? 0) + 1)
 	const checked = attempts.map((attempt) =>
-		attempt.receipt && (runCounts.get(uuidKey(attempt.receipt.runId)) ?? 0) > 1
-			? { ...attempt, receipt: null, receiptStatus: 'duplicate-run' as const }
+		attempt.receipt && (turnCounts.get(uuidKey(attempt.receipt.turnId)) ?? 0) > 1
+			? { ...attempt, receipt: null, receiptStatus: 'duplicate-turn' as const }
 			: attempt,
 	)
 	const recorded = { ownTokens: 0, treeTokens: 0, ownCostUsd: 0, unpricedOwnTokens: 0 }

package/src/manager/resident/evidence-recall.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import type { SessionEvidenceScope } from '../../store/evidence/types.js'
 import {
 	type EvidenceRecallRequest,
 	type ScopedEvidenceRecallBatch,
@@ -6,20 +7,19 @@ import {
 	createScopedEvidenceRecallStep,
 	evidenceRecallQueryTokens,
 	refineEvidenceRecallTerms,
-} from '../../run/evidence-recall.js'
-import type { RunEvidenceScope } from '../../store/evidence/types.js'
-import type { PrepareStep } from '../../types/run/prepare-step.js'
+} from '../../turn/evidence-recall.js'
+import type { PrepareStep } from '../../types/session/prepare-step.js'
 import { evidenceTokenKey } from '../../utils/evidence-tokens.js'
 import { type ResidentState, residentStateSchema } from './store.js'
 import type { ResidentToolEvidenceSource } from './tool-evidence.js'
 
-/** @experimental Automatic original-tool recall for exactly one admitted resident run. */
+/** @experimental Automatic original-tool recall for exactly one admitted resident turn. */
 export interface ResidentEvidenceRecallOptions {
 	readonly source: ResidentToolEvidenceSource
 	/** Already admitted state; summaries supply search words, never new observations. */
 	readonly state: ResidentState
-	/** The current executor, distinct from historical Session/run addresses. */
-	readonly scope: RunEvidenceScope
+	/** The current executor's turn, distinct from historical session/turn addresses. */
+	readonly scope: SessionEvidenceScope
 	readonly maxChars?: number
 	readonly maxPassages?: number
 	readonly timeoutMs?: number
@@ -31,9 +31,9 @@ const ownerSchema = z.object({
 	tenantId: z.string().uuid(),
 	projectId: z.string().uuid(),
 	sessionId: z.string().uuid(),
-	runId: z.string().uuid(),
+	turnId: z.string().uuid(),
 })
-const historicalScopeSchema = ownerSchema.omit({ sessionId: true, runId: true }).extend({
+const historicalScopeSchema = ownerSchema.omit({ sessionId: true, turnId: true }).extend({
 	agentKey: z.string().min(1).max(200),
 	pursuitId: z.string().uuid(),
 	throughRevision: z.number().int().positive().safe(),
@@ -178,8 +178,8 @@ export function createResidentEvidenceRecallStep(
 	const addresses = new WeakMap<ScopedEvidenceRecallCandidate, Readonly<Record<string, unknown>>>()
 	const search = source.search.bind(source)
 	const retrieve = async (request: EvidenceRecallRequest): Promise<ScopedEvidenceRecallBatch> => {
-		if (request.runId !== owner.runId)
-			throw new Error('Resident recall called from a different run.')
+		if (request.turnId !== owner.turnId)
+			throw new Error('Resident recall called from a different turn.')
 		assertSource()
 		const candidates: ScopedEvidenceRecallCandidate[] = []
 		let scannedBytes = 0
@@ -247,7 +247,7 @@ export function createResidentEvidenceRecallStep(
 				if (
 					original.tenantId !== owner.tenantId ||
 					original.projectId !== owner.projectId ||
-					original.runId === owner.runId ||
+					original.turnId === owner.turnId ||
 					!Number.isSafeInteger(page.revision) ||
 					(page.revision ?? 0) < 1 ||
 					(page.revision ?? Number.POSITIVE_INFINITY) > historicalScope.throughRevision ||
@@ -284,7 +284,7 @@ export function createResidentEvidenceRecallStep(
 					}
 					addresses.set(candidate, {
 						sessionId: original.sessionId,
-						runId: original.runId,
+						turnId: original.turnId,
 						seq: match.seq,
 						pursuitId: historicalScope.pursuitId,
 						revision: page.revision,
@@ -355,8 +355,8 @@ export function createResidentEvidenceRecallStep(
 		},
 	)
 	return async (context) => {
-		if (context.runId !== owner.runId)
-			throw new Error('Resident recall called from a different run.')
+		if (context.turnId !== owner.turnId)
+			throw new Error('Resident recall called from a different turn.')
 		assertSource()
 		return step(context)
 	}

package/src/manager/resident/host.ts

@@ -35,7 +35,7 @@ export interface ResidentStepContext {
 	readonly learning?: ResidentLearningState
 }
 
-/** @experimental A developer callback may bind a different SDK run for each pursuit. */
+/** @experimental A developer callback may bind a different SDK turn for each pursuit. */
 export type ResidentPursuitStep = (
 	pursuit: ResidentPursuit,
 	signal: AbortSignal,
@@ -137,7 +137,7 @@ export class ResidentHost {
 
 	/**
 	 * Signal current work and durably close future admission. Resolving this method
-	 * is NOT quiescence: await the run promise before claiming the callback stopped.
+	 * is NOT quiescence: await the turn promise before claiming the callback stopped.
 	 * An interrupted admitted pursuit remains unresolved until reconciled explicitly.
 	 */
 	async pause(): Promise<void> {

package/src/manager/resident/learning-cycle.ts

@@ -24,7 +24,9 @@ import { ResidentConflictError } from './store.js'
 export type ResidentLearningStage = 'explore' | 'generate' | 'verification' | 'confirmation'
 
 const receiptSchema = z.object({
-	runId: z.string().uuid(),
+	/** The session and turn of the execution this usage belongs to; one receipt per turn. */
+	sessionId: z.string().uuid(),
+	turnId: z.string().uuid(),
 	tokens: z.number().int().nonnegative().safe().nullable(),
 	costUsd: z.number().nonnegative().finite().nullable(),
 })
@@ -60,7 +62,7 @@ export interface ResidentLearningCycleEvent {
 	readonly data: Readonly<Record<string, unknown>>
 }
 
-/** @experimental Use this stage's signal for every owned run; await every usage append. */
+/** @experimental Use this stage's signal for every owned execution; await every usage append. */
 export interface ResidentLearningCycleContext {
 	readonly cycleId: string
 	readonly stage: ResidentLearningStage
@@ -306,7 +308,7 @@ export async function runResidentLearningCycle(
 						try {
 							if (!open) throw new Error('A closed learning stage cannot record new usage.')
 							const receipt = Object.freeze(receiptSchema.parse(input))
-							const id = receipt.runId.toLowerCase()
+							const id = receipt.turnId.toLowerCase()
 							if (receipts.has(id)) throw new Error('Duplicate learning execution receipt.')
 							if (receipts.size >= 1024) throw new Error('Learning cycle receipt bound exceeded.')
 							const totals = usage()

package/src/manager/resident/learning-observation.ts

@@ -8,11 +8,16 @@ export const learningTargetSchema = z.object({
 	baselineRevision: z.union([z.literal('none'), z.string().regex(/^[a-f0-9]{64}$/)]),
 })
 
+const lowerUuid = z
+	.string()
+	.uuid()
+	.transform((id) => id.toLowerCase())
+
 export const learningObservationSchema = learningTargetSchema.extend({
-	runId: z
-		.string()
-		.uuid()
-		.transform((id) => id.toLowerCase()),
+	/** The session whose log holds the observed turn. */
+	sessionId: lowerUuid,
+	/** The observed turn; one observation per (session, turn, evaluator, skill). */
+	turnId: lowerUuid,
 	/** Stable task identity, including input/source revision; retries keep the same key. */
 	taskKey: label,
 	outcome: z.enum(['passed', 'failed', 'execution-error', 'unresolved']),

package/src/manager/resident/learning-store.ts

@@ -52,10 +52,11 @@ const OBSERVATIONS_SCHEMA = `
 CREATE TABLE observations (
   ordinal INTEGER PRIMARY KEY AUTOINCREMENT,
   tenant_id TEXT NOT NULL, project_id TEXT NOT NULL, agent_key TEXT NOT NULL,
-  run_id TEXT NOT NULL, evaluator_revision TEXT NOT NULL, skill_name TEXT NOT NULL,
+  session_id TEXT NOT NULL, turn_id TEXT NOT NULL,
+  evaluator_revision TEXT NOT NULL, skill_name TEXT NOT NULL,
   baseline_revision TEXT NOT NULL, task_key TEXT NOT NULL,
   eligible INTEGER NOT NULL, body TEXT NOT NULL,
-  UNIQUE(tenant_id, project_id, agent_key, run_id, evaluator_revision, skill_name)
+  UNIQUE(tenant_id, project_id, agent_key, session_id, turn_id, evaluator_revision, skill_name)
 );
 CREATE INDEX observations_select ON observations(
   tenant_id, project_id, agent_key, skill_name, evaluator_revision, baseline_revision, eligible, ordinal
@@ -92,11 +93,34 @@ CREATE TABLE artifacts (
   bytes INTEGER NOT NULL, PRIMARY KEY(cycle_id, name)
 );
 CREATE TABLE usage_receipts (
-  cycle_id TEXT NOT NULL REFERENCES cycles(id), run_id TEXT NOT NULL,
-  PRIMARY KEY(cycle_id, run_id)
+  cycle_id TEXT NOT NULL REFERENCES cycles(id),
+  session_id TEXT NOT NULL, turn_id TEXT NOT NULL,
+  PRIMARY KEY(cycle_id, turn_id)
 );
 `
 
+/**
+ * The schema this store writes and reads. Versions 1 and 2 keyed observations
+ * and receipts by a turn id; a database at either (or any other version) is
+ * refused, never migrated — its rows name executions that no longer exist.
+ */
+export const RESIDENT_LEARNING_STORE_VERSION = 3
+
+/** A learning database this version of the store does not read. */
+export class ResidentLearningStoreVersionError extends Error {
+	override readonly name = 'ResidentLearningStoreVersionError'
+	readonly found: number
+	readonly expected: number
+
+	constructor(databasePath: string, found: number) {
+		super(
+			`Learning database ${databasePath} is at schema version ${found}; this store reads version ${RESIDENT_LEARNING_STORE_VERSION} only. Databases before version 3 are not read: move the file aside and start a new learning database.`,
+		)
+		this.found = found
+		this.expected = RESIDENT_LEARNING_STORE_VERSION
+	}
+}
+
 /** @experimental Private parent directories and backup policy remain host responsibilities. */
 export interface SqliteResidentLearningStoreOptions {
 	readonly databasePath: string
@@ -235,11 +259,13 @@ export class SqliteResidentLearningStore {
 							.get()
 					)
 						throw new Error('Refusing to initialize a nonempty learning database.')
-					db.exec(`${SCHEMA} ${OBSERVATIONS_SCHEMA} PRAGMA user_version = 2;`)
-				} else if (version === 1 && write) {
-					db.exec(`${OBSERVATIONS_SCHEMA} PRAGMA user_version = 2;`)
-				} else if (version !== 1 && version !== 2)
-					throw new Error(`Unsupported learning database version ${version}.`)
+					db.exec(
+						`${SCHEMA} ${OBSERVATIONS_SCHEMA} PRAGMA user_version = ${RESIDENT_LEARNING_STORE_VERSION};`,
+					)
+				} else if (version === 0)
+					throw new Error('Learning database is not initialized; open it for writing first.')
+				else if (version !== RESIDENT_LEARNING_STORE_VERSION)
+					throw new ResidentLearningStoreVersionError(this.databasePath, version)
 				const value = operation(db)
 				db.exec('COMMIT')
 				return value
@@ -272,19 +298,20 @@ export class SqliteResidentLearningStore {
 			const scope = [this.scope.tenantId, this.scope.projectId, this.scope.agentKey]
 			const previous = db
 				.prepare(
-					'SELECT body FROM observations WHERE tenant_id=? AND project_id=? AND agent_key=? AND run_id=? AND evaluator_revision=? AND skill_name=?',
+					'SELECT body FROM observations WHERE tenant_id=? AND project_id=? AND agent_key=? AND session_id=? AND turn_id=? AND evaluator_revision=? AND skill_name=?',
 				)
-				.get(...scope, value.runId, value.evaluatorRevision, value.skillName)
+				.get(...scope, value.sessionId, value.turnId, value.evaluatorRevision, value.skillName)
 			if (previous) {
 				if (previous.body !== body)
 					throw new Error('Learning observation already has different content.')
 				return
 			}
 			db.prepare(`INSERT INTO observations
-				(tenant_id, project_id, agent_key, run_id, evaluator_revision, skill_name, baseline_revision, task_key, eligible, body)
-				VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(
+				(tenant_id, project_id, agent_key, session_id, turn_id, evaluator_revision, skill_name, baseline_revision, task_key, eligible, body)
+				VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(
 				...scope,
-				value.runId,
+				value.sessionId,
+				value.turnId,
 				value.evaluatorRevision,
 				value.skillName,
 				value.baselineRevision,
@@ -498,7 +525,8 @@ export class SqliteResidentLearningStore {
 			if (event.kind === 'usage') {
 				const receipt = z
 					.object({
-						runId: uuid,
+						sessionId: uuid,
+						turnId: uuid,
 						tokens: z.number().int().nonnegative().safe().nullable(),
 						costUsd: z.number().nonnegative().finite().nullable(),
 					})
@@ -509,7 +537,9 @@ export class SqliteResidentLearningStore {
 					!Number.isFinite(row.cost_usd + (receipt.costUsd ?? 0))
 				)
 					throw new Error('Learning consumption overflow.')
-				db.prepare('INSERT INTO usage_receipts VALUES (?, ?)').run(event.cycleId, receipt.runId)
+				db.prepare(
+					'INSERT INTO usage_receipts (cycle_id, session_id, turn_id) VALUES (?, ?, ?)',
+				).run(event.cycleId, receipt.sessionId, receipt.turnId)
 				db.prepare(
 					'UPDATE cycles SET tokens = tokens + ?, cost_usd = cost_usd + ?, receipts = receipts + 1, unknown_tokens = unknown_tokens + ?, unknown_costs = unknown_costs + ? WHERE id = ?',
 				).run(

package/src/manager/resident/tool-evidence.ts

@@ -6,10 +6,10 @@ import {
 } from '../../store/evidence/search-input.js'
 import { evidenceExclusionsSchema } from '../../store/evidence/selection.js'
 import type {
-	RunEvidenceReadOptions,
-	RunEvidenceReadResult,
-	RunEvidenceSearchResult,
-	RunEvidenceSource,
+	SessionEvidenceReadOptions,
+	SessionEvidenceReadResult,
+	SessionEvidenceSearchResult,
+	SessionEvidenceSource,
 } from '../../store/evidence/types.js'
 import type {
 	ResidentHistoryMatch,
@@ -30,17 +30,22 @@ export type ResidentSettledInvocation = Pick<
 export interface ResidentToolEvidenceOptions {
 	readonly history: ResidentHistorySource
 	readonly projectId: string
-	/** Host-enforced upper bound for resolveRun's document reads, charged in full.
+	/** Host-enforced upper bound for resolveTurn's document reads, charged in full.
 	 * Required only when an operation supplies maxReadBytes. Zero asserts no
 	 * document reads. This is a declared bound, not a measured receipt.
 	 */
 	readonly resolutionReadBytes?: number
-	readonly resolveRun: (
+	/**
+	 * The evidence of the one turn that performed a settled invocation. Its
+	 * scope must name that turn (`turnId` present): a source spanning a whole
+	 * session could answer with another turn's records.
+	 */
+	readonly resolveTurn: (
 		settled: ResidentSettledInvocation,
 		signal?: AbortSignal,
-	) => Promise<RunEvidenceSource>
+	) => Promise<SessionEvidenceSource>
 }
-/** @experimental An optional shared ceiling covers history, resolution and run evidence. */
+/** @experimental An optional shared ceiling covers history, resolution and turn evidence. */
 export interface ResidentToolEvidenceSearchOptions {
 	readonly query?: string
 	/** Token discovery: 1–16 terms, matched case-insensitively. Combined query/filter JSON ≤512 UTF-8 bytes. */
@@ -60,30 +65,30 @@ export interface ResidentToolEvidenceSearchResult {
 	readonly scope: ResidentToolEvidenceScope
 	readonly revision: number | null
 	readonly claimId: string | null
-	readonly evidence: RunEvidenceSearchResult | null
+	readonly evidence: SessionEvidenceSearchResult | null
 	readonly nextCursor: string | null
 	readonly incomplete: boolean
 	readonly unavailableRevisions: readonly number[]
 	readonly historyBytes: number
-	/** Present for bounded calls: history + declared resolution + run reads.
+	/** Present for bounded calls: history + declared resolution + turn evidence reads.
 	 * Failed source reads without a receipt conservatively consume the remainder.
 	 */
 	readonly chargedBytes?: number
 }
 /** @experimental The revision is authorized anew on every read, including after restart. */
 export interface ResidentToolEvidenceReadOptions
-	extends Omit<RunEvidenceReadOptions, 'maxReadBytes'> {
+	extends Omit<SessionEvidenceReadOptions, 'maxReadBytes'> {
 	readonly revision: number
-	/** Shared operation ceiling, at most 8 MiB; reserves at least 1 MiB for run reads. */
+	/** Shared operation ceiling, at most 8 MiB; reserves at least 1 MiB for turn evidence reads. */
 	readonly maxReadBytes?: number
 }
 /** @experimental Exact invocation text plus the settled claim that authorized access. */
-export interface ResidentToolEvidenceReadResult extends RunEvidenceReadResult {
+export interface ResidentToolEvidenceReadResult extends SessionEvidenceReadResult {
 	readonly revision: number
 	readonly claimId: string
 	readonly chargedBytes?: number
 }
-/** @experimental A host must bind tool access to the executing run, not just this source. */
+/** @experimental A host must bind tool access to the executing turn, not just this source. */
 export interface ResidentToolEvidenceSource {
 	readonly scope: ResidentToolEvidenceScope
 	readonly supportsTermRefinement?: boolean
@@ -101,7 +106,7 @@ export interface ResidentToolEvidenceSource {
 export function createResidentToolEvidenceSource(
 	options: ResidentToolEvidenceOptions,
 ): ResidentToolEvidenceSource {
-	const { history, resolveRun } = options
+	const { history, resolveTurn } = options
 	const resolutionReadBytes = z
 		.number()
 		.int()
@@ -121,7 +126,9 @@ export function createResidentToolEvidenceSource(
 			.parse(maxReadBytes)
 		const historyLimit = limit - resolutionReadBytes - 1024 * 1024
 		if (historyLimit < 1)
-			throw new Error('Resident read budget cannot fit history, resolution and run reads.')
+			throw new Error(
+				'Resident read budget cannot fit history, resolution and turn evidence reads.',
+			)
 		let charged = 0
 		return {
 			historyLimit,
@@ -183,7 +190,7 @@ export function createResidentToolEvidenceSource(
 	const cursorBase = {
 		scope: z.literal(JSON.stringify(scope)),
 		revision,
-		runCursor: z.string().max(4096).optional(),
+		turnCursor: z.string().max(4096).optional(),
 	}
 	const cursorSchema = z.discriminatedUnion('version', [
 		z.object({ ...cursorBase, version: z.literal(1), query: z.string().max(256) }).strict(),
@@ -194,9 +201,9 @@ export function createResidentToolEvidenceSource(
 		if (encoded.length > 8192) throw new Error('Resident continuation exceeds its encoded bound.')
 		return encoded
 	}
-	async function run(entry: ResidentSettledInvocation, signal?: AbortSignal) {
+	async function turn(entry: ResidentSettledInvocation, signal?: AbortSignal) {
 		signal?.throwIfAborted()
-		const source = await resolveRun(entry, signal)
+		const source = await resolveTurn(entry, signal)
 		signal?.throwIfAborted()
 		if (source.scope.tenantId !== scope.tenantId || source.scope.projectId !== scope.projectId)
 			throw new Error('Historical invocation belongs to a different owner.')
@@ -205,14 +212,14 @@ export function createResidentToolEvidenceSource(
 				tenantId: z.string().uuid(),
 				projectId: z.string().uuid(),
 				sessionId: z.string().uuid(),
-				runId: z.string().uuid(),
+				turnId: z.string().uuid(),
 			})
 			.parse(source.scope)
 		return { source, owner }
 	}
 	function assertOwner(
-		page: { scope: RunEvidenceSource['scope'] },
-		owner: RunEvidenceSource['scope'],
+		page: { scope: SessionEvidenceSource['scope'] },
+		owner: SessionEvidenceSource['scope'],
 		signal?: AbortSignal,
 	) {
 		signal?.throwIfAborted()
@@ -289,7 +296,7 @@ export function createResidentToolEvidenceSource(
 			let nextRevision: number | null = null
 			let historyBytes = 0
 			const unavailable = new Set<number>()
-			if (cursor.runCursor) {
+			if (cursor.turnCursor) {
 				const page = await history.read(
 					{
 						revision: cursor.revision,
@@ -323,19 +330,19 @@ export function createResidentToolEvidenceSource(
 				// source has already verified both sides of this settlement transition.
 				if (match) selected = match
 			}
-			let evidence: RunEvidenceSearchResult | null = null
+			let evidence: SessionEvidenceSearchResult | null = null
 			if (selected) {
 				try {
 					budget?.resolve()
-					const { source, owner } = await run(selected, signal)
+					const { source, owner } = await turn(selected, signal)
 					const narrowAtCursor =
-						!!refined && !!cursor.runCursor && source.supportsTermRefinement === true
+						!!refined && !!cursor.turnCursor && source.supportsTermRefinement === true
 					const page = await source.search(
 						{
 							...(refined && !narrowAtCursor ? refined : search),
 							...(search.terms ? { matchMode: 'token' as const, caseSensitive: false } : {}),
-							...(cursor.runCursor && (!refined || narrowAtCursor)
-								? { cursor: cursor.runCursor }
+							...(cursor.turnCursor && (!refined || narrowAtCursor)
+								? { cursor: cursor.turnCursor }
 								: {}),
 							...(narrowAtCursor ? { refineTerms: refined?.terms } : {}),
 							...(budget ? { maxReadBytes: budget.remaining } : {}),
@@ -358,10 +365,10 @@ export function createResidentToolEvidenceSource(
 					? encode({
 							...advancedCursor,
 							revision: selected.revision,
-							runCursor: evidence.nextCursor,
+							turnCursor: evidence.nextCursor,
 						})
 					: nextRevision
-						? encode({ ...advancedCursor, revision: nextRevision, runCursor: undefined })
+						? encode({ ...advancedCursor, revision: nextRevision, turnCursor: undefined })
 						: null
 			return {
 				scope,
@@ -390,7 +397,7 @@ export function createResidentToolEvidenceSource(
 			budget?.charge(page.scannedBytes, budget.historyLimit)
 			if (!page.entry) throw new Error('The requested settled claim is unavailable.')
 			budget?.resolve()
-			const { source, owner } = await run(page.entry, signal)
+			const { source, owner } = await turn(page.entry, signal)
 			const result = await source.read(
 				{
 					address: input.address,