@namzu/sdk 20.0.0 → 20.1.0

package/dist/types/run/checkpoint-store.d.ts

@@ -8,7 +8,7 @@
  * {@link CheckpointRunScope} so a shared backend can key rows by the full
  * 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';
 /**
@@ -36,6 +36,153 @@ 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
@@ -46,6 +193,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. */
@@ -60,5 +228,46 @@ export interface CheckpointStore {
     listCheckpoints(scope: CheckpointRunScope): Promise<IterationCheckpoint[]>;
     /** 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>;
 }
 //# sourceMappingURL=checkpoint-store.d.ts.map

package/dist/types/run/checkpoint-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkpoint-store.d.ts","sourceRoot":"","sources":["../../../src/types/run/checkpoint-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AACzE,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAElD;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IAClC,2CAA2C;IAC3C,QAAQ,EAAE,QAAQ,CAAA;IAClB,gDAAgD;IAChD,SAAS,EAAE,SAAS,CAAA;IACpB,wCAAwC;IACxC,SAAS,EAAE,SAAS,CAAA;IACpB,2CAA2C;IAC3C,KAAK,EAAE,KAAK,CAAA;IACZ;;;;OAIG;IACH,WAAW,CAAC,EAAE,KAAK,CAAA;CACnB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe;IAC/B,kFAAkF;IAClF,eAAe,CAAC,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE1F,6EAA6E;IAC7E,cAAc,CACb,KAAK,EAAE,kBAAkB,EACzB,YAAY,EAAE,YAAY,GACxB,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAA;IAEtC;;;;OAIG;IACH,eAAe,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAA;IAE1E,wEAAwE;IACxE,gBAAgB,CAAC,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACtF"}
+{"version":3,"file":"checkpoint-store.d.ts","sourceRoot":"","sources":["../../../src/types/run/checkpoint-store.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/sdk",
-  "version": "20.0.0",
+  "version": "20.1.0",
   "description": "Open-source AI agent SDK with a built-in runtime. Nothing between you and your agents.",
   "license": "FSL-1.1-MIT",
   "type": "module",

package/src/manager/run/persistence.ts

@@ -45,12 +45,26 @@ export class RunPersistence {
 
 		// Checkpoints go through the injectable seam; the disk layout under
 		// `outputDir` (same tree the runStore writes to) stays the default.
+		//
+		// The attribution is handed over because the layout does not record
+		// it — there is no tenant segment in the path at all — and without it
+		// the default store can persist checkpoints but cannot ENUMERATE
+		// them, which is the state the contract just stopped being in. A
+		// listing capability the default store declines is a capability no
+		// host reaches.
 		this.checkpointStore =
 			config.checkpointStore ??
-			new DiskCheckpointStore({
-				baseDir: config.outputDir,
-				logger: config.log,
-			})
+			new DiskCheckpointStore(
+				{
+					baseDir: config.outputDir,
+					logger: config.log,
+				},
+				{
+					tenantId: config.tenantId,
+					projectId: config.projectId,
+					sessionId: config.sessionId,
+				},
+			)
 
 		this.run = {
 			id: config.runId,

package/src/public-runtime.ts

@@ -198,12 +198,25 @@ export {
 	DiskCheckpointStore,
 	DiskMemoryStore,
 	DiskTaskStore,
+	InMemoryCheckpointStore,
 	InMemoryMemoryIndex,
 	InMemoryMemoryStore,
 	InMemoryStore,
 	InMemoryTaskStore,
 	RunDiskStore,
 } from './store/index.js'
+export type { DiskCheckpointStoreAttribution } from './store/index.js'
+// Enumerating runs above a run id — the read an approval inbox and a park
+// sweep are built from, and the one the contract had no way to express.
+// `listDurableRuns` REFUSES on a store that cannot list rather than
+// reporting an empty page, because "nothing is waiting on a human" is not
+// what "I cannot tell" means.
+export {
+	assertContiguousListingScope,
+	listDurableRuns,
+	paginateDurableRuns,
+	toDurableRunEntry,
+} from './store/index.js'
 
 export {
 	AgentRegistry,

package/src/store/index.ts

@@ -3,6 +3,24 @@ export type { Identifiable, Timestamped } from './InMemoryStore.js'
 
 export { RunDiskStore } from './run/disk.js'
 export { DiskCheckpointStore } from './run/checkpoint-disk.js'
+export type { DiskCheckpointStoreAttribution } from './run/checkpoint-disk.js'
+export { InMemoryCheckpointStore } from './run/checkpoint-memory.js'
+// The refusing entry point to the optional listing capability, plus the two
+// projections a host implementing its own backend actually calls: one turns
+// a run's checkpoints into a row, the other applies the contract's filter,
+// ordering and cursor. Re-deriving either is how two stores start
+// disagreeing about what "outstanding" means or where a page ends.
+//
+// `summarizePark` and `DEFAULT_DURABLE_RUN_LIMIT` are deliberately NOT here.
+// The first is an internal of `toDurableRunEntry` and no caller wants half a
+// row; the second is a number a host reads by omitting `limit`. A name a
+// host has no use for is surface to keep correct forever for nobody.
+export {
+	assertContiguousListingScope,
+	listDurableRuns,
+	paginateDurableRuns,
+	toDurableRunEntry,
+} from './run/listing.js'
 
 export { ActivityStore } from './activity/memory.js'
 export type { ActivityEvent, ActivityEventListener } from './activity/memory.js'

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

@@ -1,8 +1,40 @@
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { NamzuError } from '../../types/errors/index.js'
 import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js'
-import type { RunId } from '../../types/ids/index.js'
-import type { CheckpointRunScope, CheckpointStore } from '../../types/run/checkpoint-store.js'
+import type { RunId, SessionId, TenantId } from '../../types/ids/index.js'
+import type {
+	CheckpointListingScope,
+	CheckpointRunScope,
+	CheckpointStore,
+	DurableRunEntry,
+	DurableRunPage,
+	ListDurableRunsOptions,
+} from '../../types/run/checkpoint-store.js'
 import type { RunStoreConfig } from '../../types/run/index.js'
-import { RunDiskStore } from './disk.js'
+import type { ProjectId } from '../../types/session/ids.js'
+import { RunDiskStore, readCheckpointsIn } from './disk.js'
+import { assertContiguousListingScope, paginateDurableRuns, toDurableRunEntry } from './listing.js'
+
+/**
+ * The attribution a disk store's own layout does not record.
+ *
+ * The canonical layout is
+ * `{root}/projects/{projectId}/sessions/{sessionId}/runs/{runId}` — there is
+ * no tenant segment anywhere in it, and `baseDir` is already one session's
+ * `runs/` directory, so the project and session are implicit in a string the
+ * store cannot parse back out without knowing the layout that built it.
+ *
+ * A per-run read never needed any of it: the caller supplies a full
+ * `CheckpointRunScope` and the store only uses `runId`. A LISTING does — its
+ * rows have to be addressable, and a row with no tenant is a row nothing can
+ * be resumed from. So the store is told, once, what tree it is holding.
+ */
+export interface DiskCheckpointStoreAttribution {
+	readonly tenantId: TenantId
+	readonly projectId: ProjectId
+	readonly sessionId: SessionId
+}
 
 /**
  * Disk conformance layer for {@link CheckpointStore}: adapts the existing
@@ -20,10 +52,20 @@ import { RunDiskStore } from './disk.js'
  */
 export class DiskCheckpointStore implements CheckpointStore {
 	private readonly config: RunStoreConfig
+	private readonly attribution?: DiskCheckpointStoreAttribution
 	private readonly bound = new Map<RunId, Promise<RunDiskStore>>()
 
-	constructor(config: RunStoreConfig) {
+	/**
+	 * @param config the run-store config; `baseDir` is one session's `runs/`
+	 *   directory.
+	 * @param attribution what tree this is, for
+	 *   {@link DiskCheckpointStore.listDurableRuns}. Optional so that adding
+	 *   the listing did not change an existing construction; a store built
+	 *   without it refuses to list rather than inventing a tenant.
+	 */
+	constructor(config: RunStoreConfig, attribution?: DiskCheckpointStoreAttribution) {
 		this.config = config
+		this.attribution = attribution
 	}
 
 	private bind(scope: CheckpointRunScope): Promise<RunDiskStore> {
@@ -64,4 +106,86 @@ export class DiskCheckpointStore implements CheckpointStore {
 		const store = await this.bind(scope)
 		await store.deleteCheckpoint(checkpointId)
 	}
+
+	/**
+	 * Every run with checkpoints under this store's tree.
+	 *
+	 * Reads the directories rather than binding a {@link RunDiskStore} per
+	 * run, because binding CREATES the run directory — a listing that
+	 * materialized a directory for every run it looked at would grow the tree
+	 * it is reporting on.
+	 *
+	 * ### Why a two-level walk reaches every depth
+	 *
+	 * `initRun` nests exactly one level: a run with a parent goes to
+	 * `{baseDir}/{parentRunId}/children/{runId}`, and a grandchild goes to
+	 * `{baseDir}/{itsOwnParentRunId}/children/{runId}` — beside the top-level
+	 * runs, not beneath its grandparent. So the tree is flat-with-one-nesting
+	 * at every depth, `{baseDir}/*` plus `{baseDir}/* /children/*` enumerates
+	 * all of it, and each run's `parentRunId` is the directory it sits under.
+	 * A deep run leaves a bare shell directory under its own id at the top
+	 * level (`{baseDir}/{parentRunId}` created by `mkdir -p` for a child of a
+	 * run whose own data lives elsewhere); those hold no `checkpoints/` and
+	 * drop out as entries with no durable state.
+	 */
+	async listDurableRuns(
+		scope: CheckpointListingScope,
+		options?: ListDurableRunsOptions,
+	): Promise<DurableRunPage> {
+		assertContiguousListingScope(scope, 'DiskCheckpointStore.listDurableRuns')
+
+		const attribution = this.attribution
+		if (!attribution) {
+			throw new NamzuError({
+				code: 'invalid_config',
+				message:
+					'DiskCheckpointStore.listDurableRuns: this store was constructed without attribution, so it cannot say which tenant, project or session its runs belong to — and a listing row that carries no scope is a row nothing can be resumed or swept from. Pass the second constructor argument. Refusing rather than returning rows stamped with a guessed tenant.',
+				details: { baseDir: this.config.baseDir },
+			})
+		}
+
+		// A listing is scoped, not addressed: a query for another tenant is a
+		// question this tree has no rows for, not an isolation violation. Same
+		// reasoning `SessionStore.listSessions` already states for sessions
+		// that happen to share a thread id across tenants.
+		if (
+			scope.tenantId !== attribution.tenantId ||
+			(scope.projectId !== undefined && scope.projectId !== attribution.projectId) ||
+			(scope.sessionId !== undefined && scope.sessionId !== attribution.sessionId)
+		) {
+			return { entries: [] }
+		}
+
+		const now = options?.now ?? Date.now()
+		const entries: DurableRunEntry[] = []
+
+		for (const runId of await this.readRunDirs(this.config.baseDir)) {
+			const runDir = join(this.config.baseDir, runId)
+
+			const own = toDurableRunEntry({ ...attribution, runId }, await readCheckpointsIn(runDir), now)
+			if (own) entries.push(own)
+
+			for (const childId of await this.readRunDirs(join(runDir, 'children'))) {
+				const child = toDurableRunEntry(
+					{ ...attribution, runId: childId, parentRunId: runId },
+					await readCheckpointsIn(join(runDir, 'children', childId)),
+					now,
+				)
+				if (child) entries.push(child)
+			}
+		}
+
+		return paginateDurableRuns(entries, options)
+	}
+
+	/** Directory names under `dir`, or none when `dir` does not exist. */
+	private async readRunDirs(dir: string): Promise<RunId[]> {
+		try {
+			const found = await readdir(dir, { withFileTypes: true })
+			return found.filter((e) => e.isDirectory()).map((e) => e.name as RunId)
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code === 'ENOENT') return []
+			throw err
+		}
+	}
 }

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

@@ -0,0 +1,101 @@
+import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js'
+import type {
+	CheckpointListingScope,
+	CheckpointRunScope,
+	CheckpointStore,
+	DurableRunEntry,
+	DurableRunPage,
+	ListDurableRunsOptions,
+} from '../../types/run/checkpoint-store.js'
+import { assertContiguousListingScope, paginateDurableRuns, toDurableRunEntry } from './listing.js'
+
+/**
+ * Process-local {@link CheckpointStore}, keyed by the full five-layer scope.
+ *
+ * Shipped rather than left as a test fixture for two reasons. It is the
+ * reference a host reads when writing a backend of its own — the disk store
+ * is path-addressed and answers "what does an attribution-keyed store look
+ * like" with a directory layout, which is the wrong lesson. And it is the
+ * only implementation that can hold more than one tenant at once, because
+ * the disk layout has no tenant in it: a test that two tenants' listings
+ * stay separate is not expressible against disk, and a rule that cannot be
+ * tested on the store a host will actually inject is a rule on paper.
+ *
+ * Not durable, deliberately: it is for tests, for a single-process host that
+ * genuinely wants checkpoints to die with the process, and as the parity
+ * partner that proves the listing contract is not a filesystem in disguise.
+ */
+export class InMemoryCheckpointStore implements CheckpointStore {
+	/** `tenant/project/session/run` → checkpoint id → checkpoint. */
+	private readonly runs = new Map<string, Map<CheckpointId, IterationCheckpoint>>()
+	/** Same key → the run's scope, so a listing can rebuild an addressable entry. */
+	private readonly scopes = new Map<string, CheckpointRunScope>()
+
+	private key(scope: CheckpointRunScope): string {
+		return [scope.tenantId, scope.projectId, scope.sessionId, scope.runId].join('/')
+	}
+
+	async writeCheckpoint(scope: CheckpointRunScope, checkpoint: IterationCheckpoint): Promise<void> {
+		const key = this.key(scope)
+		let run = this.runs.get(key)
+		if (!run) {
+			run = new Map()
+			this.runs.set(key, run)
+		}
+		// The run's scope is kept beside its checkpoints because the key is a
+		// joined string and a listing has to hand back the parts — above all
+		// `parentRunId`, which is what makes a sub-run's row addressable.
+		//
+		// Written on every call rather than only the first, and that is
+		// simplicity, not defence: a run's scope is fixed when the run is
+		// constructed, so the two cannot differ, and a `has` guard here would
+		// be a branch no input can take.
+		this.scopes.set(key, {
+			tenantId: scope.tenantId,
+			projectId: scope.projectId,
+			sessionId: scope.sessionId,
+			runId: scope.runId,
+			...(scope.parentRunId ? { parentRunId: scope.parentRunId } : {}),
+		})
+		run.set(checkpoint.id, checkpoint)
+	}
+
+	async readCheckpoint(
+		scope: CheckpointRunScope,
+		checkpointId: CheckpointId,
+	): Promise<IterationCheckpoint | null> {
+		return this.runs.get(this.key(scope))?.get(checkpointId) ?? null
+	}
+
+	async listCheckpoints(scope: CheckpointRunScope): Promise<IterationCheckpoint[]> {
+		const run = this.runs.get(this.key(scope))
+		if (!run) return []
+		return [...run.values()].sort((a, b) => a.createdAt - b.createdAt)
+	}
+
+	async deleteCheckpoint(scope: CheckpointRunScope, checkpointId: CheckpointId): Promise<void> {
+		this.runs.get(this.key(scope))?.delete(checkpointId)
+	}
+
+	async listDurableRuns(
+		scope: CheckpointListingScope,
+		options?: ListDurableRunsOptions,
+	): Promise<DurableRunPage> {
+		assertContiguousListingScope(scope, 'InMemoryCheckpointStore.listDurableRuns')
+		const now = options?.now ?? Date.now()
+
+		const entries: DurableRunEntry[] = []
+		for (const [key, checkpoints] of this.runs) {
+			const runScope = this.scopes.get(key)
+			if (!runScope) continue
+			if (runScope.tenantId !== scope.tenantId) continue
+			if (scope.projectId !== undefined && runScope.projectId !== scope.projectId) continue
+			if (scope.sessionId !== undefined && runScope.sessionId !== scope.sessionId) continue
+
+			const entry = toDurableRunEntry(runScope, [...checkpoints.values()], now)
+			if (entry) entries.push(entry)
+		}
+
+		return paginateDurableRuns(entries, options)
+	}
+}