@namzu/sdk 43.0.0 → 44.1.0

package/src/types/plugin/index.ts

@@ -12,9 +12,9 @@ import type {
 	RequestContextChange,
 	RequestContextSnapshot,
 } from '../../runtime/query/request-context.js'
-import type { PluginId, RunId, SessionId } from '../ids/index.js'
+import type { PluginId, SessionId, TurnId } from '../ids/index.js'
 import type { Message, ToolResultContent } from '../message/index.js'
-import type { CancelCause } from '../run/cancel-cause.js'
+import type { CancelCause } from '../session/cancel-cause.js'
 import type { ToolResult } from '../tool/index.js'
 
 // ---------------------------------------------------------------------------
@@ -90,21 +90,21 @@ export function assertPluginContributionType(type: PluginContributionType): void
 export type PluginHookEvent =
 	/**
 	 * The operator's prompt, before the model sees it. Carries `prompt`.
-	 * The one event that can BLOCK a run (`skip`) and the one that can add
+	 * The one event that can BLOCK a turn (`skip`) and the one that can add
 	 * to what the model is told (`annotate`).
 	 */
 	| 'user_prompt_submit'
-	/** A host's session opened or closed. Carries `sessionId`; `runId` is minted for the session's own hooks. */
+	/** A host's session opened or closed. Carries `sessionId` and no `turnId`: these hooks run outside any turn. */
 	| 'session_start'
 	| 'session_end'
 	/** A compaction pass is about to run / has run. Carries `compaction`. */
 	| 'pre_compact'
 	| 'post_compact'
-	/** A delegated run ended. Fired after its own `run_end`; carries `parentRunId`. */
+	/** A child session's turn ended. Fired after its own `turn_end`; carries `parentSessionId` and `parentTurnId`. */
 	| 'subagent_stop'
-	| 'run_start'
-	| 'run_end'
-	| 'run_interrupt'
+	| 'turn_start'
+	| 'turn_end'
+	| 'turn_interrupt'
 	| 'pre_tool_use'
 	| 'post_tool_use'
 	| 'pre_llm_call'
@@ -112,7 +112,21 @@ export type PluginHookEvent =
 	| 'iteration_start'
 	| 'iteration_end'
 
+/**
+ * Hook event names that were renamed when turns replaced runs. A config that
+ * still names one is refused, and the refusal names the replacement.
+ */
+export const RENAMED_PLUGIN_HOOK_EVENTS: Readonly<Record<string, PluginHookEvent>> = {
+	run_start: 'turn_start',
+	run_end: 'turn_end',
+	run_interrupt: 'turn_interrupt',
+}
+
 export function assertPluginHookEvent(event: PluginHookEvent): void {
+	const renamed = RENAMED_PLUGIN_HOOK_EVENTS[event as string]
+	if (renamed !== undefined) {
+		throw new Error(`Hook event '${event as string}' was renamed to '${renamed}'.`)
+	}
 	switch (event) {
 		case 'user_prompt_submit':
 		case 'session_start':
@@ -120,9 +134,9 @@ export function assertPluginHookEvent(event: PluginHookEvent): void {
 		case 'pre_compact':
 		case 'post_compact':
 		case 'subagent_stop':
-		case 'run_start':
-		case 'run_end':
-		case 'run_interrupt':
+		case 'turn_start':
+		case 'turn_end':
+		case 'turn_interrupt':
 		case 'pre_tool_use':
 		case 'post_tool_use':
 		case 'pre_llm_call':
@@ -149,7 +163,7 @@ export interface PluginModelRequest {
 	/** SDK provider-input content inventory; excludes adapter/server-private transformations. */
 	readonly context?: {
 		readonly snapshot: RequestContextSnapshot
-		/** Compared with the preceding pre_llm_call in this run; absent on the first. */
+		/** Compared with the preceding pre_llm_call in this turn; absent on the first. */
 		readonly change?: RequestContextChange
 	}
 	readonly model: string
@@ -183,13 +197,16 @@ export interface PluginCompactionInfo {
 }
 
 export interface PluginHookContext {
-	readonly runId: RunId
+	/** The turn the hook fired in. Absent on `session_start` and `session_end`. */
+	readonly turnId?: TurnId
 	readonly pluginId: PluginId
 	readonly event: PluginHookEvent
-	/** The host's session, on `session_*` and `user_prompt_submit`. */
-	readonly sessionId?: SessionId
-	/** The run that delegated, on `subagent_stop`. */
-	readonly parentRunId?: RunId
+	/** The host's session. Always present. */
+	readonly sessionId: SessionId
+	/** The session that delegated, on `subagent_stop`. */
+	readonly parentSessionId?: SessionId
+	/** The turn whose tool call spawned the child, on `subagent_stop`. */
+	readonly parentTurnId?: TurnId
 	/** The operator's prompt, on `user_prompt_submit`. */
 	readonly prompt?: string
 	/** The pass, on `pre_compact` and `post_compact`. */
@@ -199,9 +216,9 @@ export interface PluginHookContext {
 	readonly toolResult?: ToolResult
 	readonly iteration?: number
 	/**
-	 * Why the run was stopped, on `run_interrupt`.
+	 * Why the turn was stopped, on `turn_interrupt`.
 	 *
-	 * That hook is emitted only for a root run carrying the explicit `user`
+	 * That hook is emitted only for a root session's turn carrying the explicit `user`
 	 * cause. Keeping the field typed as the complete cause vocabulary lets a
 	 * host narrow normally and leaves room for a future, deliberate expansion
 	 * without overloading `event` or an error sentence.
@@ -212,7 +229,7 @@ export interface PluginHookContext {
 	 * The request about to be sent, on `pre_llm_call`.
 	 *
 	 * Both model-call hooks fired directly beside this data and were handed
-	 * none of it — only a run id and an iteration number — so an extension
+	 * none of it — only a turn id and an iteration number — so an extension
 	 * could observe THAT a call was happening and nothing about what it
 	 * was. A redaction pass, a prompt audit, a per-tenant token ledger: all
 	 * of them needed the one thing the hook did not carry.
@@ -225,8 +242,8 @@ export interface PluginHookContext {
 	 * accident of registration order.
 	 *
 	 * The freeze is one level deep, as elsewhere: each message is a frozen
-	 * copy, so writing to one is inert and cannot reach the run's history,
-	 * but a nested array inside a message is still the run's own.
+	 * copy, so writing to one is inert and cannot reach the turn's history,
+	 * but a nested array inside a message is still the turn's own.
 	 */
 	readonly request?: Readonly<PluginModelRequest>
 
@@ -236,14 +253,14 @@ export interface PluginHookContext {
 	readonly response?: Readonly<PluginModelResponse>
 	/**
 	 * Aborts when this hook's run is cancelled or its deadline expires.
-	 * `run_interrupt` is the exception: the run is already cancelled, so its
+	 * `turn_interrupt` is the exception: the turn is already cancelled, so its
 	 * handler receives a fresh signal that represents only the bounded cleanup
 	 * deadline. The original verdict is available as `cancelCause`.
 	 *
 	 * The runtime stops waiting on a slow hook either way, but in-process
 	 * JavaScript cannot be forcibly stopped. Without a signal the hook itself
 	 * never learns it was abandoned: an HTTP request inside it keeps a socket
-	 * open and its eventual side effects can happen after the run moved on. A
+	 * open and its eventual side effects can happen after the turn moved on. A
 	 * hook doing I/O must forward this signal and stop publishing when it
 	 * aborts.
 	 */

package/src/types/probe/event-kind.ts

@@ -1,8 +1,8 @@
 import type { AgentBusEvent } from '../bus/index.js'
-import type { RunEvent } from '../run/events.js'
+import type { SessionEvent } from '../session/events.js'
 
-export type ProbeEventKind = RunEvent['type'] | AgentBusEvent['type']
+export type ProbeEventKind = SessionEvent['type'] | AgentBusEvent['type']
 
 export type VetoableEventKind = 'tool_executing'
 
-export type ProbeEvent = RunEvent | AgentBusEvent
+export type ProbeEvent = SessionEvent | AgentBusEvent

package/src/types/probe/registry.ts

@@ -1,11 +1,12 @@
-import type { RunId } from '../ids/index.js'
+import type { SessionId, TurnId } from '../ids/index.js'
 import type { ProbeEventKind, VetoableEventKind } from './event-kind.js'
 import type { ProbeEventOf } from './event-of.js'
 
 export type Unsubscribe = () => void
 
 export interface ProbeContext {
-	readonly runId?: RunId
+	readonly sessionId?: SessionId
+	readonly turnId?: TurnId
 	readonly isReplay: boolean
 }
 

package/src/types/project/entity.ts

@@ -48,7 +48,7 @@ export type ProjectStatus = 'open' | 'archived'
  * something to the code, not only to a listing.
  *
  * "Workspace" is a different noun in this codebase and is already taken:
- * see `WorkspaceRef`, which is per-run provisioning. This is the durable
+ * see `WorkspaceRef`, which is per-turn provisioning. This is the durable
  * one, and the prose above used to say the other word.
  */
 export interface Project {
@@ -66,9 +66,9 @@ export interface Project {
 	 * slash and the real path are one project rather than three records for
 	 * one directory.
 	 *
-	 * NOT `WorkspaceRef.meta.worktreePath`. That is per-RUN provisioning and
+	 * NOT `WorkspaceRef.meta.worktreePath`. That is per-TURN provisioning and
 	 * may be a different directory entirely — a git worktree cut for one
-	 * run and discarded after it. This is the durable binding a host uses to
+	 * turn and discarded after it. This is the durable binding a host uses to
 	 * answer "which project is this directory", across sessions and across
 	 * process restarts.
 	 *

package/src/types/provider/config.ts

@@ -87,7 +87,7 @@ export interface MockScript {
 	responseText?: string
 	responseDelayMs?: number
 	/**
-	 * Scripted turns. A script shorter than the run repeats its last entry,
+	 * Scripted turns. A script shorter than the turn repeats its last entry,
 	 * so a loop bug shows up as repetition rather than a crash.
 	 */
 	turns?: MockTurn[]
@@ -96,7 +96,7 @@ export interface MockScript {
 	/**
 	 * Override the capability declaration for this instance.
 	 *
-	 * Capability negotiation degrades a run when a driver says it cannot do
+	 * Capability negotiation degrades a turn when a driver says it cannot do
 	 * something, and testing that path means being able to SAY it — a fixed
 	 * registry-level declaration cannot express "a driver with no vision".
 	 */
@@ -116,7 +116,7 @@ export interface MockProviderConfig extends MockScript {
  * service has a tools endpoint; a driver that drops `attachments`
  * declares `supportsVision: false` even for a multimodal model.
  *
- * The query runtime consults these before each run (see
+ * The query runtime consults these before each turn (see
  * `resolveProviderCapabilities` in `provider/capabilities.ts`) so
  * degradation is loud instead of silent.
  */

package/src/types/provider/error.ts

@@ -8,7 +8,7 @@ export type ProviderErrorKind =
 	| 'server'
 
 /**
- * Serializable provider-failure metadata carried by failed runs and events.
+ * Serializable provider-failure metadata carried by failed turns and events.
  *
  * No response body, URL, or `cause` belongs here. `detail` is the one thing
  * the provider itself said, and it arrives scrubbed. `providerCode` preserves

package/src/types/provider/errors.ts

@@ -9,7 +9,7 @@
  *
  * The union is deliberately small. It answers exactly three questions the
  * runtime asks: is it worth retrying, should the delay come from the
- * server, and is this a context problem the run could recover from by
+ * server, and is this a context problem the turn could recover from by
  * shedding history.
  */
 export type ProviderErrorCode =
@@ -114,7 +114,7 @@ export function isProviderError(err: unknown): err is ProviderError {
 }
 
 /**
- * An abort is a control-flow signal, not a provider failure: the run loop
+ * An abort is a control-flow signal, not a provider failure: the turn loop
  * settles it as `cancelled`. It must never be reclassified or retried.
  */
 export function isAbortError(err: unknown): boolean {
@@ -273,7 +273,7 @@ function codeFromMessage(message: string): ProviderErrorCode | undefined {
 		m.includes('prompt is too long') ||
 		// Real wordings that missed every phrase above and so classified as
 		// a plain invalid request — which is not retryable, and which the
-		// overflow rescue tests for by exact equality. The run died holding
+		// overflow rescue tests for by exact equality. The turn died holding
 		// the remedy.
 		m.includes('too long for') ||
 		m.includes('maximum length') ||

package/src/types/provider/interface.ts

@@ -48,7 +48,7 @@ export interface LLMProvider {
 	 * `collectChatCompletion(provider.chatStream(params))` from
 	 * `@namzu/sdk/provider/collect-chat-completion`. The kernel's iteration
 	 * orchestrator consumes the stream directly so it can emit
-	 * per-delta `RunEvent`s.
+	 * per-delta `SessionEvent`s.
 	 *
 	 * Phase 2 of ses_001-tool-stream-events removed the previous
 	 * non-streaming `chat()` method from this interface.
@@ -132,7 +132,7 @@ export interface LLMProvider {
 	 *
 	 * Asked rather than assumed because effort is **refused, not clamped**:
 	 * a level a model does not have makes the vendor reject the request, so a
-	 * caller offering a choice it cannot honour produces a run that fails at
+	 * caller offering a choice it cannot honour produces a turn that fails at
 	 * the start rather than a quieter one. Building that choice needs the
 	 * answer BEFORE the request exists.
 	 *
@@ -202,7 +202,7 @@ export interface LLMProvider {
 	 * The kernel's only source below an explicit host config is a
 	 * hand-maintained prefix table, and its own header records what that
 	 * costs: one vendor family's entries all carried 200k including the
-	 * models whose window is 1M, so those runs compacted at roughly 14% full
+	 * models whose window is 1M, so those turns compacted at roughly 14% full
 	 * and threw away the prompt-cache prefix to do it. Every model release drifts the table
 	 * again until somebody edits it. Meanwhile at least one driver already
 	 * parses a real per-model `context_length` off the vendor listing and
@@ -216,9 +216,9 @@ export interface LLMProvider {
 	 * "I do not know" into a confident wrong number, which is the failure
 	 * the table already made once.
 	 *
-	 * Resolved ONCE per run, not per iteration — the two consumers are
+	 * Resolved ONCE per turn, not per iteration — the two consumers are
 	 * synchronous and in the hot loop, so this must never become an await
-	 * inside it. A rejection or a hang here is not a run failure: the table
+	 * inside it. A rejection or a hang here is not a turn failure: the table
 	 * is still there, and a driver that cannot answer must not take down a
 	 * run that would otherwise work.
 	 */

package/src/types/router/task-router.ts

@@ -15,7 +15,7 @@ export type TaskType =
  * fallback.** That is stated because the rest are silently inert, and an
  * inert key is worse than an absent one — a host who sets `coding` reads it
  * as taking effect. The compaction summary is the call worth routing first
- * regardless: it is the only model call a run makes that nobody asked for,
+ * regardless: it is the only model call a turn makes that nobody asked for,
  * it reads a transcript and writes a summary, and it fires on exactly the
  * long runs where the primary model costs the most.
  *

package/src/types/sandbox/index.ts

@@ -148,9 +148,9 @@ export interface SandboxExecOptions {
 	 *
 	 * Without it a Stop (or a per-tool deadline) could only ever abandon
 	 * the *wait* — the sandboxed process kept running after the host
-	 * believed the run had been cancelled.
+	 * believed the turn had been cancelled.
 	 *
-	 * **Who honours it.** The in-process local sandbox does: the run owns a
+	 * **Who honours it.** The in-process local sandbox does: the turn owns a
 	 * listener until the process group's shared stdio closes, and terminates
 	 * that group directly. The HTTP-container backends in `@namzu/sandbox` also
 	 * do: a
@@ -316,7 +316,7 @@ export interface Sandbox {
 	 * Optional, and a backend that cannot enforce it must **throw** rather
 	 * than accept and ignore. A network policy that is accepted and not
 	 * applied is worse than one that was never offered: the caller stops
-	 * looking, and the run proceeds believing it is confined. That is the
+	 * looking, and the turn proceeds believing it is confined. That is the
 	 * same rule the tiered sandbox provider follows, for the same reason.
 	 */
 	setNetworkPolicy?(policy: SandboxNetworkPolicy): Promise<void>
@@ -423,7 +423,7 @@ export interface Sandbox {
 	/**
 	 * Release every resource owned by this sandbox.
 	 *
-	 * The signal belongs to a fresh teardown operation, not to the run that is
+	 * The signal belongs to a fresh teardown operation, not to the turn that is
 	 * already ending. Implementations should stop their teardown transport and
 	 * settle promptly when it aborts. Hosts may still impose an independent
 	 * wait bound because a third-party implementation can ignore the signal.
@@ -431,7 +431,7 @@ export interface Sandbox {
 	destroy(options?: SandboxDestroyOptions): Promise<void>
 }
 
-/** Authority for a teardown operation owned independently of the ending run. */
+/** Authority for a teardown operation owned independently of the ending turn. */
 export interface SandboxDestroyOptions {
 	readonly signal?: AbortSignal
 }
@@ -489,7 +489,7 @@ export type ContainerSandboxMountSource =
 			 * No external mount — the image itself provides the directory.
 			 * Used by managed-warm-pool backends (ACI Standby Pool) whose
 			 * claim semantics forbid per-task volume overrides. The
-			 * container's own ephemeral filesystem carries the run; the
+			 * container's own ephemeral filesystem carries the turn; the
 			 * host walks output files out via the worker's HTTP API
 			 * before destroy and persists them somewhere durable
 			 * (e.g. blob storage).
@@ -522,7 +522,7 @@ export interface ContainerSandboxLayoutMount {
  * the difference has to be legible to the model from the path alone:
  *
  *  - `outputs` — RW bind. User-visible output surface that the
- *    user consumes after the run. Default container path
+ *    user consumes after the turn. Default container path
  *    `/mnt/user-data/outputs`. **Required** for container backends:
  *    without it the model has no place to persist work past the
  *    container's lifetime.
@@ -613,7 +613,7 @@ export interface ResolvedContainerSandboxLayout {
 
 export interface SandboxCreateConfig {
 	/**
-	 * Withdraws authority to publish the allocation to the run.
+	 * Withdraws authority to publish the allocation to the turn.
 	 *
 	 * Providers should stop their transport and reconcile any resource they can
 	 * identify. This signal is not, by itself, proof that a remote allocation
@@ -684,7 +684,7 @@ export const SandboxConfigSchema = z.object({
 	memoryLimitMb: z.number().positive().default(SANDBOX_DEFAULT_MEMORY_LIMIT_MB),
 	maxProcesses: z.number().positive().default(SANDBOX_DEFAULT_MAX_PROCESSES),
 	/**
-	 * Controls the run depends on. Provider construction throws when the
+	 * Controls the turn depends on. Provider construction throws when the
 	 * host cannot enforce one of them. Empty by default, which keeps
 	 * best-effort behaviour for callers that never asked for a guarantee —
 	 * but a caller that did ask now gets it or gets an error, never a
@@ -698,13 +698,13 @@ export const SandboxConfigSchema = z.object({
 	 * the run a fresh temp directory. Nothing the agent writes touches the
 	 * caller's files, and nothing the caller has is visible to it.
 	 *
-	 * `'working-directory'` roots it at the run's own `workingDirectory`, so
+	 * `'working-directory'` roots it at the turn's own `workingDirectory`, so
 	 * a sandboxed `bash` acts on the project the agent was asked about
 	 * instead of on an empty directory. That is the case the sandbox was
 	 * wanted for and the one it could not do: the field existed on
 	 * `SandboxCreateConfig` and the kernel never set it, so configuring a
-	 * sandbox through `runConfig.sandbox` always got a temp directory
-	 * whatever the run's own cwd was.
+	 * sandbox through `turnConfig.sandbox` always got a temp directory
+	 * whatever the turn's own cwd was.
 	 *
 	 * The trade is the point of naming it rather than inferring it. Rooted
 	 * at the working directory, confinement still bounds the agent to that

package/src/types/session/answer-review.ts

@@ -0,0 +1,85 @@
+import type { SessionId, TurnId } from '../ids/index.js'
+import type { Message, UserMessage } from '../message/index.js'
+import type { PreparationTextRequest, PreparationTextResult } from './prepare-step.js'
+
+/**
+ * A host's verdict on the answer a turn is about to settle with.
+ *
+ * The halt predicate is only consulted after tools have run, so there was
+ * no seam at the point the model stops calling them: the turn finalized
+ * with whatever it had produced. Verify-then-fix — run the build, feed the
+ * failure back, let it try again — meant starting a whole new turn and
+ * re-supplying the context the first one had already assembled.
+ */
+export type AnswerReview =
+	| { readonly accept: true }
+	| {
+			readonly accept: false
+			/**
+			 * Feedback supplied as runtime context on the next model request.
+			 *
+			 * Prose rather than a code, because the model is the audience
+			 * and a code would have to be explained to it anyway. Say what
+			 * is wrong and what would satisfy the check — "the build fails
+			 * with X" gets a fix; "rejected" gets a paraphrase.
+			 */
+			readonly feedback: string
+	  }
+
+/** What the reviewer is told about the turn it is judging. */
+export interface AnswerReviewContext {
+	readonly sessionId: SessionId
+	readonly turnId: TurnId
+	readonly iteration: number
+	/** Turn cancellation; reviewers should forward it to verification operations. */
+	readonly signal?: AbortSignal
+	/** Canonical history currently retained by the turn; compaction may remove messages. */
+	readonly messages: readonly Message[]
+	/**
+	 * Isolated copy of the SDK messages dispatched for this candidate's model
+	 * request, after context projection and any image-recovery retry. Includes
+	 * request-only evidence absent from durable history; excludes this candidate
+	 * and subsequently delivered messages/results. This is the provider-chain
+	 * input, not a vendor-wire capture or proof of truth/freshness. Optional for
+	 * hosts constructing their own review context. Not checkpointed or retained
+	 * as conversation history; modifying the copy cannot edit the turn/request.
+	 */
+	readonly requestMessages?: readonly Message[]
+	/**
+	 * Isolated copy of the latest operator, goal-round or steering input accepted
+	 * before this candidate's dispatch. Retained even when compaction removes
+	 * that input from history. Excludes arrivals delivered after dispatch and
+	 * runtime reports. This is one input, not the complete task specification
+	 * or a guarantee that the original message was sent verbatim to the model.
+	 */
+	readonly latestUserMessage?: UserMessage
+	/**
+	 * Optional turn-owned, tool-free inference: at most one call per review
+	 * invocation, revoked when the callback ends. Uses the same bounded text
+	 * request/result shapes as prepareStep and the turn's metered provider chain,
+	 * selected step model and effort. No history, candidate or tools are attached
+	 * implicitly. Await its result before returning a verdict; generated text
+	 * is a model judgment, not authenticated evidence. Missing in custom hosts
+	 * which do not supply this capability.
+	 */
+	readonly generateText?: (request: PreparationTextRequest) => Promise<PreparationTextResult>
+}
+
+/**
+ * Judge a completed answer and either accept it or hand it back.
+ *
+ * Called only when the model stopped calling tools and the turn is about to
+ * settle, and never on the forced-final turn — that one exists to extract
+ * a closing summary under pressure, and rejecting it would spend budget
+ * the turn has already run out of.
+ *
+ * Exceptions and malformed verdicts fail the turn. Cancellation stops waiting;
+ * work started by a reviewer must still honor the supplied signal.
+ * Bounded: see the turn's answer-review limit. A reviewer that never
+ * accepts stops the turn with a stop reason that names it, rather than
+ * looping until the token budget ends the turn for an unrelated reason.
+ */
+export type ReviewAnswer = (
+	answer: string,
+	context: AnswerReviewContext,
+) => AnswerReview | Promise<AnswerReview>

package/src/types/session/audit.ts

@@ -0,0 +1,167 @@
+import type { CostInfo } from '../common/index.js'
+import type { AuditEventId, SessionId, TenantId, TurnId } from '../ids/index.js'
+import type { TurnExecutionStatus } from './turn.js'
+
+/**
+ * What happened to the thing this event describes.
+ *
+ * `'refused'` is a VALUE, not an absent record — the whole reason this type
+ * exists rather than reusing whatever shape {@link import('./events.js').SessionEvent}
+ * already had. Before this, a permission denial (the `AuthorizationGate`) and
+ * a guardrail block each produced nothing durable with cost/outcome/identity
+ * attached — the one outcome an auditor most needs was the one absent from
+ * the trail. See ses_020's logging design §5.
+ *
+ * `'approved'` is its counterpart for an action that crossed a boundary with
+ * consent: a path outside the working directory a review approved, a command
+ * a reviewer confirmed outside the sandbox. Like `'refused'` it is one action
+ * inside an open turn, never the turn's verdict, so {@link replayAudit} skips
+ * it.
+ */
+export type AuditOutcome = 'success' | 'failure' | 'refused' | 'approved'
+
+/**
+ * Who acted, in the compliance-audit sense: the actor's identity and the
+ * tenant it acted under.
+ *
+ * `persona` is the label a host assigned the agent for THIS turn — absent
+ * when the turn was not configured with one (most runs today), and nothing
+ * here invents a value for it. Populated only at call sites that actually
+ * have a persona in scope (`runtime/query/index.ts`'s guardrail-block
+ * branches, via `params.persona?.identity.role`); a call site with no
+ * persona in scope (the verification-gate denial inside `tool-review.ts`)
+ * legitimately omits it rather than guessing.
+ */
+export interface AuditActor {
+	readonly agentId: string
+	readonly tenantId: TenantId
+	readonly persona?: string
+}
+
+/**
+ * What was attempted. `tool` is present for a tool-scoped action; absent for
+ * a turn-level one (an input/output guardrail, the turn's own completion or
+ * failure). `resource` names the thing the action targeted when that is
+ * narrower than the tool itself — a guardrail's own name, for instance.
+ *
+ * `action` is deliberately a free-text label, not a closed union: unlike
+ * `SessionEvent['type']` (which a switch must exhaustively handle, per
+ * Convention #16), nothing here switches on `action` today, and closing it
+ * prematurely would be inventing a vocabulary nobody has asked to enumerate
+ * yet.
+ */
+export interface AuditAction {
+	readonly action: string
+	readonly tool?: string
+	readonly resource?: string
+}
+
+/**
+ * One entry in a session's audit trail — durable evidence of what the agent
+ * did, under whose identity, at what cost, and whether it was allowed.
+ *
+ * ## Why this is not an operational log line
+ *
+ * See ses_020's logging design §5 for the full reasoning. It is appended to
+ * the session log as an `audit` record. In short: an
+ * operational log is level-filtered, sampled, rotatable and legitimately
+ * absent when no host installed a sink. None of that is acceptable for the
+ * kernel's own claim — "an auditable trail of what it did and what it
+ * cost", the README's sentence about itself.
+ *
+ * ## `seq` is the audit trail's OWN sequence
+ *
+ * Independent of the session log's record `seq`: the audit entries of a
+ * session are numbered among themselves, so a reader can tell whether one is
+ * missing.
+ *
+ * ## `cost` is NON-OPTIONAL
+ *
+ * "What it did and what it cost" is the kernel's own sentence about itself
+ * (README) — an audit entry that cannot say what something cost has not
+ * answered the question it exists to answer. It carries the turn's
+ * CUMULATIVE total AT THIS MOMENT, matching `Turn.costInfo`'s own semantics
+ * (see `utils/cost.ts`'s `accumulateCost`: the field IS the running total,
+ * not a delta, so "the most recent entry carries the answer whole" is
+ * already how the derived summary treats it — see {@link replayAudit}).
+ */
+export interface AuditEvent {
+	readonly id: AuditEventId
+	readonly sessionId: SessionId
+	/** Absent for an entry recorded outside any turn. */
+	readonly turnId?: TurnId
+	readonly seq: number
+	/** Epoch ms at which the store recorded the event. */
+	readonly timestamp: number
+	readonly who: AuditActor
+	readonly what: AuditAction
+	readonly outcome: AuditOutcome
+	readonly cost: CostInfo
+	/** Present on `'refused'`, `'failure'` and `'approved'` — the reason a reader needs. */
+	readonly reason?: string
+	/**
+	 * The active span's identity at the moment this entry was recorded —
+	 * resolved the same way `utils/log/create-logger.ts`'s `emit` resolves
+	 * `LogRecord.traceId`/`spanId`: fresh per record, off the live
+	 * `@opentelemetry/api` global, never captured once and reused. Genuinely
+	 * absent — not `''`, not `'unknown'` — whenever nothing is active. See
+	 * `telemetry/runtime-accessors.ts`'s `getActiveSpanContext` for why.
+	 */
+	readonly traceId?: string
+	readonly spanId?: string
+}
+
+/**
+ * What a caller hands
+ * {@link import('../../manager/session/turn-recorder.js').TurnRecorder.recordAudit} —
+ * the fields ONLY the call site knows. `id`, `sessionId`, `turnId`, `seq`, `timestamp`,
+ * `who.agentId`/`who.tenantId` and `cost` are filled in by `recordAudit`
+ * itself from the turn it is bound to; a caller supplying them would be
+ * asserting facts about identity and cost that only the turn-persistence
+ * layer is positioned to know, and could disagree with what the turn
+ * actually holds.
+ */
+export interface AuditEventInput {
+	readonly what: AuditAction
+	readonly outcome: AuditOutcome
+	readonly reason?: string
+	readonly persona?: string
+}
+
+/** What {@link replayAudit} reconstructs from the trail alone. */
+export interface AuditSummary {
+	readonly costInfo: CostInfo
+	readonly status: Extract<TurnExecutionStatus, 'completed' | 'failed'>
+}
+
+/**
+ * Reconstruct a completed turn's cost and status from its audit trail alone,
+ * with no read of the derived `Turn`.
+ *
+ * `Turn.costInfo` and `Turn.status` are a DERIVED summary; the audit trail is
+ * the evidence, and a divergence between what this returns and what the
+ * summary holds is a defect in the summary, never in the trail.
+ *
+ * Walks from the END rather than folding forward: `cost` on each entry is
+ * already the turn's cumulative total (see {@link AuditEvent.cost}), so the
+ * most recent entry that actually SETTLES the turn — `'success'` or
+ * `'failure'` — carries the answer whole. A `'refused'` entry is a single
+ * action inside a still-open run, never the turn's own verdict, and is
+ * skipped rather than treated as terminal: otherwise a refusal that
+ * happened to be the last write before a crash would replay as the turn's
+ * final status, which is not what it means.
+ *
+ * `undefined` when no terminal entry exists — a turn still in progress, or
+ * one that crashed before a terminal write landed. Callers that need "no
+ * answer yet" and "diverges from the derived summary" to read differently
+ * should treat `undefined` as the former.
+ */
+export function replayAudit(events: readonly AuditEvent[]): AuditSummary | undefined {
+	for (let i = events.length - 1; i >= 0; i--) {
+		const event = events[i]
+		if (event === undefined) continue
+		if (event.outcome === 'success') return { costInfo: event.cost, status: 'completed' }
+		if (event.outcome === 'failure') return { costInfo: event.cost, status: 'failed' }
+	}
+	return undefined
+}