@namzu/sdk 27.1.0 → 28.0.0

package/src/manager/thread/lifecycle.ts

@@ -1,217 +0,0 @@
-/**
- * ThreadManager — thin orchestrator over {@link ThreadStore} and
- * {@link SessionStore}.
- *
- * Owns user-facing lifecycle operations on the Thread topic layer plus the
- * archive-gate contract enforced at session-creation ingress sites.
- *
- * Phase 2.6 wired `ThreadManager.requireOpen` into three ingress paths:
- *   - {@link AgentManager.provisionSpawn} (child session creation)
- *   - `executeSingleHandoff` (recipient session creation)
- *   - `executeBroadcastHandoff` (N recipient sessions per fan-out)
- * Those call sites depend on this manager, so the one-method indirection
- * stopped being "structural overhead" the moment archive/delete needed the
- * session-presence cross-check anyway.
- *
- * Archive + delete require cross-store preconditions (session-presence
- * checks) — enforced here where both stores are in scope. The stores
- * themselves stay unaware of each other's layout (Convention #0), which is
- * why the gate lives at the manager layer rather than as a universal store
- * interceptor (see `archive` JSDoc for the direct-store-bypass boundary).
- */
-
-import {
-	THREAD_NOT_EMPTY_SAMPLE_LIMIT,
-	ThreadClosedError,
-	ThreadNotEmptyError,
-} from '../../session/errors.js'
-import type { TenantId } from '../../types/ids/index.js'
-import type { Session, SessionStatus } from '../../types/session/entity.js'
-import type { ProjectId, ThreadId } from '../../types/session/ids.js'
-import type { SessionStore } from '../../types/session/store.js'
-import type { Thread } from '../../types/thread/entity.js'
-import type { CreateThreadParams, ThreadStore } from '../../types/thread/store.js'
-
-export interface ThreadManagerDeps {
-	readonly threadStore: ThreadStore
-	readonly sessionStore: SessionStore
-}
-
-/**
- * Session statuses that block Thread archival. A session in any of these
- * states has live work in-flight (mid-run, mid-handoff, blocked on human
- * input, or orchestrating a broadcast merge) — freezing the Thread while any
- * of them are active would strand resumable work.
- *
- * `idle`, `failed`, and `archived` are archival-compatible: they are
- * quiescent or already-terminal, so a newly-frozen Thread can safely contain
- * them. This list mirrors the `SessionStatus` discriminants that represent
- * "not-yet-done" work (session-hierarchy.md §5.1).
- */
-const ARCHIVAL_BLOCKING_STATUSES: ReadonlySet<SessionStatus> = new Set([
-	'active',
-	'locked',
-	'awaiting_hitl',
-	'awaiting_merge',
-])
-
-export class ThreadManager {
-	private readonly deps: ThreadManagerDeps
-
-	constructor(deps: ThreadManagerDeps) {
-		this.deps = deps
-	}
-
-	/** Persist a new Thread. Thin passthrough for uniformity at the manager surface. */
-	create(params: CreateThreadParams, tenantId: TenantId): Promise<Thread> {
-		return this.deps.threadStore.createThread(params, tenantId)
-	}
-
-	/** Read a Thread by id; returns `null` when absent for the tenant. */
-	get(threadId: ThreadId, tenantId: TenantId): Promise<Thread | null> {
-		return this.deps.threadStore.getThread(threadId, tenantId)
-	}
-
-	/**
-	 * CAS update on a Thread. Propagates {@link import('../../session/errors.js').StaleThreadError}
-	 * from the store on `ownerVersion` mismatch — callers re-read, re-apply,
-	 * and retry.
-	 */
-	update(thread: Thread, tenantId: TenantId): Promise<void> {
-		return this.deps.threadStore.updateThread(thread, tenantId)
-	}
-
-	/** List Threads under a Project, ordered by `createdAt` ascending. */
-	list(projectId: ProjectId, tenantId: TenantId): Promise<readonly Thread[]> {
-		return this.deps.threadStore.listThreads(projectId, tenantId)
-	}
-
-	/**
-	 * Load a Thread and assert it is in `'open'` state. Used by the spawn path
-	 * as a precondition — a SubSession cannot be created under an archived
-	 * Thread. Throws on absence and on archival; returns the loaded Thread on
-	 * success so callers can avoid the second round-trip.
-	 *
-	 * Convention #5: deny-by-default. A missing Thread is a hard error, not a
-	 * silent "assume archived".
-	 */
-	async requireOpen(threadId: ThreadId, tenantId: TenantId): Promise<Thread> {
-		const thread = await this.deps.threadStore.getThread(threadId, tenantId)
-		if (!thread) {
-			throw new Error(`Thread ${threadId} not found`)
-		}
-		if (thread.status === 'archived') {
-			throw new ThreadClosedError({ threadId, op: 'require-open' })
-		}
-		return thread
-	}
-
-	/**
-	 * Flip a Thread to `'archived'` via CAS on {@link Thread.ownerVersion}.
-	 *
-	 * Preconditions (checked in order):
-	 *   1. Thread exists for the tenant (throws on absence).
-	 *   2. No attached Session is in a non-terminal state (see
-	 *      {@link ARCHIVAL_BLOCKING_STATUSES}). The presence check runs
-	 *      **before** the idempotent-archive short-circuit so that an already
-	 *      archived thread harboring a live session still surfaces as
-	 *      {@link ThreadNotEmptyError} rather than a silent success.
-	 *   3. If the thread is already `'archived'` the method short-circuits
-	 *      without an `updateThread` write (idempotent re-archival). The
-	 *      returned record reflects the current persisted state.
-	 *
-	 * On a fresh archive transition the underlying
-	 * {@link ThreadStore.updateThread} call commits with `ownerVersion + 1`.
-	 * A {@link import('../../session/errors.js').StaleThreadError} from a
-	 * concurrent writer propagates unchanged — the caller is expected to
-	 * re-read + retry (mirrors the `updateThread` contract).
-	 *
-	 * Gate scope (Phase 2.6): `ThreadManager.requireOpen` is wired into
-	 * `AgentManager.provisionSpawn` and both handoff flows, so the production
-	 * ingress paths cannot attach new sessions under an archived thread.
-	 * `SessionStore.createSession` / `updateSession` remain public and
-	 * ungated at the store layer — a direct caller can still mutate a
-	 * session after archival (the store has no `ThreadStore` handle by
-	 * design; cross-store awareness lives in the manager). The defensive
-	 * re-check above catches a smuggled live session on a subsequent
-	 * archive call, but does not prevent the direct-store write from
-	 * landing. That's an acceptable boundary — kernel callers must go
-	 * through the ingress paths; direct store consumers are out of scope
-	 * for the archive invariant.
-	 */
-	async archive(threadId: ThreadId, tenantId: TenantId): Promise<Thread> {
-		const thread = await this.deps.threadStore.getThread(threadId, tenantId)
-		if (!thread) {
-			throw new Error(`Thread ${threadId} not found`)
-		}
-
-		// Always enforce the blocking-session invariant — even on re-archival.
-		// If the thread is already archived but somehow gained a live session
-		// (direct store mutation, concurrent spawn before a write-barrier
-		// existed), surfacing that via ThreadNotEmptyError is more useful to
-		// operators than a silent idempotent success.
-		const sessions = await this.deps.sessionStore.listSessions(threadId, tenantId)
-		const blocking = sessions.filter((s) => ARCHIVAL_BLOCKING_STATUSES.has(s.status))
-		if (blocking.length > 0) {
-			throw new ThreadNotEmptyError({
-				threadId,
-				tenantId,
-				op: 'archive',
-				blockingSessions: summarizeBlocking(blocking),
-				totalBlockingSessions: blocking.length,
-			})
-		}
-
-		if (thread.status === 'archived') {
-			// Idempotent: already archived, no live sessions attached. Skip the
-			// write (updateThread would still bump ownerVersion for no semantic
-			// change).
-			return thread
-		}
-
-		const next: Thread = { ...thread, status: 'archived' }
-		await this.deps.threadStore.updateThread(next, tenantId)
-		// updateThread advances ownerVersion + updatedAt; re-read so the returned
-		// record reflects the persisted state (callers rely on version monotonicity).
-		const reloaded = await this.deps.threadStore.getThread(threadId, tenantId)
-		if (!reloaded) {
-			throw new Error(`Thread ${threadId} vanished between archive and read-back`)
-		}
-		return reloaded
-	}
-
-	/**
-	 * Hard-delete a Thread record. Rejects with {@link ThreadNotEmptyError}
-	 * (`op: 'delete'`) when ANY Session still references the Thread —
-	 * deletion is stricter than archival, which tolerates quiescent sessions.
-	 * Callers must first delete or archive-and-tombstone every attached
-	 * session (via {@link SessionStore.deleteSession}) before invoking.
-	 *
-	 * The session scan runs unconditionally, so orphaned sessions pointing at
-	 * a missing thread are still detected and reject the delete. Idempotent
-	 * for genuinely absent threads (no sessions, no thread record) — missing
-	 * thread + empty session list is a no-op at the store layer. Convention
-	 * #5: deny-by-default; no implicit cascade into SessionStore.
-	 */
-	async delete(threadId: ThreadId, tenantId: TenantId): Promise<void> {
-		const sessions = await this.deps.sessionStore.listSessions(threadId, tenantId)
-		if (sessions.length > 0) {
-			throw new ThreadNotEmptyError({
-				threadId,
-				tenantId,
-				op: 'delete',
-				blockingSessions: summarizeBlocking(sessions),
-				totalBlockingSessions: sessions.length,
-			})
-		}
-		await this.deps.threadStore.deleteThread(threadId, tenantId)
-	}
-}
-
-function summarizeBlocking(
-	sessions: readonly Session[],
-): ReadonlyArray<{ sessionId: Session['id']; status: SessionStatus }> {
-	return sessions
-		.slice(0, THREAD_NOT_EMPTY_SAMPLE_LIMIT)
-		.map((s) => ({ sessionId: s.id, status: s.status }))
-}

package/src/store/thread/disk.ts

@@ -1,272 +0,0 @@
-/**
- * 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, rm } from 'node:fs/promises'
-import { join } from 'node:path'
-import { StaleThreadError, TenantIsolationError } from '../../session/errors.js'
-import type { TenantId } from '../../types/ids/index.js'
-import type { ProjectId, ThreadId } from '../../types/session/ids.js'
-import type { Thread, ThreadStatus } from '../../types/thread/entity.js'
-import type { CreateThreadParams, ThreadStore } from '../../types/thread/store.js'
-import { atomicWriteFile } from '../../utils/atomic-write.js'
-import { generateThreadId } from '../../utils/id.js'
-import { defineSchema, migrate, stamp } from '../schema.js'
-
-/**
- * This store's on-disk format, versioned as a unit — which is how a
- * migration would actually be written and shipped, and it keeps every call
- * site free of schema plumbing.
- *
- * Bump `current` and add the migration for the step you are leaving when
- * the shape changes.
- */
-const SCHEMA = defineSchema({ kind: 'thread-store', current: 1, migrations: {} })
-
-/** 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')
-		// Through the schema rather than a bare cast: a record from an older
-		// build is brought forward, and one from a NEWER build is refused
-		// instead of read partially and written back with the difference
-		// gone.
-		return migrate<T>(SCHEMA, JSON.parse(raw))
-	} 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> {
-	// Through the shared writer: the sidecar name has to be private to this
-	// write, and a fixed `.tmp` is shared by every writer of the record.
-	await atomicWriteFile(filePath, JSON.stringify(stamp(SCHEMA, value), null, 2))
-}

package/src/store/thread/index.ts

@@ -1,7 +0,0 @@
-// 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'

package/src/store/thread/memory.ts

@@ -1,104 +0,0 @@
-/**
- * InMemoryThreadStore — reference in-memory implementation of
- * {@link ThreadStore}.
- *
- * Mirrors the write-time CAS contract of the disk store: every
- * `updateThread` compares the supplied `ownerVersion` against the persisted
- * copy and rejects with `StaleThreadError` on mismatch. Convention #17:
- * cross-tenant access throws `TenantIsolationError` with no fallback.
- */
-
-import { StaleThreadError, TenantIsolationError } from '../../session/errors.js'
-import type { TenantId } from '../../types/ids/index.js'
-import type { ProjectId, ThreadId } from '../../types/session/ids.js'
-import type { Thread } from '../../types/thread/entity.js'
-import type { CreateThreadParams, ThreadStore } from '../../types/thread/store.js'
-import { generateThreadId } from '../../utils/id.js'
-
-interface ThreadRecord {
-	tenantId: TenantId
-	thread: Thread
-}
-
-export class InMemoryThreadStore implements ThreadStore {
-	private readonly threads = new Map<ThreadId, ThreadRecord>()
-
-	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,
-		}
-		this.threads.set(thread.id, { tenantId, thread })
-		return thread
-	}
-
-	async getThread(threadId: ThreadId, tenantId: TenantId): Promise<Thread | null> {
-		const record = this.threads.get(threadId)
-		if (!record) return null
-		this.assertTenant(record.tenantId, tenantId, `thread(${threadId})`)
-		return record.thread
-	}
-
-	async updateThread(thread: Thread, tenantId: TenantId): Promise<void> {
-		if (thread.tenantId !== tenantId) {
-			throw new TenantIsolationError({
-				requested: tenantId,
-				resource: `thread(${thread.id}) payload`,
-			})
-		}
-		const existing = this.threads.get(thread.id)
-		if (!existing) {
-			throw new Error(`Thread ${thread.id} not found`)
-		}
-		this.assertTenant(existing.tenantId, tenantId, `thread(${thread.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 (thread.ownerVersion !== existing.thread.ownerVersion) {
-			throw new StaleThreadError({
-				threadId: thread.id,
-				expectedVersion: thread.ownerVersion,
-				actualVersion: existing.thread.ownerVersion,
-			})
-		}
-
-		const updated: Thread = {
-			...thread,
-			ownerVersion: existing.thread.ownerVersion + 1,
-			updatedAt: new Date(),
-		}
-		this.threads.set(thread.id, { tenantId, thread: updated })
-	}
-
-	async deleteThread(threadId: ThreadId, tenantId: TenantId): Promise<void> {
-		const record = this.threads.get(threadId)
-		if (!record) return // Idempotent: missing = no-op.
-		this.assertTenant(record.tenantId, tenantId, `thread(${threadId})`)
-		this.threads.delete(threadId)
-	}
-
-	async listThreads(projectId: ProjectId, tenantId: TenantId): Promise<readonly Thread[]> {
-		const matches: Thread[] = []
-		for (const { tenantId: ownerTenant, thread } of this.threads.values()) {
-			if (ownerTenant !== tenantId) continue
-			if (thread.projectId !== projectId) continue
-			matches.push(thread)
-		}
-		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 })
-		}
-	}
-}

package/src/types/thread/index.ts

@@ -1,6 +0,0 @@
-// Sub-barrel for the Thread type surface (Convention #4).
-// Concrete types live in sibling files; re-export them here so consumers
-// import via `../types/thread/index.js`.
-
-export type { ThreadStore, CreateThreadParams } from './store.js'
-export type { Thread, ThreadStatus } from './entity.js'