@namzu/sdk 20.0.0 → 20.2.0

package/src/store/run/listing.ts

@@ -0,0 +1,307 @@
+/**
+ * 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,
+	DurableRunOrder,
+	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
+	// 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)
+
+	return {
+		tenantId: scope.tenantId,
+		projectId: scope.projectId,
+		sessionId: scope.sessionId,
+		runId: scope.runId,
+		...(scope.parentRunId ? { parentRunId: scope.parentRunId } : {}),
+		...(runCreatedAt !== undefined ? { runCreatedAt } : {}),
+		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
+
+	// 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 === 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))
+	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: 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)]
+}
+
+/**
+ * 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/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

@@ -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,213 @@ 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 {
+	/**
+	 * 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. */
+	readonly latestCheckpointId: CheckpointId
+	/** `createdAt` of {@link DurableRunEntry.latestCheckpointId}. */
+	readonly latestCheckpointAt: number
+	/** Absent when the run has never parked. */
+	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
+	 * 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 +256,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 +297,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
+	 *
+	 * Two orders, named by `options.orderBy`, and the cursor is a position in
+	 * whichever one was asked for. See {@link DurableRunOrder}.
+	 *
+	 * 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.
+	 *
+	 * `'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, 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.
+	 * @param options filters and paging. See {@link ListDurableRunsOptions}.
+	 */
+	listDurableRuns?(
+		scope: CheckpointListingScope,
+		options?: ListDurableRunsOptions,
+	): Promise<DurableRunPage>
 }