@namzu/sdk 13.0.0 → 14.0.0

package/src/manager/project/lifecycle.ts

@@ -0,0 +1,160 @@
+/**
+ * ProjectManager — open/close a workspace, and the gate the ingress paths read.
+ *
+ * This is the Thread archival model moved to the level that survives. Thread
+ * carried `status` and `ThreadManager.requireOpen`; Project — the thing a
+ * tenant actually owns, configures, and closes — carried nothing, so archiving
+ * a workspace meant nothing to the code. See the hierarchy plan.
+ *
+ * Two deliberate differences from the Thread version:
+ *
+ *   - Status moves **both ways**. A thread was archived forever; a workspace is
+ *     long-lived and a mistaken close should be recoverable.
+ *   - The gate is a **function over a store**, not a method on an injected
+ *     manager. The three ingress paths already hold a `SessionStore`, so
+ *     nothing has to be threaded through a constructor for the invariant to be
+ *     enforced — a gate that requires new wiring is a gate somebody forgets to
+ *     wire.
+ */
+
+import {
+	PROJECT_NOT_EMPTY_SAMPLE_LIMIT,
+	ProjectClosedError,
+	ProjectNotEmptyError,
+} from '../../session/errors.js'
+import type { TenantId } from '../../types/ids/index.js'
+import type { Project } from '../../types/project/entity.js'
+import type { SessionStatus } from '../../types/session/entity.js'
+import type { ProjectId } from '../../types/session/ids.js'
+import type { SessionStore } from '../../types/session/store.js'
+
+/**
+ * Session statuses that block a workspace from closing.
+ *
+ * A live session is a running agent. Closing its workspace out from under it
+ * would strand work whose owner is still watching, so the caller settles the
+ * sessions first and archival never cascades.
+ */
+const ARCHIVAL_BLOCKING_STATUSES: ReadonlySet<SessionStatus> = new Set([
+	'active',
+	'locked',
+	'awaiting_merge',
+	'awaiting_hitl',
+])
+
+/**
+ * Load a Project and assert it accepts new work.
+ *
+ * Throws on absence — a missing project is a hard error, not an assumed-open
+ * one — and {@link ProjectClosedError} on an archived project. Returns the
+ * loaded Project so the caller can skip a second read; every current caller
+ * needs `config` immediately afterwards.
+ *
+ * `op` names the operation in the error, because "archived" is not by itself
+ * an explanation of what the caller was refused.
+ */
+export async function requireOpenProject(
+	store: Pick<SessionStore, 'getProject'>,
+	projectId: ProjectId,
+	tenantId: TenantId,
+	op: string,
+): Promise<Project> {
+	const project = await store.getProject(projectId, tenantId)
+	if (!project) {
+		throw new Error(`Project ${projectId} not found for tenant ${tenantId} — ${op} rejected`)
+	}
+	if (project.status === 'archived') {
+		throw new ProjectClosedError({ projectId, op })
+	}
+	return project
+}
+
+export interface ProjectManagerDeps {
+	store: SessionStore
+}
+
+export class ProjectManager {
+	constructor(private readonly deps: ProjectManagerDeps) {}
+
+	/** See {@link requireOpenProject}. */
+	requireOpen(projectId: ProjectId, tenantId: TenantId, op = 'require-open'): Promise<Project> {
+		return requireOpenProject(this.deps.store, projectId, tenantId, op)
+	}
+
+	/**
+	 * Close a workspace.
+	 *
+	 * Refuses while any attached session is non-terminal
+	 * ({@link ARCHIVAL_BLOCKING_STATUSES}), throwing {@link ProjectNotEmptyError}
+	 * with a sample of what is blocking. The presence check runs **before** the
+	 * already-archived short-circuit, so a workspace that is archived and still
+	 * harbouring a live session reports the live session rather than reporting
+	 * success — the second call is where an operator finds out.
+	 *
+	 * Idempotent: re-archiving an empty archived project is a no-op that
+	 * returns the stored record without a write, so it does not burn a version
+	 * and cannot lose a race it is not in.
+	 */
+	async archive(projectId: ProjectId, tenantId: TenantId): Promise<Project> {
+		const project = await this.deps.store.getProject(projectId, tenantId)
+		if (!project) {
+			throw new Error(`Project ${projectId} not found for tenant ${tenantId} — archive rejected`)
+		}
+
+		const sessions = (await this.deps.store.listSessionsByProject?.(projectId, tenantId)) ?? []
+		const blocking = sessions.filter((s) => ARCHIVAL_BLOCKING_STATUSES.has(s.status))
+		if (blocking.length > 0) {
+			throw new ProjectNotEmptyError({
+				projectId,
+				tenantId,
+				op: 'archive',
+				blockingSessions: blocking
+					.slice(0, PROJECT_NOT_EMPTY_SAMPLE_LIMIT)
+					.map((s) => ({ sessionId: s.id, status: s.status })),
+				totalBlockingSessions: blocking.length,
+			})
+		}
+
+		if (project.status === 'archived') return project
+		return this.write(projectId, 'archived', tenantId, project.ownerVersion)
+	}
+
+	/**
+	 * Reopen a workspace. Idempotent in the same way, and unconditional
+	 * otherwise: there is nothing a live session could make unsafe about
+	 * accepting work again.
+	 */
+	async reopen(projectId: ProjectId, tenantId: TenantId): Promise<Project> {
+		const project = await this.deps.store.getProject(projectId, tenantId)
+		if (!project) {
+			throw new Error(`Project ${projectId} not found for tenant ${tenantId} — reopen rejected`)
+		}
+		if (project.status === 'open') return project
+		return this.write(projectId, 'open', tenantId, project.ownerVersion)
+	}
+
+	private async write(
+		projectId: ProjectId,
+		status: Project['status'],
+		tenantId: TenantId,
+		expectedOwnerVersion: number,
+	): Promise<Project> {
+		const setStatus = this.deps.store.setProjectStatus
+		if (!setStatus) {
+			throw new Error(
+				`Project ${projectId} cannot be set to '${status}': this SessionStore does not implement setProjectStatus. A store without it cannot record the state, and pretending the write succeeded would leave the gate reading 'open' forever.`,
+			)
+		}
+		const written = await setStatus.call(
+			this.deps.store,
+			projectId,
+			status,
+			tenantId,
+			expectedOwnerVersion,
+		)
+		if (!written) {
+			throw new Error(`Project ${projectId} disappeared during '${status}' write`)
+		}
+		return written
+	}
+}

package/src/public-runtime.ts

@@ -225,6 +225,7 @@ export {
 	AgentManager,
 	EmergencySaveManager,
 	PlanManager,
+	ProjectManager,
 	RunPersistence,
 	ThreadManager,
 } from './manager/index.js'
@@ -483,6 +484,14 @@ export {
 
 export {
 	AncestryCycleError,
+	// Exported, unlike `ThreadClosedError`, because a host that closes a
+	// workspace has to be able to tell "this workspace is closed" from any
+	// other spawn failure — and matching on a message string is not a
+	// contract. The comment below is the reason; these are the first three
+	// that take it seriously.
+	ProjectClosedError,
+	ProjectNotEmptyError,
+	StaleProjectError,
 	// Exported with the CAS it announces. A host that opts into
 	// `expectedOwnerVersion` has to be able to tell "somebody else took this
 	// session" from any other failure, and string-matching a message is not a

package/src/session/errors.ts

@@ -9,7 +9,7 @@
 
 import type { SessionId, TenantId } from '../types/ids/index.js'
 import type { SessionStatus } from '../types/session/entity.js'
-import type { ThreadId } from '../types/session/ids.js'
+import type { ProjectId, ThreadId } from '../types/session/ids.js'
 import type { WorkspaceBackendKind } from './workspace/driver.js'
 
 /**
@@ -186,3 +186,87 @@ export class ThreadNotEmptyError extends Error {
 		this.details = details
 	}
 }
+
+/**
+ * Raised when an ingress path is asked to attach work to an archived Project.
+ *
+ * The sibling of {@link ThreadClosedError}, on the level that survives. A
+ * closed workspace is a decision by its owner, and the paths that create
+ * sessions have to be able to see it — otherwise "archived" is a word in a
+ * listing rather than a state of the system.
+ */
+export class ProjectClosedError extends Error {
+	readonly details: {
+		projectId: ProjectId
+		op: string
+	}
+
+	constructor(details: { projectId: ProjectId; op: string }) {
+		super(`Project ${details.projectId} is archived; operation '${details.op}' rejected`)
+		this.name = 'ProjectClosedError'
+		this.details = details
+	}
+}
+
+/**
+ * Raised by the project archive path when sessions are still attached and not
+ * in a terminal state.
+ *
+ * Archiving does not cascade and does not kill anything: a live session is a
+ * running agent, and closing its workspace out from under it would strand
+ * work whose owner is still watching. The caller settles the sessions first.
+ * `blockingSessions` is truncated to {@link PROJECT_NOT_EMPTY_SAMPLE_LIMIT};
+ * `totalBlockingSessions` is the real count.
+ */
+export const PROJECT_NOT_EMPTY_SAMPLE_LIMIT = 50
+
+export class ProjectNotEmptyError extends Error {
+	readonly details: {
+		projectId: ProjectId
+		tenantId: TenantId
+		op: 'archive'
+		blockingSessions: ReadonlyArray<{ sessionId: SessionId; status: SessionStatus }>
+		totalBlockingSessions: number
+	}
+
+	constructor(details: {
+		projectId: ProjectId
+		tenantId: TenantId
+		op: 'archive'
+		blockingSessions: ReadonlyArray<{ sessionId: SessionId; status: SessionStatus }>
+		totalBlockingSessions: number
+	}) {
+		super(
+			`Project ${details.projectId} ${details.op} blocked: ${details.totalBlockingSessions} session(s) still attached`,
+		)
+		this.name = 'ProjectNotEmptyError'
+		this.details = details
+	}
+}
+
+/**
+ * Raised when a project status write loses a compare-and-set.
+ *
+ * The sibling of {@link StaleSessionError}: the caller re-reads and decides
+ * again, because the project it was about to close is not the project on
+ * disk.
+ */
+export class StaleProjectError extends Error {
+	readonly details: {
+		projectId: ProjectId
+		expectedOwnerVersion: number
+		actualOwnerVersion: number
+	}
+
+	constructor(details: {
+		projectId: ProjectId
+		expectedOwnerVersion: number
+		actualOwnerVersion: number
+	}) {
+		super(
+			`Project ${details.projectId} was modified concurrently: expected ownerVersion ${details.expectedOwnerVersion}, found ${details.actualOwnerVersion}`,
+		)
+		this.name = 'StaleProjectError'
+		this.details = details
+	}
+}

package/src/session/handoff/broadcast.ts

@@ -21,6 +21,7 @@
  * ```
  */
 
+import { requireOpenProject } from '../../manager/project/lifecycle.js'
 import type { ThreadManager } from '../../manager/thread/lifecycle.js'
 import type { SessionId, TenantId } from '../../types/ids/index.js'
 import type { Session } from '../../types/session/entity.js'
@@ -189,11 +190,9 @@ export async function executeBroadcastHandoff(
 	}
 
 	// 6. Capacity — width + depth. Width covers N new children in one shot
-	//    (§6.5); depth covers `source.depth + 1 ≤ maxDepth`.
-	const project = await deps.store.getProject(source.projectId, tenantId)
-	if (!project) {
-		throw new Error(`Project ${source.projectId} not found`)
-	}
+	//    (§6.5); depth covers `source.depth + 1 ≤ maxDepth`. The same read is
+	//    the archive gate: a closed workspace takes no broadcast either.
+	const project = await requireOpenProject(deps.store, source.projectId, tenantId, 'broadcast')
 	await deps.capacity.validateWidth(
 		source.id,
 		assignments.length,

package/src/session/handoff/single.ts

@@ -20,6 +20,7 @@
  *   9. Emit `onCommitted` with the new version.
  */
 
+import { requireOpenProject } from '../../manager/project/lifecycle.js'
 import type { ThreadManager } from '../../manager/thread/lifecycle.js'
 import type { SessionId, TenantId } from '../../types/ids/index.js'
 import type { Session } from '../../types/session/entity.js'
@@ -145,10 +146,10 @@ export async function executeSingleHandoff(
 	//    ownership of the same session. Width only applies to broadcast).
 	//    For `single` we still validate depth to future-proof should the flow
 	//    evolve into a branch variant.
-	const project = await deps.store.getProject(source.projectId, tenantId)
-	if (!project) {
-		throw new Error(`Project ${source.projectId} not found`)
-	}
+	//    The same read is the archive gate: an archived workspace accepts no
+	//    handoff either. Transferring ownership into a closed workspace would
+	//    be a new owner for work its project says is finished.
+	const project = await requireOpenProject(deps.store, source.projectId, tenantId, 'handoff')
 	await deps.capacity.validateDepth(source.id, project.config.maxDelegationDepth, tenantId)
 
 	// 5. CAS → `idle → locked`.

package/src/session/migration/__tests__/a-migrated-project-id-is-an-id.test.ts

@@ -0,0 +1,92 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { ProjectIdSchema } from '../../../contracts/schemas.js'
+import { FilesystemMigrationError } from '../errors.js'
+import { DefaultFilesystemMigrator, NOOP_FILESYSTEM_MIGRATION_SINK } from '../filesystem.js'
+
+/**
+ * The v0.2.0 migration is the only place a `ProjectId` is built from data
+ * instead of generated: it takes a legacy `thd_*` folder name off disk and
+ * mints `prj_legacy_<that name>`. The only check the name had passed was
+ * `startsWith('thd_')`, so a folder named `thd_Not An Id` produced a project
+ * id that satisfies the TypeScript type, is written into the new layout as a
+ * directory name, and is rejected by the SDK's own `ProjectIdSchema`.
+ *
+ * It refuses such a folder rather than skipping it. Skipping would leave that
+ * thread's runs on disk and unaddressable, write the completion marker anyway,
+ * and return `kind: 'migrated'` with the thread missing from the list — the
+ * failure shape this codebase keeps meeting, where the run did not fail, it
+ * succeeded while quietly not doing what it said.
+ */
+
+const dirs: string[] = []
+afterEach(async () => {
+	await Promise.all(dirs.map((d) => rm(d, { recursive: true, force: true })))
+	dirs.length = 0
+})
+
+async function seed(root: string, folder: string): Promise<void> {
+	const dir = join(root, 'threads', folder, 'runs', 'run_seed')
+	await mkdir(dir, { recursive: true })
+	await writeFile(join(dir, 'run.json'), JSON.stringify({ id: 'run_seed' }), 'utf-8')
+}
+
+async function newRoot(tag: string): Promise<string> {
+	const root = await mkdtemp(join(tmpdir(), `namzu-mig-${tag}-`))
+	dirs.push(root)
+	return root
+}
+
+describe('the migration only mints project ids that are project ids', () => {
+	it('refuses a legacy folder whose name is not a thread id, and names it', async () => {
+		const root = await newRoot('badname')
+		await seed(root, 'thd_Not An Id')
+
+		const error = await new DefaultFilesystemMigrator(NOOP_FILESYSTEM_MIGRATION_SINK)
+			.migrate(root)
+			.then(
+				() => null,
+				(e: unknown) => e,
+			)
+
+		expect(error).toBeInstanceOf(FilesystemMigrationError)
+		const details = (error as FilesystemMigrationError).details
+		expect(details.op).toBe('validate_thread_id')
+		// An operator has to be able to go and look at the folder.
+		expect(details.path).toContain('thd_Not An Id')
+	})
+
+	it('refuses rather than reporting a migration that left a thread behind', async () => {
+		// The seductive alternative is `continue`. This pins why it is wrong:
+		// the good thread would migrate, the result would say `migrated`, and
+		// the bad one would be absent from `migratedThreads` with no error.
+		const root = await newRoot('partial')
+		await seed(root, 'thd_a1b2c3d4e5f6')
+		await seed(root, 'thd_UPPER')
+
+		await expect(
+			new DefaultFilesystemMigrator(NOOP_FILESYSTEM_MIGRATION_SINK).migrate(root),
+		).rejects.toBeInstanceOf(FilesystemMigrationError)
+	})
+
+	it('still migrates a folder whose name is a thread id, and the id it mints validates', async () => {
+		// The guard must refuse only what is not an id. A guard that refuses
+		// everything passes the two cases above and breaks migration entirely.
+		const root = await newRoot('good')
+		await seed(root, 'thd_a1b2c3d4e5f6')
+
+		const result = await new DefaultFilesystemMigrator(NOOP_FILESYSTEM_MIGRATION_SINK).migrate(root)
+
+		expect(result.kind).toBe('migrated')
+		expect(result.migratedThreads.map((m) => m.legacyThreadId)).toEqual(['thd_a1b2c3d4e5f6'])
+		for (const { newProjectId } of result.migratedThreads) {
+			expect({ newProjectId, ok: ProjectIdSchema.safeParse(newProjectId).success }).toEqual({
+				newProjectId,
+				ok: true,
+			})
+		}
+	})
+})

package/src/session/migration/filesystem.ts

@@ -248,6 +248,34 @@ export class DefaultFilesystemMigrator implements FilesystemMigrator {
 
 				const legacyThreadId = entry
 				const suffix = legacyThreadId.slice('thd_'.length)
+
+				// The suffix comes off the filesystem, and `startsWith('thd_')`
+				// is the only thing it has passed. A folder named `thd_Not An
+				// Id` mints `prj_legacy_Not An Id`: structurally a `ProjectId`,
+				// accepted by no validator, and now a directory name in the new
+				// layout. The migration is the one place a project id is built
+				// from data rather than generated, so it is the one place the
+				// id contract has to be checked.
+				//
+				// (Not a containment check — it cannot be one. `readdir` yields
+				// path components, which hold no separator, and `..` is never
+				// among them; `prj_legacy_..` is a literal name, not a parent
+				// reference. Nothing here can leave the root.)
+				//
+				// It refuses rather than skipping. A skipped folder is a legacy
+				// thread whose runs are still on disk and no longer addressable,
+				// with nothing in the result saying so — and the marker would be
+				// written as if the migration were complete.
+				if (!/^[a-z0-9]+$/.test(suffix)) {
+					throw new FilesystemMigrationError({
+						op: 'validate_thread_id',
+						path: join(threadsDir, legacyThreadId),
+						cause: new Error(
+							`Legacy thread folder '${legacyThreadId}' is not a thread id: expected 'thd_' followed by lowercase alphanumerics. It is refused rather than migrated because the name is used as a directory name.`,
+						),
+					})
+				}
+
 				const newProjectId = `${LEGACY_DEFAULT_PROJECT_PREFIX}${suffix}` as ProjectId
 
 				const legacyRunsDir = join(threadsDir, legacyThreadId, 'runs')

package/src/store/session/__tests__/a-workspace-can-be-configured.test.ts

@@ -0,0 +1,210 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { TenantIsolationError } from '../../../session/errors.js'
+import type { TenantId } from '../../../types/ids/index.js'
+import type { SessionStore } from '../../../types/session/store.js'
+import { DiskSessionStore } from '../disk.js'
+import { InMemorySessionStore } from '../memory.js'
+
+/**
+ * Every project in existence ran at depth 4 and width 8.
+ *
+ * The config was hardcoded identically in both stores, `CreateProjectParams`
+ * was `{tenantId, name}`, and there was no `updateProject`. So a tenant with
+ * several workspaces could not give them different limits — which is most of
+ * what having several workspaces is for.
+ *
+ * Only the two fields something READS are settable. `ProjectConfig` declares
+ * eight; five enforcement sites read two of them. Exposing the other six would
+ * make dead fields easier to set, and a host that configures a retention policy
+ * and gets no error believes retention is on. `maxInterventionDepth` looks like
+ * an exception and is not: its three apparent readers are all comments.
+ *
+ * Both stores are driven by the same cases, because a reference implementation
+ * that disagrees with the durable one is worse than having only one.
+ */
+
+const TENANT = 'tnt_cfg' as TenantId
+const OTHER = 'tnt_other' as TenantId
+
+const dirs: string[] = []
+afterEach(async () => {
+	await Promise.all(dirs.map((d) => rm(d, { recursive: true, force: true })))
+	dirs.length = 0
+})
+
+async function diskStore(): Promise<SessionStore> {
+	const rootDir = await mkdtemp(join(tmpdir(), 'namzu-cfg-'))
+	dirs.push(rootDir)
+	return new DiskSessionStore({ rootDir })
+}
+
+const IMPLEMENTATIONS: ReadonlyArray<readonly [string, () => Promise<SessionStore>]> = [
+	['in memory', async () => new InMemorySessionStore()],
+	['on disk', diskStore],
+]
+
+describe.each(IMPLEMENTATIONS)('a workspace carries its own limits (%s)', (_name, build) => {
+	it('takes the limits it was created with', async () => {
+		const store = await build()
+
+		const project = await store.createProject(
+			{ tenantId: TENANT, name: 'w', config: { maxDelegationDepth: 2, maxDelegationWidth: 3 } },
+			TENANT,
+		)
+
+		expect(project.config.maxDelegationDepth).toBe(2)
+		expect(project.config.maxDelegationWidth).toBe(3)
+	})
+
+	it('keeps the defaults for anything not given', async () => {
+		const store = await build()
+
+		const project = await store.createProject(
+			{ tenantId: TENANT, name: 'w', config: { maxDelegationDepth: 2 } },
+			TENANT,
+		)
+
+		expect(project.config.maxDelegationDepth).toBe(2)
+		expect(project.config.maxDelegationWidth).toBe(8)
+	})
+
+	it('lets two workspaces of one tenant differ, which is the point', async () => {
+		const store = await build()
+
+		const narrow = await store.createProject(
+			{ tenantId: TENANT, name: 'narrow', config: { maxDelegationWidth: 1 } },
+			TENANT,
+		)
+		const wide = await store.createProject(
+			{ tenantId: TENANT, name: 'wide', config: { maxDelegationWidth: 16 } },
+			TENANT,
+		)
+
+		expect(narrow.config.maxDelegationWidth).toBe(1)
+		expect(wide.config.maxDelegationWidth).toBe(16)
+	})
+
+	it('changes a limit after the fact, and the change is readable back', async () => {
+		const store = await build()
+		const project = await store.createProject({ tenantId: TENANT, name: 'w' }, TENANT)
+
+		await store.updateProject?.(project.id, { maxDelegationWidth: 12 }, TENANT)
+
+		expect((await store.getProject(project.id, TENANT))?.config.maxDelegationWidth).toBe(12)
+	})
+
+	it('leaves a limit it was not asked to change', async () => {
+		// Per field, not whole-value: raising the width says nothing about the
+		// depth, and resetting it would be an answer to a question nobody asked.
+		const store = await build()
+		const project = await store.createProject(
+			{ tenantId: TENANT, name: 'w', config: { maxDelegationDepth: 2 } },
+			TENANT,
+		)
+
+		await store.updateProject?.(project.id, { maxDelegationWidth: 12 }, TENANT)
+
+		const reloaded = await store.getProject(project.id, TENANT)
+		expect(reloaded?.config.maxDelegationDepth).toBe(2)
+		expect(reloaded?.config.maxDelegationWidth).toBe(12)
+	})
+
+	it('treats an explicitly undefined limit as "leave it", not "clear it"', async () => {
+		// The case the per-field guard exists for, and the one a plain spread
+		// gets wrong: `{...config}` with an explicit `undefined` key writes the
+		// undefined through and erases a limit the caller never mentioned. A
+		// caller building an update object programmatically produces exactly
+		// this shape.
+		const store = await build()
+		const project = await store.createProject(
+			{ tenantId: TENANT, name: 'w', config: { maxDelegationDepth: 3 } },
+			TENANT,
+		)
+
+		await store.updateProject?.(
+			project.id,
+			{ maxDelegationDepth: undefined, maxDelegationWidth: 12 },
+			TENANT,
+		)
+
+		const reloaded = await store.getProject(project.id, TENANT)
+		expect(reloaded?.config.maxDelegationDepth).toBe(3)
+		expect(reloaded?.config.maxDelegationWidth).toBe(12)
+	})
+
+	it('lists what this tenant owns, oldest first', async () => {
+		// Eight, spaced past the millisecond `createdAt` is measured in, so this
+		// is an assertion about age rather than about the tie-break below. With
+		// the sort dropped the disk store returns them in directory order, which
+		// is id-ascending — it matches creation order once in 8!.
+		const store = await build()
+		const created = []
+		for (const name of ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']) {
+			created.push(await store.createProject({ tenantId: TENANT, name }, TENANT))
+			await new Promise((resolve) => setTimeout(resolve, 2))
+		}
+
+		const listed = await store.listProjects?.(TENANT)
+
+		expect(listed?.map((p) => p.id)).toEqual(created.map((p) => p.id))
+	})
+
+	it('stays a total order when several are created in the same millisecond', async () => {
+		// CI found this and a slower machine could not: on a fast filesystem
+		// projects routinely share a `createdAt`, and "oldest first" alone left
+		// the rest to `readdir`. A caller paginating a listing that reorders
+		// under it sees the same project twice and never sees another.
+		const store = await build()
+		for (const name of ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']) {
+			await store.createProject({ tenantId: TENANT, name }, TENANT)
+		}
+
+		const listed = (await store.listProjects?.(TENANT)) ?? []
+
+		expect(listed).toHaveLength(8)
+		for (let i = 1; i < listed.length; i++) {
+			const before = listed[i - 1]
+			const after = listed[i]
+			if (before === undefined || after === undefined) throw new Error('short listing')
+			const olderFirst = before.createdAt.getTime() < after.createdAt.getTime()
+			const tieByName =
+				before.createdAt.getTime() === after.createdAt.getTime() && before.id < after.id
+			expect({ pair: [before.name, after.name], ordered: olderFirst || tieByName }).toEqual({
+				pair: [before.name, after.name],
+				ordered: true,
+			})
+		}
+	})
+
+	it('omits another tenant from the listing rather than refusing', async () => {
+		// A listing is a question about what you own. Refusing would confirm
+		// that somebody else's project is there, which is the leak the tenant
+		// boundary exists to prevent.
+		const store = await build()
+		await store.createProject({ tenantId: TENANT, name: 'mine' }, TENANT)
+		await store.createProject({ tenantId: OTHER, name: 'theirs' }, OTHER)
+
+		expect((await store.listProjects?.(TENANT))?.map((p) => p.name)).toEqual(['mine'])
+	})
+
+	it('refuses to reconfigure another tenant project', async () => {
+		// Reading a listing is a question; writing to somebody else's workspace
+		// is not, so this one throws.
+		const store = await build()
+		const theirs = await store.createProject({ tenantId: OTHER, name: 'theirs' }, OTHER)
+
+		await expect(
+			store.updateProject?.(theirs.id, { maxDelegationWidth: 99 }, TENANT),
+		).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+
+	it('returns null for a project that does not exist', async () => {
+		const store = await build()
+
+		expect(await store.updateProject?.('prj_missing' as never, {}, TENANT)).toBeNull()
+	})
+})