@namzu/sdk 43.0.0 → 44.0.0

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

@@ -1,264 +0,0 @@
-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, SessionId, TenantId } from '../../types/ids/index.js'
-import type {
-	CheckpointListingScope,
-	CheckpointRunScope,
-	CheckpointStore,
-	ClaimRunOptions,
-	DurableRunEntry,
-	DurableRunPage,
-	FencingToken,
-	ListDurableRunsOptions,
-	RunLease,
-} from '../../types/run/checkpoint-store.js'
-import type { RunStoreConfig } from '../../types/run/index.js'
-import type { ProjectId } from '../../types/session/ids.js'
-import { asRunId, isEntityId } from '../../utils/id.js'
-import { acquireClaim, currentFence, readClaim, releaseClaim } from './claim-disk.js'
-import { RunDiskStore, readCheckpointsIn } from './disk.js'
-import {
-	assertContiguousListingScope,
-	fencedOut,
-	paginateDurableRuns,
-	toClaimSummary,
-	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
- * {@link RunDiskStore} checkpoint methods (which are bound to a single run
- * directory via `initRun`) to the scope-keyed store contract.
- *
- * Path-addressed: `baseDir` already encodes project/session (it is the
- * session's `runs/` directory), so only `scope.runId` / `scope.parentRunId`
- * participate in directory resolution — `tenantId`/`projectId`/`sessionId`
- * exist for backends that key by attribution instead of path.
- *
- * One `RunDiskStore` is bound per resolved run directory, then cached, so
- * repeated checkpoint operations against the same run don't re-run `initRun`.
- * Parent attribution remains part of the address even when a cache is warm.
- */
-export class DiskCheckpointStore implements CheckpointStore {
-	private readonly config: RunStoreConfig
-	private readonly attribution?: DiskCheckpointStoreAttribution
-	private readonly bound = new Map<string, Promise<RunDiskStore>>()
-
-	/**
-	 * @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> {
-		const path = this.runDir(scope)
-		const cached = this.bound.get(path)
-		if (cached) return cached
-		const promise = (async () => {
-			const store = new RunDiskStore(this.config)
-			await store.initRun(scope.runId, scope.parentRunId)
-			return store
-		})()
-		this.bound.set(path, promise)
-		// A failed bind must not poison the cache — the next call retries.
-		promise.catch(() => {
-			this.bound.delete(path)
-		})
-		return promise
-	}
-
-	async writeCheckpoint(
-		scope: CheckpointRunScope,
-		checkpoint: IterationCheckpoint,
-		fence?: FencingToken,
-	): Promise<void> {
-		const store = await this.bind(scope)
-		if (fence !== undefined) {
-			// Read at the moment of the write, not at the start of the run.
-			// A holder that stalled past its lease believes it still holds,
-			// and this is the only point at which it can be told otherwise.
-			// Names only, no parsing. The fence is the file name, so a corrupt
-			// body cannot make this check skip itself — which the previous shape
-			// did, at the one site whose entire job is refusing.
-			const current = await currentFence(this.runDir(scope))
-			if (fence < current) throw fencedOut(scope, fence, current)
-		}
-		await store.writeCheckpoint(checkpoint)
-	}
-
-	async claimRun(scope: CheckpointRunScope, options: ClaimRunOptions): Promise<RunLease | null> {
-		return acquireClaim(this.runDir(scope), options)
-	}
-
-	async releaseRun(scope: CheckpointRunScope, fence: FencingToken): Promise<void> {
-		await releaseClaim(this.runDir(scope), fence)
-	}
-
-	/**
-	 * The run's directory, resolved the same way `RunDiskStore.initRun` does.
-	 *
-	 * Duplicated rather than shared because the claim path must be derivable
-	 * WITHOUT binding a store — binding creates the directory, and a claim
-	 * read is a read. Kept beside the layout comment on `listDurableRuns` so
-	 * the two stay together if the layout ever moves.
-	 */
-	private runDir(scope: CheckpointRunScope): string {
-		asRunId(scope.runId)
-		if (scope.parentRunId !== undefined) asRunId(scope.parentRunId)
-		return scope.parentRunId
-			? join(this.config.baseDir, scope.parentRunId, 'children', scope.runId)
-			: join(this.config.baseDir, scope.runId)
-	}
-
-	async readCheckpoint(
-		scope: CheckpointRunScope,
-		checkpointId: CheckpointId,
-	): Promise<IterationCheckpoint | null> {
-		const store = await this.bind(scope)
-		return store.readCheckpoint(checkpointId)
-	}
-
-	async listCheckpoints(scope: CheckpointRunScope): Promise<IterationCheckpoint[]> {
-		const store = await this.bind(scope)
-		return store.listCheckpoints()
-	}
-
-	async deleteCheckpoint(scope: CheckpointRunScope, checkpointId: CheckpointId): Promise<void> {
-		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(await this.withClaim(own, runDir, now))
-
-			for (const childId of await this.readRunDirs(join(runDir, 'children'))) {
-				const childDir = join(runDir, 'children', childId)
-				const child = toDurableRunEntry(
-					{ ...attribution, runId: childId, parentRunId: runId },
-					await readCheckpointsIn(childDir),
-					now,
-				)
-				if (child) entries.push(await this.withClaim(child, childDir, now))
-			}
-		}
-
-		return paginateDurableRuns(entries, options)
-	}
-
-	/**
-	 * Attach the run's claim to its listing row, judged against the page's
-	 * own clock so one page cannot disagree with itself about availability.
-	 */
-	private async withClaim(
-		entry: DurableRunEntry,
-		runDir: string,
-		now: number,
-	): Promise<DurableRunEntry> {
-		const claim = await readClaim(runDir)
-		// A holding whose body could not be read still appears on the row,
-		// carrying an expiry of 0 so it reads as available. Dropping the field
-		// entirely — which is what happened before — put the run under
-		// `claimed: false` by looking unclaimed rather than by being
-		// reclaimable, so a queue reader was told a wedged run was free work.
-		return claim ? { ...entry, claim: toClaimSummary(claim, now) } : entry
-	}
-
-	/** 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 })
-			// The directory supplies the entity kind. Admit current and legacy
-			// run IDs; ignore scratch entries without hiding durable UUID runs.
-			return found
-				.filter((e) => e.isDirectory() && isEntityId(e.name, 'run'))
-				.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

@@ -1,216 +0,0 @@
-import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js'
-import type {
-	CheckpointListingScope,
-	CheckpointRunScope,
-	CheckpointStore,
-	ClaimRunOptions,
-	DurableRunEntry,
-	DurableRunPage,
-	FencingToken,
-	ListDurableRunsOptions,
-	RunLease,
-} from '../../types/run/checkpoint-store.js'
-import {
-	assertContiguousListingScope,
-	fencedOut,
-	paginateDurableRuns,
-	toClaimSummary,
-	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('/')
-	}
-
-	/** `tenant/project/session/run` → the run's current holding, if any. */
-	private readonly claims = new Map<string, RunLease>()
-
-	/**
-	 * The highest fence ever issued per run, kept separately from the claim.
-	 *
-	 * The claim is removed on release; this is not. That separation is the
-	 * whole point: the first version deleted the claim and then computed the
-	 * next fence from it, so releasing rewound the counter to 1 and a worker
-	 * stalled at fence 1 could write beside a new holder also at fence 1 —
-	 * and the documented `finally { releaseRun() }` did it on every pass.
-	 *
-	 * The disk store gets this property from file names that persist. In
-	 * memory the equivalent is a high-water mark nothing clears, and the two
-	 * must agree, because this class is what a host reads when writing a
-	 * backend of its own.
-	 */
-	private readonly highWater = new Map<string, FencingToken>()
-
-	async claimRun(scope: CheckpointRunScope, options: ClaimRunOptions): Promise<RunLease | null> {
-		const key = this.key(scope)
-		const now = options.now ?? Date.now()
-		const held = this.claims.get(key)
-
-		// Held by somebody else and still live. Not an error: two readers on
-		// one queue is the ordinary case.
-		if (held && now < held.expiresAt && held.holder !== options.holder) return null
-
-		// A reclaim of an expired holding and a renewal by the current holder
-		// are the same write. The fence advances either way, so a previous
-		// holder that wakes up is fenced out in both cases — a renewal that
-		// kept the fence would leave a stalled twin able to write.
-		// Counted from the high-water mark, never from the live claim. A
-		// released run has no claim, and computing from that absence is what
-		// rewound the counter to 1 on every release.
-		const fence = (this.highWater.get(key) ?? 0) + 1
-		const claim: RunLease = { holder: options.holder, fence, expiresAt: now + options.ttlMs }
-		this.highWater.set(key, fence)
-		this.claims.set(key, claim)
-		return claim
-	}
-
-	async releaseRun(scope: CheckpointRunScope, fence: FencingToken): Promise<void> {
-		const key = this.key(scope)
-		const held = this.claims.get(key)
-		// A stale fence releases nothing. A worker that stalled past its lease
-		// must not be able to hand away a run somebody else now holds.
-		//
-		// The high-water mark deliberately survives this. Dropping the claim
-		// returns the run to the queue; forgetting the number it reached would
-		// re-issue a fence a stalled worker still believes it holds.
-		if (!held || held.fence !== fence) return
-		this.claims.delete(key)
-		// And the counter steps past the released holding, because the disk
-		// store's release does: it appends a TOMBSTONE at `fence + 1`, which
-		// raises the maximum name and therefore the fence every later write is
-		// checked against. Without this step a holder that released could still
-		// write with the fence it just gave up — refused on disk, accepted here.
-		//
-		// The consequence is visible in the numbering: a released run's next
-		// claim is `fence + 2` in both stores, because the tombstone consumed
-		// one. That is parity, not an off-by-one.
-		this.highWater.set(key, fence + 1)
-	}
-
-	async writeCheckpoint(
-		scope: CheckpointRunScope,
-		checkpoint: IterationCheckpoint,
-		fence?: FencingToken,
-	): Promise<void> {
-		const key = this.key(scope)
-		// An unfenced write is allowed even on a claimed run: a host adopting
-		// claims on one worker must not break the workers that have not
-		// adopted them. A fenced write is checked, and that check is what
-		// makes the lease real.
-		if (fence !== undefined) {
-			// Against the HIGH-WATER MARK, not the live claim, and the difference
-			// is a silent loss rather than a duplicate.
-			//
-			// `releaseRun` deletes the claim. Reading `claims` here meant that
-			// between a release and the next take there was no holding to
-			// compare against, so `held` was `undefined` and every fence was
-			// accepted however stale. w1 stalls at fence 1; w2 reclaims at 2,
-			// finishes the work, releases cleanly; w1 wakes and writes with
-			// fence 1 — accepted — and its checkpoint carries a fresh
-			// `createdAt`, so it sorts newest and the next resume restores w1's
-			// stale history. w2's completed work is gone, with no error
-			// anywhere.
-			//
-			// The disk store refuses that write, because `currentFence` reads
-			// file names and the release tombstone raised the maximum. The
-			// minting side here already counted from the high-water mark; only
-			// the enforcement side was left reading the claim, so the two
-			// shipped stores disagreed at the one point that decides whether a
-			// lease is real.
-			const current = this.highWater.get(key) ?? 0
-			if (fence < current) throw fencedOut(scope, fence, current)
-		}
-		return this.writeUnchecked(scope, checkpoint)
-	}
-
-	private async writeUnchecked(
-		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) continue
-			const claim = this.claims.get(key)
-			entries.push(claim ? { ...entry, claim: toClaimSummary(claim, now) } : entry)
-		}
-
-		return paginateDurableRuns(entries, options)
-	}
-}