@namzu/sdk 20.0.0 → 20.1.0

package/src/store/run/disk.ts

@@ -192,33 +192,7 @@ export class RunDiskStore {
 	}
 
 	async listCheckpoints(): Promise<IterationCheckpoint[]> {
-		const dir = this.requireInit()
-		const cpDir = join(dir, 'checkpoints')
-		try {
-			const files = await readdir(cpDir)
-			const checkpoints: IterationCheckpoint[] = []
-			for (const file of files) {
-				if (!file.endsWith('.json')) continue
-				// An unreadable checkpoint used to be logged and skipped, so
-				// this returned a silently short list that four callers treat
-				// as complete. A missing NEWEST checkpoint quietly resumes
-				// from an older point and re-runs a whole iteration of tool
-				// calls; a missing PARKED one reports "not parked" and drops
-				// an approval a human already granted, because the file is
-				// the only durable record of a park. Pruning under-deletes
-				// too: a file the keep-count cannot see is immortal.
-				//
-				// The by-id read next door was already strict. Two read paths
-				// disagreeing about whether damage matters is how the lenient
-				// one gets trusted.
-				const content = await readFile(join(cpDir, file), 'utf-8')
-				checkpoints.push(parseCheckpoint(content, file))
-			}
-			return checkpoints.sort((a, b) => a.createdAt - b.createdAt)
-		} catch (err) {
-			if (isFileNotFound(err)) return []
-			throw err
-		}
+		return readCheckpointsIn(this.requireInit())
 	}
 
 	async deleteCheckpoint(checkpointId: CheckpointId): Promise<void> {
@@ -230,6 +204,29 @@ export class RunDiskStore {
 		}
 	}
 
+	/**
+	 * @deprecated Superseded by
+	 *   {@link import('../../types/run/checkpoint-store.js').CheckpointStore.listDurableRuns},
+	 *   reached through {@link import('./listing.js').listDurableRuns}.
+	 *   Removed in the next major.
+	 *
+	 *   Three things are wrong with `index.json` as the answer to "which runs
+	 *   are there":
+	 *
+	 *   1. Its entries carry no tenant, project or session, so a row cannot be
+	 *      turned back into an addressable scope — nothing can be resumed or
+	 *      swept from it.
+	 *   2. `addToIndex` skips every sub-run, so an inbox built on it drops
+	 *      every approval raised by delegated work, and the symptom looks like
+	 *      a hung specialist rather than a blind listing.
+	 *   3. It is a catalogue of runs that STARTED, not of runs with durable
+	 *      state, so it cannot tell a run something could resume from one that
+	 *      left nothing behind.
+	 *
+	 *   Deprecated for one minor rather than deleted outright: this is public
+	 *   surface and a consumer calling it today gets real data back, so the
+	 *   deprecate-before-you-remove rule applies.
+	 */
 	static async listRuns(baseDir: string): Promise<
 		Array<{
 			id: string
@@ -297,6 +294,54 @@ export class RunDiskStore {
 	}
 }
 
+/**
+ * Every checkpoint stored under one run directory, ascending by `createdAt`.
+ *
+ * A free function rather than a method because the scope-level listing walks
+ * run directories it has never bound a {@link RunDiskStore} to — and binding
+ * one would CREATE the directory, which is not something a read should do.
+ * Sharing the function is what keeps the two read paths from disagreeing
+ * about what a damaged file means.
+ *
+ * An unreadable checkpoint used to be logged and skipped, so this returned a
+ * silently short list that four callers treat as complete. A missing NEWEST
+ * checkpoint quietly resumes from an older point and re-runs a whole
+ * iteration of tool calls; a missing PARKED one reports "not parked" and
+ * drops an approval a human already granted, because the file is the only
+ * durable record of a park. Pruning under-deletes too: a file the keep-count
+ * cannot see is immortal. The by-id read next door was already strict, and
+ * two read paths disagreeing about whether damage matters is how the lenient
+ * one gets trusted.
+ *
+ * The same reasoning carries up to the listing, which is why the throw
+ * propagates there rather than dropping the run: a damaged checkpoint that
+ * removed a run from an approval inbox is the missing-park failure again,
+ * one level up.
+ *
+ * A missing `checkpoints/` directory is the only absence that reads as
+ * empty — the run genuinely has none. A file that disappears BETWEEN the
+ * directory listing and its read throws, where the old shape returned the
+ * empty array and discarded every checkpoint it had already parsed.
+ */
+export async function readCheckpointsIn(runDir: string): Promise<IterationCheckpoint[]> {
+	const cpDir = join(runDir, 'checkpoints')
+	let files: string[]
+	try {
+		files = await readdir(cpDir)
+	} catch (err) {
+		if (isFileNotFound(err)) return []
+		throw err
+	}
+
+	const checkpoints: IterationCheckpoint[] = []
+	for (const file of files) {
+		if (!file.endsWith('.json')) continue
+		const content = await readFile(join(cpDir, file), 'utf-8')
+		checkpoints.push(parseCheckpoint(content, file))
+	}
+	return checkpoints.sort((a, b) => a.createdAt - b.createdAt)
+}
+
 async function atomicWriteJson(filePath: string, value: unknown): Promise<void> {
 	await atomicWriteFile(filePath, JSON.stringify(stamp(SCHEMA, value), null, 2))
 }

package/src/store/run/listing.ts

@@ -0,0 +1,229 @@
+/**
+ * Shared machinery for {@link CheckpointStore.listDurableRuns}.
+ *
+ * Every rule the listing promises — the contiguous-prefix refusal, the park
+ * precedence, the ordering, the paging — lives here and is used by BOTH
+ * shipped implementations. A rule implemented twice is a rule that holds in
+ * one store and not the other, and the whole point of a store contract is
+ * that a host can swap the backend without swapping the semantics.
+ */
+
+import { NamzuError } from '../../types/errors/index.js'
+import type { IterationCheckpoint, PendingDecision } from '../../types/hitl/index.js'
+import type {
+	CheckpointListingScope,
+	CheckpointRunScope,
+	CheckpointStore,
+	DurableRunEntry,
+	DurableRunPage,
+	ListDurableRunsOptions,
+	ParkState,
+	ParkSummary,
+} from '../../types/run/checkpoint-store.js'
+
+/** Page size when the caller names none. */
+export const DEFAULT_DURABLE_RUN_LIMIT = 100
+
+/**
+ * Refuse a listing scope with a hole in it.
+ *
+ * `{ tenantId, sessionId }` reads as "that session under whichever project
+ * holds it". A flat backend can answer it; a hierarchical one cannot look up
+ * a session without its project. Answering differently per backend is the
+ * one thing the contract exists to prevent, so neither answers: the caller
+ * names the project it means.
+ */
+export function assertContiguousListingScope(scope: CheckpointListingScope, caller: string): void {
+	if (scope.sessionId !== undefined && scope.projectId === undefined) {
+		throw new NamzuError({
+			code: 'invalid_config',
+			message: `${caller}: listing scope has a hole — \`sessionId\` was supplied without \`projectId\`. A run listing scope is a contiguous prefix of tenant → project → session; name the project the session belongs to.`,
+			details: { tenantId: scope.tenantId, sessionId: scope.sessionId },
+		})
+	}
+}
+
+/** Whether a park's absolute deadline has passed. No deadline never expires. */
+function isPastDeadline(pending: PendingDecision, now: number): boolean {
+	return pending.deadlineAt !== undefined && now >= pending.deadlineAt
+}
+
+/**
+ * Which of the three states a recorded park is in.
+ *
+ * `resolved` is checked FIRST: a park that was answered after its deadline
+ * passed is answered, not expired. Reading the deadline first would report
+ * a decision a human actually made as an expiry nobody made, and the
+ * checkpoint is the evidence record for exactly that question.
+ */
+function parkStateOf(pending: PendingDecision, now: number): ParkState {
+	if (pending.resolvedAt !== undefined) return 'resolved'
+	return isPastDeadline(pending, now) ? 'expired' : 'outstanding'
+}
+
+function toParkSummary(
+	cp: IterationCheckpoint,
+	pending: PendingDecision,
+	now: number,
+): ParkSummary {
+	return {
+		state: parkStateOf(pending, now),
+		checkpointId: cp.id,
+		requestType: pending.request.type,
+		parkedAt: pending.parkedAt,
+		...(pending.deadlineAt !== undefined ? { deadlineAt: pending.deadlineAt } : {}),
+		...(pending.resolvedAt !== undefined ? { resolvedAt: pending.resolvedAt } : {}),
+	}
+}
+
+/**
+ * The one park that describes what a run is doing now, out of every park it
+ * ever recorded.
+ *
+ * Precedence: newest `outstanding`, else newest `expired`, else newest
+ * `resolved`.
+ *
+ * `outstanding` wins because that is the question an inbox is asking, and
+ * because the answer has to be the SAME checkpoint `findPendingCheckpoint`
+ * returns. A run can hold several parks — it parks, a human answers, it runs
+ * on, it parks again — and it can hold an outstanding one that is older than
+ * a resolved one only in the reverse case, where an earlier park expired
+ * unanswered and the run was resumed past it. Ranking by recency alone would
+ * then hand an inbox a resolved checkpoint and report the live park as
+ * nothing.
+ *
+ * @param checkpoints the run's checkpoints, any order.
+ */
+export function summarizePark(
+	checkpoints: readonly IterationCheckpoint[],
+	now: number,
+): ParkSummary | undefined {
+	let best: ParkSummary | undefined
+	let bestRank = -1
+	let bestParkedAt = Number.NEGATIVE_INFINITY
+
+	for (const cp of checkpoints) {
+		const pending = cp.pending
+		if (!pending) continue
+		const summary = toParkSummary(cp, pending, now)
+		const rank = PARK_RANK[summary.state]
+		if (rank > bestRank || (rank === bestRank && pending.parkedAt > bestParkedAt)) {
+			best = summary
+			bestRank = rank
+			bestParkedAt = pending.parkedAt
+		}
+	}
+
+	return best
+}
+
+const PARK_RANK: Record<ParkState, number> = {
+	resolved: 0,
+	expired: 1,
+	outstanding: 2,
+}
+
+/**
+ * Project one run's checkpoints into a listing entry.
+ *
+ * Returns `null` for a run with no checkpoints: the listing is of runs with
+ * DURABLE state, and a run with nothing stored has nothing a sweeper could
+ * resume. A disk walk hits this case for real — a sub-run's directory is
+ * created as a bare shell under its own id before anything is written to it.
+ */
+export function toDurableRunEntry(
+	scope: CheckpointRunScope,
+	checkpoints: readonly IterationCheckpoint[],
+	now: number,
+): DurableRunEntry | null {
+	if (checkpoints.length === 0) return null
+
+	let latest = checkpoints[0] as IterationCheckpoint
+	for (const cp of checkpoints) {
+		if (cp.createdAt > latest.createdAt) latest = cp
+	}
+
+	const park = summarizePark(checkpoints, now)
+
+	return {
+		tenantId: scope.tenantId,
+		projectId: scope.projectId,
+		sessionId: scope.sessionId,
+		runId: scope.runId,
+		...(scope.parentRunId ? { parentRunId: scope.parentRunId } : {}),
+		checkpointCount: checkpoints.length,
+		latestCheckpointId: latest.id,
+		latestCheckpointAt: latest.createdAt,
+		...(park ? { park } : {}),
+	}
+}
+
+/**
+ * Apply the park filter, the contract's ordering and the cursor to a set of
+ * entries an implementation has gathered.
+ *
+ * Both shipped stores gather differently — one walks a directory tree, one
+ * reads a map — and then hand the result here, so "ordered by `runId`, page
+ * ends where the next begins" is one implementation rather than two.
+ */
+export function paginateDurableRuns(
+	entries: readonly DurableRunEntry[],
+	options?: ListDurableRunsOptions,
+): DurableRunPage {
+	const wanted = options?.park
+	const filtered =
+		wanted && wanted.length > 0
+			? 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))
+
+	const after = options?.cursor
+	const start = after === undefined ? 0 : ordered.findIndex((e) => e.runId > after)
+	const from = start < 0 ? ordered.length : start
+
+	const limit = Math.max(1, Math.trunc(options?.limit ?? DEFAULT_DURABLE_RUN_LIMIT))
+	const page = ordered.slice(from, from + limit)
+	const exhausted = from + page.length >= ordered.length
+
+	return {
+		entries: page,
+		// No cursor when there is nothing behind it, so `while (cursor)`
+		// terminates rather than fetching one empty page to find out.
+		...(exhausted || page.length === 0
+			? {}
+			: { cursor: (page[page.length - 1] as DurableRunEntry).runId }),
+	}
+}
+
+/**
+ * Every run with durable state under a scope, refusing when the store cannot
+ * answer.
+ *
+ * The refusal is the point. `listDurableRuns` is optional on the contract so
+ * that adding it did not break every host that had already implemented the
+ * interface — and an optional capability reached without a check degrades
+ * into a wrong answer: a store that cannot list would hand an approval inbox
+ * an empty page, and "nothing is waiting on a human" is not what "I cannot
+ * tell" means. A host that gets this error knows to supply a backend that
+ * implements the listing; a host that got `[]` would ship an inbox that
+ * silently never fires.
+ */
+export async function listDurableRuns(
+	store: CheckpointStore,
+	scope: CheckpointListingScope,
+	options?: ListDurableRunsOptions,
+): Promise<DurableRunPage> {
+	if (typeof store.listDurableRuns !== 'function') {
+		throw new NamzuError({
+			code: 'capability_unavailable',
+			message:
+				'listDurableRuns: the injected checkpoint store does not implement `listDurableRuns`, so it cannot enumerate runs above a run id. Refusing rather than reporting an empty listing, which would read as "no runs are parked" when the truth is that this store cannot tell. Supply a store that implements it (the built-in disk and in-memory stores both do).',
+			details: { tenantId: scope.tenantId },
+		})
+	}
+	assertContiguousListingScope(scope, 'listDurableRuns')
+	return store.listDurableRuns(scope, options)
+}

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

@@ -9,7 +9,7 @@
  * five-layer attribution (Convention #17) instead of a filesystem path.
  */
 
-import type { CheckpointId, IterationCheckpoint } from '../hitl/index.js'
+import type { CheckpointId, HITLDecisionRequest, IterationCheckpoint } from '../hitl/index.js'
 import type { RunId, SessionId, TenantId } from '../ids/index.js'
 import type { ProjectId } from '../session/ids.js'
 
@@ -39,6 +39,160 @@ export interface CheckpointRunScope {
 	parentRunId?: RunId
 }
 
+/**
+ * A CONTIGUOUS PREFIX of the run attribution hierarchy, addressing a SET of
+ * runs rather than one.
+ *
+ * A separate type from {@link CheckpointRunScope} on purpose. That type
+ * addresses exactly one run and four accessors depend on it doing so; making
+ * its one distinguishing field optional in place would turn "the scope of a
+ * run" into "some identifiers, maybe", and every accessor's guarantee with
+ * it.
+ *
+ * Three properties, each deliberate:
+ *
+ *  - **`tenantId` is required.** Isolation is the one boundary that is never
+ *    optional here. An untenanted listing is a cross-tenant read with a
+ *    friendly name.
+ *  - **It stops ABOVE the run.** No `runId`, no `parentRunId`. A caller
+ *    holding a run id already has a full {@link CheckpointRunScope} and four
+ *    accessors that take it; admitting one here would make
+ *    `CheckpointRunScope` structurally assignable to this type and re-merge
+ *    the two ideas the split exists to keep apart.
+ *  - **The prefix must be contiguous.** A `sessionId` with no `projectId` is
+ *    REFUSED, not silently widened to "that session under whichever project
+ *    holds it". A flat backend can answer it and a hierarchical one cannot,
+ *    so the answer would depend on the backend's storage shape — which is
+ *    the one thing a store contract exists to hide.
+ */
+export interface CheckpointListingScope {
+	/** Isolation boundary (Convention #17). Never optional. */
+	readonly tenantId: TenantId
+	/** Narrow to one project. Absent = every project of the tenant. */
+	readonly projectId?: ProjectId
+	/** Narrow to one session. Requires `projectId`. */
+	readonly sessionId?: SessionId
+}
+
+/**
+ * What a run's human-in-the-loop park is doing, as far as durable state can
+ * tell.
+ *
+ * A closed union rather than a boolean because the two unanswered states are
+ * drained by DIFFERENT operators: `outstanding` is an approval inbox's queue
+ * and `expired` is a reclamation sweep's, and serving one to the other either
+ * re-presents a dead approval forever or discards a live one.
+ */
+export type ParkState =
+	/** `pending` set, no `resolvedAt`, deadline not passed. A human owes an answer. */
+	| 'outstanding'
+	/** `pending` set, no `resolvedAt`, deadline passed. Nobody will answer it. */
+	| 'expired'
+	/** `pending` set with `resolvedAt`. Kept as evidence of who decided what. */
+	| 'resolved'
+
+/**
+ * **Do not widen this union to say who is working on the run.**
+ *
+ * A consumer switches over `ParkState` exhaustively, so a fourth member is a
+ * backward-incompatible change and a `major` — and the pull to add one is
+ * real, because the next capability this contract takes is a cross-process
+ * claim, and a queue worker draining the inbox wants to skip runs another
+ * worker already holds.
+ *
+ * That is a different fact about a different subject. A park is a question
+ * put to a HUMAN; a claim is a lease held by a PROCESS, and one run can have
+ * both, neither, or either. Encoding them in one union makes the pair
+ * unsayable and loses the state a worker needs most: parked AND unclaimed.
+ *
+ * The additive shape is a sibling optional field — `claim?: …` on
+ * {@link DurableRunEntry}, `claimed?: …` on {@link ListDurableRunsOptions}.
+ * A consumer reading rows is not broken by a new optional field, so the
+ * claim ships as a second `minor` on this contract rather than a second
+ * migration of it. This note exists because the union is the obvious place
+ * to reach for and the wrong one.
+ */
+
+/** A run's park disposition, projected from the checkpoint that carries it. */
+export interface ParkSummary {
+	readonly state: ParkState
+	/** The parked checkpoint — address it directly with `readCheckpoint`. */
+	readonly checkpointId: CheckpointId
+	/** What the human was asked. Enough to route an inbox without a second read. */
+	readonly requestType: HITLDecisionRequest['type']
+	/** Epoch ms at which the run parked. */
+	readonly parkedAt: number
+	/** Absolute expiry, when the park carries one. */
+	readonly deadlineAt?: number
+	/** Epoch ms at which the answer arrived. Only on `resolved`. */
+	readonly resolvedAt?: number
+}
+
+/**
+ * One run that has durable checkpoint state under the queried scope.
+ *
+ * **Extends {@link CheckpointRunScope}, and that is the load-bearing part.**
+ * A listing whose rows cannot be turned back into an addressable scope is a
+ * report, not a work queue. Because an entry IS a run scope,
+ * `findPendingCheckpoint(store, entry)`, `new CheckpointManager(store, entry)`
+ * and `resumeRun({ scope: entry, … })` all accept a row straight out of the
+ * listing — with no re-assembly, and so no chance of assembling it wrong.
+ *
+ * ### What an entry deliberately does NOT carry
+ *
+ * A run STATUS. A checkpoint is written mid-flight, so nothing in this store
+ * distinguishes a run that finished from one that died — the same fact
+ * {@link import('../../runtime/query/run-state.js').loadRunState} already
+ * states, where a rebuilt snapshot always reports `running` and the host's
+ * own record stays the authority. A `status` field here would answer
+ * "mid-flight" for every run that ever succeeded, and a sweeper built on it
+ * would resume finished work.
+ *
+ * A crash sweep is therefore: list every run with durable state under the
+ * scope, intersect with the host's own run records, resume the difference.
+ */
+export interface DurableRunEntry extends CheckpointRunScope {
+	/** 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. */
+	readonly latestCheckpointId: CheckpointId
+	/** `createdAt` of {@link DurableRunEntry.latestCheckpointId}. */
+	readonly latestCheckpointAt: number
+	/** Absent when the run has never parked. */
+	readonly park?: ParkSummary
+}
+
+/** Filters and paging for {@link CheckpointStore.listDurableRuns}. */
+export interface ListDurableRunsOptions {
+	/**
+	 * 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
+	 * to include it.
+	 */
+	readonly park?: readonly ParkState[]
+	/** Page size. Defaults to 100, clamped to at least 1. */
+	readonly limit?: number
+	/** Resume token from the previous page's {@link DurableRunPage.cursor}. */
+	readonly cursor?: string
+	/**
+	 * Clock for expiry, so a sweep can be tested and so every entry in one
+	 * page is judged against the same instant. Defaults to `Date.now()` — the
+	 * same seam `findPendingCheckpoint` already takes.
+	 */
+	readonly now?: number
+}
+
+/** One page of {@link DurableRunEntry}. */
+export interface DurableRunPage {
+	readonly entries: readonly DurableRunEntry[]
+	/**
+	 * Pass to the next call. **Absent means the listing is exhausted**, so
+	 * `while (cursor)` terminates; a store never returns a cursor it already
+	 * knows yields nothing.
+	 */
+	readonly cursor?: string
+}
+
 /**
  * Persistence contract consumed by
  * {@link import('../../runtime/query/checkpoint.js').CheckpointManager} and
@@ -49,6 +203,27 @@ export interface CheckpointRunScope {
  * not-found error. `deleteCheckpoint` is idempotent: deleting an absent
  * checkpoint succeeds as a no-op (mirrors the disk store's ENOENT
  * swallowing).
+ *
+ * ## Optional capabilities, and the rule that comes with them
+ *
+ * {@link CheckpointStore.listDurableRuns} is optional, following
+ * `SessionStore.listSessionsByProject`. A required method would break every
+ * host that has already implemented this interface, which is a `major` for
+ * what is otherwise an additive capability.
+ *
+ * The rule optionality obliges: **a caller of an optional capability REFUSES
+ * when it is absent; it never degrades.** An approval inbox built on a store
+ * that cannot list has to throw, because an empty page would say "nothing is
+ * waiting on a human" when the truth is "I cannot tell" — an optional
+ * dependency degrading a check, which this repository has been bitten by
+ * before. Reach the capability through
+ * {@link import('../../store/run/listing.js').listDurableRuns}, which
+ * refuses on absence rather than answering.
+ *
+ * Any capability added here later takes the same shape — optional method,
+ * refusing helper. A cross-process claim is the next one, and a two-worker
+ * deployment against a store with no lease has to fail loudly rather than
+ * proceed.
  */
 export interface CheckpointStore {
 	/** Persist one checkpoint. Overwrites an existing checkpoint with the same id. */
@@ -69,4 +244,49 @@ export interface CheckpointStore {
 
 	/** Delete a checkpoint by id. Absent checkpoints succeed as a no-op. */
 	deleteCheckpoint(scope: CheckpointRunScope, checkpointId: CheckpointId): Promise<void>
+
+	/**
+	 * Every run with durable checkpoint state under a scope ABOVE the run.
+	 * OPTIONAL — see the optional-capability rule on this interface.
+	 *
+	 * This is the read an approval inbox and a park sweep are built from, and
+	 * the one thing this contract had no way to express: every other accessor
+	 * needs a `runId`, so a host could only ask about runs it already knew
+	 * about. `hitlParkTtlMs` documents a host sweep as the reclamation path
+	 * 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
+	 *
+	 * Rows come back ordered by `runId` ascending, and the cursor is a
+	 * position in that order.
+	 *
+	 * 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.
+	 *
+	 * 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.
+	 *
+	 * 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.
+	 *
+	 * @param scope contiguous prefix; `tenantId` required. Implementations
+	 *   reject a hole (`sessionId` with no `projectId`) rather than guessing.
+	 * @param options filters and paging. See {@link ListDurableRunsOptions}.
+	 */
+	listDurableRuns?(
+		scope: CheckpointListingScope,
+		options?: ListDurableRunsOptions,
+	): Promise<DurableRunPage>
 }