@namzu/sdk 20.2.0 → 20.4.0

package/src/store/run/listing.ts

@@ -14,12 +14,16 @@ import type {
 	CheckpointListingScope,
 	CheckpointRunScope,
 	CheckpointStore,
+	ClaimFence,
+	ClaimRunOptions,
+	ClaimSummary,
 	DurableRunEntry,
 	DurableRunOrder,
 	DurableRunPage,
 	ListDurableRunsOptions,
 	ParkState,
 	ParkSummary,
+	RunClaim,
 } from '../../types/run/checkpoint-store.js'
 
 /** Page size when the caller names none. */
@@ -186,11 +190,20 @@ export function paginateDurableRuns(
 	options?: ListDurableRunsOptions,
 ): DurableRunPage {
 	const wanted = options?.park
-	const filtered =
+	const byPark =
 		wanted && wanted.length > 0
 			? entries.filter((e) => e.park !== undefined && wanted.includes(e.park.state))
 			: entries
 
+	// An expired claim counts as unheld. That is what expiry means, and a
+	// queue reader that treated an expired claim as held would leave a dead
+	// worker's runs invisible forever — the exact failure a lease exists to
+	// prevent, reintroduced by the filter that reads it.
+	const filtered =
+		options?.claimed === undefined
+			? byPark
+			: byPark.filter((e) => (e.claim !== undefined && !e.claim.expired) === options.claimed)
+
 	// Both orders sort on a key that cannot move under a paging caller — see
 	// the contract comment on `listDurableRuns`.
 	const orderBy = options?.orderBy ?? 'runId'
@@ -305,3 +318,105 @@ export async function listDurableRuns(
 	assertContiguousListingScope(scope, 'listDurableRuns')
 	return store.listDurableRuns(scope, options)
 }
+
+/**
+ * Take working possession of a run, refusing when the store cannot arbitrate.
+ *
+ * The refusal is the entire safety property. `claimRun` is optional on the
+ * contract, and the natural way to reach an absent optional method is to skip
+ * it — which here means every worker proceeds, believing it holds a run
+ * nobody arbitrated. Two workers then restore the same checkpoint, both run
+ * the tools, and both write under one run id; half the work vanishes with no
+ * error anywhere.
+ *
+ * So a store with no claim support does not get "claimed by default". It gets
+ * an error naming the deployment shape it cannot support. A single-writer
+ * host never calls this and is unaffected.
+ *
+ * Returns `null` — not an error — when another holder has the run. That is
+ * the ordinary outcome of two readers on one queue, and a caller loops to the
+ * next run rather than handling a fault.
+ */
+export async function claimRun(
+	store: CheckpointStore,
+	scope: CheckpointRunScope,
+	options: ClaimRunOptions,
+): Promise<RunClaim | null> {
+	if (typeof store.claimRun !== 'function') {
+		throw new NamzuError({
+			code: 'capability_unavailable',
+			message:
+				'claimRun: the injected checkpoint store does not implement `claimRun`, so it cannot arbitrate between two workers taking the same run. Refusing rather than proceeding unclaimed — proceeding would let two workers restore one checkpoint, both execute its tools, and both write under one run id, which loses half the work and reports nothing. Supply a store that implements it, or run a single writer per run.',
+			details: { runId: scope.runId },
+		})
+	}
+	if (!Number.isFinite(options.ttlMs) || options.ttlMs <= 0) {
+		throw new NamzuError({
+			code: 'invalid_config',
+			message: `claimRun: ttlMs must be a positive number of milliseconds, got ${String(options.ttlMs)}. A lease that expires immediately is a lease every worker can take at once, which is the condition this call exists to prevent.`,
+			details: { runId: scope.runId, ttlMs: options.ttlMs },
+		})
+	}
+	return store.claimRun(scope, options)
+}
+
+/**
+ * Give a claim up early, refusing when the store cannot arbitrate.
+ *
+ * Refuses for the same reason as {@link claimRun}: a host that believes it is
+ * releasing a claim on a store that has none is a host that believes the
+ * whole mechanism is running.
+ */
+export async function releaseRun(
+	store: CheckpointStore,
+	scope: CheckpointRunScope,
+	fence: ClaimFence,
+): Promise<void> {
+	if (typeof store.releaseRun !== 'function') {
+		throw new NamzuError({
+			code: 'capability_unavailable',
+			message:
+				'releaseRun: the injected checkpoint store does not implement `releaseRun`. A release that silently does nothing would leave the run held until its lease expires while the caller believes it is back on the queue.',
+			details: { runId: scope.runId },
+		})
+	}
+	return store.releaseRun(scope, fence)
+}
+
+/**
+ * The refusal a store raises when a write presents a superseded fence.
+ *
+ * Shared so both shipped stores say the same thing, and so a host writing its
+ * own backend raises something a caller can branch on rather than a message
+ * string. This is the moment a stalled worker learns it lost the run — the
+ * only moment it CAN learn, since from the inside a pause and a partition
+ * both look like time not passing.
+ */
+export function fencedOut(
+	scope: CheckpointRunScope,
+	presented: number,
+	current: number,
+): NamzuError {
+	return new NamzuError({
+		code: 'storage_error',
+		message: `writeCheckpoint: refusing a write for run ${scope.runId} fenced at ${presented} — the run is now claimed at ${current}. Another worker took this run over, so this process no longer holds it and its work is not the record. Stop the run rather than retrying: the claim is gone, not busy.`,
+		details: { runId: scope.runId, presentedFence: presented, currentFence: current },
+		retryable: false,
+	})
+}
+
+/**
+ * Whether a recorded claim still holds at `now`, and the summary a listing
+ * reports for it.
+ */
+export function toClaimSummary(claim: RunClaim, now: number): ClaimSummary {
+	return {
+		holder: claim.holder,
+		fence: claim.fence,
+		expiresAt: claim.expiresAt,
+		// Judged here, once, against the store's clock. Left to the caller it
+		// would be judged against a different one, and a single page could
+		// then disagree with itself about which rows are available.
+		expired: now >= claim.expiresAt,
+	}
+}

package/src/store/run/memory.ts

@@ -0,0 +1,121 @@
+import type { Run } from '../../types/run/entity.js'
+import type { RunEvent } from '../../types/run/events.js'
+import type { CompletedToolRecord, RunStore } from '../../types/run/store.js'
+
+/**
+ * Process-local {@link RunStore}: a run's evidence with no filesystem.
+ *
+ * The reason it ships rather than living in a test file is that it is the
+ * only way to demonstrate the seam actually is one. A contract with a single
+ * implementation is a refactor; the second implementation is what proves a
+ * host could supply a third. It is also the parity partner for the disk
+ * store — a memory store that answers differently from disk is worse than
+ * none, because a host tests against one and ships the other.
+ *
+ * Deliberately not durable. It is for tests, for a single-process host that
+ * genuinely wants a run's evidence to die with the process, and for
+ * environments with no writable filesystem at all.
+ */
+export class InMemoryRunStore implements RunStore {
+	private runId: string | null = null
+	private parentRunId: string | undefined
+	private meta: Run | null = null
+	private messages: Run['messages'] = []
+	private report: string | null = null
+	private readonly events: RunEvent[] = []
+
+	async initRun(runId: string, parentRunId?: string): Promise<string | null> {
+		this.runId = runId
+		this.parentRunId = parentRunId
+		// No location, and that is the honest answer rather than a defect.
+		// Callers render `null` as "this run is not on a filesystem"; a
+		// synthesized path would put a directory that does not exist in front
+		// of an operator.
+		return null
+	}
+
+	private requireInit(): string {
+		if (this.runId === null) {
+			throw new Error('InMemoryRunStore not initialized — call initRun() first')
+		}
+		return this.runId
+	}
+
+	/** The run this store is bound to, and its parent when it has one. */
+	get boundTo(): { runId: string; parentRunId?: string } | null {
+		return this.runId === null
+			? null
+			: { runId: this.runId, ...(this.parentRunId ? { parentRunId: this.parentRunId } : {}) }
+	}
+
+	async writeRunMeta(run: Run): Promise<void> {
+		this.requireInit()
+		// Copied, not referenced. The caller keeps mutating this object for
+		// the rest of the run, so storing it by reference would make every
+		// historical read return the run's present state — a transcript that
+		// silently rewrites itself is worse than no transcript.
+		this.meta = structuredClone(run)
+	}
+
+	async writeMessages(run: Run): Promise<void> {
+		this.requireInit()
+		this.messages = structuredClone(run.messages)
+	}
+
+	async appendEvent(event: RunEvent): Promise<void> {
+		this.requireInit()
+		// Stamped on write, exactly as the disk store stamps its transcript
+		// line — a parity test compares the two read-backs, and a timestamp
+		// present in one medium and absent in the other would make identical
+		// runs look different depending on where they were recorded.
+		this.events.push({ ...event, timestamp: Date.now() } as unknown as RunEvent)
+	}
+
+	async writeReport(content: string): Promise<string | null> {
+		this.requireInit()
+		this.report = content
+		return null
+	}
+
+	async readCompletedTools(): Promise<Map<string, CompletedToolRecord>> {
+		this.requireInit()
+		const completed = new Map<string, CompletedToolRecord>()
+		for (const event of this.events) {
+			const e = event as unknown as Record<string, unknown>
+			if (e.type !== 'tool_completed') continue
+			const toolUseId = e.toolUseId
+			const toolName = e.toolName
+			if (typeof toolUseId !== 'string' || typeof toolName !== 'string') continue
+			// Last write wins: a retried tool emits one event per attempt and
+			// the final one is what actually answered the call. Same rule the
+			// disk store applies, and it has to be the same rule — a resumed
+			// run must not depend on which backend it was recorded with.
+			completed.set(toolUseId, {
+				toolUseId,
+				toolName,
+				result: typeof e.result === 'string' ? e.result : '',
+				isError: e.isError === true,
+			})
+		}
+		return completed
+	}
+
+	getRunDir(): string | null {
+		return null
+	}
+
+	// `addToIndex` is deliberately not implemented. It maintains a browsable
+	// catalogue for a human reading a directory, and there is no directory
+	// here. The optional method exists on the contract precisely so a backend
+	// can decline it rather than implement a no-op that looks like a listing.
+
+	/** Everything recorded for the bound run, for tests and parity checks. */
+	snapshot(): {
+		meta: Run | null
+		messages: Run['messages']
+		report: string | null
+		events: readonly RunEvent[]
+	} {
+		return { meta: this.meta, messages: this.messages, report: this.report, events: this.events }
+	}
+}

package/src/types/run/checkpoint-store.ts

@@ -175,6 +175,17 @@ export interface DurableRunEntry extends CheckpointRunScope {
 	readonly latestCheckpointAt: number
 	/** Absent when the run has never parked. */
 	readonly park?: ParkSummary
+
+	/**
+	 * Absent when no process has ever claimed the run.
+	 *
+	 * A SIBLING of {@link DurableRunEntry.park}, not a member of
+	 * {@link ParkState} — see the note on that union. A park is a question put
+	 * to a human; a claim is a lease held by a process. A run can have both,
+	 * neither, or either, and the state a queue worker needs most is parked
+	 * AND unclaimed, which one union cannot say.
+	 */
+	readonly claim?: ClaimSummary
 }
 
 /**
@@ -208,6 +219,65 @@ export type DurableRunOrder =
 	 */
 	| 'createdAt'
 
+/**
+ * A monotonically increasing number identifying one holding of a run's claim.
+ *
+ * The load-bearing word is *fencing*. A mutex answers "may I proceed", and a
+ * holder that stalls past its lease — a long GC pause, a suspended container,
+ * a partitioned network — answers it "yes" and then writes, long after
+ * somebody else legitimately took over. A fence answers a different question
+ * at the moment of the WRITE: "is the holding I belong to still the current
+ * one". Every claim of a run mints a number strictly greater than the last,
+ * so a store can reject a write from a superseded holder without knowing
+ * anything about processes, clocks or liveness.
+ *
+ * Not a random token, deliberately: randomness proves identity and cannot
+ * establish *order*, and order is the entire mechanism.
+ */
+export type ClaimFence = number
+
+/** A holding of a run's claim, as issued to the process that took it. */
+export interface RunClaim {
+	/** Opaque caller-supplied identity — a worker id, a pod name. Evidence, not authority. */
+	readonly holder: string
+	/** See {@link ClaimFence}. Present it on every durable write. */
+	readonly fence: ClaimFence
+	/**
+	 * Absolute epoch ms after which the claim may be taken by somebody else.
+	 *
+	 * Absolute rather than a duration for the same reason a park's deadline
+	 * is: it has to survive the process that set it. A duration plus an
+	 * in-process timer cannot — the holder is the thing that dies.
+	 */
+	readonly expiresAt: number
+}
+
+/** A run's claim as a listing reports it. */
+export interface ClaimSummary {
+	readonly holder: string
+	readonly fence: ClaimFence
+	readonly expiresAt: number
+	/**
+	 * Whether the claim had expired at the instant the listing was taken.
+	 *
+	 * A separate field rather than something the caller derives from
+	 * `expiresAt`, because the caller would derive it against a DIFFERENT
+	 * clock than the store used, and one page would then disagree with
+	 * itself about which rows are available.
+	 */
+	readonly expired: boolean
+}
+
+/** What a caller asks for when taking a run. */
+export interface ClaimRunOptions {
+	/** Who is taking it. Recorded so an operator can see what holds a stuck run. */
+	readonly holder: string
+	/** How long the holding is good for, in ms. */
+	readonly ttlMs: number
+	/** Clock, for tests and so one operation judges every expiry against one instant. */
+	readonly now?: number
+}
+
 /** Filters and paging for {@link CheckpointStore.listDurableRuns}. */
 export interface ListDurableRunsOptions {
 	/**
@@ -223,6 +293,16 @@ export interface ListDurableRunsOptions {
 	 * to include it.
 	 */
 	readonly park?: readonly ParkState[]
+	/**
+	 * Keep only runs that are, or are not, currently held by a worker.
+	 *
+	 * `false` is the queue-reader's filter: give me the work nobody has. A
+	 * claim that has expired counts as NOT held, because that is what expiry
+	 * means and a reader that skipped expired claims would leave a dead
+	 * worker's runs invisible forever — the exact failure the lease exists to
+	 * prevent.
+	 */
+	readonly claimed?: boolean
 	/** Page size. Defaults to 100, clamped to at least 1. */
 	readonly limit?: number
 	/** Resume token from the previous page's {@link DurableRunPage.cursor}. */
@@ -279,8 +359,27 @@ export interface DurableRunPage {
  * proceed.
  */
 export interface CheckpointStore {
-	/** Persist one checkpoint. Overwrites an existing checkpoint with the same id. */
-	writeCheckpoint(scope: CheckpointRunScope, checkpoint: IterationCheckpoint): Promise<void>
+	/**
+	 * Persist one checkpoint. Overwrites an existing checkpoint with the same id.
+	 *
+	 * @param fence the {@link ClaimFence} of the holding this write belongs
+	 *   to, when the run is claimed. A store that supports claims REFUSES a
+	 *   write whose fence is below the run's current one — that refusal is
+	 *   what makes a claim a lease rather than a suggestion, because a holder
+	 *   stalled past its expiry believes it still holds and is wrong only at
+	 *   the moment it writes.
+	 *
+	 *   Omit it and the write is unfenced, which is exactly today's behaviour
+	 *   and correct for a single-writer deployment. A store MUST NOT start
+	 *   refusing unfenced writes because some other write carried a fence:
+	 *   that would make adding a claim to one worker break every worker that
+	 *   has not adopted it yet.
+	 */
+	writeCheckpoint(
+		scope: CheckpointRunScope,
+		checkpoint: IterationCheckpoint,
+		fence?: ClaimFence,
+	): Promise<void>
 
 	/** Load a single checkpoint by id. Returns `null` when it does not exist. */
 	readCheckpoint(
@@ -342,4 +441,92 @@ export interface CheckpointStore {
 		scope: CheckpointListingScope,
 		options?: ListDurableRunsOptions,
 	): Promise<DurableRunPage>
+
+	/**
+	 * Take exclusive working possession of a run, or report that somebody
+	 * else has it. OPTIONAL — see the optional-capability rule on this
+	 * interface.
+	 *
+	 * Returns the holding on success and `null` when the run is currently
+	 * held by somebody else. `null` is not an error: "another worker got
+	 * there first" is the ordinary outcome of a queue with more than one
+	 * reader, and a thrown exception would make the normal case look like a
+	 * fault.
+	 *
+	 * ### What it is for
+	 *
+	 * Putting parked runs on a queue and letting more than one worker drain
+	 * it. Without this, two workers restore the same checkpoint, both execute
+	 * the run's tools, and both write checkpoints under one run id — each
+	 * write minting a fresh checkpoint id, so two divergent chains land in
+	 * one list and the pending lookup returns whichever wrote last. Half the
+	 * work vanishes and nothing reports an error.
+	 *
+	 * ### The lease, and why it expires
+	 *
+	 * A claim is a LEASE, not a lock. A lock held by a process that dies is
+	 * held forever, and the runs behind it are unreachable by anything except
+	 * a human with a shell. The expiry is what makes a dead holder's work
+	 * recoverable without one.
+	 *
+	 * The expiry is also why a fence exists. A holder does not know it has
+	 * expired — a long pause, a suspended container and a partition all look
+	 * from the inside like time not passing — so it wakes and writes as
+	 * though it still holds. Liveness cannot be checked from here. What CAN
+	 * be checked, at the write, is whether the holding that write belongs to
+	 * is still the current one, and that is a comparison of two numbers.
+	 *
+	 * ### Reclaiming
+	 *
+	 * Calling this on a run whose claim has expired SUCCEEDS and mints a
+	 * fence strictly greater than the expired holding's. The previous holder
+	 * is not notified — it cannot be, that is the premise — it simply stops
+	 * being able to write.
+	 *
+	 * Calling it again as the CURRENT holder also succeeds and extends the
+	 * lease, minting a new fence. Renewal and reclamation are the same
+	 * operation from the store's side, which is why there is no separate
+	 * `renew`: two code paths that must agree about who holds a run is one
+	 * more than can be kept correct.
+	 *
+	 * ### What a backend implementing this MUST guarantee
+	 *
+	 * These are the properties the fence comparison depends on. None of them
+	 * is checkable from here, and every one of them was violated by the first
+	 * built-in implementation, so they are written down rather than assumed:
+	 *
+	 *  1. **A fence exceeds every fence ever issued for the run** — including
+	 *     across a release, and across deletion of whatever recorded it. A
+	 *     counter that rewinds re-issues a number a stalled worker still
+	 *     believes it holds, and that worker's writes become legal again.
+	 *  2. **Fences are unique.** The write check is `fence < current`, so two
+	 *     holders at one number are both admitted. Equality is permissive
+	 *     here, which makes a duplicate worse than a gap.
+	 *  3. **The fence check is atomic with the write.** Reading the current
+	 *     fence and then writing is check-then-act, and the gap is a race. A
+	 *     database gets this free (`UPDATE … WHERE fence >= ?`); a filesystem
+	 *     does not, and the built-in disk store narrows rather than closes it.
+	 *  4. **`holder` is unique per process.** It is evidence rather than
+	 *     authority, but it is the only thing distinguishing a RENEWAL from a
+	 *     theft — two workers sharing a holder string take a live, unexpired
+	 *     claim from each other instantly. Use something per-process, not a
+	 *     per-deployment name.
+	 */
+	claimRun?(scope: CheckpointRunScope, options: ClaimRunOptions): Promise<RunClaim | null>
+
+	/**
+	 * Give a claim up early. Idempotent: releasing a claim that already
+	 * expired, was superseded, or never existed succeeds as a no-op.
+	 *
+	 * Presenting a stale fence releases NOTHING — a worker that stalled past
+	 * its lease must not be able to hand away a run somebody else is now
+	 * holding, and that is the same fencing comparison the write path makes.
+	 *
+	 * Optional to call, not optional to matter: a worker that finishes and
+	 * releases returns the run to the queue immediately, where one that just
+	 * exits leaves it stuck until the lease expires. That is a latency
+	 * difference, never a correctness one, which is the property that lets a
+	 * crashed worker be indistinguishable from a slow one.
+	 */
+	releaseRun?(scope: CheckpointRunScope, fence: ClaimFence): Promise<void>
 }

package/src/types/run/config.ts

@@ -136,6 +136,19 @@ export interface RunPersistenceConfig {
 	 * hosts inject a scope-keyed backend (e.g. Postgres) here.
 	 */
 	checkpointStore?: CheckpointStore
+
+	/**
+	 * Optional run-evidence persistence override. Defaults to the disk layout
+	 * under `outputDir` (a
+	 * {@link import('../../store/run/disk.js').RunDiskStore}); hosts inject
+	 * their own backend here.
+	 *
+	 * The sibling of `checkpointStore`, and it should have been one from the
+	 * start: checkpoints got an injectable seam while the run record, its
+	 * messages, its transcript and its report did not, so the evidence was
+	 * the one part of a run that could not leave the local filesystem.
+	 */
+	runStore?: import('./store.js').RunStore
 }
 
 export interface RunStoreConfig {

package/src/types/run/index.ts

@@ -3,6 +3,7 @@ export * from './prepare-step.js'
 export * from './stop-reason.js'
 export * from './config.js'
 export * from './checkpoint-store.js'
+export * from './store.js'
 export * from './entity.js'
 export * from './replay.js'
 // Domain `RunStatus` (session-hierarchy.md §4.6 state machine). Safe to

package/src/types/run/store.ts

@@ -0,0 +1,112 @@
+/**
+ * RunStore — persistence contract for a run's own evidence.
+ *
+ * The checkpoint store got an injectable seam and this did not, which left
+ * the run record, its messages, its transcript and its report reachable only
+ * through a concrete filesystem class. For a kernel whose stated purpose is
+ * auditable evidence, the evidence was the one thing that could not be
+ * pointed at durable storage: on ephemeral infrastructure the transcript dies
+ * with the container, and behind a load balancer two replicas write two
+ * disjoint run trees for one tenant.
+ *
+ * The location was already injectable through a path builder — but that
+ * returns filesystem path strings, so it relocates the directory without
+ * changing the medium.
+ *
+ * ## Bound to one run, unlike {@link CheckpointStore}
+ *
+ * Every accessor here addresses the run the store was bound to by
+ * {@link RunStore.initRun}, where a `CheckpointStore` takes an explicit scope
+ * per call. That asymmetry is inherited rather than chosen: this contract is
+ * extracted from a class the runtime already constructs per run and holds for
+ * the run's lifetime, and re-keying it would change every call site in the
+ * same change that introduces the seam — two risks where one will do.
+ *
+ * A host implementing a shared backend therefore keys its rows by the
+ * attribution it was constructed with plus the bound run id. If this is later
+ * re-keyed per call, it happens once, deliberately, as its own change.
+ */
+
+import type { Run } from './entity.js'
+import type { RunEvent } from './events.js'
+
+/**
+ * One finished tool call, recovered from the run's own transcript.
+ *
+ * Re-declared here rather than imported from the disk store so the contract
+ * does not depend on an implementation of itself.
+ */
+export interface CompletedToolRecord {
+	readonly toolUseId: string
+	readonly toolName: string
+	readonly result: string
+	readonly isError: boolean
+}
+
+export interface RunStore {
+	/**
+	 * Bind this store to a run, before any other call.
+	 *
+	 * Returns a location when the backend has one — the built-in disk store
+	 * returns the run's directory — and `null` when it does not. A caller
+	 * that renders the value must treat `null` as "this run is not on a
+	 * filesystem" rather than as an error: an in-memory or object-storage
+	 * backend has nothing to print, and inventing a path for it would put a
+	 * directory that does not exist in front of an operator.
+	 */
+	initRun(runId: string, parentRunId?: string): Promise<string | null>
+
+	/** Persist the run record: status, metadata, usage, timings. */
+	writeRunMeta(run: Run): Promise<void>
+
+	/** Persist the run's full message history. */
+	writeMessages(run: Run): Promise<void>
+
+	/**
+	 * Append one event to the run's durable event log.
+	 *
+	 * High-frequency streaming deltas are excluded before they reach here —
+	 * that exclusion is a deliberate trade and belongs to the emitter, not to
+	 * the backend, so a store must not re-filter.
+	 */
+	appendEvent(event: RunEvent): Promise<void>
+
+	/**
+	 * Persist the run's final report. Returns a location, or `null` when the
+	 * backend has none. See {@link RunStore.initRun}.
+	 */
+	writeReport(content: string): Promise<string | null>
+
+	/**
+	 * Every tool call this run has already finished, keyed by `toolUseId`.
+	 *
+	 * A batch's results reach the message history only once the WHOLE batch
+	 * settles, so a hard kill part-way through loses every result that had
+	 * already come back, and the resumed run re-executes those calls. For a
+	 * file write that is waste; for a payment or an email it is a second one.
+	 *
+	 * A backend that does not retain individual events answers with an empty
+	 * map, which costs re-execution and is honest. It must not answer with a
+	 * PARTIAL map: a caller reads a present entry as "this call is already
+	 * answered", so a half-remembered batch is worse than a forgotten one.
+	 */
+	readCompletedTools(): Promise<Map<string, CompletedToolRecord>>
+
+	/**
+	 * Where this run's evidence lives, or `null` when it is not on a
+	 * filesystem. Valid only after {@link RunStore.initRun}.
+	 */
+	getRunDir(): string | null
+
+	/**
+	 * Record the run in a browsable catalogue of runs. OPTIONAL.
+	 *
+	 * Optional because it is the one method here that is not evidence: it
+	 * maintains a convenience listing for a human reading the directory, and
+	 * a backend whose runs are already queryable has nothing to add. The
+	 * programmatic answer to "which runs are there" is
+	 * `CheckpointStore.listDurableRuns`, which carries attribution and
+	 * includes sub-runs; this does neither.
+	 */
+	addToIndex?(run: Run): Promise<void>
+}