@namzu/sdk 0.1.8 → 0.3.0

package/src/session/retention/archive.ts

@@ -0,0 +1,281 @@
+/**
+ * ArchivalManager — on-demand archival primitive for sub-sessions. Pattern
+ * doc §12.3 (Retention and Archival).
+ *
+ * Convention #9 (Registry + Manager + Store): Manager-shape with explicit
+ * deps for the {@link SessionStore}, {@link WorkspaceBackendRegistry}, and a
+ * pluggable {@link ArchiveBackend}. Convention #5 deny-by-default: absent
+ * backend → {@link ArchiveNotConfiguredError} on every `archive()` call.
+ *
+ * Atomic invariant (pattern doc §12.3):
+ *
+ *   1. Read sub-session + owning session + messages + optional summary
+ *   2. backend.store(bundle) — archive durability confirmed
+ *   3. Flip sub-session to `status: 'archived'` + attach archiveRef/archivedAt
+ *   4. Workspace driver dispose (idempotent)
+ *
+ * Step 2 is the durability boundary: if the process crashes between step 2
+ * and step 3, the archive exists but the live record is still non-archived
+ * — recovery is to re-invoke `archive()`, which sees a non-terminal status
+ * and replays. Step 3 is the single point of no return.
+ *
+ * A completed archive leaves the sub-session in-place with `status:
+ * 'archived'` + an attached `archiveRef`. Pattern doc §12.3 calls this the
+ * tombstone: `SessionStore.drill` still finds it through the normal linkage
+ * path, so the archive is navigable without a parallel index.
+ */
+
+import type { SessionId, SubSessionId, TenantId } from '../../types/ids/index.js'
+import type { WorkspaceId } from '../../types/session/ids.js'
+import type { SessionStore } from '../../types/session/store.js'
+import type { SubSession, SubSessionStatus } from '../hierarchy/sub-session.js'
+import type { WorkspaceRef } from '../workspace/ref.js'
+import type { WorkspaceBackendRegistry } from '../workspace/registry.js'
+import type { ArchiveBackend, SubSessionTombstone } from './backend.js'
+
+/**
+ * Raised when {@link ArchivalManager.archive} or {@link ArchivalManager.restore}
+ * is invoked against a project whose retention policy does not supply an
+ * {@link ArchiveBackend}. Convention #5 — explicit error rather than silent
+ * no-op.
+ */
+export class ArchiveNotConfiguredError extends Error {
+	constructor() {
+		super('Retention archival not configured for this project (Convention #5: deny-by-default)')
+		this.name = 'ArchiveNotConfiguredError'
+	}
+}
+
+/**
+ * Raised when {@link ArchivalManager.archive} targets a sub-session that is
+ * not eligible for archival. The three reasons map to pattern doc §12.3
+ * (archival only applies to idle / merged / rejected / failed sub-sessions).
+ */
+export class SubSessionNotArchivableError extends Error {
+	readonly details: {
+		readonly subSessionId: SubSessionId
+		readonly reason: 'not_idle' | 'already_archived' | 'missing'
+	}
+
+	constructor(details: {
+		subSessionId: SubSessionId
+		reason: 'not_idle' | 'already_archived' | 'missing'
+	}) {
+		super(`Sub-session ${details.subSessionId} not archivable: ${details.reason}`)
+		this.name = 'SubSessionNotArchivableError'
+		this.details = details
+	}
+}
+
+/**
+ * Raised when {@link ArchivalManager.restore} is called against a
+ * sub-session that is not currently archived. Distinct from
+ * {@link SubSessionNotArchivableError} because the semantics are inverted:
+ * restore requires an archived record, archive rejects one.
+ */
+export class SubSessionNotArchivedError extends Error {
+	readonly details: {
+		readonly subSessionId: SubSessionId
+		readonly reason: 'not_archived' | 'missing' | 'missing_archive_ref'
+	}
+
+	constructor(details: {
+		subSessionId: SubSessionId
+		reason: 'not_archived' | 'missing' | 'missing_archive_ref'
+	}) {
+		super(`Sub-session ${details.subSessionId} cannot be restored: ${details.reason}`)
+		this.name = 'SubSessionNotArchivedError'
+		this.details = details
+	}
+}
+
+/**
+ * Lookup callback resolving a live {@link WorkspaceRef} from the id stored
+ * on a {@link SubSession}. Injected by the caller because Phase 8 does not
+ * ship a dedicated workspace store — the ref typically lives in a handoff
+ * assignment or is held by the agent lifecycle manager. Return `null` when
+ * the ref is unknown or already disposed; the manager archives without
+ * workspace data in that case (the disk backend allows it).
+ */
+export type WorkspaceResolver = (
+	workspaceId: WorkspaceId,
+	tenantId: TenantId,
+) => Promise<WorkspaceRef | null>
+
+/**
+ * Sub-session statuses eligible for archival. Pattern doc §12.3 speaks of
+ * "idle" broadly; we honor the enumerated terminal-like states. Anything
+ * else (active / pending / in-flight merge) rejects with
+ * `'not_idle'`.
+ */
+const ARCHIVABLE_STATUSES: ReadonlySet<SubSessionStatus> = new Set([
+	'idle',
+	'merged',
+	'merge_rejected',
+	'failed',
+])
+
+export interface ArchivalManagerDeps {
+	readonly sessionStore: SessionStore
+	readonly workspaceRegistry: WorkspaceBackendRegistry
+	/**
+	 * Archive backend. Absent = archival disabled for this manager
+	 * (`archive()`/`restore()` throw {@link ArchiveNotConfiguredError}).
+	 */
+	readonly archiveBackend?: ArchiveBackend
+	/**
+	 * Optional workspace resolver. When absent, `archive()` skips workspace
+	 * snapshotting (only the ref would be captured) and workspace disposal
+	 * (nothing to dispose). This is the conservative default and matches
+	 * pattern doc §7.1 (lazy workspace provisioning).
+	 */
+	readonly workspaceResolver?: WorkspaceResolver
+	/**
+	 * Optional logger hook for `sub_session.archived` emission. Pattern doc
+	 * §12.3 requires the event; full event-bus wiring is a platform concern
+	 * (a later phase of the roadmap). Phase 8 ships the log seam so tests
+	 * can observe without the bus.
+	 */
+	readonly onArchived?: (tombstone: SubSessionTombstone) => void
+	readonly onRestored?: (subSessionId: SubSessionId, tenantId: TenantId) => void
+}
+
+export class ArchivalManager {
+	private readonly deps: ArchivalManagerDeps
+
+	constructor(deps: ArchivalManagerDeps) {
+		this.deps = deps
+	}
+
+	/**
+	 * Archive an eligible sub-session. See module header for the atomic
+	 * invariant and recovery semantics.
+	 *
+	 * Returns the {@link SubSessionTombstone} shape — the same identity +
+	 * archive fields the store now carries on the live record.
+	 */
+	async archive(subSessionId: SubSessionId, tenantId: TenantId): Promise<SubSessionTombstone> {
+		const backend = this.requireBackend()
+
+		// 1. Resolve + validate sub-session.
+		const sub = await this.deps.sessionStore.getSubSession(subSessionId, tenantId)
+		if (!sub) {
+			throw new SubSessionNotArchivableError({ subSessionId, reason: 'missing' })
+		}
+		if (sub.status === 'archived') {
+			throw new SubSessionNotArchivableError({ subSessionId, reason: 'already_archived' })
+		}
+		if (!ARCHIVABLE_STATUSES.has(sub.status)) {
+			throw new SubSessionNotArchivableError({ subSessionId, reason: 'not_idle' })
+		}
+
+		// 2. Load owning child session bundle (messages + optional summary).
+		// Phase 9 Known Delta #7: uses `loadSessionMessages` for full-fidelity
+		// round-trip (original MessageId + timestamp preserved). Previously
+		// the Phase 8 archivalmanager synthesized `msg_restored_N` IDs from the
+		// payload-only `loadMessages` return — that lossy reshape is gone.
+		const childSessionId: SessionId = sub.childSessionId
+		const messages = await this.deps.sessionStore.loadSessionMessages(childSessionId, tenantId)
+
+		const summaryRefOrNull = await this.deps.sessionStore.getSummary(childSessionId, tenantId)
+		const summaryRef = summaryRefOrNull ?? undefined
+
+		// 3. Resolve optional live workspace ref.
+		let workspace: WorkspaceRef | undefined
+		if (sub.workspaceId && this.deps.workspaceResolver) {
+			const resolved = await this.deps.workspaceResolver(sub.workspaceId, tenantId)
+			if (resolved) workspace = resolved
+		}
+
+		// 4. Durability boundary: persist the archive bundle.
+		const bundleOut = await backend.store({
+			subSessionId: sub.id,
+			sessionId: childSessionId,
+			tenantId,
+			...(workspace !== undefined && { workspace }),
+			...(summaryRef !== undefined && { summaryRef }),
+			messages,
+		})
+
+		// 5. Point-of-no-return: flip sub-session to archived + attach ref.
+		const archived: SubSession = {
+			...sub,
+			status: 'archived',
+			archiveRef: bundleOut.archiveRef,
+			archivedAt: bundleOut.archivedAt,
+		}
+		await this.deps.sessionStore.updateSubSession(archived, tenantId)
+
+		// 6. Dispose the workspace (idempotent — driver contract tolerates
+		//    already-disposed refs; a missing ref is a no-op).
+		if (workspace) {
+			try {
+				const driver = this.deps.workspaceRegistry.get(workspace.meta.backend)
+				await driver.dispose(workspace)
+			} catch {
+				// Idempotent — a secondary failure here must not unwind the
+				// already-committed archive. Pattern doc §12.3: workspace
+				// disposal is a cleanup operation, not part of the atomic
+				// archive envelope.
+			}
+		}
+
+		const tombstone: SubSessionTombstone = {
+			subSessionId: sub.id,
+			sessionId: childSessionId,
+			tenantId,
+			...(sub.summaryRef !== undefined && { summaryRef: sub.summaryRef }),
+			archiveRef: bundleOut.archiveRef,
+			archivedAt: bundleOut.archivedAt,
+		}
+
+		this.deps.onArchived?.(tombstone)
+		return tombstone
+	}
+
+	/**
+	 * Reverse of {@link archive}. Reads the tombstone, invokes
+	 * `backend.restore`, then flips the sub-session back to `idle`. Does NOT
+	 * re-materialize the workspace — the caller decides whether to
+	 * re-provision via a {@link WorkspaceBackendDriver}.
+	 *
+	 * The restored `ArchiveInput` bundle is NOT returned here because the
+	 * concrete pattern in Phase 8 is "flip status and make navigable again";
+	 * consumers that need the bundle itself can call the backend directly.
+	 */
+	async restore(subSessionId: SubSessionId, tenantId: TenantId): Promise<void> {
+		const backend = this.requireBackend()
+
+		const sub = await this.deps.sessionStore.getSubSession(subSessionId, tenantId)
+		if (!sub) {
+			throw new SubSessionNotArchivedError({ subSessionId, reason: 'missing' })
+		}
+		if (sub.status !== 'archived') {
+			throw new SubSessionNotArchivedError({ subSessionId, reason: 'not_archived' })
+		}
+		if (!sub.archiveRef) {
+			throw new SubSessionNotArchivedError({ subSessionId, reason: 'missing_archive_ref' })
+		}
+
+		// Validate the archive ref by invoking the backend — this surfaces
+		// ArchiveNotFoundError up the stack if the bundle is missing or
+		// corrupt, rather than silently un-archiving an orphaned record.
+		await backend.restore(sub.archiveRef)
+
+		const restored: SubSession = {
+			...sub,
+			status: 'idle',
+			archiveRef: undefined,
+			archivedAt: undefined,
+		}
+		await this.deps.sessionStore.updateSubSession(restored, tenantId)
+
+		this.deps.onRestored?.(subSessionId, tenantId)
+	}
+
+	private requireBackend(): ArchiveBackend {
+		const backend = this.deps.archiveBackend
+		if (!backend) throw new ArchiveNotConfiguredError()
+		return backend
+	}
+}

package/src/session/retention/backend.ts

@@ -0,0 +1,107 @@
+/**
+ * ArchiveBackend — pluggable archival contract. See session-hierarchy.md
+ * §12.3 Retention and Archival.
+ *
+ * Convention #10 (Provider abstraction): interface lives here; concrete
+ * implementations (disk, s3, glacier, …) live in sibling files. Phase 8 ships
+ * the reference disk impl (`disk-backend.ts`); production deployments plug
+ * their own over the same surface.
+ *
+ * Convention #9 (Registry + Manager + Store): {@link ArchivalManager} is the
+ * Manager; this `ArchiveBackend` is the Provider slot it drives; the live
+ * `SessionStore` is the Store it mutates.
+ */
+
+import type { SessionMessage } from '../../store/session/messages.js'
+import type { SessionId, SubSessionId, TenantId } from '../../types/ids/index.js'
+import type { SummaryId } 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'
+
+/**
+ * Output of a successful {@link ArchiveBackend.store} call. `archiveRef` is
+ * the opaque lookup key used by {@link ArchiveBackend.restore} to rehydrate
+ * the bundle.
+ */
+export interface ArchiveOutput {
+	readonly archiveRef: ArchiveBackendRef
+	readonly archivedAt: Date
+}
+
+/**
+ * Bundle handed to {@link ArchiveBackend.store} (and returned by
+ * {@link ArchiveBackend.restore}). Captures the minimum surface needed to
+ * re-hydrate a sub-session in the future — sub-session metadata plus the
+ * owning session's messages and optional summary.
+ */
+export interface ArchiveInput {
+	readonly subSessionId: SubSessionId
+	/**
+	 * The session the sub-session owns. Each sub-session wraps exactly one
+	 * child {@link Session} (pattern doc §4.4); the archived bundle captures
+	 * that session's messages and summary.
+	 */
+	readonly sessionId: SessionId
+	readonly tenantId: TenantId
+	/**
+	 * Present when the sub-session had a provisioned workspace at archive
+	 * time. Absent for sub-sessions that never materialized one (pattern doc
+	 * §7.1 allows lazy workspace provisioning).
+	 */
+	readonly workspace?: WorkspaceRef
+	readonly summaryRef?: SessionSummaryRef
+	/**
+	 * Full message log for the owning session. Captured at archive time;
+	 * append-only discipline (pattern doc §13.4) means this is a complete
+	 * snapshot, not a partial view.
+	 */
+	readonly messages: readonly SessionMessage[]
+}
+
+/**
+ * Pluggable archival backend. Implementations MUST write atomically
+ * (Convention #8 — write-tmp-rename per file) and MUST produce a unique
+ * {@link ArchiveBackendRef} per call. Concurrent `store` calls with
+ * overlapping input are a caller error — the Manager serializes per
+ * sub-session.
+ */
+export interface ArchiveBackend {
+	/** Discriminator. Free-form; reference impl uses `'disk'`. */
+	readonly kind: string
+
+	/**
+	 * Persist the bundle. Returns the lookup ref consumers embed in the
+	 * sub-session tombstone (§12.3). Must be atomic at the bundle level —
+	 * post-success, a restore sees the full bundle or throws.
+	 */
+	store(input: ArchiveInput): Promise<ArchiveOutput>
+
+	/**
+	 * Reverse of {@link store}. Throws when the ref does not resolve or when
+	 * the bundle is corrupt. Does NOT re-materialize the workspace on disk —
+	 * callers decide whether to re-provision via a
+	 * {@link WorkspaceBackendDriver}.
+	 */
+	restore(archiveRef: ArchiveBackendRef): Promise<ArchiveInput>
+}
+
+/**
+ * The in-store marker a sub-session becomes after archival. Replaces the
+ * live record in-slot (see pattern doc §12.3): the sub-session's status
+ * flips to `'archived'` and `archiveRef` + `archivedAt` are attached. This
+ * way `SessionStore.drill` still finds it via the normal linkage path — the
+ * tombstone is navigable without a parallel index.
+ *
+ * Fields are a subset of {@link SubSession} — the identity columns plus the
+ * archive pointer — extracted here so consumers can destructure a tombstone
+ * view without carrying the full live-record shape.
+ */
+export interface SubSessionTombstone {
+	readonly subSessionId: SubSessionId
+	readonly sessionId: SessionId
+	readonly tenantId: TenantId
+	readonly summaryRef?: SummaryId
+	readonly archiveRef: ArchiveBackendRef
+	readonly archivedAt: Date
+}

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

@@ -0,0 +1,304 @@
+/**
+ * DiskArchiveBackend — reference filesystem-backed {@link ArchiveBackend}.
+ *
+ * Convention #8 (atomic writes): every file lands via write-tmp-rename; the
+ * final `archive.json` marker is written LAST so a crash mid-bundle leaves
+ * the directory visible but UN-marked, and `restore` treats such a bundle
+ * as missing. This mirrors the Phase 5 materializer's "marker-last"
+ * invariant.
+ *
+ * Layout:
+ *
+ *   {rootDir}/archive/{arc_<opaque>}/
+ *     subsession.json        # Identity + metadata
+ *     summary.json            # SessionSummaryRef (optional — present iff input.summaryRef)
+ *     messages.jsonl          # One SessionMessage per line (append-style, serialized once)
+ *     workspace.json          # WorkspaceRef (optional — present iff input.workspace)
+ *     archive.json            # Marker — final write; presence = bundle committed
+ *
+ * Workspace directory contents are NOT archived — we persist the
+ * {@link WorkspaceRef} only. The pattern doc §12.3 explicitly allows this:
+ * the ref is the re-hydration handle; the worktree itself is disposed at
+ * archive time via the caller's {@link WorkspaceBackendDriver}, not copied
+ * into the archive bundle. This is a Phase 8 interpretation — see the
+ * roadmap deliverable report for rationale (tar bundling deferred).
+ *
+ * See session-hierarchy.md §12.3.
+ */
+
+import { randomBytes } from 'node:crypto'
+import { mkdir, readFile, readdir, rename, unlink, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { SessionMessage } from '../../store/session/messages.js'
+import type { SessionId, SubSessionId, TenantId } from '../../types/ids/index.js'
+import type { SessionSummaryRef } from '../summary/ref.js'
+import type { WorkspaceRef } from '../workspace/ref.js'
+import type { ArchiveBackendRef } from './archive-backend-ref.js'
+import type { ArchiveBackend, ArchiveInput, ArchiveOutput } from './backend.js'
+
+/**
+ * Raised when {@link DiskArchiveBackend.restore} cannot resolve the supplied
+ * ref — either the directory is missing, or the `archive.json` marker is
+ * absent (crash-mid-write signal).
+ */
+export class ArchiveNotFoundError extends Error {
+	readonly details: { archiveRef: ArchiveBackendRef; reason: 'missing' | 'incomplete' }
+
+	constructor(details: { archiveRef: ArchiveBackendRef; reason: 'missing' | 'incomplete' }) {
+		super(`Archive ${details.archiveRef} could not be resolved: ${details.reason}`)
+		this.name = 'ArchiveNotFoundError'
+		this.details = details
+	}
+}
+
+/**
+ * Config for {@link DiskArchiveBackend}. `rootDir` is absolute — bundles land
+ * under `{rootDir}/archive/`.
+ */
+export interface DiskArchiveBackendConfig {
+	readonly rootDir: string
+}
+
+interface PersistedSubSessionEntry {
+	readonly subSessionId: SubSessionId
+	readonly sessionId: SessionId
+	readonly tenantId: TenantId
+}
+
+interface PersistedWorkspaceEntry {
+	readonly workspace: WorkspaceRef
+}
+
+interface PersistedSummaryEntry {
+	readonly summary: SessionSummaryRef
+}
+
+interface PersistedMessageLine {
+	readonly id: SessionMessage['id']
+	readonly sessionId: SessionId
+	readonly tenantId: TenantId
+	readonly message: SessionMessage['message']
+	readonly at: string
+}
+
+interface PersistedArchiveMarker {
+	readonly archiveRef: ArchiveBackendRef
+	readonly archivedAt: string
+}
+
+export class DiskArchiveBackend implements ArchiveBackend {
+	readonly kind = 'disk'
+	private readonly rootDir: string
+
+	constructor(config: DiskArchiveBackendConfig) {
+		this.rootDir = config.rootDir
+	}
+
+	async store(input: ArchiveInput): Promise<ArchiveOutput> {
+		const archiveRef = generateArchiveBackendRef()
+		const archivedAt = new Date()
+		const dir = join(this.rootDir, 'archive', archiveRef)
+		await mkdir(dir, { recursive: true })
+
+		// 1. Sub-session identity.
+		const subEntry: PersistedSubSessionEntry = {
+			subSessionId: input.subSessionId,
+			sessionId: input.sessionId,
+			tenantId: input.tenantId,
+		}
+		await atomicWriteJson(join(dir, 'subsession.json'), subEntry)
+
+		// 2. Summary (optional).
+		if (input.summaryRef) {
+			const entry: PersistedSummaryEntry = { summary: serializeSummaryFields(input.summaryRef) }
+			await atomicWriteJson(join(dir, 'summary.json'), entry)
+		}
+
+		// 3. Workspace ref (optional).
+		if (input.workspace) {
+			const entry: PersistedWorkspaceEntry = {
+				workspace: serializeWorkspaceFields(input.workspace),
+			}
+			await atomicWriteJson(join(dir, 'workspace.json'), entry)
+		}
+
+		// 4. Messages — one JSON per line, serialized once with an atomic
+		//    tmp-rename. No append I/O: we have the full bundle upfront, and
+		//    single-write is atomic at the file level.
+		const lines = input.messages.map((m) => {
+			const line: PersistedMessageLine = {
+				id: m.id,
+				sessionId: m.sessionId,
+				tenantId: m.tenantId,
+				message: m.message,
+				at: m.at.toISOString(),
+			}
+			return JSON.stringify(line)
+		})
+		const body = lines.length > 0 ? `${lines.join('\n')}\n` : ''
+		await atomicWriteText(join(dir, 'messages.jsonl'), body)
+
+		// 5. Marker — ALWAYS last. Presence = bundle committed.
+		const marker: PersistedArchiveMarker = {
+			archiveRef,
+			archivedAt: archivedAt.toISOString(),
+		}
+		await atomicWriteJson(join(dir, 'archive.json'), marker)
+
+		return { archiveRef, archivedAt }
+	}
+
+	async restore(archiveRef: ArchiveBackendRef): Promise<ArchiveInput> {
+		const dir = join(this.rootDir, 'archive', archiveRef)
+
+		// Directory must exist.
+		try {
+			await readdir(dir)
+		} catch (err) {
+			const code = (err as NodeJS.ErrnoException).code
+			if (code === 'ENOENT') {
+				throw new ArchiveNotFoundError({ archiveRef, reason: 'missing' })
+			}
+			throw err
+		}
+
+		// Marker must exist — absence = crash-mid-write.
+		const marker = await readJson<PersistedArchiveMarker>(join(dir, 'archive.json'))
+		if (!marker) {
+			throw new ArchiveNotFoundError({ archiveRef, reason: 'incomplete' })
+		}
+
+		const subEntry = await readJson<PersistedSubSessionEntry>(join(dir, 'subsession.json'))
+		if (!subEntry) {
+			throw new ArchiveNotFoundError({ archiveRef, reason: 'incomplete' })
+		}
+
+		const summaryEntry = await readJson<PersistedSummaryEntry>(join(dir, 'summary.json'))
+		const summaryRef = summaryEntry ? deserializeSummaryFields(summaryEntry.summary) : undefined
+
+		const workspaceEntry = await readJson<PersistedWorkspaceEntry>(join(dir, 'workspace.json'))
+		const workspace = workspaceEntry
+			? deserializeWorkspaceFields(workspaceEntry.workspace)
+			: undefined
+
+		const messagesRaw = await readText(join(dir, 'messages.jsonl'))
+		const messages: SessionMessage[] =
+			messagesRaw === null
+				? []
+				: messagesRaw
+						.split('\n')
+						.filter((l) => l.length > 0)
+						.map((l) => {
+							const raw = JSON.parse(l) as PersistedMessageLine
+							return {
+								id: raw.id,
+								sessionId: raw.sessionId,
+								tenantId: raw.tenantId,
+								message: raw.message,
+								at: new Date(raw.at),
+							}
+						})
+
+		return {
+			subSessionId: subEntry.subSessionId,
+			sessionId: subEntry.sessionId,
+			tenantId: subEntry.tenantId,
+			...(workspace !== undefined && { workspace }),
+			...(summaryRef !== undefined && { summaryRef }),
+			messages,
+		}
+	}
+}
+
+// Serialization helpers ------------------------------------------------------
+
+function serializeSummaryFields(s: SessionSummaryRef): SessionSummaryRef {
+	// Dates survive JSON round-trip as strings; we let JSON.stringify handle
+	// the normal `toJSON` path but store them as ISO strings on the wire.
+	// On deserialize we coerce back. The in-memory record stays immutable.
+	return s
+}
+
+function deserializeSummaryFields(s: SessionSummaryRef): SessionSummaryRef {
+	// JSON revives Dates as strings — resurrect them.
+	const at = s.at instanceof Date ? s.at : new Date(s.at as unknown as string)
+	const keyDecisions = s.keyDecisions.map((k) => ({
+		at: k.at instanceof Date ? k.at : new Date(k.at as unknown as string),
+		summary: k.summary,
+	}))
+	return { ...s, at, keyDecisions }
+}
+
+function serializeWorkspaceFields(w: WorkspaceRef): WorkspaceRef {
+	return w
+}
+
+function deserializeWorkspaceFields(w: WorkspaceRef): WorkspaceRef {
+	const createdAt =
+		w.createdAt instanceof Date ? w.createdAt : new Date(w.createdAt as unknown as string)
+	return { ...w, createdAt }
+}
+
+// ID generation --------------------------------------------------------------
+
+const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz'
+const MAX_UNIFORM_BYTE = Math.floor(256 / ALPHABET.length) * ALPHABET.length
+
+/**
+ * Mints an {@link ArchiveBackendRef}. Local helper rather than a `utils/id`
+ * export because the ref's uniqueness + prefix is an archive-backend concern
+ * — other backends may mint refs very differently (e.g. S3 keys).
+ */
+function generateArchiveBackendRef(length = 12): ArchiveBackendRef {
+	let suffix = ''
+	let remaining = length
+	while (remaining > 0) {
+		const bytes = randomBytes(remaining + 8)
+		for (const byte of bytes) {
+			if (remaining <= 0) break
+			if (byte < MAX_UNIFORM_BYTE) {
+				suffix += ALPHABET[byte % ALPHABET.length]
+				remaining--
+			}
+		}
+	}
+	return `arc_${suffix}` as ArchiveBackendRef
+}
+
+// FS helpers -----------------------------------------------------------------
+
+async function atomicWriteJson(filePath: string, value: unknown): Promise<void> {
+	await atomicWriteText(filePath, JSON.stringify(value, null, 2))
+}
+
+async function atomicWriteText(filePath: string, body: string): Promise<void> {
+	const tempPath = `${filePath}.tmp`
+	try {
+		await writeFile(tempPath, body, 'utf-8')
+		await rename(tempPath, filePath)
+	} catch (err) {
+		await unlink(tempPath).catch(() => undefined)
+		throw err
+	}
+}
+
+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 readText(path: string): Promise<string | null> {
+	try {
+		return await readFile(path, 'utf-8')
+	} catch (err) {
+		const code = (err as NodeJS.ErrnoException).code
+		if (code === 'ENOENT') return null
+		throw err
+	}
+}