@namzu/sdk 0.1.8 → 0.2.0

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

@@ -0,0 +1,231 @@
+/**
+ * Integration — retention archive / restore round-trip wired through the
+ * real stack: `InMemorySessionStore` + `DiskArchiveBackend` (pointed at
+ * `tmpdir()`) + `ArchivalManager` + `GitWorktreeDriver`.
+ *
+ * Covers roadmap §5 invariants: §12.3 retention deny-by-default, §12.3
+ * archive produces tombstone (in-slot), tombstone navigable via `drill`,
+ * restore full fidelity round-trip (Phase 9 closed synthetic-id loss),
+ * idempotent workspace dispose.
+ */
+
+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 { InMemorySessionStore } from '../../../store/session/memory.js'
+import { createUserMessage } from '../../../types/message/index.js'
+import type { WorkspaceId } from '../../../types/session/ids.js'
+import { ArchivalManager, ArchiveNotConfiguredError } from '../../retention/archive.js'
+import { DiskArchiveBackend } from '../../retention/disk-backend.js'
+import type { WorkspaceRef } from '../../workspace/ref.js'
+import { WorkspaceBackendRegistry } from '../../workspace/registry.js'
+import { DEFAULT_TENANT, agentActor, userActor } from './_fixtures.js'
+
+async function seedIdleSubSession(store: InMemorySessionStore) {
+	const project = await store.createProject(
+		{ tenantId: DEFAULT_TENANT, name: 'archive' },
+		DEFAULT_TENANT,
+	)
+	const parent = await store.createSession(
+		{ projectId: project.id, currentActor: userActor('usr_a') },
+		DEFAULT_TENANT,
+	)
+	const child = await store.createSession(
+		{ projectId: project.id, currentActor: agentActor('agt_w') },
+		DEFAULT_TENANT,
+	)
+	const sub = await store.createSubSession(
+		{
+			parentSessionId: parent.id,
+			childSessionId: child.id,
+			kind: 'agent_spawn',
+			spawnedBy: userActor('usr_a'),
+		},
+		DEFAULT_TENANT,
+	)
+	await store.updateSubSession({ ...sub, status: 'idle' }, DEFAULT_TENANT)
+	return { project, parent, child, sub }
+}
+
+describe('Integration — retention archive / restore', () => {
+	let rootDir: string
+	let store: InMemorySessionStore
+	let backend: DiskArchiveBackend
+
+	beforeEach(() => {
+		rootDir = mkdtempSync(join(tmpdir(), 'namzu-integration-retention-'))
+		store = new InMemorySessionStore()
+		backend = new DiskArchiveBackend({ rootDir })
+	})
+
+	afterEach(() => {
+		rmSync(rootDir, { recursive: true, force: true })
+	})
+
+	it('archive idle sub-session → tombstone attached (status=archived + archiveRef + archivedAt)', async () => {
+		const { sub } = await seedIdleSubSession(store)
+		const manager = new ArchivalManager({
+			sessionStore: store,
+			workspaceRegistry: new WorkspaceBackendRegistry(),
+			archiveBackend: backend,
+		})
+
+		const tombstone = await manager.archive(sub.id, DEFAULT_TENANT)
+		expect(tombstone.archiveRef.startsWith('arc_')).toBe(true)
+
+		const after = await store.getSubSession(sub.id, DEFAULT_TENANT)
+		expect(after?.status).toBe('archived')
+		expect(after?.archiveRef).toBe(tombstone.archiveRef)
+		expect(after?.archivedAt).toBeInstanceOf(Date)
+	})
+
+	it('drill(parent) post-archive: archived SubSession still navigable with tombstone fields', async () => {
+		const { parent, sub } = await seedIdleSubSession(store)
+		const manager = new ArchivalManager({
+			sessionStore: store,
+			workspaceRegistry: new WorkspaceBackendRegistry(),
+			archiveBackend: backend,
+		})
+		const tombstone = await manager.archive(sub.id, DEFAULT_TENANT)
+
+		const view = await store.drill(parent.id, DEFAULT_TENANT)
+		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)
+	})
+
+	it('restore recovers the archive bundle with original MessageId fidelity (not synthetic msg_restored_N)', async () => {
+		const { sub, child } = await seedIdleSubSession(store)
+		const msg1Id = await store.appendMessage(child.id, createUserMessage('first'), DEFAULT_TENANT)
+		const msg2Id = await store.appendMessage(child.id, createUserMessage('second'), DEFAULT_TENANT)
+
+		const manager = new ArchivalManager({
+			sessionStore: store,
+			workspaceRegistry: new WorkspaceBackendRegistry(),
+			archiveBackend: backend,
+		})
+		const tombstone = await manager.archive(sub.id, DEFAULT_TENANT)
+
+		// Restore via backend directly to verify round-trip fidelity
+		// (ArchivalManager.restore does NOT return the bundle — it only flips
+		// status back to idle).
+		const bundle = await backend.restore(tombstone.archiveRef)
+		expect(bundle.messages).toHaveLength(2)
+		expect(bundle.messages[0]?.id).toBe(msg1Id)
+		expect(bundle.messages[1]?.id).toBe(msg2Id)
+		expect(bundle.messages[0]?.id.startsWith('msg_restored_')).toBe(false)
+
+		await manager.restore(sub.id, DEFAULT_TENANT)
+		const after = await store.getSubSession(sub.id, DEFAULT_TENANT)
+		expect(after?.status).toBe('idle')
+		expect(after?.archiveRef).toBeUndefined()
+		expect(after?.archivedAt).toBeUndefined()
+	})
+
+	it('deny-by-default: project without archiveBackend → ArchiveNotConfiguredError on archive()', async () => {
+		const { sub } = await seedIdleSubSession(store)
+		const manager = new ArchivalManager({
+			sessionStore: store,
+			workspaceRegistry: new WorkspaceBackendRegistry(),
+			// archiveBackend omitted — archival fully disabled.
+		})
+
+		await expect(manager.archive(sub.id, DEFAULT_TENANT)).rejects.toBeInstanceOf(
+			ArchiveNotConfiguredError,
+		)
+
+		// Sub-session untouched.
+		const after = await store.getSubSession(sub.id, DEFAULT_TENANT)
+		expect(after?.status).toBe('idle')
+	})
+
+	it('idempotent dispose: workspace already disposed → archive completes without error', async () => {
+		const { sub } = await seedIdleSubSession(store)
+
+		// Registry with a driver whose `dispose` throws a generic error.
+		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('simulated already-disposed race')
+			},
+			async inspect() {
+				return { exists: false, currentRef: 'HEAD', isDirty: false }
+			},
+		})
+
+		const workspaceRef: WorkspaceRef = {
+			id: 'wsp_live' as WorkspaceId,
+			meta: { backend: 'git-worktree', repoRoot: '/r', branch: 'main', worktreePath: '/r/y' },
+			createdAt: new Date(),
+		}
+		await store.updateSubSession(
+			{ ...sub, status: 'idle', workspaceId: workspaceRef.id },
+			DEFAULT_TENANT,
+		)
+
+		const manager = new ArchivalManager({
+			sessionStore: store,
+			workspaceRegistry: registry,
+			archiveBackend: backend,
+			workspaceResolver: async () => workspaceRef,
+		})
+
+		const tombstone = await manager.archive(sub.id, DEFAULT_TENANT)
+		expect(tombstone.archiveRef.startsWith('arc_')).toBe(true)
+
+		// Committed record persists despite dispose failure.
+		const after = await store.getSubSession(sub.id, DEFAULT_TENANT)
+		expect(after?.status).toBe('archived')
+	})
+
+	it('archive full round-trip: archive → restore → archive again succeeds', async () => {
+		const { sub } = await seedIdleSubSession(store)
+		const manager = new ArchivalManager({
+			sessionStore: store,
+			workspaceRegistry: new WorkspaceBackendRegistry(),
+			archiveBackend: backend,
+		})
+		const tombstone1 = await manager.archive(sub.id, DEFAULT_TENANT)
+		await manager.restore(sub.id, DEFAULT_TENANT)
+
+		const after = await store.getSubSession(sub.id, DEFAULT_TENANT)
+		expect(after?.status).toBe('idle')
+
+		// Re-archive produces a fresh tombstone.
+		const tombstone2 = await manager.archive(sub.id, DEFAULT_TENANT)
+		expect(tombstone2.archiveRef).not.toBe(tombstone1.archiveRef)
+	})
+
+	it('onArchived callback receives the tombstone exactly once', async () => {
+		const { sub } = await seedIdleSubSession(store)
+		const onArchived = vi.fn()
+		const manager = new ArchivalManager({
+			sessionStore: store,
+			workspaceRegistry: new WorkspaceBackendRegistry(),
+			archiveBackend: backend,
+			onArchived,
+		})
+		const tombstone = await manager.archive(sub.id, DEFAULT_TENANT)
+		expect(onArchived).toHaveBeenCalledTimes(1)
+		expect(onArchived).toHaveBeenCalledWith(tombstone)
+	})
+})

package/src/session/__tests__/integration/summary-materialization-e2e.test.ts

@@ -0,0 +1,237 @@
+/**
+ * Integration — SessionSummaryMaterializer + SessionStore atomic transition,
+ * plus the crash-recovery path.
+ *
+ * Covers roadmap §5 invariants: §8.1 (summary kernel-owned, no agent-callable
+ * emission surface), §8.1 atomic with terminal transition, recovery path
+ * when the status-flip lost to a mid-flight crash. `SessionAlreadySummarizedError`
+ * on concurrent re-materialize.
+ *
+ * The kernel-ownership assertion is expressed both structurally (the
+ * `materializedBy: 'kernel'` brand on the persisted record) and by routing
+ * every successful materialize through the Materializer — no test below calls
+ * `store.recordSummary` directly, and the compile-time type narrows the
+ * argument to `& { materializedBy: 'kernel' }` so an agent-constructed payload
+ * would fail typecheck (not just runtime validation).
+ */
+
+import { describe, expect, it } from 'vitest'
+import { InMemorySessionStore } from '../../../store/session/memory.js'
+import type { SessionId } from '../../../types/ids/index.js'
+import type { SummaryId } from '../../../types/session/ids.js'
+import { SessionSummaryMaterializer } from '../../summary/materialize.js'
+import { SessionAlreadySummarizedError } from '../../summary/ref.js'
+import { DEFAULT_TENANT, agentActor } from './_fixtures.js'
+
+async function seedActive(store: InMemorySessionStore) {
+	const project = await store.createProject(
+		{ tenantId: DEFAULT_TENANT, name: 'summary' },
+		DEFAULT_TENANT,
+	)
+	const session = await store.createSession(
+		{ projectId: project.id, currentActor: agentActor('agt_worker') },
+		DEFAULT_TENANT,
+	)
+	await store.updateSession({ ...session, status: 'active' }, DEFAULT_TENANT)
+	return { project, session: { ...session, status: 'active' as const } }
+}
+
+function makeGen(): () => SummaryId {
+	let n = 0
+	return () => `sum_materialize_${++n}` as SummaryId
+}
+
+describe('Integration — summary materialization E2E', () => {
+	it('Materializer writes summary + flips session active→idle atomically', async () => {
+		const store = new InMemorySessionStore()
+		const { session } = await seedActive(store)
+		const materializer = new SessionSummaryMaterializer({
+			store,
+			generateSummaryId: makeGen(),
+		})
+
+		const summary = await materializer.materialize({
+			sessionId: session.id,
+			tenantId: DEFAULT_TENANT,
+			finalOutcome: { status: 'succeeded' },
+			agentSummary: 'done',
+			declaredDeliverables: [],
+			keyDecisions: [],
+		})
+
+		// Persisted.
+		const stored = await store.getSummary(session.id, DEFAULT_TENANT)
+		expect(stored?.id).toBe(summary.id)
+		expect(stored?.materializedBy).toBe('kernel')
+
+		// Status atomically flipped.
+		const reloaded = await store.getSession(session.id, DEFAULT_TENANT)
+		expect(reloaded?.status).toBe('idle')
+	})
+
+	it('§8.1 atomicity invariant: no external observer sees terminal without summary', async () => {
+		// With InMemorySessionStore the two writes happen inside a single Map
+		// method call — there is no observable mid-state. We assert by reading
+		// both resources immediately after a single awaited materialize: the
+		// terminal status and the summary are visible together.
+		const store = new InMemorySessionStore()
+		const { session } = await seedActive(store)
+		const materializer = new SessionSummaryMaterializer({
+			store,
+			generateSummaryId: makeGen(),
+		})
+
+		await materializer.materialize({
+			sessionId: session.id,
+			tenantId: DEFAULT_TENANT,
+			finalOutcome: { status: 'succeeded' },
+			agentSummary: '',
+			declaredDeliverables: [],
+			keyDecisions: [],
+		})
+
+		const [finalSession, finalSummary] = await Promise.all([
+			store.getSession(session.id, DEFAULT_TENANT),
+			store.getSummary(session.id, DEFAULT_TENANT),
+		])
+		// Atomic pairing: idle status AND persisted summary present together.
+		expect(finalSession?.status).toBe('idle')
+		expect(finalSummary).not.toBeNull()
+	})
+
+	it('concurrent re-materialize rejects with SessionAlreadySummarizedError', async () => {
+		const store = new InMemorySessionStore()
+		const { session } = await seedActive(store)
+		const materializer = new SessionSummaryMaterializer({
+			store,
+			generateSummaryId: makeGen(),
+		})
+
+		await materializer.materialize({
+			sessionId: session.id,
+			tenantId: DEFAULT_TENANT,
+			finalOutcome: { status: 'succeeded' },
+			agentSummary: 'first',
+			declaredDeliverables: [],
+			keyDecisions: [],
+		})
+
+		await expect(
+			materializer.materialize({
+				sessionId: session.id,
+				tenantId: DEFAULT_TENANT,
+				finalOutcome: { status: 'succeeded' },
+				agentSummary: 'second',
+				declaredDeliverables: [],
+				keyDecisions: [],
+			}),
+		).rejects.toBeInstanceOf(SessionAlreadySummarizedError)
+	})
+
+	it('crash recovery: summary persisted + session still active → recover() replays idempotently', async () => {
+		const store = new InMemorySessionStore()
+		const { session } = await seedActive(store)
+		const materializer = new SessionSummaryMaterializer({
+			store,
+			generateSummaryId: makeGen(),
+		})
+
+		// Materialize once (happy path writes both). Then simulate a crash by
+		// forcing the session status back to `active` while the summary record
+		// stays intact — mimicking summary.json landing but session.json being
+		// lost to a mid-write power failure (see session/summary/materialize.ts
+		// `recover()` docs).
+		await materializer.materialize({
+			sessionId: session.id,
+			tenantId: DEFAULT_TENANT,
+			finalOutcome: { status: 'succeeded' },
+			agentSummary: '',
+			declaredDeliverables: [],
+			keyDecisions: [],
+		})
+		const mid = await store.getSession(session.id, DEFAULT_TENANT)
+		if (!mid) throw new Error('mid session missing')
+		await store.updateSession({ ...mid, status: 'active' }, DEFAULT_TENANT)
+
+		// Recovery call re-triggers the store's flip path without minting a
+		// new summary id.
+		const recovered = await materializer.recover(session.id, DEFAULT_TENANT)
+		expect(recovered).not.toBeNull()
+
+		const reloaded = await store.getSession(session.id, DEFAULT_TENANT)
+		expect(reloaded?.status).toBe('idle')
+
+		// Second recover call with session already idle: still idempotent.
+		const recovered2 = await materializer.recover(session.id, DEFAULT_TENANT)
+		expect(recovered2?.id).toBe(recovered?.id)
+		const reloaded2 = await store.getSession(session.id, DEFAULT_TENANT)
+		expect(reloaded2?.status).toBe('idle')
+	})
+
+	it('agent cannot construct SessionSummaryRef directly: recordSummary rejects non-kernel payload', async () => {
+		// The SessionStore contract narrows `recordSummary` to
+		// `SessionSummaryRef & { materializedBy: 'kernel' }`. Agents cannot
+		// type-construct a brand literal of `'kernel'` without going through
+		// the Materializer (see session/summary/ref.ts module header). Even
+		// attempting to cast into the shape and call directly would bypass
+		// the materialize ordering (status-check, length-check,
+		// already-exists guard). This test exercises the runtime guard: a
+		// second kernel-branded record for an already-summarized session
+		// rejects with SessionAlreadySummarizedError.
+		const store = new InMemorySessionStore()
+		const { session } = await seedActive(store)
+		const materializer = new SessionSummaryMaterializer({
+			store,
+			generateSummaryId: makeGen(),
+		})
+		await materializer.materialize({
+			sessionId: session.id,
+			tenantId: DEFAULT_TENANT,
+			finalOutcome: { status: 'succeeded' },
+			agentSummary: '',
+			declaredDeliverables: [],
+			keyDecisions: [],
+		})
+
+		// Direct call with a fabricated "kernel" ref payload — rejected
+		// because a summary already exists (store guard). The kernel-brand
+		// check at the type layer prevents naive agent-side construction; the
+		// runtime guard here catches store-level re-entry (materialize goes
+		// through the same path).
+		await expect(
+			store.recordSummary(
+				{
+					id: 'sum_fake' as SummaryId,
+					sessionRef: session.id,
+					tenantId: DEFAULT_TENANT,
+					outcome: { status: 'succeeded' },
+					deliverables: [],
+					agentSummary: 'forged',
+					keyDecisions: [],
+					at: new Date(),
+					materializedBy: 'kernel',
+				},
+				DEFAULT_TENANT,
+			),
+		).rejects.toBeInstanceOf(SessionAlreadySummarizedError)
+	})
+
+	it('missing session: materialize throws a not-found error', async () => {
+		const store = new InMemorySessionStore()
+		const materializer = new SessionSummaryMaterializer({
+			store,
+			generateSummaryId: makeGen(),
+		})
+
+		await expect(
+			materializer.materialize({
+				sessionId: 'ses_never' as SessionId,
+				tenantId: DEFAULT_TENANT,
+				finalOutcome: { status: 'succeeded' },
+				agentSummary: '',
+				declaredDeliverables: [],
+				keyDecisions: [],
+			}),
+		).rejects.toThrow(/not found/)
+	})
+})