@namzu/sdk 0.2.0 → 0.3.0

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

@@ -14,10 +14,12 @@
 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 } from '../../../types/session/ids.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(
@@ -25,11 +27,11 @@ async function seedTenantAResources() {
 		DEFAULT_TENANT,
 	)
 	const parent = await store.createSession(
-		{ projectId: project.id, currentActor: userActor('usr_a') },
+		{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: userActor('usr_a') },
 		DEFAULT_TENANT,
 	)
 	const child = await store.createSession(
-		{ projectId: project.id, currentActor: agentActor('agt_a') },
+		{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor('agt_a') },
 		DEFAULT_TENANT,
 	)
 	const sub = await store.createSubSession(
@@ -200,7 +202,11 @@ describe('Integration — tenant isolation', () => {
 		const { store, project } = await seedTenantAResources()
 		await expect(
 			store.createSession(
-				{ projectId: project.id, currentActor: userActor('usr_intruder', OTHER_TENANT) },
+				{
+					threadId: TEST_THREAD_ID,
+					projectId: project.id,
+					currentActor: userActor('usr_intruder', OTHER_TENANT),
+				},
 				OTHER_TENANT,
 			),
 		).rejects.toBeInstanceOf(TenantIsolationError)
@@ -232,7 +238,11 @@ describe('Integration — tenant isolation', () => {
 			OTHER_TENANT,
 		)
 		const otherChild = await store.createSession(
-			{ projectId: otherProject.id, currentActor: userActor('usr_other', OTHER_TENANT) },
+			{
+				threadId: TEST_THREAD_ID,
+				projectId: otherProject.id,
+				currentActor: userActor('usr_other', OTHER_TENANT),
+			},
 			OTHER_TENANT,
 		)
 
@@ -264,7 +274,7 @@ describe('Integration — tenant isolation', () => {
 			await store.createProject({ tenantId: DEFAULT_TENANT, name: 'del' }, DEFAULT_TENANT)
 		).id
 		const lonely = await store.createSession(
-			{ projectId: project, currentActor: userActor('usr_lonely') },
+			{ threadId: TEST_THREAD_ID, projectId: project, currentActor: userActor('usr_lonely') },
 			DEFAULT_TENANT,
 		)
 		await expect(store.deleteSession(lonely.id, OTHER_TENANT)).rejects.toBeInstanceOf(

package/src/session/errors.ts

@@ -8,6 +8,8 @@
  */
 
 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'
 
 /**
@@ -68,3 +70,90 @@ export class WorkspaceBackendError extends Error {
 		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
+	}
+}

package/src/session/handoff/__tests__/broadcast.test.ts

@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ThreadManager } from '../../../manager/thread/lifecycle.js'
 import type { ActorRef } from '../../../session/hierarchy/actor.js'
 import {
 	type ExecFile,
@@ -7,6 +8,7 @@ import {
 } from '../../../session/workspace/git-worktree.js'
 import { WorkspaceBackendRegistry } from '../../../session/workspace/registry.js'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
+import { InMemoryThreadStore } from '../../../store/thread/memory.js'
 import type { SessionId, TenantId, UserId } from '../../../types/ids/index.js'
 import type { ProjectId } from '../../../types/session/ids.js'
 import { generateHandoffId } from '../../../utils/id.js'
@@ -56,7 +58,11 @@ interface DepsBundle {
 	events: MockedHandoffEventSink
 }
 
-function buildDeps(store: InMemorySessionStore, execOverride?: ExecFile): DepsBundle {
+function buildDeps(
+	store: InMemorySessionStore,
+	threadStore: InMemoryThreadStore,
+	execOverride?: ExecFile,
+): DepsBundle {
 	const exec: ExecFile = execOverride ? execOverride : async (_file, _args) => okExec()
 	const driver = new GitWorktreeDriver({
 		repoRoot: '/repo',
@@ -73,29 +79,36 @@ function buildDeps(store: InMemorySessionStore, execOverride?: ExecFile): DepsBu
 		onBroadcastRollback: vi.fn<(ev: HandoffBroadcastRollbackEvent) => void>(),
 	}
 
+	const threadManager = new ThreadManager({ threadStore, sessionStore: store })
 	return {
 		deps: {
 			store,
 			workspaceRegistry: registry,
 			capacity: new DefaultCapacityValidator(store),
 			events,
+			threadManager,
 		},
 		events,
 	}
 }
 
-async function seedIdle(store: InMemorySessionStore) {
+async function seedIdle(store: InMemorySessionStore, threadStore: InMemoryThreadStore) {
 	const project = await store.createProject({ tenantId: tenant, name: 'p' }, tenant)
+	const thread = await threadStore.createThread(
+		{ projectId: project.id, title: 'handoff-broadcast-test' },
+		tenant,
+	)
 	const session = await store.createSession(
-		{ projectId: project.id, currentActor: user('usr_source') },
+		{ threadId: thread.id, projectId: project.id, currentActor: user('usr_source') },
 		tenant,
 	)
-	return { project, session }
+	return { project, thread, session }
 }
 
 function buildAssignments(
 	sourceSessionId: SessionId,
 	projectId: ProjectId,
+	threadId: Awaited<ReturnType<InMemoryThreadStore['createThread']>>['id'],
 	expectedOwnerVersion: number,
 	recipients: ActorRef[],
 	broadcastId = 'bc_1',
@@ -105,6 +118,7 @@ function buildAssignments(
 		mode: 'broadcast' as const,
 		sourceSessionId,
 		tenantId: tenant,
+		threadId,
 		projectId,
 		sourceActor: user('usr_source'),
 		recipientActor,
@@ -116,16 +130,18 @@ function buildAssignments(
 
 describe('executeBroadcastHandoff', () => {
 	let store: InMemorySessionStore
+	let threadStore: InMemoryThreadStore
 
 	beforeEach(() => {
 		store = new InMemorySessionStore()
+		threadStore = new InMemoryThreadStore()
 	})
 
 	it('happy path: 3 recipients → source ends in awaiting_merge with 3 new children', async () => {
-		const { project, session } = await seedIdle(store)
-		const { deps, events } = buildDeps(store)
+		const { project, thread, session } = await seedIdle(store, threadStore)
+		const { deps, events } = buildDeps(store, threadStore)
 
-		const assignments = buildAssignments(session.id, project.id, 0, [
+		const assignments = buildAssignments(session.id, project.id, thread.id, 0, [
 			user('usr_bob'),
 			user('usr_carol'),
 			user('usr_dan'),
@@ -149,7 +165,7 @@ describe('executeBroadcastHandoff', () => {
 	})
 
 	it('rollback on mid-fan-out failure (2nd recipient worktree add fails): source reverts, rollback emits accurate partialState', async () => {
-		const { project, session } = await seedIdle(store)
+		const { project, thread, session } = await seedIdle(store, threadStore)
 
 		let addCount = 0
 		const exec: ExecFile = async (_file, args) => {
@@ -159,9 +175,9 @@ describe('executeBroadcastHandoff', () => {
 			}
 			return okExec()
 		}
-		const { deps, events } = buildDeps(store, exec)
+		const { deps, events } = buildDeps(store, threadStore, exec)
 
-		const assignments = buildAssignments(session.id, project.id, 0, [
+		const assignments = buildAssignments(session.id, project.id, thread.id, 0, [
 			user('usr_b'),
 			user('usr_c'),
 			user('usr_d'),
@@ -196,7 +212,7 @@ describe('executeBroadcastHandoff', () => {
 	})
 
 	it('rollback performs full cleanup via deleteSubSession/deleteSession (no status-flip stopgap)', async () => {
-		const { project, session } = await seedIdle(store)
+		const { project, thread, session } = await seedIdle(store, threadStore)
 
 		let addCount = 0
 		const exec: ExecFile = async (_file, args) => {
@@ -206,9 +222,12 @@ describe('executeBroadcastHandoff', () => {
 			}
 			return okExec()
 		}
-		const { deps } = buildDeps(store, exec)
+		const { deps } = buildDeps(store, threadStore, exec)
 
-		const assignments = buildAssignments(session.id, project.id, 0, [user('usr_b'), user('usr_c')])
+		const assignments = buildAssignments(session.id, project.id, thread.id, 0, [
+			user('usr_b'),
+			user('usr_c'),
+		])
 
 		await expect(executeBroadcastHandoff(deps, assignments, tenant)).rejects.toThrow()
 
@@ -224,7 +243,7 @@ describe('executeBroadcastHandoff', () => {
 	})
 
 	it('rollback idempotency: worktree dispose throwing during rollback does not bubble a secondary failure', async () => {
-		const { project, session } = await seedIdle(store)
+		const { project, thread, session } = await seedIdle(store, threadStore)
 
 		let addCount = 0
 		let removeCount = 0
@@ -242,9 +261,12 @@ describe('executeBroadcastHandoff', () => {
 			}
 			return okExec()
 		}
-		const { deps, events } = buildDeps(store, exec)
+		const { deps, events } = buildDeps(store, threadStore, exec)
 
-		const assignments = buildAssignments(session.id, project.id, 0, [user('usr_b'), user('usr_c')])
+		const assignments = buildAssignments(session.id, project.id, thread.id, 0, [
+			user('usr_b'),
+			user('usr_c'),
+		])
 
 		// Outer failure is the PRIMARY one — the secondary dispose failure is
 		// swallowed. Primary wraps in WorkspaceBackendError (create op).
@@ -262,11 +284,15 @@ describe('executeBroadcastHandoff', () => {
 	})
 
 	it('dedupe: two assignments targeting same recipient → rejected pre-lock (no side effects)', async () => {
-		const { project, session } = await seedIdle(store)
-		const { deps, events } = buildDeps(store)
+		const { project, thread, session } = await seedIdle(store, threadStore)
+		const { deps, events } = buildDeps(store, threadStore)
 
 		const bob = user('usr_bob')
-		const assignments = buildAssignments(session.id, project.id, 0, [bob, bob, user('usr_dan')])
+		const assignments = buildAssignments(session.id, project.id, thread.id, 0, [
+			bob,
+			bob,
+			user('usr_dan'),
+		])
 
 		await expect(executeBroadcastHandoff(deps, assignments, tenant)).rejects.toThrow(
 			/duplicate recipient/,
@@ -281,11 +307,11 @@ describe('executeBroadcastHandoff', () => {
 	})
 
 	it('width cap: 9 recipients exceeds default maxWidth=8 → rejected before source lock', async () => {
-		const { project, session } = await seedIdle(store)
-		const { deps, events } = buildDeps(store)
+		const { project, thread, session } = await seedIdle(store, threadStore)
+		const { deps, events } = buildDeps(store, threadStore)
 
 		const recipients = Array.from({ length: 9 }, (_, i) => user(`usr_${i}`))
-		const assignments = buildAssignments(session.id, project.id, 0, recipients)
+		const assignments = buildAssignments(session.id, project.id, thread.id, 0, recipients)
 
 		await expect(executeBroadcastHandoff(deps, assignments, tenant)).rejects.toThrow(
 			/Delegation capacity exceeded/,
@@ -298,12 +324,13 @@ describe('executeBroadcastHandoff', () => {
 	})
 
 	it('concurrent broadcast on same source: second attempt rejected with HandoffVersionConflict', async () => {
-		const { project, session } = await seedIdle(store)
-		const { deps } = buildDeps(store)
+		const { project, thread, session } = await seedIdle(store, threadStore)
+		const { deps } = buildDeps(store, threadStore)
 
 		const firstAssignments = buildAssignments(
 			session.id,
 			project.id,
+			thread.id,
 			0,
 			[user('usr_b'), user('usr_c')],
 			'bc_1',
@@ -322,6 +349,7 @@ describe('executeBroadcastHandoff', () => {
 		const second = buildAssignments(
 			session.id,
 			project.id,
+			thread.id,
 			0, // stale — actual is 1
 			[user('usr_d'), user('usr_e')],
 			'bc_2',
@@ -332,16 +360,16 @@ describe('executeBroadcastHandoff', () => {
 	})
 
 	it('empty assignments → throws a descriptive error', async () => {
-		const { deps } = buildDeps(store)
+		const { deps } = buildDeps(store, threadStore)
 		await expect(executeBroadcastHandoff(deps, [], tenant)).rejects.toThrow(
 			/assignments must not be empty/,
 		)
 	})
 
 	it('single-row broadcast → rejected (caller must use executeSingleHandoff)', async () => {
-		const { project, session } = await seedIdle(store)
-		const { deps } = buildDeps(store)
-		const assignments = buildAssignments(session.id, project.id, 0, [user('usr_b')])
+		const { project, thread, session } = await seedIdle(store, threadStore)
+		const { deps } = buildDeps(store, threadStore)
+		const assignments = buildAssignments(session.id, project.id, thread.id, 0, [user('usr_b')])
 
 		await expect(executeBroadcastHandoff(deps, assignments, tenant)).rejects.toThrow(
 			/single-recipient handoffs must use executeSingleHandoff/,

package/src/session/handoff/__tests__/capacity.test.ts

@@ -1,7 +1,9 @@
 import { describe, expect, it } from 'vitest'
 import type { ActorRef } from '../../../session/hierarchy/actor.js'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
+import { InMemoryThreadStore } from '../../../store/thread/memory.js'
 import type { AgentId, SessionId, TenantId, UserId } from '../../../types/ids/index.js'
+import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
 import { DefaultCapacityValidator, DelegationCapacityExceeded } from '../capacity.js'
 
 const tenant = 'tnt_alpha' as TenantId
@@ -16,18 +18,22 @@ function agent(): ActorRef {
 
 async function seedProject(store: InMemorySessionStore) {
 	const project = await store.createProject({ tenantId: tenant, name: 'p' }, tenant)
-	const root = await store.createSession({ projectId: project.id, currentActor: user() }, tenant)
-	return { project, root }
+	const threadStore = new InMemoryThreadStore()
+	const thread = await threadStore.createThread({ projectId: project.id, title: 'default' }, tenant)
+	const root = await store.createSession(
+		{ threadId: thread.id, projectId: project.id, currentActor: user() },
+		tenant,
+	)
+	return { project, thread, root }
 }
 
 async function spawnChild(
 	store: InMemorySessionStore,
 	parentId: SessionId,
-	projectId: ReturnType<typeof String> extends never
-		? never
-		: Parameters<InMemorySessionStore['createSession']>[0]['projectId'],
+	projectId: ProjectId,
+	threadId: ThreadId,
 ): Promise<{ childId: SessionId }> {
-	const child = await store.createSession({ projectId, currentActor: user() }, tenant)
+	const child = await store.createSession({ threadId, projectId, currentActor: user() }, tenant)
 	await store.createSubSession(
 		{
 			parentSessionId: parentId,
@@ -51,11 +57,11 @@ describe('DefaultCapacityValidator', () => {
 
 	it('depth: chain of 4 (root→c1→c2→c3→c4) allows a 5th (depth 5) to pass when limit = 5', async () => {
 		const store = new InMemorySessionStore()
-		const { project, root } = await seedProject(store)
-		const c1 = await spawnChild(store, root.id, project.id)
-		const c2 = await spawnChild(store, c1.childId, project.id)
-		const c3 = await spawnChild(store, c2.childId, project.id)
-		const c4 = await spawnChild(store, c3.childId, project.id)
+		const { project, thread, root } = await seedProject(store)
+		const c1 = await spawnChild(store, root.id, project.id, thread.id)
+		const c2 = await spawnChild(store, c1.childId, project.id, thread.id)
+		const c3 = await spawnChild(store, c2.childId, project.id, thread.id)
+		const c4 = await spawnChild(store, c3.childId, project.id, thread.id)
 
 		const validator = new DefaultCapacityValidator(store)
 		// Ancestry of c4: root→c1→c2→c3→c4 = length 5. Spawning under c4 = depth 5.
@@ -64,11 +70,11 @@ describe('DefaultCapacityValidator', () => {
 
 	it('depth: over-limit throws DelegationCapacityExceeded with dimension=depth', async () => {
 		const store = new InMemorySessionStore()
-		const { project, root } = await seedProject(store)
-		const c1 = await spawnChild(store, root.id, project.id)
-		const c2 = await spawnChild(store, c1.childId, project.id)
-		const c3 = await spawnChild(store, c2.childId, project.id)
-		const c4 = await spawnChild(store, c3.childId, project.id)
+		const { project, thread, root } = await seedProject(store)
+		const c1 = await spawnChild(store, root.id, project.id, thread.id)
+		const c2 = await spawnChild(store, c1.childId, project.id, thread.id)
+		const c3 = await spawnChild(store, c2.childId, project.id, thread.id)
+		const c4 = await spawnChild(store, c3.childId, project.id, thread.id)
 
 		const validator = new DefaultCapacityValidator(store)
 		try {
@@ -94,9 +100,9 @@ describe('DefaultCapacityValidator', () => {
 
 	it('width: existing 5 + pending 3 = 8 passes exactly at the limit', async () => {
 		const store = new InMemorySessionStore()
-		const { project, root } = await seedProject(store)
+		const { project, thread, root } = await seedProject(store)
 		for (let i = 0; i < 5; i++) {
-			await spawnChild(store, root.id, project.id)
+			await spawnChild(store, root.id, project.id, thread.id)
 		}
 		const validator = new DefaultCapacityValidator(store)
 		await expect(validator.validateWidth(root.id, 3, 8, tenant)).resolves.toBeUndefined()
@@ -104,9 +110,9 @@ describe('DefaultCapacityValidator', () => {
 
 	it('width: existing 6 + pending 3 = 9 exceeds 8, throws dimension=width', async () => {
 		const store = new InMemorySessionStore()
-		const { project, root } = await seedProject(store)
+		const { project, thread, root } = await seedProject(store)
 		for (let i = 0; i < 6; i++) {
-			await spawnChild(store, root.id, project.id)
+			await spawnChild(store, root.id, project.id, thread.id)
 		}
 		const validator = new DefaultCapacityValidator(store)
 		try {