@namzu/sdk 42.0.2 → 44.0.0

package/src/types/session/fork.ts

@@ -0,0 +1,52 @@
+import type { CheckpointId, SessionId, ToolCallId, TurnId } from '../ids/index.js'
+import type { ToolResult } from '../tool/index.js'
+
+/**
+ * Controlled mutation applied at the fork point when a session is forked
+ * from a checkpoint. A fork always creates a NEW session whose
+ * `session_started.forkedFrom` names the source.
+ *
+ * v1 ships a single variant: `injectToolResponse` — the 80% debugging use
+ * case. Additional variants (`swapProvider`, `overrideBudget`, etc.) are
+ * deferred; see ses_005-deterministic-replay §3.3.
+ */
+export type Mutation = {
+	type: 'injectToolResponse'
+	toolCallId: ToolCallId
+	response: ToolResult
+}
+
+/**
+ * Lightweight listing entry returned by `listCheckpoints`. Projected from a
+ * checkpoint document — not the full payload, just enough to pick a fork
+ * point.
+ *
+ * Named `CheckpointListEntry` (not `CheckpointSummary`) to avoid collision
+ * with the pre-existing HITL `CheckpointSummary` shape at
+ * `types/hitl/index.ts`.
+ */
+export interface CheckpointListEntry {
+	id: CheckpointId
+	sessionId: SessionId
+	turnId: TurnId
+	iteration: number
+	createdAt: number
+	/** Records of the session log the checkpoint covers (`throughSeq`). */
+	throughSeq: number
+}
+
+/**
+ * Thrown when a {@link Mutation} cannot be applied at the resolved fork
+ * point. Currently raised by `injectToolResponse` when the supplied
+ * `toolCallId` does not match any pending tool call in the checkpoint's
+ * last assistant message.
+ */
+export class MutationNotApplicableError extends Error {
+	constructor(
+		message: string,
+		public readonly availableToolCallIds: readonly ToolCallId[],
+	) {
+		super(message)
+		this.name = 'MutationNotApplicableError'
+	}
+}

package/src/types/session/ids.ts

@@ -16,7 +16,7 @@ export type {
 	DeliverableId,
 	SessionId,
 	TenantId,
-	RunId,
+	TurnId,
 	AgentId,
 	UserId,
 	TaskId,

package/src/types/session/index.ts

@@ -1,6 +1,6 @@
-// Sub-barrel for session-hierarchy type surface.
-// Concrete definitions live in sibling files; re-export them here so other
-// modules import via `../types/session/index.js`.
+// The session → turn → message type surface. This directory is the only
+// definition of a turn, its events, its records and its durable state;
+// other modules import it through `../types/session/index.js`.
 
 export type {
 	ProjectId,
@@ -11,7 +11,7 @@ export type {
 	DeliverableId,
 	SessionId,
 	TenantId,
-	RunId,
+	TurnId,
 	AgentId,
 	UserId,
 	TaskId,
@@ -40,3 +40,23 @@ export type {
 	SubSessionDelegationStatus,
 	SubSessionStatus,
 } from './sub-session.js'
+
+export * from './turn.js'
+export * from './config.js'
+export * from './events.js'
+export * from './records.js'
+export * from './checkpoint.js'
+export * from './turn-state.js'
+export * from './durable.js'
+export * from './log-cursor.js'
+export * from './tool-execution.js'
+export * from './fork.js'
+export * from './audit.js'
+export * from './cancel-cause.js'
+export * from './derive-status.js'
+export * from './lineage.js'
+export * from './memory-promotion.js'
+export * from './answer-review.js'
+export * from './prepare-step.js'
+export * from './step.js'
+export * from './stop-reason.js'

package/src/types/session/lineage.ts

@@ -0,0 +1,15 @@
+import type { SessionId } from '../ids/index.js'
+
+/**
+ * Parent/root linkage carried on every sub-session event.
+ *
+ * Per session-hierarchy.md §10.4 every `SessionEvent` emitted from a sub-session
+ * carries a {@link Lineage} so consumers can reconstruct the delegation tree
+ * without walking the store. `depth` is 0 at the root session and grows by 1
+ * per delegation level.
+ */
+export interface Lineage {
+	parentSessionId: SessionId
+	rootSessionId: SessionId
+	depth: number
+}

package/src/types/session/log-cursor.ts

@@ -0,0 +1,69 @@
+/**
+ * Where a reconnecting consumer left off in a session log, and whether the
+ * kernel can honour it.
+ *
+ * The shortfall is a VALUE here, not a sentence in a document. A consumer that
+ * asks for everything after seq 400 and silently receives a splice from a
+ * different generation of the log is wrong and has no way to find out; a
+ * consumer handed `{ status: 'unavailable', reason: 'cursor_ahead' }` re-derives
+ * from the log and is right.
+ */
+
+import type { SessionLogHead } from '../../store/session-log/index.js'
+import type { FencingToken } from './durable.js'
+import type { SessionRecord } from './records.js'
+
+/** What a consumer holds when it comes back. */
+export interface SessionLogCursor {
+	/** The last record `seq` the consumer received. Zero means "from the beginning". */
+	readonly sinceSeq: number
+	/**
+	 * The lease fence (`gen`) of the records the consumer received, when it
+	 * tracked one. Compared for equality only.
+	 */
+	readonly generation?: FencingToken
+}
+
+/** Why a cursor could not be honoured. */
+export type SessionLogReplayRefusal =
+	/** The consumer claims to have seen more than the log holds. */
+	| 'cursor_ahead'
+	/** The session has been taken over since; the consumer's position belongs to an older holding. */
+	| 'generation_changed'
+	/** The first record returned is not the one right after the cursor. */
+	| 'gap'
+
+/** What came of a cursor. */
+export type SessionLogReplay =
+	/** The cursor is already at the log's head. Nothing was missed. */
+	| { readonly status: 'complete' }
+	/** Contiguous from `sinceSeq + 1`, oldest first. */
+	| { readonly status: 'replayed'; readonly records: readonly SessionRecord[] }
+	/** Nothing is delivered. The consumer re-derives from the log. */
+	| { readonly status: 'unavailable'; readonly reason: SessionLogReplayRefusal }
+
+/**
+ * Decide what a cursor is owed, given the log's head and the records read
+ * after `cursor.sinceSeq`.
+ *
+ * Pure. The generation check runs FIRST: a takeover invalidates the position,
+ * so comparing sequences across generations would be arithmetic on two
+ * different scales. A `null` head is an empty log.
+ */
+export function resolveSessionLogReplay(
+	cursor: SessionLogCursor,
+	head: SessionLogHead | null,
+	records: readonly SessionRecord[],
+): SessionLogReplay {
+	const lastSeq = head?.pointer.seq ?? 0
+	if (cursor.generation !== undefined && head !== null && cursor.generation !== head.gen) {
+		return { status: 'unavailable', reason: 'generation_changed' }
+	}
+	if (cursor.sinceSeq > lastSeq) return { status: 'unavailable', reason: 'cursor_ahead' }
+	if (cursor.sinceSeq === lastSeq) return { status: 'complete' }
+	const first = records[0]
+	if (!first || first.seq !== cursor.sinceSeq + 1) {
+		return { status: 'unavailable', reason: 'gap' }
+	}
+	return { status: 'replayed', records }
+}

package/src/types/session/memory-promotion.ts

@@ -0,0 +1,116 @@
+import type { SessionId, TurnId } from '../ids/index.js'
+
+/**
+ * What a turn learned, offered to whoever decides what is worth keeping.
+ *
+ * namzu could store a memory and could not *form* one. `MemoryStore` and
+ * its disk implementation have been here all along, and the only path
+ * into them is the model calling `save_memory` — so a turn that worked out
+ * a durable fact and never thought to write it down lost it at settle,
+ * along with everything the compaction pass had already extracted and
+ * structured on the way.
+ *
+ * The extraction is the part that was already built: the compaction pass
+ * distils the transcript into decisions, discoveries, constraints and
+ * failures precisely because a summary of prose is worth less than a list
+ * of facts. That structure was serialized into one system message and
+ * then dropped on the floor when the turn ended.
+ */
+export interface SessionMemoryCandidate {
+	readonly sessionId: SessionId
+	readonly turnId: TurnId
+	/** What the turn was asked to do, as the extractor recorded it. */
+	readonly task: string
+	/** Choices the turn made and did not revisit. */
+	readonly decisions: readonly string[]
+	/** Things it found out — the shape of a codebase, the name of a table. */
+	readonly discoveries: readonly string[]
+	/** What the user said must hold. The most durable category of the four. */
+	readonly userRequirements: readonly string[]
+	/** Approaches that failed, so a later turn does not pay for them again. */
+	readonly failures: readonly string[]
+	/** Facts about the machine, the toolchain, the environment. */
+	readonly environment: readonly string[]
+	/** Files the turn touched, by path. */
+	readonly files: readonly string[]
+	/**
+	 * How many entries each capped list dropped during the turn.
+	 *
+	 * Carried rather than hidden: a host deciding whether this is worth
+	 * storing should know it is looking at a truncated record.
+	 */
+	readonly evicted: Readonly<Record<string, number>>
+}
+
+/**
+ * Decide what a finished turn should leave behind.
+ *
+ * Called once, when the turn settles, with everything the compaction pass
+ * extracted. Deliberately a callback rather than a store the runtime
+ * writes into: what is worth remembering is a policy question the host
+ * owns, and a runtime that decided it would be writing a row for every
+ * run whether or not anything happened.
+ *
+ * Never blocks and never fails the turn. It runs after the answer is
+ * settled, so a throw is logged and swallowed — a memory that failed to
+ * form must not retract an answer that was already produced. A host that
+ * needs the write to be part of the turn's success should do it in its own
+ * code, where it can fail loudly.
+ */
+export type PromoteMemory = (candidate: SessionMemoryCandidate) => void | Promise<void>
+
+/**
+ * Project the compaction pass's working state into a promotion candidate.
+ *
+ * A projection rather than the state itself, for the same reason the
+ * plugin hooks got one: the working state is an internal structure with
+ * caps, eviction counters and slot objects that exist to serve
+ * compaction, and handing it over would make every future field of it
+ * part of a host-facing contract by accident.
+ */
+export function toMemoryCandidate(
+	sessionId: SessionId,
+	turnId: TurnId,
+	state: {
+		task: string
+		decisions: string[]
+		discoveries: string[]
+		userRequirements: string[]
+		failures: string[]
+		environment: string[]
+		files: Map<string, unknown>
+		evicted: Record<string, number>
+	},
+): SessionMemoryCandidate {
+	return {
+		sessionId,
+		turnId,
+		task: state.task,
+		decisions: [...state.decisions],
+		discoveries: [...state.discoveries],
+		userRequirements: [...state.userRequirements],
+		failures: [...state.failures],
+		environment: [...state.environment],
+		files: [...state.files.keys()],
+		evicted: { ...state.evicted },
+	}
+}
+
+/**
+ * The candidate for this turn, or `undefined` when there is nothing to
+ * offer.
+ *
+ * A separate function because "was anything extracted?" is a decision,
+ * and a decision inlined into a `try` is one a test cannot tell apart
+ * from the catch that swallows its failure. Without an extractor there
+ * is no working state, and inventing an empty candidate would ask a host
+ * to store a record of nothing.
+ */
+export function memoryCandidateFor(
+	sessionId: SessionId,
+	turnId: TurnId,
+	manager: { getState(): Parameters<typeof toMemoryCandidate>[2] } | undefined,
+): SessionMemoryCandidate | undefined {
+	if (!manager) return undefined
+	return toMemoryCandidate(sessionId, turnId, manager.getState())
+}

package/src/types/session/messages.ts

@@ -5,7 +5,7 @@
  * Rename of the legacy `ConversationMessage` concept, scoped by
  * {@link SessionId} and carrying {@link TenantId} for the Convention #17
  * key tuple (session-hierarchy.md §12.1). The `message` field preserves the
- * full Run-scoped `Message` payload verbatim; the wrapper only adds
+ * full Turn-scoped `Message` payload verbatim; the wrapper only adds
  * addressability + tenant isolation.
  */
 

package/src/types/session/prepare-step.ts

@@ -0,0 +1,299 @@
+import type { TokenUsage } from '../common/index.js'
+import type { SessionId, TurnId } from '../ids/index.js'
+import type { Message, UserMessage } from '../message/index.js'
+import type { ToolChoice } from '../provider/chat.js'
+import type { Skill } from '../skills/index.js'
+import type { StepResult } from './step.js'
+import type { StepProvenance } from './step.js'
+
+/** @experimental Bounded, tool-free inference shared by preparation and answer review. */
+export interface PreparationTextRequest {
+	readonly system: string
+	readonly prompt: string
+	/** Default 256; maximum 1,024. A provider limit, not a hard billing ceiling. */
+	readonly maxTokens?: number
+	/**
+	 * Accepted and validated; no longer bounds the request.
+	 *
+	 * @deprecated An auxiliary request that ends without its final usage
+	 * receipt leaves the turn's shared ledger with unresolved spend, which stops
+	 * the turn — so a deadline short enough to fire in normal use does not bound
+	 * the call, it ends the turn that made it. The call is bounded by the
+	 * provider's own request timeout and by the turn's cancellation instead, the
+	 * same two bounds every other model request in the turn has. Passing this
+	 * field changes nothing; it is retained so an existing caller keeps
+	 * compiling until it is removed in a later major.
+	 */
+	readonly timeoutMs?: number
+	readonly signal?: AbortSignal
+}
+
+/** @experimental Side-call usage also contributes to the owning turn's totals. */
+export interface PreparationTextResult {
+	readonly text: string
+	readonly usage: TokenUsage
+	readonly servedBy: StepProvenance
+}
+
+/**
+ * What the loop knows before it calls the model again.
+ *
+ * `stopWhen` (shipped earlier) let a turn DECIDE TO STOP based on what the
+ * steps produced. This is the other half of the same idea: deciding how
+ * the next step should be shaped. Without it, a turn's tool surface, model
+ * and sampling parameters are fixed at `query()` time, so a phased agent —
+ * research with search tools, then write with file tools, then verify with
+ * a cheaper model — had to be built as three separate turns, each losing
+ * the prior one's context.
+ */
+export interface PrepareStepContext {
+	readonly sessionId: SessionId
+	readonly turnId: TurnId
+	/**
+	 * When the turn began, in epoch milliseconds. A resumed turn keeps the
+	 * time of its `turn_started` record, whichever process wrote it, so a
+	 * step can tell what happened in this turn before it paused.
+	 */
+	readonly turnStartedAt?: number
+	/**
+	 * Optional turn-owned inference for context preparation. At most one call per
+	 * stage invocation; cannot be called after that stage returns. Uses the turn's
+	 * metered provider/fallback chain and the model selected by preceding stages.
+	 * Only supplied text is sent (12,000 characters total); no tools or history
+	 * are implicitly attached. Returned text is bounded to 8,192 characters.
+	 * Absent in beforeStep and in hosts which do not supply this capability.
+	 */
+	readonly generateText?: (request: PreparationTextRequest) => Promise<PreparationTextResult>
+	/**
+	 * Optional writer-bound snapshot of this invocation's completed events.
+	 * Never discovers other sessions or repeats tools. Unsupported stores return
+	 * undefined; cancellation or a settled invocation rejects capture. A local
+	 * signal can shorten, never extend, the turn's lifetime.
+	 */
+	readonly captureSessionEvidence?: (
+		maxReadBytes?: number,
+		signal?: AbortSignal,
+	) => Promise<import('../../store/evidence/types.js').SessionTextEvidenceSource | undefined>
+	/** 1-based, matching the iteration number in events and traces. */
+	readonly stepNumber: number
+	/** Full history as it stands, so a decision can read what happened. */
+	readonly messages: readonly Message[]
+	/**
+	 * Latest operator, goal-round, or steering input accepted by this turn,
+	 * retained even when compaction removes it from `messages`. Project
+	 * instructions and task-completion context do not replace operator intent.
+	 */
+	readonly latestUserMessage?: UserMessage
+	/** The turn's cancellation signal, for bounded asynchronous preparation. */
+	readonly signal?: AbortSignal
+	/**
+	 * Estimated room for additional step context after existing messages,
+	 * earlier stages' system/skills/context, and a response reserve. Recomputed for
+	 * each stage and its selected model; not a billing limit or fit guarantee.
+	 * `beforeStep` observes its existing boundary before compaction runs.
+	 */
+	readonly contextBudget?: {
+		readonly remainingTokens: number
+		readonly windowTokens: number
+	}
+	/** Every completed step, in order. */
+	readonly steps: readonly StepResult[]
+
+	/**
+	 * What the stages before this one decided, when several were supplied.
+	 *
+	 * Empty for the first stage, and empty for a single `prepareStep`.
+	 * Reading it is how a later stage refines an earlier one — narrowing a
+	 * tool set that has already been narrowed, or leaving a model alone
+	 * because something upstream had a reason to change it.
+	 */
+	readonly prepared: Readonly<PrepareStepResult>
+}
+
+/**
+ * Overrides for the NEXT step. Every field is optional; an omitted field
+ * keeps the turn's configured value, and returning nothing at all is the
+ * same as not supplying a `prepareStep`.
+ */
+export interface PrepareStepResult {
+	/**
+	 * Restrict which tools the model may call this step, by name. Names
+	 * that are not registered are dropped with a warning rather than
+	 * failing the turn.
+	 *
+	 * **Dropping every name leaves the step able to call nothing**, and that
+	 * is deliberate rather than an accident of the filter. This list means
+	 * "only these": if a rename outlives a phase list, the only set
+	 * satisfying "only the tools that no longer exist" is the empty one, and
+	 * widening back to the turn's list would grant precisely what the caller
+	 * did not ask for. The step is constrained, not crashed — the model
+	 * answers from what it has and the turn continues.
+	 *
+	 * This changed meaning when the list started bounding what may RUN
+	 * rather than only what the model is shown. Before, an aged-out list hid
+	 * every tool from the model while leaving all of them callable, which
+	 * was neither reading.
+	 *
+	 * The warning is the part to watch: it goes to the logger, and a host
+	 * that silences its logger sees a phase quietly stop doing anything.
+	 *
+	 * **This costs a prompt-cache prefix.** Tools render at position 0, so
+	 * changing the set between steps invalidates the cached prefix for that
+	 * step. That is inherent to narrowing, not an implementation detail, so
+	 * it is worth doing when a phase boundary genuinely changes what the
+	 * agent should reach for — and not worth doing every step.
+	 *
+	 * Note it does NOT imply a `tool_choice`. Not every provider has an
+	 * `allowed_tools` parameter, and moving `tool_choice` invalidates cached
+	 * MESSAGE blocks as well — a strictly worse trade for the same effect.
+	 * When a step genuinely needs the model FORCED rather than narrowed, ask
+	 * for it explicitly through {@link PrepareStepResult.toolChoice} and pay
+	 * that cost knowingly.
+	 */
+	readonly activeTools?: readonly string[]
+
+	/**
+	 * Force this step's tool use: `'required'` to make the model call
+	 * something, `'none'` to forbid it, or a named function to demand that
+	 * one. Absent leaves the provider's default.
+	 *
+	 * **It applies to this step only, by construction.** That is the whole
+	 * reason it lives here rather than on the turn config. A forced choice
+	 * that persists makes the model call a tool, see the result, and be
+	 * forced again — an agent that cannot stop. The one peer SDK that puts
+	 * `tool_choice` on persistent model settings has to undo it with a
+	 * tool-use tracker, an opt-out flag and a reset applied at two call
+	 * sites; the flag defaults to on precisely because turning it off hangs
+	 * the agent. Here there is nothing to reset and no flag to get wrong:
+	 * the next step is prepared fresh, so the force cannot outlive the step
+	 * that asked for it.
+	 *
+	 * **It costs more cache than `activeTools`.** Narrowing tools
+	 * invalidates the tool prefix; moving `tool_choice` invalidates cached
+	 * message blocks too. Worth it at a real phase boundary — "this step
+	 * must produce the structured answer" — and not worth it as a habit.
+	 */
+	readonly toolChoice?: ToolChoice
+
+	/**
+	 * Put these skills in front of the model for this step only.
+	 *
+	 * A turn's skills are fixed at `query()` time and rendered into the cached
+	 * system prefix, so every skill a turn might ever need is paid for on
+	 * every single turn. A phased agent rarely needs them all at once —
+	 * research wants the search skill, writing wants the style guide, and
+	 * neither benefits from carrying the other.
+	 *
+	 * Rendered into the same ephemeral system message `system` uses. Providers
+	 * may move that message before history, so changing skills can invalidate
+	 * reuse of the conversation prefix even though the turn's prompt is unchanged.
+	 *
+	 * ADDITIVE to the turn's skills, not a replacement. A skill the turn
+	 * always carries is not something a step should be able to take away by
+	 * naming a different one — that would make every step's list a complete
+	 * restatement, and a phase that forgot one would silently lose it.
+	 *
+	 * Sub-agents are deliberately NOT per-step. Which agents `create_task`
+	 * can reach is baked into that tool's input schema, so varying it would
+	 * rebuild the tool catalogue every step — a worse prompt-cache trade
+	 * than moving tools, for a narrowing a step can already express by
+	 * withholding `create_task` through {@link PrepareStepResult.activeTools}.
+	 */
+	readonly skills?: readonly Skill[]
+
+	/** Use a different model for this step. */
+	readonly model?: string
+
+	/**
+	 * Guidance for this step ONLY, appended as a system message that is not
+	 * retained afterwards.
+	 *
+	 * Some providers collect all system messages before conversation history.
+	 * Changing this field can therefore invalidate reuse of the history prefix.
+	 * Use `context` for changing observations that do not require system authority.
+	 */
+	readonly system?: string
+
+	/**
+	 * Current observations for this request only, appended after history and any
+	 * step system guidance. Carried as a visibly labelled user-role message with
+	 * runtime provenance, not operator input or system authority. It never enters
+	 * durable conversation history or replaces `latestUserMessage`.
+	 *
+	 * Useful for changing inventories and retrieved data on providers that hoist
+	 * system messages. This preserves the history's placement, not a cache-hit
+	 * guarantee. Later stages may compose `prepared.context` or replace it; an
+	 * empty string clears it. The next step starts without it.
+	 */
+	readonly context?: string
+
+	readonly temperature?: number
+	readonly maxResponseTokens?: number
+}
+
+/**
+ * Called before each model call, with everything the turn has produced so
+ * far.
+ *
+ * A throw fails OPEN — the step proceeds with the turn's configured values.
+ * Same reasoning as `stopWhen` and deliberately opposite to a guardrail: a
+ * broken step-shaping hook should not kill an otherwise healthy turn, and
+ * unlike a safety check, nothing unsafe gets through when it is skipped.
+ */
+export type PrepareStep = (
+	context: PrepareStepContext,
+) => PrepareStepResult | undefined | Promise<PrepareStepResult | undefined>
+
+/**
+ * A refusal of the next model call, with the reason it happened.
+ *
+ * An object rather than a boolean, for two reasons that are both about the
+ * reader. A bare boolean does not say which polarity means stop — `true`
+ * is equally readable as "allowed" and as "veto" — and it carries nothing
+ * into the turn record, so an operator finds a turn that stopped and no
+ * account of why.
+ */
+export interface StepVeto {
+	readonly reason: string
+}
+
+/**
+ * Called before each model call, and able to refuse it.
+ *
+ * `prepareStep` can only RESHAPE a step — `activeTools`, `model`,
+ * `system`, `temperature` — and cannot reject one. `StopCondition` reads
+ * `steps`, so it fires after the step it disliked has already run and been
+ * paid for. Neither is what a host with a live rate limit, a revoked
+ * tenant or a spend ceiling needs, and the only remaining path was a
+ * durable checkpoint built for human review of tool calls.
+ *
+ * A throw fails CLOSED, deliberately opposite to `prepareStep` above.
+ * They are different kinds of hook: a broken step-SHAPER should not kill
+ * an otherwise healthy turn, because nothing unsafe gets through when it is
+ * skipped. A broken step-REFUSER skipped is a refusal that did not happen,
+ * which is the thing it exists to prevent.
+ */
+export type BeforeStep = (
+	context: PrepareStepContext,
+) => StepVeto | undefined | Promise<StepVeto | undefined>
+
+/**
+ * One shaping stage, or several applied in order.
+ *
+ * A single slot is enough for one concern and no help with two. A host
+ * with a per-tenant system prefix AND a cost-based model downgrade had to
+ * hand-compose them into one callback, which puts the ordering in the
+ * host's code where nothing can see it and makes each concern's failure
+ * the other's problem.
+ *
+ * An ARRAY is ordered by declaration, not by registration. That
+ * distinction is the whole reason this is safe where a plugin-style
+ * fan-out would not be: the author writes the order down, so "who wins"
+ * is a line of their code rather than an accident of install history.
+ * Each stage sees what the ones before it decided, and a later stage
+ * overrides a field an earlier one set — last writer wins, visibly.
+ *
+ * A stage that throws is skipped and the rest still run, so one broken
+ * concern cannot silently disable the others.
+ */
+export type PrepareStepChain = PrepareStep | readonly PrepareStep[]