@namzu/sdk 27.1.0 → 29.0.0

package/src/types/hitl/policy.ts

@@ -0,0 +1,83 @@
+import type { RunId } from '../ids/index.js'
+import type { ResumeHandler } from './index.js'
+
+/**
+ * Who answers when the run asks a human, as a value rather than a closure.
+ *
+ * `ResumeHandler` was captured once at `query()` start and never read again
+ * from anywhere a host could reach — so switching from "ask me about every
+ * write" to "go ahead, I'm stepping out" meant ending the run and starting
+ * another. That is the same defect `permissionMode` had before it became a
+ * box the executor reads through, and it has the same cost: the fix
+ * discards the in-flight step and the context that step was built from.
+ *
+ * The `name` is not decoration. A durable log entry saying a policy changed
+ * is useless if the only thing it can print is `[Function (anonymous)]`,
+ * and this event exists to answer "who approved that, and under what rule"
+ * months later.
+ */
+export interface ApprovalPolicy {
+	/**
+	 * A stable name for this policy — `auto-approve`, `operator-tui`,
+	 * `deny-all`. Written to the durable log and shown to an operator.
+	 */
+	readonly name: string
+	readonly handler: ResumeHandler
+}
+
+/**
+ * The policy RIGHT NOW, plus the only supported way to change it.
+ *
+ * `set` is async because the change is durably recorded before it takes
+ * effect, and that ordering is deliberate: a policy that started approving
+ * writes before the record landed would leave a log where the approvals
+ * precede the decision that permitted them.
+ */
+export interface RunApprovalPolicy {
+	readonly current: ApprovalPolicy
+	/**
+	 * Swap the policy, recording who and why.
+	 *
+	 * `reason` is required rather than optional. Every field here is read by
+	 * somebody reconstructing an incident, and an optional reason is a field
+	 * that is absent exactly when it matters most — the change nobody
+	 * expected.
+	 */
+	set(policy: ApprovalPolicy, reason: string): Promise<void>
+
+	/**
+	 * The change the model has not been told about yet — and reading it is
+	 * what marks it told.
+	 *
+	 * The model plans around how closely it is being watched. A run that
+	 * silently stops asking a human, or silently starts, leaves the model
+	 * working from a supervision assumption that is no longer true: it will
+	 * keep batching destructive calls it expects to be reviewed, or keep
+	 * asking permission nobody is left to give.
+	 *
+	 * Read-and-clear rather than a flag somebody must remember to reset.
+	 * Told twice is worse than a plain notice: the second copy reads as a
+	 * second change, and the model will believe supervision moved again.
+	 * Only the LAST unannounced change is kept — three swaps between two
+	 * model calls are one fact by the time the model can act on it, and
+	 * replaying the intermediate ones would describe a history rather than
+	 * a state.
+	 */
+	takeUnannouncedChange(): ApprovalPolicyChange | undefined
+}
+
+/** A change the model has not yet been told about. */
+export interface ApprovalPolicyChange {
+	readonly from: string
+	readonly to: string
+	readonly reason: string
+}
+
+/** The durable record of a policy change. */
+export interface ApprovalPolicyChangedEvent {
+	readonly type: 'approval_policy_changed'
+	readonly runId: RunId
+	readonly from: string
+	readonly to: string
+	readonly reason: string
+}

package/src/types/ids/brand.ts

@@ -0,0 +1,58 @@
+/**
+ * Nominal-brand machinery for the id types — declared here, not yet applied.
+ *
+ * Today every id in `./index.ts` is a bare template-literal type, and
+ * TypeScript's assignability rule for those means
+ * `const x: RunId = 'run_totally-made-up'` compiles with no cast and no
+ * factory call. The result is indistinguishable at the type level from an id
+ * `generateRunId()` actually minted, so the compiler cannot tell a real id
+ * from a plausible-looking string.
+ *
+ * Applying this brand is a separate change, on purpose: flipping the
+ * declarations turns every existing bare literal into an error at once, and
+ * that is a `major` with a migration in front of it. This file ships the
+ * machinery and the runtime constructors that use it so the two can land
+ * independently — the constructors are useful on their own, since there is
+ * no runtime prefix validation in the tree at all today.
+ *
+ * **The prefix stays in the type, and that is the one place this diverges
+ * from a plain `Branded<B>`.** A brand alone would render as `RunId` in
+ * hovers and errors and tell a reader nothing about the shape. Keeping
+ * `` `${Prefix}_${string}` `` in the intersection means an editor hover still
+ * shows `run_${string}`, which is most of what makes these ids readable in
+ * a log line.
+ */
+
+declare const ID_BRAND: unique symbol
+
+/**
+ * An id with both its wire shape and a nominal tag.
+ *
+ * `B` is a string tag rather than the type's own name by convention — two
+ * ids with the same prefix but different meanings must not be mutually
+ * assignable, and only the tag can separate them.
+ */
+export type Id<Prefix extends string, B extends string> = `${Prefix}_${string}` & {
+	readonly [ID_BRAND]: B
+}
+
+/**
+ * The one way to produce a branded id without a runtime check.
+ *
+ * A brand cannot be constructed by writing it — `{ [ID_BRAND]: 'RunId' }` is
+ * not something a caller can type, since the symbol is not exported. So
+ * every id has to come from somewhere, and there are exactly three places:
+ * `generate*Id()` mints one, `as*Id()` checks a string into one, and this.
+ *
+ * Named `unsafeId` rather than `toId` because the name is the warning, and
+ * kept HERE rather than in `utils/id.ts` because this file has no imports —
+ * `types/ids/index.ts` needs it for `UNKNOWN_TENANT_ID` and cannot import
+ * from `utils/id.ts` without closing a cycle.
+ *
+ * Not exported from the package barrel. A consumer that needs an id from a
+ * string wants the checked constructor; one that wants to skip the check is
+ * asking for the thing the brand exists to prevent.
+ */
+export function unsafeId<T extends string>(value: string): T {
+	return value as unknown as T
+}

package/src/types/ids/index.ts

@@ -1,7 +1,23 @@
-export type RunId = `run_${string}`
-export type MessageId = `msg_${string}`
-export type SessionId = `ses_${string}`
-export type ToolCallId = `call_${string}`
+import { type Id, unsafeId } from './brand.js'
+
+/**
+ * Every id here is NOMINAL as of NZ-SURF-11: `Id<Prefix, Tag>` intersects the
+ * wire shape with a unique-symbol brand, so `const a: RunId = 'run_x'` no
+ * longer compiles and neither does handing a `SessionId` where a `RunId` was
+ * asked for. Ids are minted by `generate*Id()` or checked by `as*Id()` in
+ * `utils/id.ts`; fixtures use `test-support/ids.ts`.
+ *
+ * **What this does NOT stop, measured rather than assumed:** a type
+ * ASSERTION. `'run_x' as RunId` and `someString as RunId` both still compile,
+ * because TypeScript's assertion rule only asks that the two types be
+ * comparable and a string is comparable to a branded string. The brand makes
+ * a rule against `as <IdType>` enforceable — it does not replace one. See
+ * `__tests__/an-id-is-not-a-string.test.ts`, which pins both halves.
+ */
+export type RunId = Id<'run', 'RunId'>
+export type MessageId = Id<'msg', 'MessageId'>
+export type SessionId = Id<'ses', 'SessionId'>
+export type ToolCallId = Id<'call', 'ToolCallId'>
 /**
  * Provider-issued tool-use identifier surfaced on the streaming event bus.
  * Providers emit different prefixes (`toolu_*`, `call_*`,
@@ -12,52 +28,85 @@ export type ToolCallId = `call_${string}`
  * persisted assistant messages and replay records.
  */
 export type ToolUseId = string
-export type ActivityId = `act_${string}`
-export type TaskId = `task_${string}`
-export type PlanId = `plan_${string}`
-export type KnowledgeBaseId = `kb_${string}`
-export type DocumentId = `doc_${string}`
-export type ChunkId = `chk_${string}`
-export type ConnectorId = `conn_${string}`
-export type ConnectorInstanceId = `ci_${string}`
-export type TenantId = `tnt_${string}`
-export type CredentialId = `cred_${string}`
-export type ExecutionContextId = `ectx_${string}`
-export type MCPServerId = `mcp_${string}`
-export type MCPClientId = `mcpc_${string}`
-export type MCPSessionId = `mcps_${string}`
-export type EnvironmentId = `env_${string}`
-export type CheckpointId = `cp_${string}`
-export type LockId = `lock_${string}`
-export type AdvisoryId = `adv_${string}`
-export type AdvisoryCallId = `advc_${string}`
-export type EmergencySaveId = `esave_${string}`
-export type MemoryId = `mem_${string}`
-export type PluginId = `plg_${string}`
-export type SandboxId = `sbx_${string}`
+export type ActivityId = Id<'act', 'ActivityId'>
+export type TaskId = Id<'task', 'TaskId'>
+export type PlanId = Id<'plan', 'PlanId'>
+export type KnowledgeBaseId = Id<'kb', 'KnowledgeBaseId'>
+export type DocumentId = Id<'doc', 'DocumentId'>
+export type ChunkId = Id<'chk', 'ChunkId'>
+export type ConnectorId = Id<'conn', 'ConnectorId'>
+export type ConnectorInstanceId = Id<'ci', 'ConnectorInstanceId'>
+export type TenantId = Id<'tnt', 'TenantId'>
+export type CredentialId = Id<'cred', 'CredentialId'>
+export type ExecutionContextId = Id<'ectx', 'ExecutionContextId'>
+export type MCPServerId = Id<'mcp', 'MCPServerId'>
+export type MCPClientId = Id<'mcpc', 'MCPClientId'>
+export type MCPSessionId = Id<'mcps', 'MCPSessionId'>
+export type EnvironmentId = Id<'env', 'EnvironmentId'>
+export type CheckpointId = Id<'cp', 'CheckpointId'>
+export type LockId = Id<'lock', 'LockId'>
+export type AdvisoryId = Id<'adv', 'AdvisoryId'>
+export type AdvisoryCallId = Id<'advc', 'AdvisoryCallId'>
+export type EmergencySaveId = Id<'esave', 'EmergencySaveId'>
+export type MemoryId = Id<'mem', 'MemoryId'>
+export type PluginId = Id<'plg', 'PluginId'>
+export type SandboxId = Id<'sbx', 'SandboxId'>
+/** LOG-14: the audit trail's own record id — distinct from `RunEvent.seq`. */
+export type AuditEventId = Id<'aud', 'AuditEventId'>
+
+// Actor identifiers (Session Hierarchy §4.3).
+//
+// This block used to say "branded so actor refs cannot be constructed from
+// bare strings" while the compiler enforced nothing. NZ-SURF-11 made that
+// true for `UserId`: `const a: UserId = 'usr_made-up'` is now an error.
+export type UserId = Id<'usr', 'UserId'>
 
-// Actor identifiers (Session Hierarchy §4.3). Branded so actor refs cannot be
-// constructed from bare strings.
-export type UserId = `usr_${string}`
-export type AgentId = `agt_${string}`
+/**
+ * @deprecated An agent is identified by its REGISTRY KEY, and this type
+ * never described one. Removal is a later major.
+ *
+ * `ActorRef.agentId` was annotated `AgentId` and every value that ever
+ * reached it was a key an operator chose — `'worker'`, `'reviewer'`,
+ * `'supervisor'` — reaching the field through an `as AgentId` cast. There is
+ * no producer: nothing in this kernel has ever called `generateAgentId`
+ * (there isn't one), so an `agt_`-prefixed agent identifier has never
+ * existed. NZ-SURF-11 changed `ActorRef.agentId` to `string`, which is what
+ * it always held.
+ *
+ * Kept for one release rather than deleted, per the deprecate-before-remove
+ * rule: a consumer that annotated its own variable `AgentId` still compiles
+ * and gets a warning. `asAgentId` is deprecated for the same reason and
+ * would throw on every value the kernel actually produces.
+ */
+export type AgentId = Id<'agt', 'AgentId'>
 
 // Shared-store placeholder refs (Session Hierarchy §4.2 / §3.2). Full shapes
 // land in later phases; kept here as opaque branded IDs so ProjectConfig can
 // reference them today.
-export type MemoryStoreRef = `mms_${string}`
-export type VaultRef = `vlt_${string}`
-export type KnowledgeBaseRef = `kbs_${string}`
+export type MemoryStoreRef = Id<'mms', 'MemoryStoreRef'>
+export type VaultRef = Id<'vlt', 'VaultRef'>
+export type KnowledgeBaseRef = Id<'kbs', 'KnowledgeBaseRef'>
 
 // Session hierarchy IDs. Convention #2 branded IDs; prefixes mandated by the
 // five-layer hierarchy (Project → Thread → Session → SubSession → Run). The
 // `types/session/ids.ts` barrel re-exports these for co-location ergonomics.
-export type ProjectId = `prj_${string}`
-export type ThreadId = `thd_${string}`
-export type SubSessionId = `sub_${string}`
-export type HandoffId = `hof_${string}`
-export type WorkspaceId = `wsp_${string}`
-export type SummaryId = `sum_${string}`
-export type DeliverableId = `del_${string}`
+export type ProjectId = Id<'prj', 'ProjectId'>
+/**
+ * NZ-TOPIC-04: narrowed from the NZ-TOPIC-01 alias `type TopicId = ThreadId`
+ * (both `thd_${string}`) to its own prefix. `thd_` from here on means only
+ * the pre-0.2.0 top-level container (`session/migration/id-prefix.ts`,
+ * `session/migration/filesystem.ts`) -- a meaning `ThreadId` never carried;
+ * it was purely the deprecated name for THIS type. Deleted rather than
+ * repurposed to mean the legacy container instead: a name whose meaning
+ * silently changes under unmigrated callers is worse than a name that is
+ * gone (Convention #0, no silent long-lived compat).
+ */
+export type TopicId = Id<'top', 'TopicId'>
+export type SubSessionId = Id<'sub', 'SubSessionId'>
+export type HandoffId = Id<'hof', 'HandoffId'>
+export type WorkspaceId = Id<'wsp', 'WorkspaceId'>
+export type SummaryId = Id<'sum', 'SummaryId'>
+export type DeliverableId = Id<'del', 'DeliverableId'>
 
 /**
  * Sentinel {@link TenantId} for legacy pre-0.2.0 runs rehomed by the
@@ -66,4 +115,7 @@ export type DeliverableId = `del_${string}`
  * real tenant is assigned — the kernel surfaces the sentinel but does not
  * prescribe policy (Convention #17).
  */
-export const UNKNOWN_TENANT_ID = 'tnt_unknown_legacy' as TenantId
+// `unsafeId`, not `asTenantId`: `utils/id.ts` imports this file, so reaching
+// for its constructor here would close a cycle. The prefix is pinned by
+// `__tests__/an-id-is-not-a-string.test.ts` instead.
+export const UNKNOWN_TENANT_ID = unsafeId<TenantId>('tnt_unknown_legacy')

package/src/types/message/index.ts

@@ -80,7 +80,31 @@ export interface Citation {
 }
 
 /** What a user message may carry alongside its text. */
-export type MessageAttachment = ImageAttachment | DocumentAttachment
+/**
+ * An attachment whose bytes are held by a store, not by the message.
+ *
+ * Structural rather than an import from `store/attachment`, so this types
+ * module keeps depending on nothing — the same reasoning `ToolRegistryRef`
+ * gives. `store/attachment` owns the resolution and its refusals; this is
+ * the shape a message may carry.
+ *
+ * Inline base64 puts the bytes in the durable transcript, in every
+ * checkpoint, in every compaction pass, and — because a conversation
+ * resends its history — on the wire once per turn. A 4 MB PDF attached once
+ * is 4 MB per request for the rest of the run.
+ */
+export interface StoredAttachmentRef {
+	readonly type: 'stored'
+	/** Opaque to the kernel. Meaningful to the store that minted it. */
+	readonly ref: string
+	readonly mediaType: string
+	/** Which kind of content block to build once the bytes arrive. */
+	readonly kind: 'image' | 'document'
+	readonly name?: string
+	readonly citations?: boolean
+}
+
+export type MessageAttachment = ImageAttachment | DocumentAttachment | StoredAttachmentRef
 
 export const isDocumentAttachment = (
 	attachment: MessageAttachment,

package/src/types/project/entity.ts

@@ -28,7 +28,7 @@ export interface ProjectConfig {
 }
 
 /**
- * Whether the workspace accepts new work.
+ * Whether the project accepts new work.
  *
  * Owner-managed, like the status it replaces: a project does not derive
  * `archived` from having no live sessions, because "empty right now" and
@@ -42,9 +42,13 @@ export type ProjectStatus = 'open' | 'archived'
  *
  * `status` is the gate the ingress paths read: an archived project accepts no
  * new session and no handoff. It lives here rather than on Thread because the
- * project is the thing a tenant actually closes — a workspace with its own
+ * project is the thing a tenant actually closes — a scope with its own
  * limits, its own environment, and its own memory — and closing it has to mean
  * 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
+ * one, and the prose above used to say the other word.
  */
 export interface Project {
 	id: ProjectId
@@ -54,6 +58,22 @@ export interface Project {
 	status: ProjectStatus
 	/** CAS counter for status transitions. Mirrors `Session.ownerVersion`. */
 	ownerVersion: number
+	/**
+	 * The canonical directory this project's work happens in.
+	 *
+	 * Resolved through `realpath` at creation, so a symlink and a trailing
+	 * 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
+	 * 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
+	 * answer "which project is this directory", across sessions and across
+	 * process restarts.
+	 *
+	 * Optional: a project need not be on disk at all.
+	 */
+	readonly rootPath?: string
 	createdAt: Date
 	updatedAt: Date
 }

package/src/types/provider/interface.ts

@@ -19,6 +19,22 @@ export interface LLMProvider {
 	 */
 	readonly capabilities?: ProviderCapabilities
 
+	/**
+	 * Retry behaviour this DRIVER wants, when the generic default is wrong
+	 * for the vendor behind it.
+	 *
+	 * One config was applied to every member of a chain, so an operator
+	 * running [expensive primary, cheap self-hosted backup] could not give
+	 * the backup a shorter budget — the two have different failure shapes
+	 * and different costs per attempt, and only the driver knows which.
+	 *
+	 * Merged UNDER a caller's config, never over it: the host asked for
+	 * something specific and the driver is expressing a default. Absent
+	 * means the generic default, which is what every driver had before this
+	 * existed.
+	 */
+	readonly retryDefaults?: Partial<import('../../provider/retry.js').ProviderRetryConfig>
+
 	/**
 	 * The single LLM entry point. Returns an async iterable of
 	 * {@link StreamChunk} carrying text deltas, tool-call argument
@@ -26,8 +42,8 @@ export interface LLMProvider {
 	 *
 	 * Consumers that need an aggregated response (legacy
 	 * `ChatCompletionResponse` shape) call
-	 * `collect(provider.chatStream(params))` from
-	 * `@namzu/sdk/provider/collect`. The kernel's iteration
+	 * `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.
 	 *
@@ -144,4 +160,31 @@ export interface LLMProvider {
 		model: string,
 		thinking?: import('./chat.js').ThinkingConfig,
 	): readonly import('./chat.js').ReasoningEffort[]
+
+	/**
+	 * How large a context this model actually has, if the vendor says.
+	 *
+	 * 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
+	 * 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
+	 * throws it away, because there was no member to return it through.
+	 *
+	 * Three states, exactly like {@link LLMProvider.effortLevelsFor}: the
+	 * member ABSENT means this driver cannot answer at all; a resolved
+	 * `undefined` means it asked and does not know; a number is the answer.
+	 * The three are different facts and collapsing any two of them turns
+	 * "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
+	 * 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
+	 * is still there, and a driver that cannot answer must not take down a
+	 * run that would otherwise work.
+	 */
+	resolveContextWindow?(model: string, signal?: AbortSignal): Promise<number | undefined>
 }

package/src/types/provider/model.ts

@@ -1,8 +1,22 @@
 export interface ModelInfo {
 	id: string
 	name: string
-	contextWindow: number
-	maxOutputTokens: number
+	/**
+	 * Tokens the model's context holds, when the driver knows.
+	 *
+	 * OPTIONAL, and the optionality is the fix. Four drivers filled this
+	 * with `0` where the vendor listing carries no value — and zero is not
+	 * a window, it is "I do not know" written as a number, which reads to
+	 * every consumer as a real measurement of a model that can hold
+	 * nothing. A caller dividing by it gets `Infinity`; one comparing
+	 * against it concludes every prompt is too long.
+	 *
+	 * Absent says the same thing honestly, and a consumer can then fall
+	 * back to its own table instead of trusting a zero.
+	 */
+	contextWindow?: number
+	/** Same, and absent for the same reason. */
+	maxOutputTokens?: number
 	inputPrice: number
 	outputPrice: number
 	supportsToolUse: boolean

package/src/types/run/audit.ts

@@ -0,0 +1,164 @@
+import type { CostInfo, RunExecutionStatus } from '../common/index.js'
+import type { AuditEventId, RunId, TenantId } from '../ids/index.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').RunEvent}
+ * 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.
+ */
+export type AuditOutcome = 'success' | 'failure' | 'refused'
+
+/**
+ * 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 run — absent
+ * when the run 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 run-level one (an input/output guardrail, the run'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
+ * `RunEvent['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 run's audit trail — durable evidence of what the agent
+ * did, under whose identity, at what cost, and whether it was allowed.
+ *
+ * ## Why this is a SEPARATE trail from `RunEvent`
+ *
+ * See {@link import('./store.js').RunStore.appendAuditEvent}'s own doc and
+ * ses_020's logging design §5 for the full reasoning. 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 this trail's OWN sequence space
+ *
+ * Independent of {@link import('./events.js').RunEvent}'s envelope `seq`,
+ * which numbers the (much higher-volume) operational transcript. Two logs,
+ * two cursors, and forcing them to share one counter would make an
+ * unrelated burst on one trail move the other's cursor — see
+ * `manager/run/persistence.ts`'s `_lastAuditSeq` for where this is held.
+ *
+ * ## `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 run's
+ * CUMULATIVE total AT THIS MOMENT, matching `Run.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 replayRun}).
+ */
+export interface AuditEvent {
+	readonly id: AuditEventId
+	readonly runId: RunId
+	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'` and `'failure'` — 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/run/persistence.js').RunPersistence.recordAudit} —
+ * the fields ONLY the call site knows. `id`, `runId`, `seq`, `timestamp`,
+ * `who.agentId`/`who.tenantId` and `cost` are filled in by `recordAudit`
+ * itself from the run it is bound to; a caller supplying them would be
+ * asserting facts about identity and cost that only the run-persistence
+ * layer is positioned to know, and could disagree with what the run
+ * actually holds.
+ */
+export interface AuditEventInput {
+	readonly what: AuditAction
+	readonly outcome: AuditOutcome
+	readonly reason?: string
+	readonly persona?: string
+}
+
+/** What {@link replayRun} reconstructs from the trail alone. */
+export interface RunSummary {
+	readonly costInfo: CostInfo
+	readonly status: Extract<RunExecutionStatus, 'completed' | 'failed'>
+}
+
+/**
+ * Reconstruct a completed run's cost and status from its audit trail alone,
+ * with no read of the derived `Run` record.
+ *
+ * This is the verification ses_020's design promises (§5): `Run.costInfo`
+ * and `Run.status`, persisted through `RunStore.writeRunMeta`
+ * (`manager/run/persistence.ts:221`/`:569`), are a full-record overwrite
+ * with no `seq` and no prior-value retention — a DERIVED summary cache, not
+ * the evidence. The audit trail is the evidence, and a divergence between
+ * what this returns and what `Run.costInfo`/`Run.status` actually hold 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 run's cumulative total (see {@link AuditEvent.cost}), so the
+ * most recent entry that actually SETTLES the run — `'success'` or
+ * `'failure'` — carries the answer whole. A `'refused'` entry is a single
+ * action inside a still-open run, never the run'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 run's
+ * final status, which is not what it means.
+ *
+ * `undefined` when no terminal entry exists — a run 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 replayRun(events: readonly AuditEvent[]): RunSummary | 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
+}