@namzu/sdk 0.1.8 → 0.3.0

package/src/session/__tests__/integration/summary-materialization-e2e.test.ts

@@ -0,0 +1,239 @@
+/**
+ * Integration — SessionSummaryMaterializer + SessionStore atomic transition,
+ * plus the crash-recovery path.
+ *
+ * Covers roadmap §5 invariants: §8.1 (summary kernel-owned, no agent-callable
+ * emission surface), §8.1 atomic with terminal transition, recovery path
+ * when the status-flip lost to a mid-flight crash. `SessionAlreadySummarizedError`
+ * on concurrent re-materialize.
+ *
+ * The kernel-ownership assertion is expressed both structurally (the
+ * `materializedBy: 'kernel'` brand on the persisted record) and by routing
+ * every successful materialize through the Materializer — no test below calls
+ * `store.recordSummary` directly, and the compile-time type narrows the
+ * argument to `& { materializedBy: 'kernel' }` so an agent-constructed payload
+ * would fail typecheck (not just runtime validation).
+ */
+
+import { describe, expect, it } from 'vitest'
+import { InMemorySessionStore } from '../../../store/session/memory.js'
+import type { SessionId } from '../../../types/ids/index.js'
+import type { SummaryId, ThreadId } from '../../../types/session/ids.js'
+import { SessionSummaryMaterializer } from '../../summary/materialize.js'
+import { SessionAlreadySummarizedError } from '../../summary/ref.js'
+import { DEFAULT_TENANT, agentActor } from './_fixtures.js'
+
+const TEST_THREAD_ID = 'thd_test' as ThreadId
+
+async function seedActive(store: InMemorySessionStore) {
+	const project = await store.createProject(
+		{ tenantId: DEFAULT_TENANT, name: 'summary' },
+		DEFAULT_TENANT,
+	)
+	const session = await store.createSession(
+		{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor('agt_worker') },
+		DEFAULT_TENANT,
+	)
+	await store.updateSession({ ...session, status: 'active' }, DEFAULT_TENANT)
+	return { project, session: { ...session, status: 'active' as const } }
+}
+
+function makeGen(): () => SummaryId {
+	let n = 0
+	return () => `sum_materialize_${++n}` as SummaryId
+}
+
+describe('Integration — summary materialization E2E', () => {
+	it('Materializer writes summary + flips session active→idle atomically', async () => {
+		const store = new InMemorySessionStore()
+		const { session } = await seedActive(store)
+		const materializer = new SessionSummaryMaterializer({
+			store,
+			generateSummaryId: makeGen(),
+		})
+
+		const summary = await materializer.materialize({
+			sessionId: session.id,
+			tenantId: DEFAULT_TENANT,
+			finalOutcome: { status: 'succeeded' },
+			agentSummary: 'done',
+			declaredDeliverables: [],
+			keyDecisions: [],
+		})
+
+		// Persisted.
+		const stored = await store.getSummary(session.id, DEFAULT_TENANT)
+		expect(stored?.id).toBe(summary.id)
+		expect(stored?.materializedBy).toBe('kernel')
+
+		// Status atomically flipped.
+		const reloaded = await store.getSession(session.id, DEFAULT_TENANT)
+		expect(reloaded?.status).toBe('idle')
+	})
+
+	it('§8.1 atomicity invariant: no external observer sees terminal without summary', async () => {
+		// With InMemorySessionStore the two writes happen inside a single Map
+		// method call — there is no observable mid-state. We assert by reading
+		// both resources immediately after a single awaited materialize: the
+		// terminal status and the summary are visible together.
+		const store = new InMemorySessionStore()
+		const { session } = await seedActive(store)
+		const materializer = new SessionSummaryMaterializer({
+			store,
+			generateSummaryId: makeGen(),
+		})
+
+		await materializer.materialize({
+			sessionId: session.id,
+			tenantId: DEFAULT_TENANT,
+			finalOutcome: { status: 'succeeded' },
+			agentSummary: '',
+			declaredDeliverables: [],
+			keyDecisions: [],
+		})
+
+		const [finalSession, finalSummary] = await Promise.all([
+			store.getSession(session.id, DEFAULT_TENANT),
+			store.getSummary(session.id, DEFAULT_TENANT),
+		])
+		// Atomic pairing: idle status AND persisted summary present together.
+		expect(finalSession?.status).toBe('idle')
+		expect(finalSummary).not.toBeNull()
+	})
+
+	it('concurrent re-materialize rejects with SessionAlreadySummarizedError', async () => {
+		const store = new InMemorySessionStore()
+		const { session } = await seedActive(store)
+		const materializer = new SessionSummaryMaterializer({
+			store,
+			generateSummaryId: makeGen(),
+		})
+
+		await materializer.materialize({
+			sessionId: session.id,
+			tenantId: DEFAULT_TENANT,
+			finalOutcome: { status: 'succeeded' },
+			agentSummary: 'first',
+			declaredDeliverables: [],
+			keyDecisions: [],
+		})
+
+		await expect(
+			materializer.materialize({
+				sessionId: session.id,
+				tenantId: DEFAULT_TENANT,
+				finalOutcome: { status: 'succeeded' },
+				agentSummary: 'second',
+				declaredDeliverables: [],
+				keyDecisions: [],
+			}),
+		).rejects.toBeInstanceOf(SessionAlreadySummarizedError)
+	})
+
+	it('crash recovery: summary persisted + session still active → recover() replays idempotently', async () => {
+		const store = new InMemorySessionStore()
+		const { session } = await seedActive(store)
+		const materializer = new SessionSummaryMaterializer({
+			store,
+			generateSummaryId: makeGen(),
+		})
+
+		// Materialize once (happy path writes both). Then simulate a crash by
+		// forcing the session status back to `active` while the summary record
+		// stays intact — mimicking summary.json landing but session.json being
+		// lost to a mid-write power failure (see session/summary/materialize.ts
+		// `recover()` docs).
+		await materializer.materialize({
+			sessionId: session.id,
+			tenantId: DEFAULT_TENANT,
+			finalOutcome: { status: 'succeeded' },
+			agentSummary: '',
+			declaredDeliverables: [],
+			keyDecisions: [],
+		})
+		const mid = await store.getSession(session.id, DEFAULT_TENANT)
+		if (!mid) throw new Error('mid session missing')
+		await store.updateSession({ ...mid, status: 'active' }, DEFAULT_TENANT)
+
+		// Recovery call re-triggers the store's flip path without minting a
+		// new summary id.
+		const recovered = await materializer.recover(session.id, DEFAULT_TENANT)
+		expect(recovered).not.toBeNull()
+
+		const reloaded = await store.getSession(session.id, DEFAULT_TENANT)
+		expect(reloaded?.status).toBe('idle')
+
+		// Second recover call with session already idle: still idempotent.
+		const recovered2 = await materializer.recover(session.id, DEFAULT_TENANT)
+		expect(recovered2?.id).toBe(recovered?.id)
+		const reloaded2 = await store.getSession(session.id, DEFAULT_TENANT)
+		expect(reloaded2?.status).toBe('idle')
+	})
+
+	it('agent cannot construct SessionSummaryRef directly: recordSummary rejects non-kernel payload', async () => {
+		// The SessionStore contract narrows `recordSummary` to
+		// `SessionSummaryRef & { materializedBy: 'kernel' }`. Agents cannot
+		// type-construct a brand literal of `'kernel'` without going through
+		// the Materializer (see session/summary/ref.ts module header). Even
+		// attempting to cast into the shape and call directly would bypass
+		// the materialize ordering (status-check, length-check,
+		// already-exists guard). This test exercises the runtime guard: a
+		// second kernel-branded record for an already-summarized session
+		// rejects with SessionAlreadySummarizedError.
+		const store = new InMemorySessionStore()
+		const { session } = await seedActive(store)
+		const materializer = new SessionSummaryMaterializer({
+			store,
+			generateSummaryId: makeGen(),
+		})
+		await materializer.materialize({
+			sessionId: session.id,
+			tenantId: DEFAULT_TENANT,
+			finalOutcome: { status: 'succeeded' },
+			agentSummary: '',
+			declaredDeliverables: [],
+			keyDecisions: [],
+		})
+
+		// Direct call with a fabricated "kernel" ref payload — rejected
+		// because a summary already exists (store guard). The kernel-brand
+		// check at the type layer prevents naive agent-side construction; the
+		// runtime guard here catches store-level re-entry (materialize goes
+		// through the same path).
+		await expect(
+			store.recordSummary(
+				{
+					id: 'sum_fake' as SummaryId,
+					sessionRef: session.id,
+					tenantId: DEFAULT_TENANT,
+					outcome: { status: 'succeeded' },
+					deliverables: [],
+					agentSummary: 'forged',
+					keyDecisions: [],
+					at: new Date(),
+					materializedBy: 'kernel',
+				},
+				DEFAULT_TENANT,
+			),
+		).rejects.toBeInstanceOf(SessionAlreadySummarizedError)
+	})
+
+	it('missing session: materialize throws a not-found error', async () => {
+		const store = new InMemorySessionStore()
+		const materializer = new SessionSummaryMaterializer({
+			store,
+			generateSummaryId: makeGen(),
+		})
+
+		await expect(
+			materializer.materialize({
+				sessionId: 'ses_never' as SessionId,
+				tenantId: DEFAULT_TENANT,
+				finalOutcome: { status: 'succeeded' },
+				agentSummary: '',
+				declaredDeliverables: [],
+				keyDecisions: [],
+			}),
+		).rejects.toThrow(/not found/)
+	})
+})

package/src/session/__tests__/integration/tenant-isolation.test.ts

@@ -0,0 +1,292 @@
+/**
+ * Integration — multi-tenant isolation enforcement at every store accessor
+ * and cross-store boundary.
+ *
+ * Covers roadmap §5 invariants: §12 `tenantId` denormalized on every
+ * persisted entity, §12.2 cross-tenant rejection (TenantIsolationError at
+ * every accessor), broadcast handoff rejecting when recipient tenant
+ * differs.
+ *
+ * Every assertion here crosses a kernel boundary with a mismatched tenantId
+ * and checks that the SDK rejects rather than silently re-scoping.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { InMemorySessionStore } from '../../../store/session/memory.js'
+import { createUserMessage } from '../../../types/message/index.js'
+import type { ProjectId, SubSessionId, SummaryId, ThreadId } from '../../../types/session/ids.js'
+import { TenantIsolationError } from '../../errors.js'
+import { DEFAULT_TENANT, OTHER_TENANT, agentActor, userActor } from './_fixtures.js'
+
+const TEST_THREAD_ID = 'thd_test' as ThreadId
+
+async function seedTenantAResources() {
+	const store = new InMemorySessionStore()
+	const project = await store.createProject(
+		{ tenantId: DEFAULT_TENANT, name: 'tenA' },
+		DEFAULT_TENANT,
+	)
+	const parent = await store.createSession(
+		{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: userActor('usr_a') },
+		DEFAULT_TENANT,
+	)
+	const child = await store.createSession(
+		{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor('agt_a') },
+		DEFAULT_TENANT,
+	)
+	const sub = await store.createSubSession(
+		{
+			parentSessionId: parent.id,
+			childSessionId: child.id,
+			kind: 'agent_spawn',
+			spawnedBy: userActor('usr_a'),
+		},
+		DEFAULT_TENANT,
+	)
+	return { store, project, parent, child, sub }
+}
+
+describe('Integration — tenant isolation', () => {
+	it('getProject with wrong tenantId → TenantIsolationError', async () => {
+		const { store, project } = await seedTenantAResources()
+		await expect(store.getProject(project.id, OTHER_TENANT)).rejects.toBeInstanceOf(
+			TenantIsolationError,
+		)
+	})
+
+	it('getSession with wrong tenantId → TenantIsolationError', async () => {
+		const { store, parent } = await seedTenantAResources()
+		await expect(store.getSession(parent.id, OTHER_TENANT)).rejects.toBeInstanceOf(
+			TenantIsolationError,
+		)
+	})
+
+	it('getSubSession with wrong tenantId → TenantIsolationError', async () => {
+		const { store, sub } = await seedTenantAResources()
+		await expect(store.getSubSession(sub.id, OTHER_TENANT)).rejects.toBeInstanceOf(
+			TenantIsolationError,
+		)
+	})
+
+	it('updateSession with wrong tenantId → TenantIsolationError', async () => {
+		const { store, parent } = await seedTenantAResources()
+		await expect(
+			store.updateSession({ ...parent, status: 'active' }, OTHER_TENANT),
+		).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+
+	it('createSubSession from a session owned by another tenant → TenantIsolationError', async () => {
+		const { store, parent, child } = await seedTenantAResources()
+		await expect(
+			store.createSubSession(
+				{
+					parentSessionId: parent.id,
+					childSessionId: child.id,
+					kind: 'agent_spawn',
+					spawnedBy: userActor('usr_intruder', OTHER_TENANT),
+				},
+				OTHER_TENANT,
+			),
+		).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+
+	it('appendMessage with wrong tenantId → TenantIsolationError', async () => {
+		const { store, child } = await seedTenantAResources()
+		await expect(
+			store.appendMessage(child.id, createUserMessage('intruder'), OTHER_TENANT),
+		).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+
+	it('loadSessionMessages cross-tenant → TenantIsolationError', async () => {
+		const { store, child } = await seedTenantAResources()
+		await store.appendMessage(child.id, createUserMessage('legit'), DEFAULT_TENANT)
+		await expect(store.loadSessionMessages(child.id, OTHER_TENANT)).rejects.toBeInstanceOf(
+			TenantIsolationError,
+		)
+	})
+
+	it('loadMessages cross-tenant → TenantIsolationError', async () => {
+		const { store, child } = await seedTenantAResources()
+		await store.appendMessage(child.id, createUserMessage('legit'), DEFAULT_TENANT)
+		await expect(store.loadMessages(child.id, OTHER_TENANT)).rejects.toBeInstanceOf(
+			TenantIsolationError,
+		)
+	})
+
+	it('drill(sessionId, OTHER_TENANT) on an existing session → TenantIsolationError (pattern doc §12.2 hard reject)', async () => {
+		const { store, parent } = await seedTenantAResources()
+		// Existing session owned by DEFAULT_TENANT, caller supplies OTHER_TENANT.
+		// Pattern doc §12 specifies hard reject — no silent null masking.
+		await expect(store.drill(parent.id, OTHER_TENANT)).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+
+	it('drill on a missing session returns null (deny-by-default surface without leaking tenant info)', async () => {
+		const { store } = await seedTenantAResources()
+		const view = await store.drill(
+			'ses_never_existed' as Parameters<typeof store.drill>[0],
+			OTHER_TENANT,
+		)
+		// Missing session for the queried tenant returns null (Convention #5).
+		// The tenant check is conditional on the resource existing; absent
+		// resources don't leak tenant info via a thrown isolation error.
+		expect(view).toBeNull()
+	})
+
+	it('getChildren cross-tenant → TenantIsolationError', async () => {
+		const { store, parent } = await seedTenantAResources()
+		await expect(store.getChildren(parent.id, OTHER_TENANT)).rejects.toBeInstanceOf(
+			TenantIsolationError,
+		)
+	})
+
+	it('getAncestry cross-tenant → TenantIsolationError', async () => {
+		const { store, parent } = await seedTenantAResources()
+		await expect(store.getAncestry(parent.id, OTHER_TENANT)).rejects.toBeInstanceOf(
+			TenantIsolationError,
+		)
+	})
+
+	it('recordSummary with mismatched payload tenantId → TenantIsolationError', async () => {
+		const { store, parent } = await seedTenantAResources()
+		// Attempt to record a summary whose payload tenantId differs from the
+		// caller tenantId — runtime guard rejects.
+		await expect(
+			store.recordSummary(
+				{
+					id: 'sum_intruder' as SummaryId,
+					sessionRef: parent.id,
+					tenantId: OTHER_TENANT,
+					outcome: { status: 'succeeded' },
+					deliverables: [],
+					agentSummary: '',
+					keyDecisions: [],
+					at: new Date(),
+					materializedBy: 'kernel',
+				},
+				DEFAULT_TENANT,
+			),
+		).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+
+	it('getSummary cross-tenant → TenantIsolationError when a summary exists', async () => {
+		const { store, parent } = await seedTenantAResources()
+		await store.updateSession({ ...parent, status: 'active' }, DEFAULT_TENANT)
+		await store.recordSummary(
+			{
+				id: 'sum_ok' as SummaryId,
+				sessionRef: parent.id,
+				tenantId: DEFAULT_TENANT,
+				outcome: { status: 'succeeded' },
+				deliverables: [],
+				agentSummary: '',
+				keyDecisions: [],
+				at: new Date(),
+				materializedBy: 'kernel',
+			},
+			DEFAULT_TENANT,
+		)
+
+		await expect(store.getSummary(parent.id, OTHER_TENANT)).rejects.toBeInstanceOf(
+			TenantIsolationError,
+		)
+	})
+
+	it('createProject with params.tenantId ≠ caller tenantId → TenantIsolationError (deep check)', async () => {
+		const store = new InMemorySessionStore()
+		await expect(
+			store.createProject({ tenantId: OTHER_TENANT, name: 'mismatch' }, DEFAULT_TENANT),
+		).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+
+	it('createSession with project owned by another tenant → TenantIsolationError', async () => {
+		const { store, project } = await seedTenantAResources()
+		await expect(
+			store.createSession(
+				{
+					threadId: TEST_THREAD_ID,
+					projectId: project.id,
+					currentActor: userActor('usr_intruder', OTHER_TENANT),
+				},
+				OTHER_TENANT,
+			),
+		).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+
+	it('tenant denormalization: Session, SubSession records carry tenantId explicitly', async () => {
+		const { store, parent, sub } = await seedTenantAResources()
+		const parentReloaded = await store.getSession(parent.id, DEFAULT_TENANT)
+		expect(parentReloaded?.tenantId).toBe(DEFAULT_TENANT)
+
+		// SubSession record itself does not carry tenantId in its shape — the
+		// isolation is stored via the parent record tuple (subSessions map:
+		// { tenantId, subSession }). Getting it via the correct tenant succeeds;
+		// via the wrong tenant rejects — already covered above. This test just
+		// confirms the successful access path.
+		const reloaded = await store.getSubSession(sub.id, DEFAULT_TENANT)
+		expect(reloaded?.id).toBe(sub.id)
+	})
+
+	it('broadcast-style cross-tenant attempt: cannot createSubSession linking parents owned by another tenant', async () => {
+		// Pattern doc §12 requires recipient & source to share tenant. The
+		// store-level guard here catches the shape violation — createSubSession
+		// refuses to link parent/child across tenants.
+		const { store, parent } = await seedTenantAResources()
+
+		// Create a session in OTHER_TENANT with its own project.
+		const otherProject = await store.createProject(
+			{ tenantId: OTHER_TENANT, name: 'other' },
+			OTHER_TENANT,
+		)
+		const otherChild = await store.createSession(
+			{
+				threadId: TEST_THREAD_ID,
+				projectId: otherProject.id,
+				currentActor: userActor('usr_other', OTHER_TENANT),
+			},
+			OTHER_TENANT,
+		)
+
+		await expect(
+			store.createSubSession(
+				{
+					parentSessionId: parent.id, // DEFAULT_TENANT
+					childSessionId: otherChild.id, // OTHER_TENANT
+					kind: 'agent_spawn',
+					spawnedBy: userActor('usr_a'),
+				},
+				DEFAULT_TENANT,
+			),
+		).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+
+	it('deleteSubSession cross-tenant → TenantIsolationError', async () => {
+		const { store, sub } = await seedTenantAResources()
+		await expect(store.deleteSubSession(sub.id, OTHER_TENANT)).rejects.toBeInstanceOf(
+			TenantIsolationError,
+		)
+	})
+
+	it('deleteSession cross-tenant → TenantIsolationError', async () => {
+		const { store } = await seedTenantAResources()
+		// Parent has a sub-session attached → deleteSession would fail anyway,
+		// but the tenant guard fires first. Use a standalone session.
+		const project: ProjectId = (
+			await store.createProject({ tenantId: DEFAULT_TENANT, name: 'del' }, DEFAULT_TENANT)
+		).id
+		const lonely = await store.createSession(
+			{ threadId: TEST_THREAD_ID, projectId: project, currentActor: userActor('usr_lonely') },
+			DEFAULT_TENANT,
+		)
+		await expect(store.deleteSession(lonely.id, OTHER_TENANT)).rejects.toBeInstanceOf(
+			TenantIsolationError,
+		)
+	})
+
+	it('missing sub-session returns null for correct tenant (not a leak channel)', async () => {
+		const { store } = await seedTenantAResources()
+		// Missing id via correct tenant → null, not thrown. Confirms the
+		// missing-resource fast-path doesn't pre-empt the tenant check.
+		const missing = await store.getSubSession('sub_never_existed' as SubSessionId, DEFAULT_TENANT)
+		expect(missing).toBeNull()
+	})
+})

package/src/session/errors.ts

@@ -0,0 +1,159 @@
+/**
+ * Typed errors for the session hierarchy module.
+ *
+ * See session-hierarchy.md §12.2 (cross-tenant rejection), §6.2 (workspace
+ * backend operation failures), §4.5 (intervention DAG). Each error carries a
+ * structured `details` payload so consumers can route without string parsing
+ * (Convention #5: deny-by-default, fail fast).
+ */
+
+import type { SessionId, TenantId } from '../types/ids/index.js'
+import type { ThreadId } from '../types/session/ids.js'
+import type { SessionStatus } from './hierarchy/session.js'
+import type { WorkspaceBackendKind } from './workspace/driver.js'
+
+/**
+ * Raised by {@link SessionStore} accessors when the supplied {@link TenantId}
+ * does not match the tenant owning the target resource. Convention #17:
+ * cross-tenant access is a hard error at the kernel boundary — there is no
+ * escape hatch. See session-hierarchy.md §12.2.
+ */
+export class TenantIsolationError extends Error {
+	readonly details: {
+		requested: TenantId
+		resource: string
+	}
+
+	constructor(details: { requested: TenantId; resource: string }) {
+		super(`Tenant isolation violation: ${details.requested} accessed ${details.resource}`)
+		this.name = 'TenantIsolationError'
+		this.details = details
+	}
+}
+
+/**
+ * Raised by {@link SessionStore.getAncestry} / {@link SessionStore.drill}
+ * when walking parent sub-session links encounters a revisit. Indicates store
+ * corruption — the write path enforces acyclicity (session-hierarchy.md §4.5).
+ */
+export class AncestryCycleError extends Error {
+	readonly details: {
+		sessionId: SessionId
+		cyclePath: readonly SessionId[]
+	}
+
+	constructor(details: { sessionId: SessionId; cyclePath: readonly SessionId[] }) {
+		super(
+			`Ancestry cycle detected starting at ${details.sessionId}: ${details.cyclePath.join(' -> ')}`,
+		)
+		this.name = 'AncestryCycleError'
+		this.details = details
+	}
+}
+
+/**
+ * Raised by {@link WorkspaceBackendDriver} implementations on any I/O or
+ * invariant failure. Wraps the underlying cause; callers can match on
+ * `details.op` + `details.kind` for routing (Convention #0: no silent
+ * fallbacks — surface the failure). See session-hierarchy.md §6.2 / §7.
+ */
+export class WorkspaceBackendError extends Error {
+	readonly details: {
+		op: string
+		kind: WorkspaceBackendKind
+		cause?: unknown
+	}
+
+	constructor(details: { op: string; kind: WorkspaceBackendKind; cause?: unknown }) {
+		super(`Workspace backend ${details.kind} failed on ${details.op}`)
+		this.name = 'WorkspaceBackendError'
+		this.details = details
+	}
+}
+
+/**
+ * Raised by {@link import('../types/thread/store.js').ThreadStore.updateThread}
+ * when the supplied {@link Thread.ownerVersion} does not match the persisted
+ * record. The caller must re-read via `getThread`, re-apply its intended
+ * mutation on top of the fresh record, and retry. Mirrors the Session
+ * handoff CAS pattern (§6.1).
+ */
+export class StaleThreadError extends Error {
+	readonly details: {
+		threadId: ThreadId
+		expectedVersion: number
+		actualVersion: number
+	}
+
+	constructor(details: { threadId: ThreadId; expectedVersion: number; actualVersion: number }) {
+		super(
+			`Stale Thread ${details.threadId}: expected ownerVersion=${details.expectedVersion}, actual=${details.actualVersion}`,
+		)
+		this.name = 'StaleThreadError'
+		this.details = details
+	}
+}
+
+/**
+ * Raised by the spawn path (and any caller that enforces the open-thread
+ * precondition) when a Thread is in `'archived'` state and would-be mutations
+ * require it to be `'open'`. Convention #5: deny-by-default — archival is a
+ * hard read-only boundary.
+ */
+export class ThreadClosedError extends Error {
+	readonly details: {
+		threadId: ThreadId
+		op: string
+	}
+
+	constructor(details: { threadId: ThreadId; op: string }) {
+		super(`Thread ${details.threadId} is archived; operation '${details.op}' rejected`)
+		this.name = 'ThreadClosedError'
+		this.details = details
+	}
+}
+
+/**
+ * Raised by {@link import('../manager/thread/lifecycle.js').ThreadManager.archive}
+ * and `.delete` when the Thread's session-presence precondition is violated:
+ *
+ * - `op: 'archive'` — at least one Session under the Thread is in a
+ *   non-terminal state (`active | locked | awaiting_hitl | awaiting_merge`).
+ *   The caller must first quiesce those sessions (let them reach `idle`,
+ *   `failed`, or `archived`) before flipping the Thread to archived.
+ * - `op: 'delete'` — the Thread still has at least one attached Session.
+ *   Callers must either archive + tombstone those sessions (`deleteSession`)
+ *   before calling `deleteThread`, or accept that deletion is not yet safe.
+ *
+ * `blockingSessions` carries the first {@link THREAD_NOT_EMPTY_SAMPLE_LIMIT}
+ * offenders with their current status so operator tooling can surface an
+ * actionable list without unbounded error payloads on large threads.
+ * `totalBlockingSessions` holds the full count even when the sample is
+ * truncated. Convention #5: deny-by-default — no implicit cascade, no silent
+ * no-op.
+ */
+export const THREAD_NOT_EMPTY_SAMPLE_LIMIT = 50
+
+export class ThreadNotEmptyError extends Error {
+	readonly details: {
+		threadId: ThreadId
+		tenantId: TenantId
+		op: 'archive' | 'delete'
+		blockingSessions: ReadonlyArray<{ sessionId: SessionId; status: SessionStatus }>
+		totalBlockingSessions: number
+	}
+
+	constructor(details: {
+		threadId: ThreadId
+		tenantId: TenantId
+		op: 'archive' | 'delete'
+		blockingSessions: ReadonlyArray<{ sessionId: SessionId; status: SessionStatus }>
+		totalBlockingSessions: number
+	}) {
+		super(
+			`Thread ${details.threadId} ${details.op} blocked: ${details.totalBlockingSessions} session(s) still attached`,
+		)
+		this.name = 'ThreadNotEmptyError'
+		this.details = details
+	}
+}