@namzu/sdk 0.1.7 → 0.2.0

package/dist/session/migration/filesystem.js

@@ -0,0 +1,319 @@
+/**
+ * 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 { UNKNOWN_TENANT_ID } from '../../types/ids/index.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';
+/** 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;
+export const NOOP_FILESYSTEM_MIGRATION_SINK = {
+    emit() { },
+};
+/**
+ * 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 {
+    sink;
+    constructor(sink = NOOP_FILESYSTEM_MIGRATION_SINK) {
+        this.sink = sink;
+    }
+    async migrate(rootDir) {
+        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.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;
+            try {
+                entries = await readdir(threadsDir);
+            }
+            catch (cause) {
+                throw new FilesystemMigrationError({
+                    op: 'enumerate_threads',
+                    path: threadsDir,
+                    cause,
+                });
+            }
+            const migrated = [];
+            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}`;
+                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 = {
+                    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 = {
+                    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 = {
+                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, value) {
+    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) {
+    try {
+        const s = await stat(path);
+        return s.isDirectory();
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT')
+            return false;
+        throw err;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=filesystem.js.map

package/dist/session/migration/filesystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.js","sourceRoot":"","sources":["../../../src/session/migration/filesystem.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAE5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AACtD,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAEjG;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,oBAAiC,CAAA;AAE1E,mEAAmE;AACnE,MAAM,CAAC,MAAM,6BAA6B,GAAG,aAAa,CAAA;AAE1D,8DAA8D;AAC9D,MAAM,CAAC,MAAM,iBAAiB,GAAG,OAAO,CAAA;AAExC,4CAA4C;AAC5C,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAA;AAE3D,oDAAoD;AACpD,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,CAAA;AAE7D,2EAA2E;AAC3E,MAAM,YAAY,GAAG,GAAG,CAAA;AAyBxB,MAAM,CAAC,MAAM,8BAA8B,GAA4B;IACtE,IAAI,KAAI,CAAC;CACT,CAAA;AA8CD;;;;GAIG;AACH,MAAM,OAAO,yBAAyB;IACR;IAA7B,YAA6B,OAAgC,8BAA8B;QAA9D,SAAI,GAAJ,IAAI,CAA0D;IAAG,CAAC;IAE/F,KAAK,CAAC,OAAO,CAAC,OAAe;QAC5B,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,CAAA;QACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,CAAA;QAC7C,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAA;QAC3C,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAA;QAE7C,uEAAuE;QACvE,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,UAAU,CAAC,CAAA;QAC7C,IAAI,QAAQ,EAAE,CAAC;YACd,OAAO;gBACN,IAAI,EAAE,kBAAkB;gBACxB,eAAe,EAAE,EAAE;gBACnB,UAAU;gBACV,EAAE,EAAE,QAAQ,CAAC,EAAE;aACf,CAAA;QACF,CAAC;QAED,sEAAsE;QACtE,iEAAiE;QACjE,MAAM,aAAa,GAAG,MAAM,eAAe,CAAC,UAAU,CAAC,CAAA;QACvD,IAAI,CAAC,aAAa,EAAE,CAAC;YACpB,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAA;YACrB,IAAI,CAAC;gBACJ,MAAM,WAAW,CAAC,UAAU,EAAE;oBAC7B,OAAO,EAAE,iBAAiB;oBAC1B,EAAE;oBACF,eAAe,EAAE,EAAE;iBACnB,CAAC,CAAA;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,MAAM,IAAI,wBAAwB,CAAC;oBAClC,EAAE,EAAE,cAAc;oBAClB,IAAI,EAAE,UAAU;oBAChB,KAAK;iBACL,CAAC,CAAA;YACH,CAAC;YACD,OAAO;gBACN,IAAI,EAAE,gBAAgB;gBACtB,eAAe,EAAE,EAAE;gBACnB,UAAU;gBACV,EAAE;aACF,CAAA;QACF,CAAC;QAED,qCAAqC;QACrC,IAAI,CAAC;YACJ,MAAM,oBAAoB,CAAC,QAAQ,CAAC,CAAA;QACrC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAA;YAChD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACvB,oEAAoE;gBACpE,MAAM,KAAK,CAAC,YAAY,CAAC,CAAA;gBACzB,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,UAAU,CAAC,CAAA;gBAC3C,IAAI,MAAM,EAAE,CAAC;oBACZ,OAAO;wBACN,IAAI,EAAE,kBAAkB;wBACxB,eAAe,EAAE,EAAE;wBACnB,UAAU;wBACV,EAAE,EAAE,MAAM,CAAC,EAAE;qBACb,CAAA;gBACF,CAAC;gBACD,gEAAgE;gBAChE,+DAA+D;gBAC/D,yCAAyC;gBACzC,MAAM,IAAI,wBAAwB,CAAC;oBAClC,EAAE,EAAE,cAAc;oBAClB,IAAI,EAAE,QAAQ;oBACd,KAAK,EAAE,GAAG;iBACV,CAAC,CAAA;YACH,CAAC;YACD,MAAM,IAAI,wBAAwB,CAAC;gBAClC,EAAE,EAAE,cAAc;gBAClB,IAAI,EAAE,QAAQ;gBACd,KAAK,EAAE,GAAG;aACV,CAAC,CAAA;QACH,CAAC;QAED,IAAI,CAAC;YACJ,yCAAyC;YACzC,IAAI,OAAiB,CAAA;YACrB,IAAI,CAAC;gBACJ,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,CAAA;YACpC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,MAAM,IAAI,wBAAwB,CAAC;oBAClC,EAAE,EAAE,mBAAmB;oBACvB,IAAI,EAAE,UAAU;oBAChB,KAAK;iBACL,CAAC,CAAA;YACH,CAAC;YAED,MAAM,QAAQ,GAA0D,EAAE,CAAA;YAC1E,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAA;YAEtB,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC7B,8DAA8D;gBAC9D,2DAA2D;gBAC3D,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC;oBAAE,SAAQ;gBAEvC,MAAM,cAAc,GAAG,KAAK,CAAA;gBAC5B,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;gBAClD,MAAM,YAAY,GAAG,GAAG,6BAA6B,GAAG,MAAM,EAAe,CAAA;gBAE7E,MAAM,aAAa,GAAG,IAAI,CAAC,UAAU,EAAE,cAAc,EAAE,MAAM,CAAC,CAAA;gBAC9D,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAA;gBACrD,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,EAAE,UAAU,EAAE,yBAAyB,CAAC,CAAA;gBAChF,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,CAAA;gBAE9C,8DAA8D;gBAC9D,IAAI,CAAC;oBACJ,MAAM,KAAK,CAAC,aAAa,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;gBAChD,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBAChB,MAAM,IAAI,wBAAwB,CAAC;wBAClC,EAAE,EAAE,eAAe;wBACnB,IAAI,EAAE,aAAa;wBACnB,KAAK;qBACL,CAAC,CAAA;gBACH,CAAC;gBAED,gEAAgE;gBAChE,iEAAiE;gBACjE,MAAM,gBAAgB,GAAG,MAAM,eAAe,CAAC,aAAa,CAAC,CAAA;gBAC7D,IAAI,gBAAgB,EAAE,CAAC;oBACtB,IAAI,CAAC;wBACJ,MAAM,MAAM,CAAC,aAAa,EAAE,UAAU,CAAC,CAAA;oBACxC,CAAC;oBAAC,OAAO,KAAK,EAAE,CAAC;wBAChB,MAAM,IAAI,wBAAwB,CAAC;4BAClC,EAAE,EAAE,aAAa;4BACjB,IAAI,EAAE,aAAa;4BACnB,KAAK;yBACL,CAAC,CAAA;oBACH,CAAC;gBACF,CAAC;gBAED,yDAAyD;gBACzD,MAAM,WAAW,GAAqB;oBACrC,EAAE,EAAE,YAAY;oBAChB,QAAQ,EAAE,iBAAiB;oBAC3B,IAAI,EAAE,UAAU,cAAc,EAAE;oBAChC,MAAM,EAAE;wBACP,kBAAkB,EAAE,CAAC;wBACrB,kBAAkB,EAAE,CAAC;wBACrB,oBAAoB,EAAE,EAAE;qBACxB;oBACD,SAAS,EAAE,GAAG,CAAC,WAAW,EAAE;oBAC5B,SAAS,EAAE,GAAG,CAAC,WAAW,EAAE;oBAC5B,OAAO,EAAE,IAAI;iBACb,CAAA;gBACD,MAAM,eAAe,GAAG,IAAI,CAAC,aAAa,EAAE,cAAc,CAAC,CAAA;gBAC3D,IAAI,CAAC;oBACJ,MAAM,eAAe,CAAC,eAAe,EAAE,WAAW,CAAC,CAAA;gBACpD,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBAChB,MAAM,IAAI,wBAAwB,CAAC;wBAClC,EAAE,EAAE,oBAAoB;wBACxB,IAAI,EAAE,eAAe;wBACrB,KAAK;qBACL,CAAC,CAAA;gBACH,CAAC;gBAED,mEAAmE;gBACnE,MAAM,WAAW,GAAqB;oBACrC,EAAE,EAAE,yBAAyB;oBAC7B,SAAS,EAAE,YAAY;oBACvB,QAAQ,EAAE,iBAAiB;oBAC3B,MAAM,EAAE,MAAM;oBACd,YAAY,EAAE,IAAI;oBAClB,cAAc,EAAE,EAAE;oBAClB,WAAW,EAAE,IAAI;oBACjB,YAAY,EAAE,CAAC;oBACf,SAAS,EAAE,GAAG,CAAC,WAAW,EAAE;oBAC5B,SAAS,EAAE,GAAG,CAAC,WAAW,EAAE;oBAC5B,OAAO,EAAE,IAAI;iBACb,CAAA;gBACD,MAAM,eAAe,GAAG,IAAI,CAAC,aAAa,EAAE,cAAc,CAAC,CAAA;gBAC3D,IAAI,CAAC;oBACJ,MAAM,eAAe,CAAC,eAAe,EAAE,WAAW,CAAC,CAAA;gBACpD,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBAChB,MAAM,IAAI,wBAAwB,CAAC;wBAClC,EAAE,EAAE,oBAAoB;wBACxB,IAAI,EAAE,eAAe;wBACrB,KAAK;qBACL,CAAC,CAAA;gBACH,CAAC;gBAED,QAAQ,CAAC,IAAI,CAAC,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC,CAAA;YAChD,CAAC;YAED,6DAA6D;YAC7D,IAAI,CAAC;gBACJ,MAAM,WAAW,CAAC,UAAU,EAAE;oBAC7B,OAAO,EAAE,iBAAiB;oBAC1B,EAAE,EAAE,GAAG;oBACP,eAAe,EAAE,QAAQ;iBACzB,CAAC,CAAA;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,MAAM,IAAI,wBAAwB,CAAC;oBAClC,EAAE,EAAE,cAAc;oBAClB,IAAI,EAAE,UAAU;oBAChB,KAAK;iBACL,CAAC,CAAA;YACH,CAAC;YAED,MAAM,MAAM,GAA8B;gBACzC,IAAI,EAAE,UAAU;gBAChB,eAAe,EAAE,QAAQ;gBACzB,UAAU;gBACV,EAAE,EAAE,GAAG;aACP,CAAA;YAED,sBAAsB;YACtB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,qBAAqB,EAAE,MAAM,EAAE,CAAC,CAAA;YAEvD,OAAO,MAAM,CAAA;QACd,CAAC;gBAAS,CAAC;YACV,oEAAoE;YACpE,mEAAmE;YACnE,oCAAoC;YACpC,MAAM,oBAAoB,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;QAC5D,CAAC;IACF,CAAC;CACD;AAED;;;;GAIG;AACH,KAAK,UAAU,eAAe,CAAC,QAAgB,EAAE,KAAc;IAC9D,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAA;IAClF,MAAM,GAAG,GAAG,GAAG,QAAQ,MAAM,CAAA;IAC7B,IAAI,CAAC;QACJ,MAAM,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAA;QAC7D,MAAM,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;IAChC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;QACxC,MAAM,GAAG,CAAA;IACV,CAAC;AACF,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,IAAY;IAC1C,IAAI,CAAC;QACJ,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAA;QAC1B,OAAO,CAAC,CAAC,WAAW,EAAE,CAAA;IACvB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAA;QAChD,IAAI,IAAI,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAA;QACnC,MAAM,GAAG,CAAA;IACV,CAAC;AACF,CAAC;AAED,SAAS,KAAK,CAAC,EAAU;IACxB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAA;AACzD,CAAC"}

package/dist/session/migration/id-prefix.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 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 declare const NOOP_MIGRATION_WARNING_SINK: MigrationWarningSink;
+/**
+ * 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 declare class StalePrefixError extends Error {
+    readonly details: {
+        rawId: string;
+        kind: 'thd_rejected' | 'unknown_prefix';
+    };
+    constructor(details: {
+        rawId: string;
+        kind: 'thd_rejected' | 'unknown_prefix';
+    });
+}
+/**
+ * 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 declare const WINDOW_OPEN = true;
+/**
+ * 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 declare function acceptLegacyThreadId(raw: string, sink: MigrationWarningSink): ProjectId;
+/**
+ * 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 declare function rejectLegacyPrefix(id: string): void;
+/**
+ * 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 declare function __resetSeenLegacyForTests(): void;
+//# sourceMappingURL=id-prefix.d.ts.map

package/dist/session/migration/id-prefix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-prefix.d.ts","sourceRoot":"","sources":["../../../src/session/migration/id-prefix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAE3D;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,uBAAuB,CAAA;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,SAAS,CAAA;IACvB,EAAE,EAAE,IAAI,CAAA;IACR,qBAAqB,EAAE,IAAI,CAAA;CAC3B;AAED,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACpC,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAAA;CACrC;AAED;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,EAAE,oBAEzC,CAAA;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,cAAc,GAAG,gBAAgB,CAAA;KAAE,CAAA;gBAEhE,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,cAAc,GAAG,gBAAgB,CAAA;KAAE;CAS/E;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,OAAO,CAAA;AAS/B;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,GAAG,SAAS,CAsBvF;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAInD;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/dist/session/migration/id-prefix.js

@@ -0,0 +1,116 @@
+/**
+ * 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.
+ */
+/**
+ * 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 = {
+    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 {
+    details;
+    constructor(details) {
+        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();
+/**
+ * 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, sink) {
+    if (raw.startsWith('prj_')) {
+        return raw;
+    }
+    if (raw.startsWith('thd_')) {
+        if (!WINDOW_OPEN) {
+            throw new StalePrefixError({ rawId: raw, kind: 'thd_rejected' });
+        }
+        const normalized = `prj_${raw.slice('thd_'.length)}`;
+        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) {
+    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() {
+    seenLegacy.clear();
+}
+//# sourceMappingURL=id-prefix.js.map

package/dist/session/migration/id-prefix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-prefix.js","sourceRoot":"","sources":["../../../src/session/migration/id-prefix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAwBH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAyB;IAChE,IAAI,KAAI,CAAC;CACT,CAAA;AAED;;;;GAIG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACjC,OAAO,CAA4D;IAE5E,YAAY,OAAmE;QAC9E,MAAM,MAAM,GACX,OAAO,CAAC,IAAI,KAAK,cAAc;YAC9B,CAAC,CAAC,0BAA0B,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,+CAA+C;YACpG,CAAC,CAAC,sBAAsB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,gCAAgC,CAAA;QACnF,KAAK,CAAC,MAAM,CAAC,CAAA;QACb,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAA;QAC9B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;IACvB,CAAC;CACD;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAA;AAE/B;;;;GAIG;AACH,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAA;AAEpC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW,EAAE,IAA0B;IAC3E,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5B,OAAO,GAAgB,CAAA;IACxB,CAAC;IACD,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5B,IAAI,CAAC,WAAW,EAAE,CAAC;YAClB,MAAM,IAAI,gBAAgB,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAA;QACjE,CAAC;QACD,MAAM,UAAU,GAAG,OAAO,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAe,CAAA;QACjE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YACnB,IAAI,CAAC,IAAI,CAAC;gBACT,IAAI,EAAE,uBAAuB;gBAC7B,QAAQ,EAAE,GAAG;gBACb,YAAY,EAAE,UAAU;gBACxB,EAAE,EAAE,IAAI,IAAI,EAAE;gBACd,qBAAqB,EAAE,IAAI;aAC3B,CAAC,CAAA;QACH,CAAC;QACD,OAAO,UAAU,CAAA;IAClB,CAAC;IACD,MAAM,IAAI,gBAAgB,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC,CAAA;AACnE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAU;IAC5C,IAAI,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,gBAAgB,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAA;IAChE,CAAC;AACF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB;IACxC,UAAU,CAAC,KAAK,EAAE,CAAA;AACnB,CAAC"}

package/dist/session/migration/index.d.ts

@@ -0,0 +1,8 @@
+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';
+//# sourceMappingURL=index.d.ts.map

package/dist/session/migration/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/session/migration/index.ts"],"names":[],"mappings":"AAIA,OAAO,EACN,oBAAoB,EACpB,kBAAkB,EAClB,2BAA2B,EAC3B,gBAAgB,EAChB,WAAW,GACX,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAE5E,OAAO,EACN,yBAAyB,EACzB,8BAA8B,EAC9B,yBAAyB,EACzB,6BAA6B,EAC7B,iBAAiB,EACjB,eAAe,EACf,aAAa,GACb,MAAM,iBAAiB,CAAA;AACxB,YAAY,EACX,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,uBAAuB,GACvB,MAAM,iBAAiB,CAAA;AAExB,OAAO,EACN,UAAU,EACV,WAAW,EACX,oBAAoB,EACpB,oBAAoB,GACpB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAElD,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA"}

package/dist/session/migration/index.js

@@ -0,0 +1,8 @@
+// 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 { 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 { readMarker, writeMarker, acquireMigrationLock, releaseMigrationLock, } from './marker.js';
+export { FilesystemMigrationError } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/session/migration/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/session/migration/index.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,qEAAqE;AACrE,uEAAuE;AAEvE,OAAO,EACN,oBAAoB,EACpB,kBAAkB,EAClB,2BAA2B,EAC3B,gBAAgB,EAChB,WAAW,GACX,MAAM,gBAAgB,CAAA;AAGvB,OAAO,EACN,yBAAyB,EACzB,8BAA8B,EAC9B,yBAAyB,EACzB,6BAA6B,EAC7B,iBAAiB,EACjB,eAAe,EACf,aAAa,GACb,MAAM,iBAAiB,CAAA;AAQxB,OAAO,EACN,UAAU,EACV,WAAW,EACX,oBAAoB,EACpB,oBAAoB,GACpB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA"}

package/dist/session/migration/marker.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 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;
+    }[];
+}
+/**
+ * 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 declare function readMarker(path: string): Promise<MigrationMarker | null>;
+/**
+ * Write a marker atomically via write-tmp-rename. Parent directory is
+ * created on demand so callers do not have to mkdir separately.
+ */
+export declare function writeMarker(path: string, marker: MigrationMarker): Promise<void>;
+/**
+ * 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 declare function acquireMigrationLock(tmpPath: string): Promise<void>;
+/**
+ * Release the lock. Missing file is tolerated — lock release is idempotent
+ * by design so crashed mid-migrations do not wedge subsequent boots.
+ */
+export declare function releaseMigrationLock(tmpPath: string): Promise<void>;
+//# sourceMappingURL=marker.d.ts.map

package/dist/session/migration/marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker.d.ts","sourceRoot":"","sources":["../../../src/session/migration/marker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAE3D;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,EAAE,EAAE,IAAI,CAAA;IACR,eAAe,EAAE,SAAS;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,SAAS,CAAA;KAAE,EAAE,CAAA;CAC/E;AAQD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAmC9E;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBtF;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGzE;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQzE"}