@namzu/sdk 0.1.8 → 0.2.0

package/src/session/migration/marker.ts

@@ -0,0 +1,131 @@
+/**
+ * Migration marker file I/O — ensures the boot-time v0.2.0 re-layout is
+ * idempotent and race-safe.
+ *
+ * Layout:
+ *   {rootDir}/.migration/v0.2.0       — completion marker (JSON body)
+ *   {rootDir}/.migration/v0.2.0.tmp   — in-flight lock (O_EXCL / `wx` flag)
+ *
+ * Atomicity contract (Convention #8):
+ *  - `writeMarker` goes through write-tmp-rename so readers never see a
+ *    partially serialized body.
+ *  - `acquireMigrationLock` uses the `wx` flag (O_CREAT | O_EXCL) so
+ *    concurrent boots detect each other rather than overwriting. Loser
+ *    cooperates (see filesystem.ts — waits and re-checks the main marker).
+ *  - `readMarker` tolerates missing / corrupt files: missing → null,
+ *    corrupt JSON → null (not throw). The migrator treats either as "run
+ *    again"; a corrupt marker is safer to retry than to honor as valid.
+ */
+
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import type { ProjectId } from '../../types/session/ids.js'
+
+/**
+ * Marker payload. `migratedThreads` preserves the legacy → new mapping so
+ * later tooling (e.g. `namzu sdk migrate-ids`) can cross-reference.
+ */
+export interface MigrationMarker {
+	version: string
+	at: Date
+	migratedThreads: readonly { legacyThreadId: string; newProjectId: ProjectId }[]
+}
+
+interface PersistedMarker {
+	version: string
+	at: string
+	migratedThreads: readonly { legacyThreadId: string; newProjectId: string }[]
+}
+
+/**
+ * Read a marker file. Returns `null` when the file is absent OR when the
+ * contents fail JSON.parse — corruption is treated as "migration did not
+ * complete cleanly", so the caller re-runs rather than honoring stale data.
+ */
+export async function readMarker(path: string): Promise<MigrationMarker | null> {
+	let raw: string
+	try {
+		raw = await readFile(path, 'utf-8')
+	} catch (err) {
+		const code = (err as NodeJS.ErrnoException).code
+		if (code === 'ENOENT') return null
+		throw err
+	}
+
+	let parsed: PersistedMarker
+	try {
+		parsed = JSON.parse(raw) as PersistedMarker
+	} catch {
+		return null
+	}
+
+	if (
+		typeof parsed !== 'object' ||
+		parsed === null ||
+		typeof parsed.version !== 'string' ||
+		typeof parsed.at !== 'string' ||
+		!Array.isArray(parsed.migratedThreads)
+	) {
+		return null
+	}
+
+	return {
+		version: parsed.version,
+		at: new Date(parsed.at),
+		migratedThreads: parsed.migratedThreads.map((m) => ({
+			legacyThreadId: m.legacyThreadId,
+			newProjectId: m.newProjectId as ProjectId,
+		})),
+	}
+}
+
+/**
+ * Write a marker atomically via write-tmp-rename. Parent directory is
+ * created on demand so callers do not have to mkdir separately.
+ */
+export async function writeMarker(path: string, marker: MigrationMarker): Promise<void> {
+	await mkdir(dirname(path), { recursive: true })
+	const serialized: PersistedMarker = {
+		version: marker.version,
+		at: marker.at.toISOString(),
+		migratedThreads: marker.migratedThreads.map((m) => ({
+			legacyThreadId: m.legacyThreadId,
+			newProjectId: m.newProjectId as string,
+		})),
+	}
+	const tmp = `${path}.write.tmp`
+	try {
+		await writeFile(tmp, JSON.stringify(serialized, null, 2), 'utf-8')
+		await rename(tmp, path)
+	} catch (err) {
+		await unlink(tmp).catch(() => undefined)
+		throw err
+	}
+}
+
+/**
+ * Acquire an exclusive lock by creating `tmpPath` with the `wx` flag.
+ * EEXIST means another process is mid-migration — callers must treat that
+ * as "wait and re-check the main marker" rather than overwriting.
+ *
+ * Returns on success; throws the raw `NodeJS.ErrnoException` on EEXIST or
+ * any other FS failure so the caller can branch on `code`.
+ */
+export async function acquireMigrationLock(tmpPath: string): Promise<void> {
+	await mkdir(dirname(tmpPath), { recursive: true })
+	await writeFile(tmpPath, JSON.stringify({ at: new Date().toISOString() }), { flag: 'wx' })
+}
+
+/**
+ * Release the lock. Missing file is tolerated — lock release is idempotent
+ * by design so crashed mid-migrations do not wedge subsequent boots.
+ */
+export async function releaseMigrationLock(tmpPath: string): Promise<void> {
+	try {
+		await unlink(tmpPath)
+	} catch (err) {
+		const code = (err as NodeJS.ErrnoException).code
+		if (code === 'ENOENT') return
+		throw err
+	}
+}

package/src/session/retention/__tests__/archive.test.ts

@@ -0,0 +1,316 @@
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { ActorRef } from '../../../session/hierarchy/actor.js'
+import type { SubSession } from '../../../session/hierarchy/sub-session.js'
+import { type ExecFile, GitWorktreeDriver } from '../../../session/workspace/git-worktree.js'
+import type { WorkspaceRef } from '../../../session/workspace/ref.js'
+import { WorkspaceBackendRegistry } from '../../../session/workspace/registry.js'
+import { InMemorySessionStore } from '../../../store/session/memory.js'
+import type { AgentId, TenantId, UserId } from '../../../types/ids/index.js'
+import { createUserMessage } from '../../../types/message/index.js'
+import type { WorkspaceId } from '../../../types/session/ids.js'
+import {
+	ArchivalManager,
+	ArchiveNotConfiguredError,
+	SubSessionNotArchivableError,
+} from '../archive.js'
+import { DiskArchiveBackend } from '../disk-backend.js'
+
+const tenantA = 'tnt_alpha' as TenantId
+
+function stubLogger() {
+	return {
+		debug: vi.fn(),
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+		child() {
+			return stubLogger()
+		},
+	}
+}
+
+function userActor(tenantId: TenantId): ActorRef {
+	return { kind: 'user', userId: 'usr_a' as UserId, tenantId }
+}
+
+function agentActor(tenantId: TenantId): ActorRef {
+	return { kind: 'agent', agentId: 'agt_a' as AgentId, tenantId }
+}
+
+async function seedIdleSubSession(store: InMemorySessionStore) {
+	const project = await store.createProject({ tenantId: tenantA, name: 'p' }, tenantA)
+	const parent = await store.createSession(
+		{ projectId: project.id, currentActor: userActor(tenantA) },
+		tenantA,
+	)
+	const child = await store.createSession(
+		{ projectId: project.id, currentActor: agentActor(tenantA) },
+		tenantA,
+	)
+	const sub = await store.createSubSession(
+		{
+			parentSessionId: parent.id,
+			childSessionId: child.id,
+			kind: 'agent_spawn',
+			spawnedBy: userActor(tenantA),
+		},
+		tenantA,
+	)
+	// Flip the newly-created sub-session from 'pending' → 'idle' so it's
+	// eligible for archival.
+	await store.updateSubSession({ ...sub, status: 'idle' }, tenantA)
+	return { project, parent, child, sub }
+}
+
+function buildRegistry(): WorkspaceBackendRegistry {
+	const exec: ExecFile = async () => ({ stdout: '', stderr: '' })
+	const driver = new GitWorktreeDriver({
+		repoRoot: '/repo',
+		logger: stubLogger(),
+		execFile: exec,
+	})
+	const registry = new WorkspaceBackendRegistry()
+	registry.register(driver)
+	return registry
+}
+
+describe('ArchivalManager', () => {
+	let rootDir: string
+	let store: InMemorySessionStore
+	let backend: DiskArchiveBackend
+
+	beforeEach(() => {
+		rootDir = mkdtempSync(join(tmpdir(), 'namzu-retention-archive-'))
+		store = new InMemorySessionStore()
+		backend = new DiskArchiveBackend({ rootDir })
+	})
+
+	afterEach(() => {
+		rmSync(rootDir, { recursive: true, force: true })
+	})
+
+	it('archive happy path: idle sub-session → tombstone attached, backend called once', async () => {
+		const { sub, child } = await seedIdleSubSession(store)
+		await store.appendMessage(child.id, createUserMessage('hi'), tenantA)
+
+		const storeSpy = vi.spyOn(backend, 'store')
+		const manager = new ArchivalManager({
+			sessionStore: store,
+			workspaceRegistry: buildRegistry(),
+			archiveBackend: backend,
+		})
+
+		const tombstone = await manager.archive(sub.id, tenantA)
+
+		expect(tombstone.subSessionId).toBe(sub.id)
+		expect(tombstone.archiveRef).toMatch(/^arc_/)
+		expect(tombstone.archivedAt).toBeInstanceOf(Date)
+		expect(storeSpy).toHaveBeenCalledTimes(1)
+
+		const after = await store.getSubSession(sub.id, tenantA)
+		expect(after?.status).toBe('archived')
+		expect(after?.archiveRef).toBe(tombstone.archiveRef)
+		expect(after?.archivedAt).toBeInstanceOf(Date)
+	})
+
+	it('rejects non-archivable statuses (running/active → not_idle)', async () => {
+		const { sub } = await seedIdleSubSession(store)
+		await store.updateSubSession({ ...sub, status: 'active' }, tenantA)
+
+		const manager = new ArchivalManager({
+			sessionStore: store,
+			workspaceRegistry: buildRegistry(),
+			archiveBackend: backend,
+		})
+
+		await expect(manager.archive(sub.id, tenantA)).rejects.toBeInstanceOf(
+			SubSessionNotArchivableError,
+		)
+	})
+
+	it('rejects already-archived sub-sessions', async () => {
+		const { sub } = await seedIdleSubSession(store)
+		const manager = new ArchivalManager({
+			sessionStore: store,
+			workspaceRegistry: buildRegistry(),
+			archiveBackend: backend,
+		})
+		await manager.archive(sub.id, tenantA)
+
+		await expect(manager.archive(sub.id, tenantA)).rejects.toMatchObject({
+			name: 'SubSessionNotArchivableError',
+			details: { reason: 'already_archived' },
+		})
+	})
+
+	it('rejects missing sub-sessions', async () => {
+		const manager = new ArchivalManager({
+			sessionStore: store,
+			workspaceRegistry: buildRegistry(),
+			archiveBackend: backend,
+		})
+		await expect(manager.archive('sub_missing' as SubSession['id'], tenantA)).rejects.toMatchObject(
+			{ name: 'SubSessionNotArchivableError', details: { reason: 'missing' } },
+		)
+	})
+
+	it('deny-by-default: backend absent → ArchiveNotConfiguredError', async () => {
+		const { sub } = await seedIdleSubSession(store)
+		const manager = new ArchivalManager({
+			sessionStore: store,
+			workspaceRegistry: buildRegistry(),
+			// archiveBackend intentionally omitted.
+		})
+		await expect(manager.archive(sub.id, tenantA)).rejects.toBeInstanceOf(ArchiveNotConfiguredError)
+	})
+
+	it('restore reads tombstone, invokes backend.restore, flips status back to idle', async () => {
+		const { sub } = await seedIdleSubSession(store)
+		const manager = new ArchivalManager({
+			sessionStore: store,
+			workspaceRegistry: buildRegistry(),
+			archiveBackend: backend,
+		})
+		await manager.archive(sub.id, tenantA)
+
+		const restoreSpy = vi.spyOn(backend, 'restore')
+		await manager.restore(sub.id, tenantA)
+
+		expect(restoreSpy).toHaveBeenCalledTimes(1)
+		const after = await store.getSubSession(sub.id, tenantA)
+		expect(after?.status).toBe('idle')
+		expect(after?.archiveRef).toBeUndefined()
+		expect(after?.archivedAt).toBeUndefined()
+	})
+
+	it('tombstone is navigable via drill post-archive with status=archived + archiveRef', async () => {
+		const { parent, sub } = await seedIdleSubSession(store)
+		const manager = new ArchivalManager({
+			sessionStore: store,
+			workspaceRegistry: buildRegistry(),
+			archiveBackend: backend,
+		})
+		const tombstone = await manager.archive(sub.id, tenantA)
+
+		const view = await store.drill(parent.id, tenantA)
+		expect(view).not.toBeNull()
+		expect(view?.children).toHaveLength(1)
+		const child = view?.children[0]
+		expect(child?.id).toBe(sub.id)
+		expect(child?.status).toBe('archived')
+		expect(child?.archiveRef).toBe(tombstone.archiveRef)
+		expect(child?.archivedAt).toBeInstanceOf(Date)
+	})
+
+	it('workspace disposal failures do not unwind the committed archive', async () => {
+		const { sub } = await seedIdleSubSession(store)
+
+		// Registry with a driver whose `dispose` always throws.
+		const registry = new WorkspaceBackendRegistry()
+		registry.register({
+			kind: 'git-worktree',
+			async create() {
+				return {
+					id: 'wsp_x' as WorkspaceId,
+					meta: {
+						backend: 'git-worktree',
+						repoRoot: '/r',
+						branch: 'main',
+						worktreePath: '/r/x',
+					},
+					createdAt: new Date(),
+				}
+			},
+			async branch(ref) {
+				return ref
+			},
+			async dispose() {
+				throw new Error('dispose boom')
+			},
+			async inspect() {
+				return { exists: true, currentRef: 'HEAD', isDirty: false }
+			},
+		})
+
+		const workspaceRef: WorkspaceRef = {
+			id: 'wsp_y' as WorkspaceId,
+			meta: { backend: 'git-worktree', repoRoot: '/r', branch: 'main', worktreePath: '/r/y' },
+			createdAt: new Date(),
+		}
+		// Seed the sub-session with a workspaceId and a resolver that returns
+		// the live ref.
+		await store.updateSubSession({ ...sub, status: 'idle', workspaceId: workspaceRef.id }, tenantA)
+
+		const manager = new ArchivalManager({
+			sessionStore: store,
+			workspaceRegistry: registry,
+			archiveBackend: backend,
+			workspaceResolver: async () => workspaceRef,
+		})
+
+		// Archive must complete even though dispose throws internally.
+		const tombstone = await manager.archive(sub.id, tenantA)
+		expect(tombstone.archiveRef).toMatch(/^arc_/)
+
+		const after = await store.getSubSession(sub.id, tenantA)
+		expect(after?.status).toBe('archived')
+	})
+
+	it('SessionMessage round-trip: archive preserves original MessageId + timestamps', async () => {
+		// Phase 9 Known Delta #7: ArchivalManager now uses
+		// SessionStore.loadSessionMessages for full-fidelity archival (no more
+		// synthetic `msg_restored_N` IDs).
+		const { sub, child } = await seedIdleSubSession(store)
+		const id1 = await store.appendMessage(child.id, createUserMessage('m1'), tenantA)
+		const id2 = await store.appendMessage(child.id, createUserMessage('m2'), tenantA)
+
+		const captured: unknown[] = []
+		const capturingBackend: DiskArchiveBackend = Object.assign(
+			new DiskArchiveBackend({ rootDir }),
+			{
+				store: vi.fn(async (bundle: unknown) => {
+					captured.push(bundle)
+					return {
+						archiveRef: 'arc_test_ref',
+						archivedAt: new Date(),
+					}
+				}),
+			},
+		) as unknown as DiskArchiveBackend
+
+		const manager = new ArchivalManager({
+			sessionStore: store,
+			workspaceRegistry: buildRegistry(),
+			archiveBackend: capturingBackend,
+		})
+		await manager.archive(sub.id, tenantA)
+
+		expect(captured).toHaveLength(1)
+		const bundle = captured[0] as {
+			messages: Array<{ id: string; at: Date; message: unknown }>
+		}
+		expect(bundle.messages).toHaveLength(2)
+		expect(bundle.messages[0]?.id).toBe(id1)
+		expect(bundle.messages[1]?.id).toBe(id2)
+		expect(bundle.messages[0]?.id).not.toMatch(/^msg_restored_/)
+		expect(bundle.messages[0]?.at).toBeInstanceOf(Date)
+	})
+
+	it('onArchived callback fires exactly once on success with the tombstone', async () => {
+		const { sub } = await seedIdleSubSession(store)
+		const onArchived = vi.fn()
+		const manager = new ArchivalManager({
+			sessionStore: store,
+			workspaceRegistry: buildRegistry(),
+			archiveBackend: backend,
+			onArchived,
+		})
+		const tombstone = await manager.archive(sub.id, tenantA)
+
+		expect(onArchived).toHaveBeenCalledTimes(1)
+		expect(onArchived).toHaveBeenCalledWith(tombstone)
+	})
+})

package/src/session/retention/__tests__/disk-backend.test.ts

@@ -0,0 +1,180 @@
+import { mkdtempSync, rmSync } from 'node:fs'
+import { readFile, readdir } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import type { SessionMessage } from '../../../store/session/messages.js'
+import type { MessageId, SessionId, TenantId } from '../../../types/ids/index.js'
+import { createUserMessage } from '../../../types/message/index.js'
+import type { SubSessionId, SummaryId, WorkspaceId } from '../../../types/session/ids.js'
+import type { SessionSummaryRef } from '../../summary/ref.js'
+import type { WorkspaceRef } from '../../workspace/ref.js'
+import type { ArchiveBackendRef } from '../archive-backend-ref.js'
+import { DiskArchiveBackend } from '../disk-backend.js'
+
+const tenantA = 'tnt_alpha' as TenantId
+
+function fakeSessionId(): SessionId {
+	return 'ses_fake_1' as SessionId
+}
+
+function fakeSubSessionId(): SubSessionId {
+	return 'sub_fake_1' as SubSessionId
+}
+
+function buildMessages(sessionId: SessionId): SessionMessage[] {
+	return [
+		{
+			id: 'msg_1' as MessageId,
+			sessionId,
+			tenantId: tenantA,
+			message: createUserMessage('hello'),
+			at: new Date('2026-04-01T00:00:00Z'),
+		},
+		{
+			id: 'msg_2' as MessageId,
+			sessionId,
+			tenantId: tenantA,
+			message: createUserMessage('world'),
+			at: new Date('2026-04-01T00:01:00Z'),
+		},
+	]
+}
+
+function buildSummary(sessionId: SessionId): SessionSummaryRef {
+	return {
+		id: 'sum_disk_archive_1' as SummaryId,
+		sessionRef: sessionId,
+		tenantId: tenantA,
+		outcome: { status: 'succeeded' },
+		deliverables: [],
+		agentSummary: 'done',
+		keyDecisions: [{ at: new Date('2026-04-01T00:00:30Z'), summary: 'decided x' }],
+		at: new Date('2026-04-01T00:02:00Z'),
+		materializedBy: 'kernel',
+	}
+}
+
+function buildWorkspace(): WorkspaceRef {
+	return {
+		id: 'wsp_archive_1' as WorkspaceId,
+		meta: {
+			backend: 'git-worktree',
+			repoRoot: '/repo',
+			branch: 'feature/x',
+			worktreePath: '/repo/worktrees/x',
+		},
+		createdAt: new Date('2026-04-01T00:00:00Z'),
+	}
+}
+
+describe('DiskArchiveBackend', () => {
+	let rootDir: string
+	let backend: DiskArchiveBackend
+
+	beforeEach(() => {
+		rootDir = mkdtempSync(join(tmpdir(), 'namzu-archive-disk-'))
+		backend = new DiskArchiveBackend({ rootDir })
+	})
+
+	afterEach(() => {
+		rmSync(rootDir, { recursive: true, force: true })
+	})
+
+	it('store + restore round-trip preserves summary, messages, and subsession metadata', async () => {
+		const sessionId = fakeSessionId()
+		const subSessionId = fakeSubSessionId()
+		const messages = buildMessages(sessionId)
+		const summaryRef = buildSummary(sessionId)
+		const workspace = buildWorkspace()
+
+		const out = await backend.store({
+			subSessionId,
+			sessionId,
+			tenantId: tenantA,
+			workspace,
+			summaryRef,
+			messages,
+		})
+
+		expect(out.archiveRef).toMatch(/^arc_/)
+		expect(out.archivedAt).toBeInstanceOf(Date)
+
+		const restored = await backend.restore(out.archiveRef)
+		expect(restored.subSessionId).toBe(subSessionId)
+		expect(restored.sessionId).toBe(sessionId)
+		expect(restored.tenantId).toBe(tenantA)
+		expect(restored.workspace?.id).toBe(workspace.id)
+		expect(restored.summaryRef?.id).toBe(summaryRef.id)
+		expect(restored.summaryRef?.at).toBeInstanceOf(Date)
+		expect(restored.messages).toHaveLength(2)
+		expect(restored.messages[0]?.at).toBeInstanceOf(Date)
+	})
+
+	it('archive location is under {rootDir}/archive/{arc_*}/', async () => {
+		const out = await backend.store({
+			subSessionId: fakeSubSessionId(),
+			sessionId: fakeSessionId(),
+			tenantId: tenantA,
+			messages: [],
+		})
+
+		const archivesRoot = join(rootDir, 'archive')
+		const entries = await readdir(archivesRoot)
+		expect(entries).toContain(out.archiveRef)
+	})
+
+	it('writes the archive.json marker last (atomic via tmp-rename; no stray .tmp after)', async () => {
+		const out = await backend.store({
+			subSessionId: fakeSubSessionId(),
+			sessionId: fakeSessionId(),
+			tenantId: tenantA,
+			messages: buildMessages(fakeSessionId()),
+		})
+
+		const dir = join(rootDir, 'archive', out.archiveRef)
+		const entries = await readdir(dir)
+		expect(entries).toContain('archive.json')
+		expect(entries).toContain('subsession.json')
+		expect(entries).toContain('messages.jsonl')
+		// No lingering .tmp files from the write-tmp-rename sequence.
+		expect(entries.some((e) => e.endsWith('.tmp'))).toBe(false)
+
+		const marker = JSON.parse(await readFile(join(dir, 'archive.json'), 'utf-8'))
+		expect(marker.archiveRef).toBe(out.archiveRef)
+	})
+
+	it('restore on missing archive throws ArchiveNotFoundError (reason: missing)', async () => {
+		await expect(backend.restore('arc_nonexistent' as ArchiveBackendRef)).rejects.toMatchObject({
+			name: 'ArchiveNotFoundError',
+			details: { reason: 'missing' },
+		})
+	})
+
+	it('multiple archives receive unique refs (no collisions)', async () => {
+		const refs = new Set<string>()
+		for (let i = 0; i < 5; i++) {
+			const out = await backend.store({
+				subSessionId: fakeSubSessionId(),
+				sessionId: fakeSessionId(),
+				tenantId: tenantA,
+				messages: [],
+			})
+			refs.add(out.archiveRef)
+		}
+		expect(refs.size).toBe(5)
+	})
+
+	it('store without optional fields (no workspace, no summary, no messages) still round-trips', async () => {
+		const out = await backend.store({
+			subSessionId: fakeSubSessionId(),
+			sessionId: fakeSessionId(),
+			tenantId: tenantA,
+			messages: [],
+		})
+		const restored = await backend.restore(out.archiveRef)
+		expect(restored.workspace).toBeUndefined()
+		expect(restored.summaryRef).toBeUndefined()
+		expect(restored.messages).toHaveLength(0)
+	})
+})

package/src/session/retention/archive-backend-ref.ts

@@ -0,0 +1,17 @@
+/**
+ * Branded lookup identifier for an archived sub-session in a pluggable
+ * {@link ArchiveBackend}. Produced by
+ * {@link ArchiveBackend.store} on a successful archival write and consumed by
+ * {@link ArchiveBackend.restore} to re-hydrate the bundle.
+ *
+ * Follows Convention #2 (`<prefix>_<opaque>` template literal brand). Prefix
+ * chosen as `arc_` to match the `archive` domain — short, unambiguous, and
+ * distinct from every existing prefix (`prj_`, `ses_`, `sub_`, `sum_`, …).
+ *
+ * The string after the prefix is opaque — backend-specific. A disk backend
+ * embeds it in a directory path; an object-store backend may encode a key;
+ * callers MUST NOT parse or pattern-match beyond the brand check.
+ *
+ * See session-hierarchy.md §12.3 Retention and Archival.
+ */
+export type ArchiveBackendRef = `arc_${string}`