@namzu/sdk 43.0.0 → 44.1.0

package/src/store/budget/memory.ts

@@ -0,0 +1,39 @@
+import {
+	type SessionTokenBudgetStore,
+	assertSameRoot,
+	validateBudgetScope,
+	validateSnapshotScope,
+} from './disk.js'
+import type { SessionTokenBudgetScope, SessionTokenBudgetSnapshot } from './ledger.js'
+
+/**
+ * Process-local {@link SessionTokenBudgetStore}: one ledger per
+ * `(rootSessionId, rootTurnId)`, no filesystem.
+ *
+ * It refuses exactly what the disk store refuses (a snapshot for another
+ * key, a replaced root account, reduced usage, a forgotten receipt), so a
+ * host that tests against one and ships the other sees the same answers.
+ * Records are copied on the way in and out, so a caller holding a snapshot
+ * cannot change what the store holds.
+ */
+export class InMemorySessionTokenBudgetStore implements SessionTokenBudgetStore {
+	readonly #records = new Map<string, SessionTokenBudgetSnapshot>()
+
+	#key(scope: SessionTokenBudgetScope): string {
+		const checked = validateBudgetScope(scope)
+		return `${checked.rootSessionId}/${checked.rootTurnId}`
+	}
+
+	async load(scope: SessionTokenBudgetScope): Promise<SessionTokenBudgetSnapshot | null> {
+		const saved = this.#records.get(this.#key(scope))
+		return saved === undefined ? null : structuredClone(saved)
+	}
+
+	async save(scope: SessionTokenBudgetScope, snapshot: SessionTokenBudgetSnapshot): Promise<void> {
+		const key = this.#key(scope)
+		const checked = validateSnapshotScope(structuredClone(snapshot), validateBudgetScope(scope))
+		const existing = this.#records.get(key)
+		if (existing) assertSameRoot(existing, checked)
+		this.#records.set(key, checked)
+	}
+}

package/src/store/checkpoint/contract.ts

@@ -0,0 +1,225 @@
+import { createHash } from 'node:crypto'
+import type { CheckpointId, SessionId, TenantId, TurnId } from '../../types/ids/index.js'
+import { type Checkpoint, parseCheckpoint } from '../../types/session/checkpoint.js'
+import type { ProjectId } from '../../types/session/ids.js'
+import { asCheckpointId, asProjectId, asSessionId, asTenantId, asTurnId } from '../../utils/id.js'
+
+/**
+ * The turn whose checkpoints are addressed.
+ *
+ * A checkpoint belongs to one turn of one session. Tenant and project are
+ * part of the key so a shared backend can enforce isolation; the built-in
+ * disk store is rooted in one project of one tenant's `NAMZU_HOME` and
+ * addresses by session only.
+ */
+export interface CheckpointScope {
+	readonly tenantId: TenantId
+	readonly projectId: ProjectId
+	readonly sessionId: SessionId
+	readonly turnId: TurnId
+	/**
+	 * The session's ancestors, root first, when it is a child session. A
+	 * layout hint only: the disk store nests a child's directory under
+	 * `<parent>/subagents/`, and a store keyed by id ignores it.
+	 */
+	readonly ancestors?: readonly SessionId[]
+}
+
+/**
+ * What a write hands back: exactly the payload of the `checkpoint_written`
+ * record the caller appends next. The document is on disk before this
+ * resolves, so the record never names a file that is not there.
+ */
+export interface CheckpointWriteReceipt {
+	readonly checkpointId: CheckpointId
+	readonly iteration: number
+	readonly throughSeq: number
+	readonly throughSha256: string
+	/** Relative to the session directory: `checkpoints/<id>.json`. */
+	readonly path: string
+	/** SHA-256 (lowercase hex) of the document's stored bytes. */
+	readonly docSha256: string
+}
+
+/**
+ * What a checkpoint store needs from the session log, injected so the store
+ * does not depend on one log implementation.
+ *
+ * Every member answers from the log of `scope.sessionId`.
+ */
+export interface CheckpointLogView {
+	/**
+	 * True when the record at `throughSeq` exists and hashes to
+	 * `throughSha256`. A checkpoint's context is the fold of the log through
+	 * that seq, so a log truncated or edited below it restores a context the
+	 * checkpoint never saw.
+	 */
+	verifyThrough(scope: CheckpointScope, throughSeq: number, throughSha256: string): Promise<boolean>
+	/** `docSha256` of the `checkpoint_written` record for `checkpointId`, or null when there is none. */
+	writtenDocSha256(scope: CheckpointScope, checkpointId: CheckpointId): Promise<string | null>
+	/**
+	 * Checkpoints named by a `decision_requested` record that has no
+	 * `decision_resolved` or `decision_expired` yet. `prune` never deletes one.
+	 */
+	openDecisionCheckpoints(scope: CheckpointScope): Promise<Iterable<CheckpointId>>
+}
+
+/** Why a restore refused a checkpoint. */
+export type CheckpointRefusalReason =
+	/** No `checkpoint_written` record names it: it was never committed to the log. */
+	| 'not-recorded'
+	/** The stored bytes do not hash to the record's `docSha256`. */
+	| 'document-mismatch'
+	/** The record at `throughSeq` is missing or does not hash to `throughSha256`. */
+	| 'through-mismatch'
+
+/** A checkpoint that exists but cannot be trusted to restore the turn it describes. */
+export class CheckpointIntegrityError extends Error {
+	override readonly name = 'CheckpointIntegrityError'
+	constructor(
+		readonly checkpointId: CheckpointId,
+		readonly reason: CheckpointRefusalReason,
+	) {
+		super(`Refusing checkpoint ${checkpointId}: ${REASONS[reason]}`)
+	}
+}
+
+const REASONS: Record<CheckpointRefusalReason, string> = {
+	'not-recorded': 'no checkpoint_written record names it in the session log.',
+	'document-mismatch':
+		'its stored bytes do not match the docSha256 of its checkpoint_written record.',
+	'through-mismatch':
+		'the session log record it was taken through is missing or no longer matches throughSha256.',
+}
+
+/**
+ * Checkpoint persistence for one project: documents under
+ * `<session-id>/checkpoints/`, addressed by turn.
+ *
+ * Reads return `null` or an empty list when nothing exists; `delete` of an
+ * absent checkpoint is a no-op. A write never replaces an existing document:
+ * the log records the hash of the bytes first written, and a replacement
+ * would make that record lie.
+ *
+ * Writes are not fenced here. The document is inert until its
+ * `checkpoint_written` record is appended, and that append is what the
+ * session lease fences; a stale writer's document is refused on restore as
+ * `not-recorded`.
+ */
+export interface SessionCheckpointStore {
+	/** Persist a new checkpoint of `scope.turnId` and return the record payload that commits it. */
+	write(scope: CheckpointScope, checkpoint: Checkpoint): Promise<CheckpointWriteReceipt>
+	/** Read one of the turn's checkpoints without checking it against the log. */
+	read(scope: CheckpointScope, checkpointId: CheckpointId): Promise<Checkpoint | null>
+	/**
+	 * Read one of the turn's checkpoints for a resume: refused with
+	 * {@link CheckpointIntegrityError} unless its record exists, its bytes
+	 * hash to the record's `docSha256`, and the log still holds the record it
+	 * was taken through.
+	 */
+	restore(scope: CheckpointScope, checkpointId: CheckpointId): Promise<Checkpoint | null>
+	/** The turn's checkpoints, oldest first (`createdAt`, then id). */
+	list(scope: CheckpointScope): Promise<Checkpoint[]>
+	delete(scope: CheckpointScope, checkpointId: CheckpointId): Promise<void>
+	/**
+	 * Delete the turn's oldest committed checkpoints until `keepLast` newer
+	 * committed ones remain, never one an open decision references. Only a
+	 * checkpoint a `checkpoint_written` record names is counted or deleted: a
+	 * document no record commits is inert and left alone, so it can never
+	 * stand in for the turn's resume point. Returns the deleted ids, oldest
+	 * first, for the `checkpoint_pruned` record (none: append nothing).
+	 */
+	prune(scope: CheckpointScope, keepLast: number): Promise<CheckpointId[]>
+}
+
+/** Validate every id of a scope, so none can reach a path or a key unchecked. */
+export function validateCheckpointScope(scope: CheckpointScope): CheckpointScope {
+	return {
+		tenantId: asTenantId(scope.tenantId),
+		projectId: asProjectId(scope.projectId),
+		sessionId: asSessionId(scope.sessionId),
+		turnId: asTurnId(scope.turnId),
+		...(scope.ancestors === undefined ? {} : { ancestors: scope.ancestors.map(asSessionId) }),
+	}
+}
+
+/** The one serialisation every store writes and hashes. */
+export function serializeCheckpoint(checkpoint: Checkpoint): string {
+	return `${JSON.stringify(checkpoint)}\n`
+}
+
+export function sha256Hex(text: string): string {
+	return createHash('sha256').update(text, 'utf8').digest('hex')
+}
+
+/** The record `path` of a checkpoint, relative to its session directory. */
+export function checkpointRecordPath(checkpointId: CheckpointId): string {
+	return `checkpoints/${asCheckpointId(checkpointId)}.json`
+}
+
+/**
+ * Parse a document and check it belongs where it was found: a document
+ * whose session or id differs from its address is damage, not a miss.
+ */
+export function parseStoredCheckpoint(
+	text: string,
+	scope: CheckpointScope,
+	checkpointId: CheckpointId,
+): Checkpoint {
+	const checkpoint = parseCheckpoint(JSON.parse(text))
+	if (checkpoint.sessionId !== scope.sessionId || checkpoint.checkpointId !== checkpointId) {
+		throw new CheckpointOwnerError(
+			`Checkpoint document ${checkpointId} names session ${checkpoint.sessionId} and id ${checkpoint.checkpointId}; it is stored under session ${scope.sessionId}.`,
+		)
+	}
+	return checkpoint
+}
+
+/** A checkpoint document stored under an address it does not name, or written for another scope. */
+export class CheckpointOwnerError extends Error {
+	override readonly name = 'CheckpointOwnerError'
+}
+
+/** Refuse a write whose document names another session or turn than its scope. */
+export function checkWriteOwner(scope: CheckpointScope, checkpoint: Checkpoint): Checkpoint {
+	const parsed = parseCheckpoint(checkpoint)
+	if (parsed.sessionId !== scope.sessionId || parsed.turnId !== scope.turnId) {
+		throw new CheckpointOwnerError(
+			`Checkpoint ${parsed.checkpointId} belongs to session ${parsed.sessionId} turn ${parsed.turnId}; it cannot be written under session ${scope.sessionId} turn ${scope.turnId}.`,
+		)
+	}
+	return parsed
+}
+
+/** Build the receipt a successful write returns. */
+export function writeReceipt(checkpoint: Checkpoint, text: string): CheckpointWriteReceipt {
+	return {
+		checkpointId: checkpoint.checkpointId,
+		iteration: checkpoint.iteration,
+		throughSeq: checkpoint.throughSeq,
+		throughSha256: checkpoint.throughSha256,
+		path: checkpointRecordPath(checkpoint.checkpointId),
+		docSha256: sha256Hex(text),
+	}
+}
+
+/**
+ * The restore rule, shared by every store: the checkpoint's bytes must be
+ * the ones its record committed, and the log prefix it covers must be intact.
+ */
+export async function verifyCheckpoint(
+	log: CheckpointLogView,
+	scope: CheckpointScope,
+	checkpoint: Checkpoint,
+	text: string,
+): Promise<Checkpoint> {
+	const recorded = await log.writtenDocSha256(scope, checkpoint.checkpointId)
+	if (recorded === null) throw new CheckpointIntegrityError(checkpoint.checkpointId, 'not-recorded')
+	if (recorded !== sha256Hex(text)) {
+		throw new CheckpointIntegrityError(checkpoint.checkpointId, 'document-mismatch')
+	}
+	if (!(await log.verifyThrough(scope, checkpoint.throughSeq, checkpoint.throughSha256))) {
+		throw new CheckpointIntegrityError(checkpoint.checkpointId, 'through-mismatch')
+	}
+	return checkpoint
+}

package/src/store/checkpoint/disk.ts

@@ -0,0 +1,209 @@
+import { link, mkdir, open, readFile, readdir, unlink } from 'node:fs/promises'
+import type { FileHandle } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import type { SessionLocator, SessionPaths } from '../../session/paths.js'
+import type { CheckpointId } from '../../types/ids/index.js'
+import type { Checkpoint } from '../../types/session/checkpoint.js'
+import { syncDirectory, temporaryPathFor } from '../../utils/atomic-write.js'
+import { asCheckpointId, isEntityId } from '../../utils/id.js'
+import {
+	type CheckpointLogView,
+	type CheckpointScope,
+	type CheckpointWriteReceipt,
+	type SessionCheckpointStore,
+	checkWriteOwner,
+	parseStoredCheckpoint,
+	serializeCheckpoint,
+	validateCheckpointScope,
+	verifyCheckpoint,
+	writeReceipt,
+} from './contract.js'
+import { compareCheckpoints, selectStoredCheckpointsToPrune } from './prune.js'
+
+export interface DiskSessionCheckpointStoreOptions {
+	/** The project whose sessions hold the checkpoints. */
+	readonly paths: SessionPaths
+	/** The session log the checkpoints are verified and protected against. */
+	readonly log: CheckpointLogView
+	/**
+	 * The session this store answers for, with its ancestors when it is a
+	 * child session. A scope for that session that names no `ancestors` is
+	 * placed by this locator, so a child's checkpoints land in
+	 * `<parent-session-dir>/subagents/<child-id>/checkpoints/` even when the
+	 * caller building the scope knows only the session id. A scope that names
+	 * its own `ancestors` is placed by them.
+	 */
+	readonly session?: SessionLocator
+}
+
+const DOCUMENT = /^(.+)\.json$/
+
+/**
+ * {@link SessionCheckpointStore} at `<session-dir>/checkpoints/<id>.json`.
+ *
+ * A write is durable before it resolves: the document is written to a private
+ * sidecar, fsynced, linked to its final name (which fails rather than
+ * replacing an existing document), and the directory is fsynced. When the
+ * write creates `checkpoints/` (or any directory above it), the parent of each
+ * directory it created is fsynced too, so the new directory's own entry
+ * survives as well as the document's. The caller
+ * appends `checkpoint_written` only after that, so the record never names a
+ * file a power loss could take back.
+ *
+ * Directories are mode 0700 and documents 0600.
+ */
+export class DiskSessionCheckpointStore implements SessionCheckpointStore {
+	readonly #paths: SessionPaths
+	readonly #log: CheckpointLogView
+	readonly #session: SessionLocator | undefined
+
+	constructor(options: DiskSessionCheckpointStoreOptions) {
+		this.#paths = options.paths
+		this.#log = options.log
+		this.#session = options.session
+	}
+
+	#locator(scope: CheckpointScope): SessionLocator {
+		if (scope.ancestors !== undefined) {
+			return { sessionId: scope.sessionId, ancestors: scope.ancestors }
+		}
+		if (this.#session?.sessionId === scope.sessionId) return this.#session
+		return { sessionId: scope.sessionId }
+	}
+
+	async write(scope: CheckpointScope, checkpoint: Checkpoint): Promise<CheckpointWriteReceipt> {
+		const checked = validateCheckpointScope(scope)
+		const document = checkWriteOwner(checked, checkpoint)
+		const locator = this.#locator(checked)
+		const directory = this.#paths.checkpoints(locator)
+		const path = this.#paths.checkpointFile(locator, document.checkpointId)
+		const text = serializeCheckpoint(document)
+		await syncCreatedDirectories(
+			directory,
+			await mkdir(directory, { recursive: true, mode: 0o700 }),
+		)
+		const temporary = temporaryPathFor(path)
+		let handle: FileHandle | undefined
+		try {
+			handle = await open(temporary, 'wx', 0o600)
+			await handle.writeFile(text, 'utf8')
+			await handle.sync()
+			await handle.close()
+			handle = undefined
+			// `link` publishes atomically and, unlike `rename`, refuses an existing target.
+			await link(temporary, path)
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+				throw new Error(
+					`Checkpoint ${document.checkpointId} already exists; a checkpoint is never replaced.`,
+				)
+			}
+			throw error
+		} finally {
+			await handle?.close().catch(() => undefined)
+			await unlink(temporary).catch(() => undefined)
+		}
+		await syncDirectory(directory)
+		return writeReceipt(document, text)
+	}
+
+	async read(scope: CheckpointScope, checkpointId: CheckpointId): Promise<Checkpoint | null> {
+		return (await this.#readText(scope, checkpointId))?.checkpoint ?? null
+	}
+
+	async restore(scope: CheckpointScope, checkpointId: CheckpointId): Promise<Checkpoint | null> {
+		const found = await this.#readText(scope, checkpointId)
+		if (!found) return null
+		return verifyCheckpoint(this.#log, validateCheckpointScope(scope), found.checkpoint, found.text)
+	}
+
+	async #readText(
+		scope: CheckpointScope,
+		checkpointId: CheckpointId,
+	): Promise<{ checkpoint: Checkpoint; text: string } | null> {
+		const checked = validateCheckpointScope(scope)
+		const id = asCheckpointId(checkpointId)
+		const text = await readIfPresent(this.#paths.checkpointFile(this.#locator(checked), id))
+		if (text === null) return null
+		const checkpoint = parseStoredCheckpoint(text, checked, id)
+		// Another turn's checkpoint in the same session directory is not this turn's.
+		return checkpoint.turnId === checked.turnId ? { checkpoint, text } : null
+	}
+
+	async list(scope: CheckpointScope): Promise<Checkpoint[]> {
+		const checked = validateCheckpointScope(scope)
+		const locator = this.#locator(checked)
+		let names: string[]
+		try {
+			names = await readdir(this.#paths.checkpoints(locator))
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []
+			throw error
+		}
+		const checkpoints: Checkpoint[] = []
+		for (const name of names) {
+			// Sidecars (`<id>.json.<pid>.<n>.<hex>.tmp`) and strangers are not documents.
+			const id = DOCUMENT.exec(name)?.[1]
+			if (id === undefined || !isEntityId(id, 'checkpoint')) continue
+			const text = await readIfPresent(this.#paths.checkpointFile(locator, id))
+			// Deleted between the listing and the read: a concurrent prune, not damage.
+			if (text === null) continue
+			const checkpoint = parseStoredCheckpoint(text, checked, id)
+			if (checkpoint.turnId === checked.turnId) checkpoints.push(checkpoint)
+		}
+		return checkpoints.sort(compareCheckpoints)
+	}
+
+	async delete(scope: CheckpointScope, checkpointId: CheckpointId): Promise<void> {
+		const checked = validateCheckpointScope(scope)
+		const id = asCheckpointId(checkpointId)
+		// Only this turn's checkpoint: a scope must not reach into another turn.
+		if (!(await this.read(checked, id))) return
+		try {
+			await unlink(this.#paths.checkpointFile(this.#locator(checked), id))
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+		}
+	}
+
+	async prune(scope: CheckpointScope, keepLast: number): Promise<CheckpointId[]> {
+		const checked = validateCheckpointScope(scope)
+		const doomed = await selectStoredCheckpointsToPrune(
+			this.#log,
+			checked,
+			await this.list(checked),
+			keepLast,
+		)
+		for (const id of doomed) await this.delete(checked, id)
+		return doomed
+	}
+}
+
+async function readIfPresent(path: string): Promise<string | null> {
+	try {
+		return await readFile(path, 'utf8')
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
+		throw error
+	}
+}
+
+/**
+ * Make the directories `mkdir(directory, { recursive: true })` just created
+ * survive a power loss: fsync the parent of each, from `directory` up to the
+ * first one created. `created` is what `mkdir` returned, the outermost
+ * directory it made, or undefined when `directory` already existed.
+ */
+async function syncCreatedDirectories(
+	directory: string,
+	created: string | undefined,
+): Promise<void> {
+	if (created === undefined) return
+	let current = directory
+	for (;;) {
+		const parent = dirname(current)
+		await syncDirectory(parent)
+		if (current === created || parent === current) return
+		current = parent
+	}
+}

package/src/store/checkpoint/index.ts

@@ -0,0 +1,22 @@
+// Checkpoint documents under `<session-id>/checkpoints/` and their retention.
+// The public barrels re-export this module.
+export {
+	CheckpointIntegrityError,
+	CheckpointOwnerError,
+	checkpointRecordPath,
+	serializeCheckpoint,
+	validateCheckpointScope,
+} from './contract.js'
+export type {
+	CheckpointLogView,
+	CheckpointRefusalReason,
+	CheckpointScope,
+	CheckpointWriteReceipt,
+	SessionCheckpointStore,
+} from './contract.js'
+export { DiskSessionCheckpointStore } from './disk.js'
+export type { DiskSessionCheckpointStoreOptions } from './disk.js'
+export { InMemorySessionCheckpointStore } from './memory.js'
+export type { InMemorySessionCheckpointStoreOptions } from './memory.js'
+export { selectSessionCheckpointsToPrune } from './prune.js'
+export type { PrunableSessionCheckpoint } from './prune.js'

package/src/store/checkpoint/memory.ts

@@ -0,0 +1,112 @@
+import type { CheckpointId } from '../../types/ids/index.js'
+import type { Checkpoint } from '../../types/session/checkpoint.js'
+import { asCheckpointId } from '../../utils/id.js'
+import {
+	type CheckpointLogView,
+	type CheckpointScope,
+	type CheckpointWriteReceipt,
+	type SessionCheckpointStore,
+	checkWriteOwner,
+	parseStoredCheckpoint,
+	serializeCheckpoint,
+	validateCheckpointScope,
+	verifyCheckpoint,
+	writeReceipt,
+} from './contract.js'
+import { compareCheckpoints, selectStoredCheckpointsToPrune } from './prune.js'
+
+export interface InMemorySessionCheckpointStoreOptions {
+	/** The session log the checkpoints are verified and protected against. */
+	readonly log: CheckpointLogView
+}
+
+/**
+ * Process-local {@link SessionCheckpointStore}, keyed by the full
+ * tenant/project/session/turn scope.
+ *
+ * It keeps the serialised bytes rather than the object, so `restore` hashes
+ * exactly what `write` hashed and refuses exactly what the disk store
+ * refuses. It is the parity partner of the disk store and the store an
+ * in-memory session keeps its checkpoints in.
+ */
+export class InMemorySessionCheckpointStore implements SessionCheckpointStore {
+	readonly #log: CheckpointLogView
+	/** `tenant/project/session` → checkpoint id → stored text. */
+	readonly #sessions = new Map<string, Map<CheckpointId, string>>()
+
+	constructor(options: InMemorySessionCheckpointStoreOptions) {
+		this.#log = options.log
+	}
+
+	#documents(scope: CheckpointScope): Map<CheckpointId, string> | undefined {
+		const checked = validateCheckpointScope(scope)
+		return this.#sessions.get([checked.tenantId, checked.projectId, checked.sessionId].join('/'))
+	}
+
+	async write(scope: CheckpointScope, checkpoint: Checkpoint): Promise<CheckpointWriteReceipt> {
+		const checked = validateCheckpointScope(scope)
+		const document = checkWriteOwner(checked, checkpoint)
+		const key = [checked.tenantId, checked.projectId, checked.sessionId].join('/')
+		let documents = this.#sessions.get(key)
+		if (!documents) {
+			documents = new Map()
+			this.#sessions.set(key, documents)
+		}
+		if (documents.has(document.checkpointId)) {
+			throw new Error(
+				`Checkpoint ${document.checkpointId} already exists; a checkpoint is never replaced.`,
+			)
+		}
+		const text = serializeCheckpoint(document)
+		documents.set(document.checkpointId, text)
+		return writeReceipt(document, text)
+	}
+
+	async read(scope: CheckpointScope, checkpointId: CheckpointId): Promise<Checkpoint | null> {
+		return (await this.#readText(scope, checkpointId))?.checkpoint ?? null
+	}
+
+	async restore(scope: CheckpointScope, checkpointId: CheckpointId): Promise<Checkpoint | null> {
+		const found = await this.#readText(scope, checkpointId)
+		if (!found) return null
+		return verifyCheckpoint(this.#log, scope, found.checkpoint, found.text)
+	}
+
+	async #readText(
+		scope: CheckpointScope,
+		checkpointId: CheckpointId,
+	): Promise<{ checkpoint: Checkpoint; text: string } | null> {
+		const id = asCheckpointId(checkpointId)
+		const text = this.#documents(scope)?.get(id)
+		if (text === undefined) return null
+		const checkpoint = parseStoredCheckpoint(text, scope, id)
+		// Another turn's checkpoint is not this turn's: absent, as the disk store answers.
+		return checkpoint.turnId === scope.turnId ? { checkpoint, text } : null
+	}
+
+	async list(scope: CheckpointScope): Promise<Checkpoint[]> {
+		const documents = this.#documents(scope)
+		if (!documents) return []
+		return [...documents]
+			.map(([id, text]) => parseStoredCheckpoint(text, scope, id))
+			.filter((checkpoint) => checkpoint.turnId === scope.turnId)
+			.sort(compareCheckpoints)
+	}
+
+	async delete(scope: CheckpointScope, checkpointId: CheckpointId): Promise<void> {
+		const id = asCheckpointId(checkpointId)
+		if (await this.read(scope, id)) this.#documents(scope)?.delete(id)
+	}
+
+	async prune(scope: CheckpointScope, keepLast: number): Promise<CheckpointId[]> {
+		const checked = validateCheckpointScope(scope)
+		const doomed = await selectStoredCheckpointsToPrune(
+			this.#log,
+			checked,
+			await this.list(checked),
+			keepLast,
+		)
+		for (const id of doomed) await this.delete(checked, id)
+		return doomed
+	}
+}