@namzu/sdk 0.2.0 → 0.3.0

package/src/store/session/__tests__/disk.test.ts

@@ -23,7 +23,7 @@ function agentActor(tenantId: TenantId): ActorRef {
 async function seed(store: DiskSessionStore, tenantId: TenantId) {
 	const project = await store.createProject({ tenantId, name: 'p1' }, tenantId)
 	const session = await store.createSession(
-		{ projectId: project.id, currentActor: userActor(tenantId) },
+		{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: userActor(tenantId) },
 		tenantId,
 	)
 	return { project, session }
@@ -45,7 +45,7 @@ describe('DiskSessionStore', () => {
 	it('writes the canonical directory layout (projects/.../sessions/.../subsessions)', async () => {
 		const { project, session } = await seed(store, tenantA)
 		const child = await store.createSession(
-			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 		const sub = await store.createSubSession(
@@ -143,7 +143,7 @@ describe('DiskSessionStore', () => {
 	it('drill returns children and ancestry after a cold reload', async () => {
 		const { project, session: root } = await seed(store, tenantA)
 		const child = await store.createSession(
-			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 		await store.createSubSession(
@@ -278,7 +278,7 @@ describe('DiskSessionStore', () => {
 	it('deleteSession rejects if sub-sessions are still attached', async () => {
 		const { project, session: root } = await seed(store, tenantA)
 		const child = await store.createSession(
-			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 		await store.createSubSession(
@@ -297,7 +297,7 @@ describe('DiskSessionStore', () => {
 	it('deleteSubSession removes the sub-session directory and is idempotent', async () => {
 		const { project, session: root } = await seed(store, tenantA)
 		const child = await store.createSession(
-			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 		const sub = await store.createSubSession(
@@ -338,9 +338,60 @@ describe('DiskSessionStore', () => {
 
 		await expect(store.getSummary(session.id, tenantB)).rejects.toBeInstanceOf(TenantIsolationError)
 	})
+
+	describe('listSessions(threadId, tenantId)', () => {
+		const threadX = 'thd_x' as ThreadId
+		const threadY = 'thd_y' as ThreadId
+
+		it('returns [] when the projects root is empty', async () => {
+			// Fresh temp root — no projects directory yet.
+			expect(await store.listSessions(threadX, tenantA)).toEqual([])
+		})
+
+		it('filters by threadId and tenant; orders by createdAt ascending', async () => {
+			const project = await store.createProject({ tenantId: tenantA, name: 'p' }, tenantA)
+
+			const first = await store.createSession(
+				{ threadId: threadX, projectId: project.id, currentActor: userActor(tenantA) },
+				tenantA,
+			)
+			await new Promise((r) => setTimeout(r, 2))
+			const second = await store.createSession(
+				{ threadId: threadX, projectId: project.id, currentActor: userActor(tenantA) },
+				tenantA,
+			)
+			// Same project, different thread — must not appear.
+			await store.createSession(
+				{ threadId: threadY, projectId: project.id, currentActor: userActor(tenantA) },
+				tenantA,
+			)
+
+			const listed = await store.listSessions(threadX, tenantA)
+			expect(listed.map((s) => s.id)).toEqual([first.id, second.id])
+		})
+
+		it('skips cross-tenant sessions even when threadId matches', async () => {
+			const pA = await store.createProject({ tenantId: tenantA, name: 'pa' }, tenantA)
+			const pB = await store.createProject({ tenantId: tenantB, name: 'pb' }, tenantB)
+
+			const own = await store.createSession(
+				{ threadId: threadX, projectId: pA.id, currentActor: userActor(tenantA) },
+				tenantA,
+			)
+			await store.createSession(
+				{ threadId: threadX, projectId: pB.id, currentActor: userActor(tenantB) },
+				tenantB,
+			)
+
+			const listed = await store.listSessions(threadX, tenantA)
+			expect(listed.map((s) => s.id)).toEqual([own.id])
+		})
+	})
 })
 
 import type { SessionSummaryRef } from '../../../session/summary/ref.js'
 // Import after use so tests are self-contained w.r.t. types we already use.
 import type { SessionId } from '../../../types/ids/index.js'
-import type { SummaryId } from '../../../types/session/ids.js'
+import type { SummaryId, ThreadId } from '../../../types/session/ids.js'
+
+const TEST_THREAD_ID = 'thd_test' as ThreadId

package/src/store/session/__tests__/memory.test.ts

@@ -4,8 +4,11 @@ import type { ActorRef } from '../../../session/hierarchy/actor.js'
 import type { SubSession } from '../../../session/hierarchy/sub-session.js'
 import type { AgentId, SessionId, TenantId, UserId } from '../../../types/ids/index.js'
 import { createUserMessage } from '../../../types/message/index.js'
+import type { ThreadId } from '../../../types/session/ids.js'
 import { InMemorySessionStore } from '../memory.js'
 
+const TEST_THREAD_ID = 'thd_test' as ThreadId
+
 function userActor(tenantId: TenantId): ActorRef {
 	return { kind: 'user', userId: 'usr_a' as UserId, tenantId }
 }
@@ -25,7 +28,7 @@ const tenantB = 'tnt_beta' as TenantId
 async function seed(store: InMemorySessionStore, tenantId: TenantId) {
 	const project = await store.createProject({ tenantId, name: 'p1' }, tenantId)
 	const session = await store.createSession(
-		{ projectId: project.id, currentActor: userActor(tenantId) },
+		{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: userActor(tenantId) },
 		tenantId,
 	)
 	return { project, session }
@@ -84,7 +87,7 @@ describe('InMemorySessionStore', () => {
 
 		// Create a child session + link via sub-session.
 		const child = await store.createSession(
-			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 		const sub = await store.createSubSession(
@@ -139,7 +142,7 @@ describe('InMemorySessionStore', () => {
 		const { project: pB, session: rootB } = await seed(store, tenantB)
 
 		const childA = await store.createSession(
-			{ projectId: pA.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: pA.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 		await store.createSubSession(
@@ -153,7 +156,7 @@ describe('InMemorySessionStore', () => {
 		)
 
 		const childB = await store.createSession(
-			{ projectId: pB.id, currentActor: agentActor(tenantB) },
+			{ threadId: TEST_THREAD_ID, projectId: pB.id, currentActor: agentActor(tenantB) },
 			tenantB,
 		)
 		await store.createSubSession(
@@ -186,7 +189,7 @@ describe('InMemorySessionStore', () => {
 		const store = new InMemorySessionStore()
 		const { project, session: rootA } = await seed(store, tenantA)
 		const sessionB = await store.createSession(
-			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 
@@ -235,7 +238,7 @@ describe('InMemorySessionStore', () => {
 		const store = new InMemorySessionStore()
 		const { project, session: root } = await seed(store, tenantA)
 		const child = await store.createSession(
-			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 		await store.createSubSession(
@@ -265,7 +268,7 @@ describe('InMemorySessionStore', () => {
 		const store = new InMemorySessionStore()
 		const { project, session: root } = await seed(store, tenantA)
 		const child = await store.createSession(
-			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 		const sub = await store.createSubSession(
@@ -293,11 +296,11 @@ describe('InMemorySessionStore', () => {
 		const { project, session: root } = await seed(store, tenantA)
 
 		const c1 = await store.createSession(
-			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 		const c2 = await store.createSession(
-			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 
@@ -324,4 +327,76 @@ describe('InMemorySessionStore', () => {
 		const ids = children.map((s: SubSession) => s.id)
 		expect(new Set(ids)).toEqual(new Set([s1.id, s2.id]))
 	})
+
+	describe('listSessions(threadId, tenantId)', () => {
+		const threadX = 'thd_x' as ThreadId
+		const threadY = 'thd_y' as ThreadId
+
+		it('returns [] when the thread has no sessions', async () => {
+			const store = new InMemorySessionStore()
+			expect(await store.listSessions(threadX, tenantA)).toEqual([])
+		})
+
+		it('returns only sessions whose threadId matches, for the caller tenant', async () => {
+			const store = new InMemorySessionStore()
+			const project = await store.createProject({ tenantId: tenantA, name: 'p' }, tenantA)
+
+			const sX1 = await store.createSession(
+				{ threadId: threadX, projectId: project.id, currentActor: userActor(tenantA) },
+				tenantA,
+			)
+			const sX2 = await store.createSession(
+				{ threadId: threadX, projectId: project.id, currentActor: userActor(tenantA) },
+				tenantA,
+			)
+			// Same project, different thread — must not appear.
+			await store.createSession(
+				{ threadId: threadY, projectId: project.id, currentActor: userActor(tenantA) },
+				tenantA,
+			)
+
+			const listed = await store.listSessions(threadX, tenantA)
+			expect(listed.map((s) => s.id).sort()).toEqual([sX1.id, sX2.id].sort())
+		})
+
+		it('orders results by createdAt ascending', async () => {
+			const store = new InMemorySessionStore()
+			const project = await store.createProject({ tenantId: tenantA, name: 'p' }, tenantA)
+
+			const first = await store.createSession(
+				{ threadId: threadX, projectId: project.id, currentActor: userActor(tenantA) },
+				tenantA,
+			)
+			// Nudge clock for deterministic ordering; in-memory uses `new Date()`.
+			await new Promise((r) => setTimeout(r, 2))
+			const second = await store.createSession(
+				{ threadId: threadX, projectId: project.id, currentActor: userActor(tenantA) },
+				tenantA,
+			)
+
+			const listed = await store.listSessions(threadX, tenantA)
+			expect(listed.map((s) => s.id)).toEqual([first.id, second.id])
+		})
+
+		it('silently skips cross-tenant sessions sharing the same threadId', async () => {
+			// Thread ids are tenant-scoped in practice but nothing at the type
+			// level prevents the same string identifier being reused across
+			// tenants — the listing must filter by tenant without erroring.
+			const store = new InMemorySessionStore()
+			const pA = await store.createProject({ tenantId: tenantA, name: 'pa' }, tenantA)
+			const pB = await store.createProject({ tenantId: tenantB, name: 'pb' }, tenantB)
+
+			const own = await store.createSession(
+				{ threadId: threadX, projectId: pA.id, currentActor: userActor(tenantA) },
+				tenantA,
+			)
+			await store.createSession(
+				{ threadId: threadX, projectId: pB.id, currentActor: userActor(tenantB) },
+				tenantB,
+			)
+
+			const listed = await store.listSessions(threadX, tenantA)
+			expect(listed.map((s) => s.id)).toEqual([own.id])
+		})
+	})
 })

package/src/store/session/disk.ts

@@ -45,7 +45,7 @@ import type {
 } from '../../session/summary/ref.js'
 import type { MessageId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { Message } 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 type {
 	CreateProjectParams,
 	CreateSessionParams,
@@ -82,6 +82,7 @@ interface PersistedProject {
 
 interface PersistedSession {
 	id: SessionId
+	threadId: ThreadId
 	projectId: ProjectId
 	tenantId: TenantId
 	status: Session['status']
@@ -221,6 +222,7 @@ export class DiskSessionStore implements SessionStore {
 		const now = new Date()
 		const session: Session = {
 			id: generateSessionId(),
+			threadId: params.threadId,
 			projectId: params.projectId,
 			tenantId,
 			status: 'idle',
@@ -251,6 +253,58 @@ export class DiskSessionStore implements SessionStore {
 		return deserializeSession(raw)
 	}
 
+	async listSessions(threadId: ThreadId, tenantId: TenantId): Promise<readonly Session[]> {
+		// Walk projects/*/sessions/* and filter on the persisted record. Sessions
+		// don't live under a thread-scoped path in the current layout — the
+		// denormalized `threadId` on every session.json is the authority. Matches
+		// DiskThreadStore.listThreads in scan semantics.
+		//
+		// Cost: O(all sessions across all projects in the root) per call. The
+		// MVP disk store prioritizes simplicity over index freshness, matching
+		// `buildLinkageView` / `locateSession` which use the same pattern. A
+		// production driver would maintain a threadId → sessionIds secondary
+		// index populated on createSession / deleteSession. Acceptable for
+		// ThreadManager archive/delete today because those operations are
+		// admin-initiated and infrequent.
+		const projectsDir = join(this.rootDir, 'projects')
+		let projectDirs: string[]
+		try {
+			projectDirs = await readdir(projectsDir)
+		} catch (err) {
+			const code = (err as NodeJS.ErrnoException).code
+			if (code === 'ENOENT') return []
+			throw err
+		}
+
+		const results: Session[] = []
+		for (const rawProject of projectDirs) {
+			if (!rawProject.startsWith('prj_')) continue
+			const sessionsRoot = join(projectsDir, rawProject, 'sessions')
+			let sessionDirs: string[]
+			try {
+				sessionDirs = await readdir(sessionsRoot)
+			} catch {
+				continue
+			}
+			for (const rawSessionId of sessionDirs) {
+				if (!rawSessionId.startsWith('ses_')) continue
+				const path = join(sessionsRoot, rawSessionId)
+				const raw = await readJson<PersistedSession>(join(path, 'session.json'))
+				if (!raw) continue
+				if (raw.tenantId !== tenantId) continue
+				if (raw.threadId !== threadId) continue
+				results.push(deserializeSession(raw))
+				this.sessionIndex.set(raw.id, {
+					sessionId: raw.id,
+					projectId: rawProject as ProjectId,
+					path,
+				})
+			}
+		}
+		results.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())
+		return results
+	}
+
 	async updateSession(session: Session, tenantId: TenantId): Promise<void> {
 		const located = await this.locateSession(session.id)
 		if (!located) {
@@ -785,6 +839,7 @@ function deserializeProject(p: PersistedProject): Project {
 function serializeSession(s: Session): PersistedSession {
 	return {
 		id: s.id,
+		threadId: s.threadId,
 		projectId: s.projectId,
 		tenantId: s.tenantId,
 		status: s.status,
@@ -800,6 +855,7 @@ function serializeSession(s: Session): PersistedSession {
 function deserializeSession(s: PersistedSession): Session {
 	return {
 		id: s.id,
+		threadId: s.threadId,
 		projectId: s.projectId,
 		tenantId: s.tenantId,
 		status: s.status,

package/src/store/session/index.ts

@@ -1,9 +1,8 @@
 // Sub-barrel for the session-scoped persistence module (Convention #4).
 //
-// `SessionStore` replaces the legacy `ConversationStore`; messages are scoped
-// to a `SessionId` (not a bare thread) and every accessor carries explicit
-// `TenantId` per session-hierarchy.md §12.1. Concrete implementations live
-// in sibling files; re-export them here so consumers import via
+// Messages are scoped to a `SessionId` and every accessor carries explicit
+// `TenantId` (Convention #17). Concrete implementations live in sibling
+// files; re-export them here so consumers import via
 // `../store/session/index.js`.
 
 export { InMemorySessionStore } from './memory.js'

package/src/store/session/memory.ts

@@ -16,7 +16,7 @@ import { SessionAlreadySummarizedError } from '../../session/summary/ref.js'
 import type { SessionSummaryRef } from '../../session/summary/ref.js'
 import type { MessageId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
-import type { ProjectId, SubSessionId } from '../../types/session/ids.js'
+import type { ProjectId, SubSessionId, ThreadId } from '../../types/session/ids.js'
 import type {
 	CreateProjectParams,
 	CreateSessionParams,
@@ -118,6 +118,7 @@ export class InMemorySessionStore implements SessionStore {
 		const now = new Date()
 		const session: Session = {
 			id: generateSessionId(),
+			threadId: params.threadId,
 			projectId: params.projectId,
 			tenantId,
 			status: 'idle',
@@ -139,6 +140,17 @@ export class InMemorySessionStore implements SessionStore {
 		return record.session
 	}
 
+	async listSessions(threadId: ThreadId, tenantId: TenantId): Promise<readonly Session[]> {
+		const matches: Session[] = []
+		for (const record of this.sessions.values()) {
+			if (record.tenantId !== tenantId) continue
+			if (record.session.threadId !== threadId) continue
+			matches.push(record.session)
+		}
+		matches.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())
+		return matches
+	}
+
 	async updateSession(session: Session, tenantId: TenantId): Promise<void> {
 		const record = this.sessions.get(session.id)
 		if (!record) {

package/src/store/thread/disk.ts

@@ -0,0 +1,261 @@
+/**
+ * DiskThreadStore — filesystem-backed implementation of {@link ThreadStore}.
+ *
+ * Every mutation is write-tmp-rename (Convention #8). Layout uses the Phase 2
+ * intermediate shape:
+ *
+ *   {rootDir}/projects/{projectId}/threads/{threadId}/
+ *     thread.json
+ *
+ * Sessions stay under `projects/{projectId}/sessions/{sessionId}/...` rather
+ * than nesting under `threads/{threadId}/` — the denormalized `threadId` on
+ * each session record (Phase 2.4 decision) makes thread-scoped queries
+ * addressable without path-level nesting, and keeps Project-scoped consumers
+ * (handoff, retention, archival) a single-directory scan. Phase 6 collapses
+ * `projects/{projectId}/` to `.namzu/` as part of `namzu init` folder binding.
+ *
+ * Tenant scoping is enforced through the JSON payload (`tenantId` field on
+ * every record), not the path — cross-tenant reads reject with
+ * {@link TenantIsolationError} (Convention #17).
+ */
+
+import { mkdir, readFile, readdir, rename, rm, unlink, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { StaleThreadError, TenantIsolationError } from '../../session/errors.js'
+import type { Thread, ThreadStatus } from '../../session/hierarchy/thread.js'
+import type { TenantId } from '../../types/ids/index.js'
+import type { ProjectId, ThreadId } from '../../types/session/ids.js'
+import type { CreateThreadParams, ThreadStore } from '../../types/thread/store.js'
+import { generateThreadId } from '../../utils/id.js'
+
+/** Config for {@link DiskThreadStore}. `rootDir` is absolute. */
+export interface DiskThreadStoreConfig {
+	rootDir: string
+}
+
+interface PersistedThread {
+	id: ThreadId
+	projectId: ProjectId
+	tenantId: TenantId
+	title: string
+	status: ThreadStatus
+	ownerVersion: number
+	createdAt: string
+	updatedAt: string
+}
+
+/** Index of threadId → (projectId, path). Lazy; populated on create / lookup. */
+interface ThreadIndexEntry {
+	threadId: ThreadId
+	projectId: ProjectId
+	path: string
+}
+
+export class DiskThreadStore implements ThreadStore {
+	private readonly rootDir: string
+	private readonly threadIndex = new Map<ThreadId, ThreadIndexEntry>()
+
+	constructor(config: DiskThreadStoreConfig) {
+		this.rootDir = config.rootDir
+	}
+
+	async createThread(params: CreateThreadParams, tenantId: TenantId): Promise<Thread> {
+		const now = new Date()
+		const thread: Thread = {
+			id: generateThreadId(),
+			projectId: params.projectId,
+			tenantId,
+			title: params.title,
+			status: 'open',
+			ownerVersion: 0,
+			createdAt: now,
+			updatedAt: now,
+		}
+		const dir = join(this.rootDir, 'projects', params.projectId, 'threads', thread.id)
+		await mkdir(dir, { recursive: true })
+		await atomicWriteJson(join(dir, 'thread.json'), serializeThread(thread))
+		this.threadIndex.set(thread.id, {
+			threadId: thread.id,
+			projectId: params.projectId,
+			path: dir,
+		})
+		return thread
+	}
+
+	async getThread(threadId: ThreadId, tenantId: TenantId): Promise<Thread | null> {
+		const located = await this.locateThread(threadId)
+		if (!located) return null
+		const raw = await readJson<PersistedThread>(join(located.path, 'thread.json'))
+		if (!raw) return null
+		this.assertTenant(raw.tenantId, tenantId, `thread(${threadId})`)
+		return deserializeThread(raw)
+	}
+
+	async updateThread(thread: Thread, tenantId: TenantId): Promise<void> {
+		if (thread.tenantId !== tenantId) {
+			throw new TenantIsolationError({
+				requested: tenantId,
+				resource: `thread(${thread.id}) payload`,
+			})
+		}
+		const located = await this.locateThread(thread.id)
+		if (!located) {
+			throw new Error(`Thread ${thread.id} not found`)
+		}
+		const existing = await readJson<PersistedThread>(join(located.path, 'thread.json'))
+		if (!existing) {
+			throw new Error(`Thread ${thread.id} not found`)
+		}
+		this.assertTenant(existing.tenantId, tenantId, `thread(${thread.id})`)
+
+		// CAS on ownerVersion. On mismatch, caller must re-read + re-apply +
+		// retry. No silent overwrite (Convention #0).
+		if (thread.ownerVersion !== existing.ownerVersion) {
+			throw new StaleThreadError({
+				threadId: thread.id,
+				expectedVersion: thread.ownerVersion,
+				actualVersion: existing.ownerVersion,
+			})
+		}
+
+		const updated: Thread = {
+			...thread,
+			ownerVersion: existing.ownerVersion + 1,
+			updatedAt: new Date(),
+		}
+		await atomicWriteJson(join(located.path, 'thread.json'), serializeThread(updated))
+	}
+
+	async deleteThread(threadId: ThreadId, tenantId: TenantId): Promise<void> {
+		const located = await this.locateThread(threadId)
+		if (!located) return // Idempotent: missing = no-op.
+		const existing = await readJson<PersistedThread>(join(located.path, 'thread.json'))
+		if (!existing) return
+		this.assertTenant(existing.tenantId, tenantId, `thread(${threadId})`)
+
+		// The store does NOT enforce "no attached sessions" here — that is a
+		// cross-store precondition owned by ThreadManager. This keeps the
+		// boundary clean; ThreadStore has no awareness of SessionStore layout.
+		await rm(located.path, { recursive: true, force: true })
+		this.threadIndex.delete(threadId)
+	}
+
+	async listThreads(projectId: ProjectId, tenantId: TenantId): Promise<readonly Thread[]> {
+		const threadsDir = join(this.rootDir, 'projects', projectId, 'threads')
+		let entries: string[]
+		try {
+			entries = await readdir(threadsDir)
+		} catch (err) {
+			const code = (err as NodeJS.ErrnoException).code
+			if (code === 'ENOENT') return []
+			throw err
+		}
+
+		const results: Thread[] = []
+		for (const entry of entries) {
+			if (!entry.startsWith('thd_')) continue
+			const path = join(threadsDir, entry)
+			const raw = await readJson<PersistedThread>(join(path, 'thread.json'))
+			if (!raw) continue
+			// Cross-tenant records in the same directory are skipped silently —
+			// the listing is scoped to the caller's tenant. Mismatch is not an
+			// isolation violation because the caller never requested the record.
+			if (raw.tenantId !== tenantId) continue
+			results.push(deserializeThread(raw))
+			this.threadIndex.set(raw.id, { threadId: raw.id, projectId, path })
+		}
+		results.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())
+		return results
+	}
+
+	private async locateThread(threadId: ThreadId): Promise<ThreadIndexEntry | null> {
+		const cached = this.threadIndex.get(threadId)
+		if (cached) return cached
+
+		// Walk projects/* looking for the thread dir. Cost is bounded by number
+		// of projects (usually 1) × number of threads per project.
+		const projectsDir = join(this.rootDir, 'projects')
+		let projectDirs: string[]
+		try {
+			projectDirs = await readdir(projectsDir)
+		} catch (err) {
+			const code = (err as NodeJS.ErrnoException).code
+			if (code === 'ENOENT') return null
+			throw err
+		}
+
+		for (const rawProject of projectDirs) {
+			if (!rawProject.startsWith('prj_')) continue
+			const threadPath = join(projectsDir, rawProject, 'threads', threadId)
+			const raw = await readJson<PersistedThread>(join(threadPath, 'thread.json'))
+			if (raw?.id === threadId) {
+				const entry: ThreadIndexEntry = {
+					threadId,
+					projectId: rawProject as ProjectId,
+					path: threadPath,
+				}
+				this.threadIndex.set(threadId, entry)
+				return entry
+			}
+		}
+		return null
+	}
+
+	private assertTenant(owning: TenantId, requested: TenantId, resource: string): void {
+		if (owning !== requested) {
+			throw new TenantIsolationError({ requested, resource })
+		}
+	}
+}
+
+// Serialization -----------------------------------------------------------
+
+function serializeThread(thread: Thread): PersistedThread {
+	return {
+		id: thread.id,
+		projectId: thread.projectId,
+		tenantId: thread.tenantId,
+		title: thread.title,
+		status: thread.status,
+		ownerVersion: thread.ownerVersion,
+		createdAt: thread.createdAt.toISOString(),
+		updatedAt: thread.updatedAt.toISOString(),
+	}
+}
+
+function deserializeThread(raw: PersistedThread): Thread {
+	return {
+		id: raw.id,
+		projectId: raw.projectId,
+		tenantId: raw.tenantId,
+		title: raw.title,
+		status: raw.status,
+		ownerVersion: raw.ownerVersion,
+		createdAt: new Date(raw.createdAt),
+		updatedAt: new Date(raw.updatedAt),
+	}
+}
+
+// FS helpers -----------------------------------------------------------------
+
+async function readJson<T>(path: string): Promise<T | null> {
+	try {
+		const raw = await readFile(path, 'utf-8')
+		return JSON.parse(raw) as T
+	} catch (err) {
+		const code = (err as NodeJS.ErrnoException).code
+		if (code === 'ENOENT') return null
+		throw err
+	}
+}
+
+async function atomicWriteJson(filePath: string, value: unknown): Promise<void> {
+	const tempPath = `${filePath}.tmp`
+	try {
+		await writeFile(tempPath, JSON.stringify(value, null, 2), 'utf-8')
+		await rename(tempPath, filePath)
+	} catch (err) {
+		await unlink(tempPath).catch(() => undefined)
+		throw err
+	}
+}

package/src/store/thread/index.ts

@@ -0,0 +1,7 @@
+// Sub-barrel for the Thread persistence module (Convention #4).
+// Concrete implementations live in sibling files; re-export them here so
+// consumers import via `../store/thread/index.js`.
+
+export { InMemoryThreadStore } from './memory.js'
+export { DiskThreadStore } from './disk.js'
+export type { DiskThreadStoreConfig } from './disk.js'