@namzu/sdk 20.1.0 → 20.3.0

package/src/store/run/disk.ts

@@ -2,6 +2,7 @@ import { appendFile, mkdir, readFile, readdir, unlink } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js'
 import type { Run, RunEvent, RunStoreConfig } from '../../types/run/index.js'
+import type { CompletedToolRecord, RunStore } from '../../types/run/store.js'
 import { atomicWriteFile } from '../../utils/atomic-write.js'
 import { type Logger, getRootLogger } from '../../utils/logger.js'
 import { defineSchema, migrate, stamp } from '../schema.js'
@@ -16,15 +17,16 @@ import { defineSchema, migrate, stamp } from '../schema.js'
  */
 const SCHEMA = defineSchema({ kind: 'run-store', current: 1, migrations: {} })
 
-/** One finished tool call, recovered from the transcript. */
-export interface CompletedToolRecord {
-	readonly toolUseId: string
-	readonly toolName: string
-	readonly result: string
-	readonly isError: boolean
-}
+/**
+ * One finished tool call, recovered from the transcript.
+ *
+ * Re-exported from the store contract rather than declared twice. Two
+ * declarations of one concept, each populated by its own mapper, is the shape
+ * this repository has a rule about.
+ */
+export type { CompletedToolRecord }
 
-export class RunDiskStore {
+export class RunDiskStore implements RunStore {
 	private baseDir: string
 	private runDir: string | null = null
 	private log: Logger

package/src/store/run/listing.ts

@@ -15,6 +15,7 @@ import type {
 	CheckpointRunScope,
 	CheckpointStore,
 	DurableRunEntry,
+	DurableRunOrder,
 	DurableRunPage,
 	ListDurableRunsOptions,
 	ParkState,
@@ -139,8 +140,21 @@ export function toDurableRunEntry(
 	if (checkpoints.length === 0) return null
 
 	let latest = checkpoints[0] as IterationCheckpoint
+	// The EARLIEST recorded stamp, not the one on any particular checkpoint.
+	// Every checkpoint of a run carries the same value, so under that
+	// invariant the minimum is that value. Taking the minimum rather than
+	// reading one checkpoint is what makes the read safe if the invariant is
+	// ever broken: it can only err toward the run's true attribution, never
+	// away from it, and it cannot move when a later checkpoint is added.
+	let runCreatedAt: number | undefined
 	for (const cp of checkpoints) {
 		if (cp.createdAt > latest.createdAt) latest = cp
+		if (
+			cp.runCreatedAt !== undefined &&
+			(runCreatedAt === undefined || cp.runCreatedAt < runCreatedAt)
+		) {
+			runCreatedAt = cp.runCreatedAt
+		}
 	}
 
 	const park = summarizePark(checkpoints, now)
@@ -151,6 +165,7 @@ export function toDurableRunEntry(
 		sessionId: scope.sessionId,
 		runId: scope.runId,
 		...(scope.parentRunId ? { parentRunId: scope.parentRunId } : {}),
+		...(runCreatedAt !== undefined ? { runCreatedAt } : {}),
 		checkpointCount: checkpoints.length,
 		latestCheckpointId: latest.id,
 		latestCheckpointAt: latest.createdAt,
@@ -176,12 +191,16 @@ export function paginateDurableRuns(
 			? entries.filter((e) => e.park !== undefined && wanted.includes(e.park.state))
 			: entries
 
-	// Ordered by `runId` because it is the only per-run key that cannot move
-	// under a paging caller — see the contract comment on `listDurableRuns`.
-	const ordered = [...filtered].sort((a, b) => (a.runId < b.runId ? -1 : a.runId > b.runId ? 1 : 0))
+	// Both orders sort on a key that cannot move under a paging caller — see
+	// the contract comment on `listDurableRuns`.
+	const orderBy = options?.orderBy ?? 'runId'
+	const ordered = [...filtered].sort((a, b) =>
+		compareKeys(sortKey(a, orderBy), sortKey(b, orderBy)),
+	)
 
-	const after = options?.cursor
-	const start = after === undefined ? 0 : ordered.findIndex((e) => e.runId > after)
+	const after = options?.cursor === undefined ? undefined : decodeCursor(options.cursor, orderBy)
+	const start =
+		after === undefined ? 0 : ordered.findIndex((e) => compareKeys(sortKey(e, orderBy), after) > 0)
 	const from = start < 0 ? ordered.length : start
 
 	const limit = Math.max(1, Math.trunc(options?.limit ?? DEFAULT_DURABLE_RUN_LIMIT))
@@ -194,8 +213,67 @@ export function paginateDurableRuns(
 		// terminates rather than fetching one empty page to find out.
 		...(exhausted || page.length === 0
 			? {}
-			: { cursor: (page[page.length - 1] as DurableRunEntry).runId }),
+			: { cursor: encodeCursor(sortKey(page[page.length - 1] as DurableRunEntry, orderBy)) }),
+	}
+}
+
+/**
+ * A row's position in the requested order, as a comparable tuple.
+ *
+ * The first element is a rank rather than the timestamp itself, so that
+ * "never recorded" is a position in its own right instead of a number
+ * standing in for one. In `createdAt` order it ranks 0 and everything
+ * stamped ranks 1 — unrecorded runs first, and truthfully so: the stamp is
+ * written by the checkpoint manager, so a run without one was checkpointed
+ * by a build that predates it, and predates every run that has one.
+ */
+type SortKey = readonly [number, number, string]
+
+function sortKey(entry: DurableRunEntry, orderBy: DurableRunOrder): SortKey {
+	if (orderBy === 'runId') return [0, 0, entry.runId]
+	return entry.runCreatedAt === undefined
+		? [0, 0, entry.runId]
+		: [1, entry.runCreatedAt, entry.runId]
+}
+
+function compareKeys(a: SortKey, b: SortKey): number {
+	if (a[0] !== b[0]) return a[0] - b[0]
+	if (a[1] !== b[1]) return a[1] - b[1]
+	return a[2] < b[2] ? -1 : a[2] > b[2] ? 1 : 0
+}
+
+/**
+ * The cursor is the last row's key, and nothing else.
+ *
+ * Opaque to callers by contract — the shape is written down here rather than
+ * in the type so a host is not tempted to construct one. Run ids come from a
+ * 36-character lowercase alphabet with a `run_` prefix and contain no
+ * separator, so joining on `:` is unambiguous.
+ */
+function encodeCursor(key: SortKey): string {
+	return `${key[0]}:${key[1]}:${key[2]}`
+}
+
+function decodeCursor(cursor: string, orderBy: DurableRunOrder): SortKey {
+	const first = cursor.indexOf(':')
+	const second = cursor.indexOf(':', first + 1)
+	if (first < 0 || second < 0) {
+		throw new NamzuError({
+			code: 'invalid_config',
+			message: `listDurableRuns: "${cursor}" is not a cursor this listing issued. Pass back the \`cursor\` from the previous page rather than constructing one; its shape is not part of the contract.`,
+			details: { cursor, orderBy },
+		})
+	}
+	const rank = Number(cursor.slice(0, first))
+	const stamp = Number(cursor.slice(first + 1, second))
+	if (!Number.isFinite(rank) || !Number.isFinite(stamp)) {
+		throw new NamzuError({
+			code: 'invalid_config',
+			message: `listDurableRuns: cursor "${cursor}" is malformed — its position fields are not numbers. Pass back the \`cursor\` from the previous page.`,
+			details: { cursor, orderBy },
+		})
 	}
+	return [rank, stamp, cursor.slice(second + 1)]
 }
 
 /**

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/hitl/index.ts

@@ -210,6 +210,34 @@ export interface IterationCheckpoint {
 	 */
 	planStatus?: PlanStatus
 
+	/**
+	 * When the RUN was attributed — not when this checkpoint was written.
+	 * See {@link IterationCheckpoint.createdAt} for the latter.
+	 *
+	 * Denormalized onto every checkpoint of the run, identically, and that
+	 * repetition is the whole point. A listing above the run needs a key it
+	 * can order by, and a key a paging caller can trust is one that cannot
+	 * MOVE. Every other time a checkpoint store can derive per run moves: the
+	 * newest checkpoint's `createdAt` advances every time the run checkpoints
+	 * again, and the oldest one's advances every time `prune` deletes
+	 * oldest-first. Carried on all of them, this one survives both — pruning
+	 * cannot reach a value every survivor also holds.
+	 *
+	 * `readonly`, and written exactly once per run by
+	 * {@link import('../../runtime/query/checkpoint.js').CheckpointManager},
+	 * which settles it on whichever comes first — adopting it from the
+	 * checkpoint a resume restores, or minting it from the run's own start
+	 * instant — and never reassigns after. A field that COULD be updated is
+	 * one edit away from moving again, which would put the ordering back
+	 * where it started.
+	 *
+	 * Absent on checkpoints written before this existed. That absence is
+	 * information, not a gap: a run with no stamp on any of its checkpoints
+	 * was attributed before the stamp existed, and therefore before every
+	 * run that has one.
+	 */
+	readonly runCreatedAt?: number
+
 	/**
 	 * Present when the run parked at this checkpoint awaiting a human.
 	 * See {@link PendingDecision}.

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

@@ -152,6 +152,21 @@ export interface ParkSummary {
  * scope, intersect with the host's own run records, resume the difference.
  */
 export interface DurableRunEntry extends CheckpointRunScope {
+	/**
+	 * When the run was attributed. Absent when it was never recorded.
+	 *
+	 * The only per-run key this store holds that does not move, which is why
+	 * it is the one an oldest-first listing can page over — see
+	 * {@link CheckpointStore.listDurableRuns} and
+	 * `IterationCheckpoint.runCreatedAt`.
+	 *
+	 * **Absent means "not recorded", and a caller should render it that way
+	 * rather than as a date it invents.** Every run checkpointed by a build
+	 * carrying the stamp has one; a run that has none was checkpointed
+	 * before the stamp existed.
+	 */
+	readonly runCreatedAt?: number
+
 	/** How many checkpoints the run has right now. Pruning lowers it. */
 	readonly checkpointCount: number
 	/** Newest checkpoint by `createdAt` — the one a resume restores by default. */
@@ -162,8 +177,46 @@ export interface DurableRunEntry extends CheckpointRunScope {
 	readonly park?: ParkSummary
 }
 
+/**
+ * Which order a listing comes back in.
+ *
+ * Explicit rather than implied, because the two available orders answer
+ * different questions and neither is right for both. "Show me every run
+ * waiting on a human" wants stable paging; "show me the one that has been
+ * waiting longest" wants chronology. A listing that silently picked one
+ * would be the same ambiguity the scope type removed by splitting.
+ */
+export type DurableRunOrder =
+	/**
+	 * By `runId` ascending. Stable and total, and meaningless as chronology —
+	 * run ids carry no timestamp. The default, because it is what shipped.
+	 */
+	| 'runId'
+	/**
+	 * Oldest first, by {@link DurableRunEntry.runCreatedAt} then `runId`.
+	 * This is the triage order: it answers which run has been waiting
+	 * longest. Safe to page over, because the stamp is recorded once at
+	 * attribution and never rewritten.
+	 *
+	 * **Runs whose creation was never recorded come FIRST**, ordered among
+	 * themselves by `runId`. That is not a guess dressed up as a date: the
+	 * stamp is written by the checkpoint manager, so a run lacking it on
+	 * every checkpoint was checkpointed by a build that predates the stamp,
+	 * and therefore predates every run that has one. Their
+	 * `runCreatedAt` is absent on the row, so a caller can render "unknown"
+	 * instead of a date nobody recorded.
+	 */
+	| 'createdAt'
+
 /** Filters and paging for {@link CheckpointStore.listDurableRuns}. */
 export interface ListDurableRunsOptions {
+	/**
+	 * Ordering, and therefore what the cursor is a position in. Defaults to
+	 * `'runId'`. A cursor is only meaningful within one order — do not carry
+	 * one across a change of `orderBy`.
+	 */
+	readonly orderBy?: DurableRunOrder
+
 	/**
 	 * Keep only runs whose park is in one of these states. A run that never
 	 * parked has no state and is excluded by ANY value here; omit the filter
@@ -256,30 +309,30 @@ export interface CheckpointStore {
 	 * for an unanswered park, and until this existed the sweep had no way to
 	 * enumerate what to sweep.
 	 *
-	 * ### Ordering, and why it is not chronological
+	 * ### Ordering
 	 *
-	 * Rows come back ordered by `runId` ascending, and the cursor is a
-	 * position in that order.
+	 * Two orders, named by `options.orderBy`, and the cursor is a position in
+	 * whichever one was asked for. See {@link DurableRunOrder}.
 	 *
-	 * A cursor has to sort on a key that cannot move, or a paging caller
-	 * skips rows and repeats rows. Every time-valued key this store can
-	 * derive per run DOES move: the newest checkpoint's timestamp advances
-	 * whenever the run checkpoints again, and the oldest one's advances
-	 * whenever `CheckpointManager.prune` deletes oldest-first, which is what
-	 * pruning does. `runId` is the only immutable, unique per-run key
-	 * available, and being unique it is already a total order — the
-	 * degenerate case of the rule `orderChildren` follows (sort on a key that
-	 * cannot move, make the order total with an id), not a departure from it.
+	 * Both sort on a key that cannot MOVE, which is the property a cursor
+	 * needs — sort on a moving key and a paging caller skips rows and repeats
+	 * rows. That rules out every time a checkpoint store can derive on its
+	 * own: the newest checkpoint's timestamp advances whenever the run
+	 * checkpoints again, and the oldest one's advances whenever
+	 * `CheckpointManager.prune` deletes oldest-first, which is what pruning
+	 * does. It leaves `runId`, which is immutable and unique but carries no
+	 * timestamp, and `runCreatedAt`, which is recorded once at attribution
+	 * and denormalized onto every checkpoint so pruning cannot reach it.
 	 *
-	 * The cost is that page order is arbitrary rather than oldest-first,
-	 * because run ids carry no timestamp. Entries carry `latestCheckpointAt`
-	 * and `park.parkedAt` so a caller can sort what it has read.
+	 * `'runId'` alone is already a total order. `'createdAt'` tiebreaks on
+	 * `runId`, which is the rule `orderChildren` follows: sort on a key that
+	 * cannot move, make the order total with an id.
 	 *
 	 * A run whose FIRST checkpoint is written after paging began may be
-	 * missed by that pass — it lands at whatever `runId` it minted, possibly
-	 * behind the cursor. That is the right trade for a queue: the sweep runs
-	 * again and picks it up next pass, whereas a moving sort key loses runs
-	 * that already existed.
+	 * missed by that pass, in either order — it lands wherever its key puts
+	 * it, possibly behind the cursor. That is the right trade for a queue:
+	 * the sweep runs again and picks it up next pass, whereas a moving sort
+	 * key loses runs that already existed.
 	 *
 	 * @param scope contiguous prefix; `tenantId` required. Implementations
 	 *   reject a hole (`sessionId` with no `projectId`) rather than guessing.

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>
+}