@namzu/sdk 0.1.8 → 0.2.0

package/src/session/migration/filesystem.ts

@@ -0,0 +1,401 @@
+/**
+ * Boot-time filesystem re-layout — `.namzu/threads/{thd_X}/` →
+ * `.namzu/projects/{prj_legacy_<X>}/sessions/ses_legacy_default/runs/...`.
+ *
+ * Trigger: first {@link RunContextFactory.build} call per process. The
+ * factory invokes {@link DefaultFilesystemMigrator.migrate} before resolving
+ * any path so legacy runs are never orphaned by the new layout.
+ *
+ * See session-hierarchy.md §13.4.1 for the detection / trigger / atomicity
+ * contract. Concurrency model:
+ *
+ *   1. Main marker present → short-circuit `already_migrated`. Idempotent.
+ *   2. Legacy `.namzu/threads/` absent → write the main marker and return
+ *      `noop_no_legacy`. This plants the marker on fresh installs so the
+ *      `threads/` detection branch is only ever entered once.
+ *   3. Legacy layout detected → acquire the `.tmp` lock via `wx`; on
+ *      EEXIST another boot is mid-migration. The loser waits 100ms and
+ *      re-checks the main marker — cooperating, not competing. Roadmap
+ *      Risk #4 mitigation.
+ *   4. Per-legacy-thread: rename the whole `runs/` subtree in a single
+ *      `fs.rename` call (cross-OS atomic on the same filesystem; different
+ *      filesystems fall back to copy-then-unlink via Node's default — a
+ *      known limitation documented below).
+ *   5. Synthesize `project.json` + `session.json` via write-tmp-rename
+ *      (Convention #8) so partial crashes leave no half-serialised state.
+ *   6. Write main marker last — presence of the marker is the canonical
+ *      "migration done" signal.
+ *
+ * Known limitations:
+ *  - Cross-filesystem moves: Node's `fs.rename` rejects with `EXDEV` when
+ *    source and target live on different filesystems. This migrator does
+ *    NOT fall back to copy-then-unlink; the error surfaces as
+ *    {@link FilesystemMigrationError} with op `'rename_runs'`. Consumers
+ *    running `.namzu/threads` and `.namzu/projects` on different mounts
+ *    must migrate manually (documented INTERP flag).
+ *  - `UNKNOWN_TENANT_ID`: legacy threads have no tenant denormalisation on
+ *    disk. The synthesised project.json carries the sentinel so consumers
+ *    know these are legacy-rehomed and can either tag-then-retain or
+ *    reject until a real tenant is assigned (policy is consumer-owned).
+ */
+
+import { mkdir, readdir, rename, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { TenantId } from '../../types/ids/index.js'
+import { UNKNOWN_TENANT_ID } from '../../types/ids/index.js'
+import type { ProjectId, SessionId } from '../../types/session/ids.js'
+import { FilesystemMigrationError } from './errors.js'
+import { acquireMigrationLock, readMarker, releaseMigrationLock, writeMarker } from './marker.js'
+
+/**
+ * Sentinel SessionId used for legacy pre-0.2.0 runs that pre-date the
+ * Session entity. Every migrated thread collapses into this single session
+ * so consumers can still address the runs through the new layout.
+ */
+export const LEGACY_DEFAULT_SESSION_ID = 'ses_legacy_default' as SessionId
+
+/** Prefix for projects synthesised from legacy `thd_*` folders. */
+export const LEGACY_DEFAULT_PROJECT_PREFIX = 'prj_legacy_'
+
+/** Marker version string persisted at `.migration/v0.2.0`. */
+export const MIGRATION_VERSION = '0.2.0'
+
+/** Marker file path relative to rootDir. */
+export const MARKER_REL_PATH = join('.migration', 'v0.2.0')
+
+/** In-flight lock file path relative to rootDir. */
+export const LOCK_REL_PATH = join('.migration', 'v0.2.0.tmp')
+
+/** Delay before the loser re-checks the main marker on lock contention. */
+const LOCK_WAIT_MS = 100
+
+/**
+ * Result of a migration attempt. `kind` discriminates the three outcomes;
+ * `migratedThreads` is only non-empty for `kind: 'migrated'`. Sinks and
+ * callers can switch on `kind` without string parsing.
+ */
+export interface FilesystemMigrationResult {
+	kind: 'migrated' | 'already_migrated' | 'noop_no_legacy'
+	migratedThreads: readonly { legacyThreadId: string; newProjectId: ProjectId }[]
+	markerPath: string
+	at: Date
+}
+
+/** Event emitted on successful migration (`kind === 'migrated'` only). */
+export interface FilesystemMigrationEvent {
+	type: 'filesystem.migrated'
+	result: FilesystemMigrationResult
+}
+
+/** Sink contract — one `emit` method. */
+export interface FilesystemMigrationSink {
+	emit(event: FilesystemMigrationEvent): void
+}
+
+export const NOOP_FILESYSTEM_MIGRATION_SINK: FilesystemMigrationSink = {
+	emit() {},
+}
+
+/** Interface so consumers can inject a stub migrator in tests. */
+export interface FilesystemMigrator {
+	migrate(rootDir: string): Promise<FilesystemMigrationResult>
+}
+
+/**
+ * Persisted synthetic `project.json` shape. Matches
+ * `store/session/disk.ts:PersistedProject` plus a `_legacy: true` flag so
+ * readers can distinguish auto-synthesised records from real ones.
+ */
+interface SyntheticProject {
+	id: ProjectId
+	tenantId: TenantId
+	name: string
+	config: {
+		maxDelegationDepth: number
+		maxDelegationWidth: number
+		maxInterventionDepth: number
+	}
+	createdAt: string
+	updatedAt: string
+	_legacy: true
+}
+
+/**
+ * Persisted synthetic `session.json` shape. Matches
+ * `store/session/disk.ts:PersistedSession` minimally. Status is `idle` so
+ * any read path that drills into these sessions does not mistake them for
+ * active work. `_legacy: true` flags them as auto-synthesised.
+ */
+interface SyntheticSession {
+	id: SessionId
+	projectId: ProjectId
+	tenantId: TenantId
+	status: 'idle'
+	currentActor: null
+	previousActors: readonly []
+	workspaceId: null
+	ownerVersion: 0
+	createdAt: string
+	updatedAt: string
+	_legacy: true
+}
+
+/**
+ * Default implementation. Migration is driven by the contract documented in
+ * the module header — readers should trace concerns to this comment rather
+ * than re-deriving from code.
+ */
+export class DefaultFilesystemMigrator implements FilesystemMigrator {
+	constructor(private readonly sink: FilesystemMigrationSink = NOOP_FILESYSTEM_MIGRATION_SINK) {}
+
+	async migrate(rootDir: string): Promise<FilesystemMigrationResult> {
+		const markerPath = join(rootDir, MARKER_REL_PATH)
+		const lockPath = join(rootDir, LOCK_REL_PATH)
+		const threadsDir = join(rootDir, 'threads')
+		const projectsDir = join(rootDir, 'projects')
+
+		// Step 1: completed-marker short-circuit (cheapest idempotency check).
+		const existing = await readMarker(markerPath)
+		if (existing) {
+			return {
+				kind: 'already_migrated',
+				migratedThreads: [],
+				markerPath,
+				at: existing.at,
+			}
+		}
+
+		// Step 2: legacy absent → no-op. Plant the marker so subsequent boots
+		// do not re-enter this branch. Fresh installs fall through here.
+		const threadsExists = await directoryExists(threadsDir)
+		if (!threadsExists) {
+			const at = new Date()
+			try {
+				await writeMarker(markerPath, {
+					version: MIGRATION_VERSION,
+					at,
+					migratedThreads: [],
+				})
+			} catch (cause) {
+				throw new FilesystemMigrationError({
+					op: 'write_marker',
+					path: markerPath,
+					cause,
+				})
+			}
+			return {
+				kind: 'noop_no_legacy',
+				migratedThreads: [],
+				markerPath,
+				at,
+			}
+		}
+
+		// Step 3: cooperate on the tmp lock.
+		try {
+			await acquireMigrationLock(lockPath)
+		} catch (err) {
+			const code = (err as NodeJS.ErrnoException).code
+			if (code === 'EEXIST') {
+				// Another boot is mid-migration — wait and re-read the main marker.
+				await sleep(LOCK_WAIT_MS)
+				const follow = await readMarker(markerPath)
+				if (follow) {
+					return {
+						kind: 'already_migrated',
+						migratedThreads: [],
+						markerPath,
+						at: follow.at,
+					}
+				}
+				// Main marker still absent — the winning boot is still going OR
+				// crashed. We re-throw so the caller sees a contention surface
+				// rather than silently assuming success.
+				throw new FilesystemMigrationError({
+					op: 'acquire_lock',
+					path: lockPath,
+					cause: err,
+				})
+			}
+			throw new FilesystemMigrationError({
+				op: 'acquire_lock',
+				path: lockPath,
+				cause: err,
+			})
+		}
+
+		try {
+			// Step 4a: enumerate legacy thread dirs.
+			let entries: string[]
+			try {
+				entries = await readdir(threadsDir)
+			} catch (cause) {
+				throw new FilesystemMigrationError({
+					op: 'enumerate_threads',
+					path: threadsDir,
+					cause,
+				})
+			}
+
+			const migrated: { legacyThreadId: string; newProjectId: ProjectId }[] = []
+			const now = new Date()
+
+			for (const entry of entries) {
+				// Accept only `thd_*` (and tolerate `prj_*` legacy in case of
+				// rerun after a partial-crash-with-renamed-but-no-marker).
+				if (!entry.startsWith('thd_')) continue
+
+				const legacyThreadId = entry
+				const suffix = legacyThreadId.slice('thd_'.length)
+				const newProjectId = `${LEGACY_DEFAULT_PROJECT_PREFIX}${suffix}` as ProjectId
+
+				const legacyRunsDir = join(threadsDir, legacyThreadId, 'runs')
+				const newProjectDir = join(projectsDir, newProjectId)
+				const newSessionDir = join(newProjectDir, 'sessions', LEGACY_DEFAULT_SESSION_ID)
+				const newRunsDir = join(newSessionDir, 'runs')
+
+				// Ensure parent path exists for the atomic rename of `runs/`.
+				try {
+					await mkdir(newSessionDir, { recursive: true })
+				} catch (cause) {
+					throw new FilesystemMigrationError({
+						op: 'mkdir_session',
+						path: newSessionDir,
+						cause,
+					})
+				}
+
+				// Move the whole `runs/` subtree in a single rename — atomic on
+				// same-filesystem, EXDEV on cross-mount (documented limitation).
+				const legacyRunsExists = await directoryExists(legacyRunsDir)
+				if (legacyRunsExists) {
+					try {
+						await rename(legacyRunsDir, newRunsDir)
+					} catch (cause) {
+						throw new FilesystemMigrationError({
+							op: 'rename_runs',
+							path: legacyRunsDir,
+							cause,
+						})
+					}
+				}
+
+				// Step 4b: synthesize project.json via write-tmp-rename.
+				const projectJson: SyntheticProject = {
+					id: newProjectId,
+					tenantId: UNKNOWN_TENANT_ID,
+					name: `legacy ${legacyThreadId}`,
+					config: {
+						maxDelegationDepth: 4,
+						maxDelegationWidth: 8,
+						maxInterventionDepth: 10,
+					},
+					createdAt: now.toISOString(),
+					updatedAt: now.toISOString(),
+					_legacy: true,
+				}
+				const projectJsonPath = join(newProjectDir, 'project.json')
+				try {
+					await atomicWriteJson(projectJsonPath, projectJson)
+				} catch (cause) {
+					throw new FilesystemMigrationError({
+						op: 'write_project_json',
+						path: projectJsonPath,
+						cause,
+					})
+				}
+
+				// Step 4c: synthesize session.json for the legacy-default session.
+				const sessionJson: SyntheticSession = {
+					id: LEGACY_DEFAULT_SESSION_ID,
+					projectId: newProjectId,
+					tenantId: UNKNOWN_TENANT_ID,
+					status: 'idle',
+					currentActor: null,
+					previousActors: [],
+					workspaceId: null,
+					ownerVersion: 0,
+					createdAt: now.toISOString(),
+					updatedAt: now.toISOString(),
+					_legacy: true,
+				}
+				const sessionJsonPath = join(newSessionDir, 'session.json')
+				try {
+					await atomicWriteJson(sessionJsonPath, sessionJson)
+				} catch (cause) {
+					throw new FilesystemMigrationError({
+						op: 'write_session_json',
+						path: sessionJsonPath,
+						cause,
+					})
+				}
+
+				migrated.push({ legacyThreadId, newProjectId })
+			}
+
+			// Step 5: write the completion marker last. Presence = done.
+			try {
+				await writeMarker(markerPath, {
+					version: MIGRATION_VERSION,
+					at: now,
+					migratedThreads: migrated,
+				})
+			} catch (cause) {
+				throw new FilesystemMigrationError({
+					op: 'write_marker',
+					path: markerPath,
+					cause,
+				})
+			}
+
+			const result: FilesystemMigrationResult = {
+				kind: 'migrated',
+				migratedThreads: migrated,
+				markerPath,
+				at: now,
+			}
+
+			// Step 6: emit event.
+			this.sink.emit({ type: 'filesystem.migrated', result })
+
+			return result
+		} finally {
+			// Always release the lock — even on failure, a crashed run with the
+			// main marker absent will retry on the next boot; the stale `.tmp`
+			// would otherwise wedge that retry.
+			await releaseMigrationLock(lockPath).catch(() => undefined)
+		}
+	}
+}
+
+/**
+ * Shared atomic-write helper. Mirrors `store/session/disk.ts:atomicWriteJson`
+ * — intentionally duplicated so `session/migration/` has no inbound
+ * dependency on the store layer (Convention #4 dependency direction).
+ */
+async function atomicWriteJson(filePath: string, value: unknown): Promise<void> {
+	const { writeFile, rename: renameFile, unlink } = await import('node:fs/promises')
+	const tmp = `${filePath}.tmp`
+	try {
+		await writeFile(tmp, JSON.stringify(value, null, 2), 'utf-8')
+		await renameFile(tmp, filePath)
+	} catch (err) {
+		await unlink(tmp).catch(() => undefined)
+		throw err
+	}
+}
+
+async function directoryExists(path: string): Promise<boolean> {
+	try {
+		const s = await stat(path)
+		return s.isDirectory()
+	} catch (err) {
+		const code = (err as NodeJS.ErrnoException).code
+		if (code === 'ENOENT') return false
+		throw err
+	}
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms))
+}

package/src/session/migration/id-prefix.ts

@@ -0,0 +1,146 @@
+/**
+ * ID-prefix migration window — read-side compat for legacy `thd_*` IDs.
+ *
+ * Phase 1 already ships {@link parseThreadId} in `utils/id.ts` that accepts
+ * either `thd_*` or `prj_*` silently. This module formalises the warning
+ * emission path called out in session-hierarchy.md §13.3.1:
+ *
+ * | Version | Reader accepts      | Writer emits | Legacy read behaviour         |
+ * |---------|---------------------|--------------|-------------------------------|
+ * | 0.2.x   | `thd_*` AND `prj_*` | `prj_*` only | emits `MigrationWarning` once |
+ * | 0.3.x   | `prj_*` only        | `prj_*` only | rejects `StalePrefixError`    |
+ *
+ * Consumers that touch raw legacy IDs (filesystem migrator, wire decoders,
+ * CLI imports) route through {@link acceptLegacyThreadId} so the warning
+ * signal is structured rather than ad-hoc console output (Convention #18).
+ *
+ * The `WINDOW_OPEN` constant is the single switch that flips this module
+ * from soft-accept to hard-reject when 0.3.0 cuts. Convention #0: no silent
+ * long-lived compat — the window is explicit, dated, and fails closed when
+ * the clock runs out.
+ */
+
+import type { ProjectId } from '../../types/session/ids.js'
+
+/**
+ * Structured event emitted when the reader accepts a legacy `thd_*` ID.
+ *
+ * Shape is stable across the 0.2.x window — platform consumers can wire
+ * this into their observability pipeline (metrics, audit log) without
+ * string parsing (Convention #18).
+ */
+export interface MigrationWarning {
+	kind: 'id_prefix_legacy_read'
+	legacyId: string
+	normalizedId: ProjectId
+	at: Date
+	emittedOncePerProcess: true
+}
+
+/** Sink contract — one `emit` method so callers can swap implementations. */
+export interface MigrationWarningSink {
+	emit(warning: MigrationWarning): void
+}
+
+/**
+ * Default sink used when consumers do not inject one. Drops warnings on the
+ * floor — migration still runs; observers just lose the signal. Convention
+ * #5 deny-by-default applies to behaviour, not telemetry; missing a warning
+ * sink is not a failure mode.
+ */
+export const NOOP_MIGRATION_WARNING_SINK: MigrationWarningSink = {
+	emit() {},
+}
+
+/**
+ * Raised when the reader encounters a string that is neither a valid
+ * `prj_*` nor `thd_*` prefix. In the 0.3.x window the legacy branch will
+ * also throw this error — flip {@link WINDOW_OPEN} to `false` to cut over.
+ */
+export class StalePrefixError extends Error {
+	readonly details: { rawId: string; kind: 'thd_rejected' | 'unknown_prefix' }
+
+	constructor(details: { rawId: string; kind: 'thd_rejected' | 'unknown_prefix' }) {
+		const reason =
+			details.kind === 'thd_rejected'
+				? `Stale ThreadId prefix '${details.rawId.slice(0, 4)}…' — run 'namzu sdk migrate-ids' before 0.3.0`
+				: `Unknown ID prefix '${details.rawId.slice(0, 4)}…' — expected 'prj_' or 'thd_'`
+		super(reason)
+		this.name = 'StalePrefixError'
+		this.details = details
+	}
+}
+
+/**
+ * 0.2.x: compat window OPEN — `thd_*` coerces to `prj_*` with a warning.
+ * 0.3.x: flip to `false` — legacy branch becomes throw-only.
+ */
+export const WINDOW_OPEN = true
+
+/**
+ * Process-lifetime dedup map. Keyed by raw legacy ID so each distinct legacy
+ * string emits exactly one warning — spamming observability on a hot loop
+ * of reads is the anti-goal.
+ */
+const seenLegacy = new Set<string>()
+
+/**
+ * Accept-on-read for legacy `thd_*` IDs during the 0.2.x window.
+ *
+ * Contract:
+ *  - `prj_*` inputs return as-is; no warning emitted.
+ *  - `thd_*` inputs normalize to `prj_<suffix>` and emit a single
+ *    {@link MigrationWarning} per distinct input string per process.
+ *  - Everything else throws {@link StalePrefixError}.
+ *  - When {@link WINDOW_OPEN} flips to `false`, the `thd_*` branch throws
+ *    too — single knob, single commit.
+ *
+ * Testing hook: {@link __resetSeenLegacyForTests} clears the dedup Set so
+ * each test starts with a clean emission history.
+ */
+export function acceptLegacyThreadId(raw: string, sink: MigrationWarningSink): ProjectId {
+	if (raw.startsWith('prj_')) {
+		return raw as ProjectId
+	}
+	if (raw.startsWith('thd_')) {
+		if (!WINDOW_OPEN) {
+			throw new StalePrefixError({ rawId: raw, kind: 'thd_rejected' })
+		}
+		const normalized = `prj_${raw.slice('thd_'.length)}` as ProjectId
+		if (!seenLegacy.has(raw)) {
+			seenLegacy.add(raw)
+			sink.emit({
+				kind: 'id_prefix_legacy_read',
+				legacyId: raw,
+				normalizedId: normalized,
+				at: new Date(),
+				emittedOncePerProcess: true,
+			})
+		}
+		return normalized
+	}
+	throw new StalePrefixError({ rawId: raw, kind: 'unknown_prefix' })
+}
+
+/**
+ * Writer guard: reject emission of `thd_*` at encode time. Phase 1's
+ * {@link generateProjectId} already emits `prj_*` only; this helper exists
+ * so write paths that handle raw strings (e.g. synthesis during filesystem
+ * migration) can fail fast on accidental legacy re-emission. Convention #0:
+ * no silent back-sliding to the old prefix.
+ */
+export function rejectLegacyPrefix(id: string): void {
+	if (id.startsWith('thd_')) {
+		throw new StalePrefixError({ rawId: id, kind: 'thd_rejected' })
+	}
+}
+
+/**
+ * Test-only: clear the process-level dedup Set so subsequent
+ * {@link acceptLegacyThreadId} calls emit warnings again. Production code
+ * must never call this — the whole point is one warning per distinct
+ * legacy id per process.
+ */
+export function __resetSeenLegacyForTests(): void {
+	seenLegacy.clear()
+}

package/src/session/migration/index.ts

@@ -0,0 +1,38 @@
+// Sub-barrel for the migration module (Convention #4).
+// Public surface for boot-time FS re-layout + ID-prefix read-accept.
+// See session-hierarchy.md §13.3.1 (ID prefix) + §13.4.1 (filesystem).
+
+export {
+	acceptLegacyThreadId,
+	rejectLegacyPrefix,
+	NOOP_MIGRATION_WARNING_SINK,
+	StalePrefixError,
+	WINDOW_OPEN,
+} from './id-prefix.js'
+export type { MigrationWarning, MigrationWarningSink } from './id-prefix.js'
+
+export {
+	DefaultFilesystemMigrator,
+	NOOP_FILESYSTEM_MIGRATION_SINK,
+	LEGACY_DEFAULT_SESSION_ID,
+	LEGACY_DEFAULT_PROJECT_PREFIX,
+	MIGRATION_VERSION,
+	MARKER_REL_PATH,
+	LOCK_REL_PATH,
+} from './filesystem.js'
+export type {
+	FilesystemMigrator,
+	FilesystemMigrationResult,
+	FilesystemMigrationEvent,
+	FilesystemMigrationSink,
+} from './filesystem.js'
+
+export {
+	readMarker,
+	writeMarker,
+	acquireMigrationLock,
+	releaseMigrationLock,
+} from './marker.js'
+export type { MigrationMarker } from './marker.js'
+
+export { FilesystemMigrationError } from './errors.js'