@namzu/sdk 27.1.0 → 29.0.0

package/src/store/session/memory.ts

@@ -8,13 +8,18 @@
  * (Convention #5 deny-by-default, session-hierarchy.md §12.2).
  */
 
-import { StaleProjectError, StaleSessionError, TenantIsolationError } from '../../session/errors.js'
+import {
+	ProjectRootPathTakenError,
+	StaleProjectError,
+	StaleSessionError,
+	TenantIsolationError,
+} from '../../session/errors.js'
 import { SessionAlreadySummarizedError } from '../../session/summary/errors.js'
 import type { MessageId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
 import type { Project, ProjectStatus } from '../../types/project/entity.js'
 import type { Session } from '../../types/session/entity.js'
-import type { ProjectId, SubSessionId, ThreadId } from '../../types/session/ids.js'
+import type { ProjectId, SubSessionId, TopicId } from '../../types/session/ids.js'
 import type { SessionMessage } from '../../types/session/messages.js'
 import type {
 	CreateProjectParams,
@@ -32,6 +37,7 @@ import {
 	generateSessionId,
 	generateSubSessionId,
 } from '../../utils/id.js'
+import { canonicalizePath } from './canonical-path.js'
 import { getAncestry, getChildren, orderChildren } from './linkage.js'
 import type { LinkageView } from './linkage.js'
 
@@ -83,6 +89,18 @@ export class InMemorySessionStore implements SessionStore {
 				resource: `project(name=${params.name})`,
 			})
 		}
+		// Canonicalized BEFORE the uniqueness check, not after storage. A path
+		// stored as typed makes `/tmp/p`, `/tmp/p/` and a symlink to it three
+		// records for one directory, and the check would pass every time.
+		const rootPath =
+			params.rootPath === undefined ? undefined : await canonicalizePath(params.rootPath)
+		if (rootPath !== undefined) {
+			const existing = await this.findProjectByRootPath(rootPath, tenantId)
+			if (existing) {
+				throw new ProjectRootPathTakenError({ rootPath, existingProjectId: existing.id })
+			}
+		}
+
 		const now = new Date()
 		const project: Project = {
 			id: generateProjectId(),
@@ -95,6 +113,7 @@ export class InMemorySessionStore implements SessionStore {
 			},
 			status: 'open',
 			ownerVersion: 0,
+			...(rootPath !== undefined ? { rootPath } : {}),
 			createdAt: now,
 			updatedAt: now,
 		}
@@ -102,6 +121,25 @@ export class InMemorySessionStore implements SessionStore {
 		return project
 	}
 
+	/**
+	 * Scanned rather than indexed, and that is the right call HERE and only
+	 * here: this store's projects are already a `Map` in memory, so an index
+	 * would be a second copy of the same data with a consistency problem
+	 * attached. The disk store, where a scan means opening every
+	 * `project.json`, keeps a real index.
+	 */
+	async findProjectByRootPath(rootPath: string, tenantId: TenantId): Promise<Project | null> {
+		const canonical = await canonicalizePath(rootPath)
+		for (const record of this.projects.values()) {
+			// Tenant FIRST, not as a post-filter. Two tenants may legitimately
+			// bind projects to the same path on a shared machine, and matching
+			// on path alone would hand one tenant the other's project id.
+			if (record.tenantId !== tenantId) continue
+			if (record.project.rootPath === canonical) return record.project
+		}
+		return null
+	}
+
 	async getProject(projectId: ProjectId, tenantId: TenantId): Promise<Project | null> {
 		const record = this.projects.get(projectId)
 		if (!record) return null
@@ -193,7 +231,7 @@ export class InMemorySessionStore implements SessionStore {
 		const now = new Date()
 		const session: Session = {
 			id: generateSessionId(),
-			threadId: params.threadId,
+			topicId: params.topicId,
 			projectId: params.projectId,
 			tenantId,
 			status: 'idle',
@@ -215,11 +253,11 @@ export class InMemorySessionStore implements SessionStore {
 		return record.session
 	}
 
-	async listSessions(threadId: ThreadId, tenantId: TenantId): Promise<readonly Session[]> {
+	async listSessionsByTopic(topicId: TopicId, 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
+			if (record.session.topicId !== topicId) continue
 			matches.push(record.session)
 		}
 		matches.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())

package/src/store/task/disk.ts

@@ -1,5 +1,6 @@
-import { mkdir, readFile, readdir, unlink } from 'node:fs/promises'
+import { mkdir, readdir, unlink } from 'node:fs/promises'
 import { join } from 'node:path'
+import { NAMZU } from '../../constants/telemetry/index.js'
 import type { RunId, TaskId, TenantId } from '../../types/ids/index.js'
 import type {
 	CreateTaskParams,
@@ -10,10 +11,11 @@ import type {
 	TaskStore,
 	UpdateTaskParams,
 } from '../../types/task/index.js'
-import { atomicWriteFile } from '../../utils/atomic-write.js'
 import { generateTaskId } from '../../utils/id.js'
-import { type Logger, getRootLogger } from '../../utils/logger.js'
-import { defineSchema, migrate, stamp } from '../schema.js'
+import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
+import { type Logger, resolveLogger } from '../../utils/logger.js'
+import { DiskRecordStore } from '../kv/record-store.js'
+import { defineSchema } from '../schema.js'
 
 /**
  * This store's on-disk format, versioned as a unit — which is how a
@@ -25,6 +27,24 @@ import { defineSchema, migrate, stamp } from '../schema.js'
  */
 const SCHEMA = defineSchema({ kind: 'task-store', current: 1, migrations: {} })
 
+/**
+ * Read, write and list, through the one implementation.
+ *
+ * This file used to carry its own `readFile` + `JSON.parse` + `migrate`
+ * with ENOENT collapsed to null, its own `atomicWriteJson`, and three
+ * separate `readdir` scans — the same twenty lines four stores each kept a
+ * copy of. The properties are not obvious ones (a missing file is an empty
+ * read, a record from a NEWER build is refused rather than silently
+ * downgraded, a listing needs a stable order), and every one fixed here had
+ * to be remembered into the other three.
+ *
+ * The try/catch at each call site stays. The primitive THROWS on a
+ * corrupt record; this store logs and returns null, because a single
+ * unreadable task must not make the whole list unavailable. That is a
+ * policy of this store, not of the primitive, and it belongs here.
+ */
+const records = new DiskRecordStore<Task>(SCHEMA)
+
 export interface DiskTaskStoreConfig {
 	baseDir: string
 
@@ -64,7 +84,7 @@ export class DiskTaskStore implements TaskStore {
 		this.baseDir = config.baseDir
 		this.defaultRunId = config.defaultRunId
 		this.tenantId = config.tenantId
-		this.log = (config.logger ?? getRootLogger()).child({ component: 'DiskTaskStore' })
+		this.log = resolveLogger(config.logger).child({ [SCOPE_ATTRIBUTE]: 'store/task/disk' })
 	}
 
 	private taskDir(runId: RunId): string {
@@ -111,7 +131,10 @@ export class DiskTaskStore implements TaskStore {
 	 * Duplicates are removed; each ID is locked exactly once.
 	 */
 	private async withLocks<T>(taskIds: readonly TaskId[], fn: () => Promise<T>): Promise<T> {
-		const unique = [...new Set(taskIds)].sort() as TaskId[]
+		// `new Set(readonly TaskId[])` is a `Set<TaskId>`; spreading and sorting
+		// it keeps that. The `as TaskId[]` this replaced asserted a type the
+		// expression already had.
+		const unique = [...new Set(taskIds)].sort()
 		const acquire = async (i: number): Promise<T> => {
 			if (i >= unique.length) return fn()
 			const nextId = unique[i]
@@ -134,8 +157,8 @@ export class DiskTaskStore implements TaskStore {
 				listener(event)
 			} catch (err) {
 				this.log.warn('Task event listener threw', {
-					error: err instanceof Error ? err.message : String(err),
-					eventType: event.type,
+					'exception.message': err instanceof Error ? err.message : String(err),
+					'namzu.event.type': event.type,
 				})
 			}
 		}
@@ -165,7 +188,7 @@ export class DiskTaskStore implements TaskStore {
 
 		const blockers = params.blockedBy ?? []
 		if (blockers.length === 0) {
-			await atomicWriteJson(this.taskPath(runId, taskId), task)
+			await records.write(this.taskPath(runId, taskId), task)
 		} else {
 			// Hold locks on all blockers while establishing the bidirectional edge:
 			// update each blocker's `blocks` list AND write the new task together,
@@ -175,17 +198,21 @@ export class DiskTaskStore implements TaskStore {
 					const blocker = await this.readTask(runId, blockerId)
 					if (blocker && !blocker.blocks.includes(taskId)) {
 						blocker.blocks.push(taskId)
-						await atomicWriteJson(this.taskPath(runId, blockerId), blocker)
+						await records.write(this.taskPath(runId, blockerId), blocker)
 					}
 					// If blocker is missing, we still write the new task with its
 					// blockedBy reference; the dangling reference is visible to
 					// subsequent readers rather than silently pruned.
 				}
-				await atomicWriteJson(this.taskPath(runId, taskId), task)
+				await records.write(this.taskPath(runId, taskId), task)
 			})
 		}
 
-		this.log.info('Task created', { taskId, subject: params.subject, runId })
+		this.log.info('Task created', {
+			'namzu.task.id': taskId,
+			'namzu.store.subject': params.subject,
+			[NAMZU.RUN_ID]: runId,
+		})
 		this.emit({ type: 'task.created', taskId, task, timestamp: Date.now() })
 		return task
 	}
@@ -228,7 +255,7 @@ export class DiskTaskStore implements TaskStore {
 				}
 			}
 
-			await atomicWriteJson(this.taskPath(task.runId, id), task)
+			await records.write(this.taskPath(task.runId, id), task)
 			this.emit({ type: 'task.updated', taskId: id, task, previousStatus, timestamp: Date.now() })
 			return task
 		})
@@ -264,14 +291,14 @@ export class DiskTaskStore implements TaskStore {
 				const blocker = await this.readTask(task.runId, blockerId)
 				if (blocker) {
 					blocker.blocks = blocker.blocks.filter((bid) => bid !== id)
-					await atomicWriteJson(this.taskPath(task.runId, blockerId), blocker)
+					await records.write(this.taskPath(task.runId, blockerId), blocker)
 				}
 			}
 			for (const blockedId of task.blocks) {
 				const blocked = await this.readTask(task.runId, blockedId)
 				if (blocked) {
 					blocked.blockedBy = blocked.blockedBy.filter((bid) => bid !== id)
-					await atomicWriteJson(this.taskPath(task.runId, blockedId), blocked)
+					await records.write(this.taskPath(task.runId, blockedId), blocked)
 				}
 			}
 
@@ -283,15 +310,15 @@ export class DiskTaskStore implements TaskStore {
 					this.log.error(
 						'Failed to delete task file; relations may be in a partially-updated state',
 						{
-							taskId: id,
-							error: err instanceof Error ? err.message : String(err),
+							'namzu.task.id': id,
+							'exception.message': err instanceof Error ? err.message : String(err),
 						},
 					)
 					throw err
 				}
 				// ENOENT: already gone, treat as success.
 			}
-			this.log.info('Task deleted', { taskId: id })
+			this.log.info('Task deleted', { 'namzu.task.id': id })
 			this.emit({ type: 'task.deleted', taskId: id, task, timestamp: Date.now() })
 			return true
 		})
@@ -303,13 +330,11 @@ export class DiskTaskStore implements TaskStore {
 
 		let files: string[]
 		try {
-			files = await readdir(dir)
+			files = await records.scanNames(dir, '')
 		} catch (err) {
-			const code = (err as NodeJS.ErrnoException).code
-			if (code === 'ENOENT') return []
 			this.log.warn('Failed to list task directory', {
-				dir,
-				error: err instanceof Error ? err.message : String(err),
+				'namzu.store.dir': dir,
+				'exception.message': err instanceof Error ? err.message : String(err),
 			})
 			return []
 		}
@@ -318,13 +343,12 @@ export class DiskTaskStore implements TaskStore {
 		for (const file of files) {
 			if (!file.endsWith('.json')) continue
 			try {
-				const raw = await readFile(join(dir, file), 'utf-8')
-				const task = migrate<Task>(SCHEMA, JSON.parse(raw))
-				tasks.push(task)
+				const task = await records.read(join(dir, file))
+				if (task !== null) tasks.push(task)
 			} catch (err) {
 				this.log.warn('Failed to read task file', {
-					file,
-					error: err instanceof Error ? err.message : String(err),
+					'namzu.store.file': file,
+					'exception.message': err instanceof Error ? err.message : String(err),
 				})
 			}
 		}
@@ -354,7 +378,7 @@ export class DiskTaskStore implements TaskStore {
 			task.status = 'in_progress'
 			task.startedAt = Date.now()
 
-			await atomicWriteJson(this.taskPath(task.runId, id), task)
+			await records.write(this.taskPath(task.runId, id), task)
 			this.emit({ type: 'task.claimed', taskId: id, task, timestamp: Date.now() })
 			return task
 		})
@@ -378,10 +402,10 @@ export class DiskTaskStore implements TaskStore {
 			// whole operation instead.
 			if (!blocker || !blocked) {
 				this.log.warn('block(): task disappeared before lock acquired; skipping', {
-					blockerId,
-					blockedId,
-					blockerExists: !!blocker,
-					blockedExists: !!blocked,
+					'namzu.store.blocker_id': blockerId,
+					'namzu.store.blocked_id': blockedId,
+					'namzu.store.blocker_exists': !!blocker,
+					'namzu.store.blocked_exists': !!blocked,
 				})
 				return
 			}
@@ -389,16 +413,19 @@ export class DiskTaskStore implements TaskStore {
 			let mutated = false
 			if (!blocker.blocks.includes(blockedId)) {
 				blocker.blocks.push(blockedId)
-				await atomicWriteJson(this.taskPath(blocker.runId, blockerId), blocker)
+				await records.write(this.taskPath(blocker.runId, blockerId), blocker)
 				mutated = true
 			}
 			if (!blocked.blockedBy.includes(blockerId)) {
 				blocked.blockedBy.push(blockerId)
-				await atomicWriteJson(this.taskPath(blocked.runId, blockedId), blocked)
+				await records.write(this.taskPath(blocked.runId, blockedId), blocked)
 				mutated = true
 			}
 			if (!mutated) {
-				this.log.debug('block(): edge already exists', { blockerId, blockedId })
+				this.log.debug('block(): edge already exists', {
+					'namzu.store.blocker_id': blockerId,
+					'namzu.store.blocked_id': blockedId,
+				})
 				return
 			}
 
@@ -414,12 +441,7 @@ export class DiskTaskStore implements TaskStore {
 
 	async reset(): Promise<void> {
 		const dir = this.taskDir(this.defaultRunId)
-		let files: string[]
-		try {
-			files = await readdir(dir)
-		} catch {
-			return
-		}
+		const files = await records.scanNames(dir, '')
 		for (const file of files) {
 			if (file.endsWith('.json')) {
 				await unlink(join(dir, file)).catch(() => undefined)
@@ -429,27 +451,13 @@ export class DiskTaskStore implements TaskStore {
 
 	private async readTask(runId: RunId, taskId: TaskId): Promise<Task | null> {
 		const path = this.taskPath(runId, taskId)
-		let raw: string
-		try {
-			raw = await readFile(path, 'utf-8')
-		} catch (err) {
-			const code = (err as NodeJS.ErrnoException).code
-			if (code === 'ENOENT') return null
-			this.log.warn('Failed to read task', {
-				taskId,
-				path,
-				error: err instanceof Error ? err.message : String(err),
-			})
-			return null
-		}
-
 		try {
-			return migrate<Task>(SCHEMA, JSON.parse(raw))
+			return await records.read(path)
 		} catch (err) {
 			this.log.error('Corrupt task JSON on disk', {
-				taskId,
-				path,
-				error: err instanceof Error ? err.message : String(err),
+				'namzu.task.id': taskId,
+				'namzu.store.path': path,
+				'exception.message': err instanceof Error ? err.message : String(err),
 			})
 			return null
 		}
@@ -490,20 +498,22 @@ export class DiskTaskStore implements TaskStore {
 			: join(this.baseDir, 'tasks')
 		try {
 			const entries = await readdir(root, { withFileTypes: true })
-			return entries.filter((e) => e.isDirectory()).map((e) => e.name as RunId)
+			// Prefix-filtered for the reason `DiskCheckpointStore.readRunDirs`
+			// gives, including the honest half: a directory that is not a run must
+			// not be enumerated as one, this is not observable downstream today,
+			// and it is the declared return type that makes it worth keeping.
+			return entries
+				.filter((e) => e.isDirectory() && e.name.startsWith('run_'))
+				.map((e) => e.name as RunId)
 		} catch (err) {
 			const code = (err as NodeJS.ErrnoException).code
 			if (code !== 'ENOENT') {
 				this.log.warn('Failed to enumerate task run directories', {
-					root,
-					error: err instanceof Error ? err.message : String(err),
+					'namzu.store.root': root,
+					'exception.message': err instanceof Error ? err.message : String(err),
 				})
 			}
 			return []
 		}
 	}
 }
-
-async function atomicWriteJson(filePath: string, value: unknown): Promise<void> {
-	await atomicWriteFile(filePath, JSON.stringify(stamp(SCHEMA, value), null, 2))
-}

package/src/store/topic/index.ts

@@ -0,0 +1,33 @@
+// Sub-barrel for the Topic persistence module (Convention #4).
+// Concrete implementations live in sibling files; re-export them here so
+// consumers import via `../store/topic/index.js`.
+//
+// There is no disk implementation. `DiskThreadStore` was deleted in
+// NZ-TOPIC-02 as declared-but-undriven — nothing in the monorepo ever
+// constructed one, and the untested code had a live indexing bug to show for
+// it. Reintroducing it here under the new name would undo that decision
+// silently, which is the one way a rename commit can lose an argument nobody
+// re-made. A durable TopicStore is still owed; it lands with the capability
+// that needs one, a caller, and a test.
+
+export { InMemoryTopicStore } from './memory.js'
+
+// Where a conversation's mutable state lives between runs — its own record
+// beside the Topic, because the Topic is identity and this is session state
+// that changes several times inside one conversation.
+export { DiskTopicStateStore, InMemoryTopicStateStore } from './state.js'
+export type { DiskTopicStateStoreConfig, TopicStateStore } from './state.js'
+
+// Work that outlives one run: the objective, its round cap and the
+// compare-and-set that makes the cap durable.
+export {
+	DiskTopicObjectiveStore,
+	InMemoryTopicObjectiveStore,
+	ObjectiveExhaustedError,
+	ObjectiveExistsError,
+} from './objective.js'
+export type {
+	CreateObjectiveParams,
+	DiskTopicObjectiveStoreConfig,
+	TopicObjectiveStore,
+} from './objective.js'

package/src/store/topic/memory.ts

@@ -0,0 +1,111 @@
+/**
+ * InMemoryTopicStore — reference in-memory implementation of
+ * {@link TopicStore}.
+ *
+ * Mirrors the write-time CAS contract of the disk store: every
+ * `updateTopic` compares the supplied `ownerVersion` against the persisted
+ * copy and rejects with `StaleThreadError` on mismatch (class name
+ * unchanged this release — see NZ-TOPIC-01 risks). Convention #17:
+ * cross-tenant access throws `TenantIsolationError` with no fallback.
+ *
+ * NZ-TOPIC-01 renamed this from `InMemoryThreadStore` (moved from
+ * `store/thread/memory.ts`) and re-exported the old name as an identity
+ * binding. NZ-TOPIC-05 removed that re-export, once 28.0.0 had carried the
+ * deprecation to the registry — the class is reachable only as
+ * `InMemoryTopicStore` now.
+ */
+
+import { StaleThreadError, TenantIsolationError } from '../../session/errors.js'
+import type { TenantId } from '../../types/ids/index.js'
+import type { ProjectId, TopicId } from '../../types/session/ids.js'
+import type { Topic } from '../../types/topic/entity.js'
+import type { CreateTopicParams, TopicStore } from '../../types/topic/store.js'
+import { generateTopicId } from '../../utils/id.js'
+
+interface TopicRecord {
+	tenantId: TenantId
+	topic: Topic
+}
+
+export class InMemoryTopicStore implements TopicStore {
+	private readonly topics = new Map<TopicId, TopicRecord>()
+
+	async createTopic(params: CreateTopicParams, tenantId: TenantId): Promise<Topic> {
+		const now = new Date()
+		const topic: Topic = {
+			id: generateTopicId(),
+			projectId: params.projectId,
+			tenantId,
+			title: params.title,
+			status: 'open',
+			ownerVersion: 0,
+			createdAt: now,
+			updatedAt: now,
+		}
+		this.topics.set(topic.id, { tenantId, topic })
+		return topic
+	}
+
+	async getTopic(topicId: TopicId, tenantId: TenantId): Promise<Topic | null> {
+		const record = this.topics.get(topicId)
+		if (!record) return null
+		this.assertTenant(record.tenantId, tenantId, `topic(${topicId})`)
+		return record.topic
+	}
+
+	async updateTopic(topic: Topic, tenantId: TenantId): Promise<void> {
+		if (topic.tenantId !== tenantId) {
+			throw new TenantIsolationError({
+				requested: tenantId,
+				resource: `topic(${topic.id}) payload`,
+			})
+		}
+		const existing = this.topics.get(topic.id)
+		if (!existing) {
+			throw new Error(`Topic ${topic.id} not found`)
+		}
+		this.assertTenant(existing.tenantId, tenantId, `topic(${topic.id})`)
+
+		// CAS on ownerVersion — supplied version must match persisted exactly.
+		// Any drift means another writer already advanced the record; the caller
+		// must re-read + re-apply + retry.
+		if (topic.ownerVersion !== existing.topic.ownerVersion) {
+			throw new StaleThreadError({
+				threadId: topic.id,
+				expectedVersion: topic.ownerVersion,
+				actualVersion: existing.topic.ownerVersion,
+			})
+		}
+
+		const updated: Topic = {
+			...topic,
+			ownerVersion: existing.topic.ownerVersion + 1,
+			updatedAt: new Date(),
+		}
+		this.topics.set(topic.id, { tenantId, topic: updated })
+	}
+
+	async deleteTopic(topicId: TopicId, tenantId: TenantId): Promise<void> {
+		const record = this.topics.get(topicId)
+		if (!record) return // Idempotent: missing = no-op.
+		this.assertTenant(record.tenantId, tenantId, `topic(${topicId})`)
+		this.topics.delete(topicId)
+	}
+
+	async listTopics(projectId: ProjectId, tenantId: TenantId): Promise<readonly Topic[]> {
+		const matches: Topic[] = []
+		for (const { tenantId: ownerTenant, topic } of this.topics.values()) {
+			if (ownerTenant !== tenantId) continue
+			if (topic.projectId !== projectId) continue
+			matches.push(topic)
+		}
+		matches.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())
+		return matches
+	}
+
+	private assertTenant(owning: TenantId, requested: TenantId, resource: string): void {
+		if (owning !== requested) {
+			throw new TenantIsolationError({ requested, resource })
+		}
+	}
+}