@jini-ai/platform 0.5.2 → 0.5.3

package/dist/fs/durable-json.js

@@ -5,6 +5,7 @@
  * Recovery policy stays with each store: salvage, restart, or leave untouched is not decided here.
  * Native effects are Electron-free so desktop, CLI, and bridge processes can share the mechanism.
  */
+import { readBootIdentity } from "./boot-identity.js";
 import nodeFs from "node:fs";
 import path from "node:path";
 import { randomBytes } from "node:crypto";
@@ -18,7 +19,7 @@ export function createNodeDurableJsonPorts(_required) {
         clock: { nowMs: () => Date.now() },
         // Synchronous store/IPC writers cannot await lock polling without changing all callers' ABI.
         sleep: { sleep: ({ durationMs }) => { Atomics.wait(cell, 0, 0, durationMs); } },
-        process: { pid: process.pid, isAlive: ({ pid }) => {
+        process: { pid: process.pid, bootIdentity: () => readBootIdentity({}), isAlive: ({ pid }) => {
                 // Signal zero sends nothing. Only ESRCH proves death; permission failure must count as alive
                 // because a false "dead" authorizes breaking a lock still owned by another process.
                 try {
@@ -40,9 +41,9 @@ export function createNodeDurableJsonPorts(_required) {
 export function createDurableJsonFile({ filePath, filesystem: fs, clock, sleep, process, random, report, notices }, { pollMs = 10, staleMs = 30000 } = {}) {
     if (!filePath)
         throw new TypeError("filePath is required");
-    for (const value of [pollMs, staleMs])
-        if (!Number.isSafeInteger(value) || value <= 0)
-            throw new TypeError("lock intervals must be positive safe integers");
+    if (!Number.isSafeInteger(pollMs) || pollMs <= 0 ||
+        ((!Number.isSafeInteger(staleMs) && staleMs !== Infinity) || staleMs <= 0))
+        throw new TypeError("lock intervals must be positive safe integers");
     // A synchronous read-modify-write normally takes milliseconds; five seconds allows contention
     // while refusing a wedged change. Short ten-millisecond polling fits those short critical sections.
     // Thirty-second staleness also handles pid reuse after a crash:
@@ -163,4 +164,58 @@ function endOfString(text, start) {
     }
     return text.length;
 }
+/** Update related JSON pointers under their existing locks, with atomic replacement per file.
+ * Compute every change before writing; a failed write restores prior bytes before releasing locks.
+ * The host supplies schema transforms, so this owner knows nothing about product catalogs.
+ * @throws Unreadable input, transform, lock or persistence failures (including rollback failures).
+ * @example updateDurableJsonFiles({ changes, fileAt, remove });
+ * @complexity O(total JSON bytes), O(total JSON bytes) rollback storage, one lock per file.
+ */
+export function updateDurableJsonFiles({ changes, fileAt, remove }, _options = {}) {
+    if (new Set(changes.map((change) => change.filePath)).size !== changes.length)
+        throw new Error("Duplicate JSON transaction path.");
+    const ordered = [...changes].sort((a, b) => a.filePath.localeCompare(b.filePath));
+    const files = ordered.map((change) => fileAt(change.filePath));
+    const lock = (index) => {
+        if (index < files.length) {
+            files[index].withLock({ critical: () => lock(index + 1) });
+            return;
+        }
+        const updates = ordered.map((change, i) => {
+            const before = files[i].read({});
+            if (before.state === "unreadable")
+                throw new Error(`JSON reference is unreadable: ${change.filePath}. Nothing was moved.`);
+            const previous = before.state === "ok" ? before.value : undefined;
+            return { file: files[i], filePath: change.filePath, previous, next: change.transform(previous) };
+        }).filter((item) => JSON.stringify(item.previous) !== JSON.stringify(item.next));
+        const attempted = [];
+        try {
+            for (const item of updates) {
+                attempted.push(item); // A write can fail after its rename; include it in rollback.
+                if (item.next === undefined)
+                    remove({ filePath: item.filePath });
+                else
+                    item.file.write({ value: item.next });
+            }
+        }
+        catch (failure) {
+            const errors = [failure];
+            for (const item of attempted.reverse()) {
+                try {
+                    if (item.previous === undefined)
+                        remove({ filePath: item.filePath });
+                    else
+                        item.file.write({ value: item.previous });
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            if (errors.length > 1)
+                throw new AggregateError(errors, "JSON reference rollback failed.");
+            throw failure;
+        }
+    };
+    lock(0);
+}
 //# sourceMappingURL=durable-json.js.map

package/dist/fs/file-lock.d.ts

@@ -10,6 +10,7 @@
  * multi-process races and are deliberately avoided. Atomic file replacement independently prevents
  * torn content. Hosts whose operations can legitimately exceed the stale budget use staleMs: Infinity.
  */
+import { type BootIdentity } from "./boot-identity.js";
 import fs from "node:fs";
 import * as asyncFs from "node:fs/promises";
 import { type Clock } from "@jini-ai/core/primitives";
@@ -21,6 +22,7 @@ export interface FileLockHolder {
     readonly hostname: string;
     readonly token: string;
     readonly acquiredAt: string;
+    readonly bootId?: string;
 }
 export interface HeldFileLock {
     readonly lockPath: string;
@@ -50,6 +52,7 @@ export interface FileLockOptions {
         isAlive(required: {
             pid: number;
         }): boolean;
+        bootIdentity?: () => BootIdentity | undefined;
     };
     token?: () => string;
     hostname?: () => string;

package/dist/fs/file-lock.js

@@ -10,6 +10,7 @@
  * multi-process races and are deliberately avoided. Atomic file replacement independently prevents
  * torn content. Hosts whose operations can legitimately exceed the stale budget use staleMs: Infinity.
  */
+import { readBootIdentity } from "./boot-identity.js";
 import fs from "node:fs";
 import * as asyncFs from "node:fs/promises";
 import { randomUUID } from "node:crypto";
@@ -52,7 +53,7 @@ function parseHolder(raw) {
         const value = JSON.parse(raw);
         if (typeof value !== "object" || value === null || !("pid" in value) || !validPid(value.pid) || !("hostname" in value) || typeof value.hostname !== "string" || !("token" in value) || typeof value.token !== "string" || !("acquiredAt" in value) || typeof value.acquiredAt !== "string")
             return undefined;
-        return { pid: value.pid, hostname: value.hostname, token: value.token, acquiredAt: value.acquiredAt };
+        return { pid: value.pid, hostname: value.hostname, token: value.token, acquiredAt: value.acquiredAt, ...("bootId" in value && typeof value.bootId === "string" ? { bootId: value.bootId } : {}) };
     }
     catch {
         return undefined;
@@ -67,7 +68,7 @@ function settings(options) {
     const timeoutMs = options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS, staleMs = options.staleMs ?? DEFAULT_LOCK_STALE_AFTER_MS, pollMs = options.pollMs ?? 10;
     if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0 || (!Number.isSafeInteger(staleMs) && staleMs !== Infinity) || staleMs <= 0 || !Number.isSafeInteger(pollMs) || pollMs <= 0)
         throw new RangeError((options.messages ?? defaultPlatformMessages).fileLockIntervalsInvalid());
-    const processPort = options.process ?? { pid: process.pid, isAlive: ({ pid }) => { try {
+    const processPort = options.process ?? { pid: process.pid, bootIdentity: () => readBootIdentity({}), isAlive: ({ pid }) => { try {
             process.kill(pid, 0);
             return true;
         }
@@ -76,19 +77,27 @@ function settings(options) {
         } } };
     const clock = options.clock ?? createSystemClock();
     const monotonicMs = options.monotonicMs ?? (() => clock.nowMs());
-    return { timeoutMs, staleMs, pollMs, processPort, clock, monotonicMs, hostname: (options.hostname ?? nodeHostname)(), token: (options.token ?? randomUUID)() };
+    return { timeoutMs, staleMs, pollMs, processPort, clock, monotonicMs, boot: processPort.bootIdentity?.(), hostname: (options.hostname ?? nodeHostname)(), token: (options.token ?? randomUUID)() };
 }
 function ownership(s, options) {
-    return options.format === "token" ? `${s.processPort.pid}:${s.token}` : JSON.stringify({ pid: s.processPort.pid, hostname: s.hostname, token: s.token, acquiredAt: new Date(s.clock.nowMs()).toISOString() });
+    return options.format === "token" ? `${s.processPort.pid}:${s.token}${s.boot ? ":" + s.boot.id : ""}` : JSON.stringify({ pid: s.processPort.pid, hostname: s.hostname, token: s.token, acquiredAt: new Date(s.clock.nowMs()).toISOString(), ...(s.boot ? { bootId: s.boot.id } : {}) });
 }
 function ownerAlive(snapshot, s) {
     const holder = snapshot.holder;
-    if (holder)
-        return holder.hostname === s.hostname ? s.processPort.isAlive({ pid: holder.pid }) : undefined;
+    if (holder) {
+        if (holder.hostname !== s.hostname)
+            return undefined;
+        if (s.boot && (holder.bootId !== undefined ? holder.bootId !== s.boot.id : Date.parse(holder.acquiredAt) < s.boot.startedAtMs))
+            return false;
+        return s.processPort.isAlive({ pid: holder.pid });
+    }
     // Legacy synchronous stores wrote pid:random rather than JSON. Malformed pids remain unknown.
     if (!/^\d+:/.test(snapshot.raw))
         return undefined;
-    const pid = Number(snapshot.raw.split(":", 1)[0]);
+    const parts = snapshot.raw.split(":");
+    const pid = Number(parts[0]);
+    if (validPid(pid) && s.boot && (parts[2] ? parts[2] !== s.boot.id : snapshot.mtimeMs < s.boot.startedAtMs))
+        return false;
     return validPid(pid) ? s.processPort.isAlive({ pid }) : undefined;
 }
 function unchanged(a, b) { return a.ino === b.ino && a.dev === b.dev && a.raw === b.raw && a.mtimeMs === b.mtimeMs; }

package/dist/fs/index.d.ts

@@ -5,4 +5,10 @@ export * from "./strict-containment.js";
 export * from "./guarded-reader.js";
 export * from "./durable-json.js";
 export { withFileLock, withFileLockSync, isLockStale } from "./file-lock.js";
+export * from "./directory-home.js";
+export * from "./directory-registry.js";
+export * from "./directory-running-lock.js";
+export * from "./directory-workspace.js";
+export * from "./workspace-directory.js";
+export * from "./verified-directory-move.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/fs/index.js

@@ -6,4 +6,10 @@ export * from "./strict-containment.js";
 export * from "./guarded-reader.js";
 export * from "./durable-json.js";
 export { withFileLock, withFileLockSync, isLockStale } from "./file-lock.js";
+export * from "./directory-home.js";
+export * from "./directory-registry.js";
+export * from "./directory-running-lock.js";
+export * from "./directory-workspace.js";
+export * from "./workspace-directory.js";
+export * from "./verified-directory-move.js";
 //# sourceMappingURL=index.js.map

package/dist/fs/user-data-directories.d.ts

@@ -0,0 +1,28 @@
+export interface UserDirectoryOptions {
+    /** Resolved host profile directory; owns config/catalog/DB/lease paths without an app-name suffix. */
+    appDataDir?: string;
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    readText?: (file: string) => string | undefined;
+    windowsDocuments?: () => string | undefined;
+    windowsOneDriveRoots?: () => readonly string[];
+}
+/** Electron-free OS directory rules. Windows uses roaming app-data and the redirected Personal
+ * known folder; Linux honors XDG user-dirs. No directories are created by this resolver.
+ * env-paths is intentionally not used: its Windows data directory is LocalAppData/<app>/Data.
+ * @complexity O(1) bounded configuration reads.
+ */
+export declare function resolveUserDataDirectories({ homeDir, appName }: {
+    homeDir: string;
+    appName: string;
+}, { platform, env, appDataDir, readText, windowsDocuments }?: UserDirectoryOptions): {
+    appData: string;
+    documents: string;
+};
+/** Native reads are isolated so cross-platform fixtures never execute registry commands. */
+export declare function readOptionalText({ file }: {
+    file: string;
+}, _options?: {}): string | undefined;
+/** OneDrive publishes account mount paths in HKCU; absent accounts are a normal empty result. */
+export declare function readWindowsOneDriveRoots(_required: Record<string, never>, _options?: {}): readonly string[];
+//# sourceMappingURL=user-data-directories.d.ts.map

package/dist/fs/user-data-directories.js

@@ -0,0 +1,53 @@
+import path from "node:path";
+import fs from "node:fs";
+import { execFileSync } from "node:child_process";
+/** Electron-free OS directory rules. Windows uses roaming app-data and the redirected Personal
+ * known folder; Linux honors XDG user-dirs. No directories are created by this resolver.
+ * env-paths is intentionally not used: its Windows data directory is LocalAppData/<app>/Data.
+ * @complexity O(1) bounded configuration reads.
+ */
+export function resolveUserDataDirectories({ homeDir, appName }, { platform = process.platform, env = process.env, appDataDir, readText = (file) => readOptionalText({ file }), windowsDocuments = readWindowsDocuments } = {}) {
+    const paths = platform === "win32" ? path.win32 : path.posix;
+    if (appDataDir !== undefined && (!appDataDir.trim() || !paths.isAbsolute(appDataDir)))
+        throw new Error("appDataDir must be an absolute profile directory.");
+    if (platform === "win32") {
+        const personal = windowsDocuments();
+        const documents = personal?.replace(/%([^%]+)%/g, (match, key) => env[key] ?? match);
+        return { appData: appDataDir ?? paths.join(env.APPDATA ?? paths.join(homeDir, "AppData", "Roaming"), appName),
+            documents: documents ?? paths.join(homeDir, "Documents") };
+    }
+    if (platform === "darwin")
+        return { appData: appDataDir ?? paths.join(homeDir, "Library", "Application Support", appName), documents: paths.join(homeDir, "Documents") };
+    const userDirs = readText(paths.join(env.XDG_CONFIG_HOME ?? paths.join(homeDir, ".config"), "user-dirs.dirs"));
+    const configured = /^XDG_DOCUMENTS_DIR="([^"\n]*)"/m.exec(userDirs ?? "")?.[1]?.replace(/\$HOME/g, homeDir);
+    return { appData: appDataDir ?? paths.join(env.XDG_DATA_HOME ?? paths.join(homeDir, ".local", "share"), appName),
+        documents: configured && paths.isAbsolute(configured) ? configured : paths.join(homeDir, "Documents") };
+}
+/** Native reads are isolated so cross-platform fixtures never execute registry commands. */
+export function readOptionalText({ file }, _options = {}) {
+    try {
+        return fs.readFileSync(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+function readWindowsDocuments() {
+    const output = execFileSync("reg.exe", ["query", "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\User Shell Folders", "/v", "Personal"], { encoding: "utf8", timeout: 3000, windowsHide: true });
+    return /Personal\s+REG_(?:EXPAND_)?SZ\s+(.+)/.exec(output)?.[1]?.trim();
+}
+/** OneDrive publishes account mount paths in HKCU; absent accounts are a normal empty result. */
+export function readWindowsOneDriveRoots(_required, _options = {}) {
+    try {
+        const output = execFileSync("reg.exe", ["query", "HKCU\\Software\\Microsoft\\OneDrive\\Accounts", "/s", "/v", "UserFolder"], { encoding: "utf8", timeout: 3000, windowsHide: true });
+        return [...output.matchAll(/UserFolder\s+REG_(?:EXPAND_)?SZ\s+([^\r\n]+)/g)].map((match) => match[1].trim());
+    }
+    catch (error) {
+        if (error.status === 1)
+            return [];
+        throw error;
+    }
+}
+//# sourceMappingURL=user-data-directories.js.map

package/dist/fs/verified-directory-move.d.ts

@@ -0,0 +1,37 @@
+import { type VerifiedFileGroup } from "./verified-file-relocation.js";
+import fs from "node:fs";
+/** Fingerprint relative names, entry kinds, symlink targets and file bytes without following links.
+ * This is verification, never a log of file contents. Lease files are excluded by the host.
+ * @complexity O(bytes + entries log entries), O(entries + a fixed 64 KiB read buffer) space.
+ */
+export declare function directoryFingerprint({ dir }: {
+    dir: string;
+}, { excluded, filesystem }?: {
+    excluded?: readonly string[];
+    filesystem?: typeof fs;
+}): string;
+/** Move only into an absent target. Verify before registry commit or source deletion.
+ * EXDEV uses copy/verify/retire/commit; failure restores the source and removes only our new copy.
+ * Same-filesystem failures roll the rename back. Commit must atomically update the host registry.
+ * @complexity O(bytes + entries log entries), with two verification passes.
+ */
+export declare function moveDirectoryVerified({ from, to, commit }: {
+    from: string;
+    to: string;
+    commit: () => void;
+}, { excluded, filesystem, prepareDestination, relocateFiles, verifyFile, backupId }?: {
+    excluded?: readonly string[];
+    filesystem?: typeof fs;
+    prepareDestination?: (required: {
+        path: string;
+    }) => void;
+    relocateFiles?: (required: {
+        source: string;
+        target: string;
+    }) => readonly VerifiedFileGroup[];
+    verifyFile?: (required: {
+        path: string;
+    }) => string;
+    backupId?: () => string;
+}): void;
+//# sourceMappingURL=verified-directory-move.d.ts.map

package/dist/fs/verified-directory-move.js

@@ -0,0 +1,138 @@
+import { stageVerifiedFileRelocation } from "./verified-file-relocation.js";
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+/** Fingerprint relative names, entry kinds, symlink targets and file bytes without following links.
+ * This is verification, never a log of file contents. Lease files are excluded by the host.
+ * @complexity O(bytes + entries log entries), O(entries + a fixed 64 KiB read buffer) space.
+ */
+export function directoryFingerprint({ dir }, { excluded = [], filesystem = fs } = {}) {
+    const digest = createHash("sha256");
+    function visit(relative) {
+        for (const entry of filesystem.readdirSync(path.join(dir, relative), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!relative && excluded.includes(entry.name))
+                continue;
+            const name = path.join(relative, entry.name), absolute = path.join(dir, name);
+            const stat = filesystem.lstatSync(absolute);
+            const kind = stat.isSymbolicLink() ? "link" : stat.isDirectory() ? "directory" : stat.isFile() ? "file" : "unsupported";
+            if (kind === "unsupported")
+                throw new Error(`Cannot move special filesystem entry: ${name}`);
+            digest.update(JSON.stringify([name, kind, stat.mode & 0o777]));
+            if (kind === "directory")
+                visit(name);
+            else if (kind === "link")
+                digest.update(JSON.stringify(filesystem.readlinkSync(absolute)));
+            else {
+                const fileDigest = createHash("sha256"), buffer = Buffer.allocUnsafe(64 * 1024);
+                const descriptor = filesystem.openSync(absolute, "r");
+                try {
+                    let bytes;
+                    while ((bytes = filesystem.readSync(descriptor, buffer, 0, buffer.length, null)) > 0)
+                        fileDigest.update(buffer.subarray(0, bytes));
+                }
+                finally {
+                    filesystem.closeSync(descriptor);
+                }
+                digest.update(fileDigest.digest());
+            }
+        }
+    }
+    visit("");
+    return digest.digest("hex");
+}
+/** Move only into an absent target. Verify before registry commit or source deletion.
+ * EXDEV uses copy/verify/retire/commit; failure restores the source and removes only our new copy.
+ * Same-filesystem failures roll the rename back. Commit must atomically update the host registry.
+ * @complexity O(bytes + entries log entries), with two verification passes.
+ */
+export function moveDirectoryVerified({ from, to, commit }, { excluded = [], filesystem = fs, prepareDestination, relocateFiles, verifyFile, backupId = randomUUID } = {}) {
+    const source = filesystem.realpathSync(from);
+    const target = path.resolve(to);
+    if (target === source || target.startsWith(source + path.sep))
+        throw new Error("A directory cannot be moved into itself.");
+    try {
+        filesystem.lstatSync(target);
+        throw new Error(`Move target already exists: ${target}`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const before = directoryFingerprint({ dir: source }, { excluded, filesystem });
+    let copied = false;
+    try {
+        filesystem.renameSync(source, target);
+    }
+    catch (error) {
+        if (error.code !== "EXDEV")
+            throw error;
+        filesystem.mkdirSync(target);
+        copied = true;
+        try {
+            // The host may reserve the empty destination before any commit marker or database is copied.
+            prepareDestination?.({ path: target });
+            filesystem.cpSync(source, target, { recursive: true, force: false, errorOnExist: true, preserveTimestamps: true, verbatimSymlinks: true,
+                filter: (candidate) => candidate === source || !excluded.includes(path.relative(source, candidate).split(path.sep)[0]),
+            });
+        }
+        catch (failure) {
+            filesystem.rmSync(target, { recursive: true });
+            throw failure;
+        }
+    }
+    let retiredSource;
+    let staged;
+    try {
+        if (directoryFingerprint({ dir: target }, { excluded, filesystem }) !== before)
+            throw new Error("Moved directory verification failed.");
+        if (relocateFiles) {
+            if (!verifyFile)
+                throw new Error("File relocation requires a verification port.");
+            staged = stageVerifiedFileRelocation({ groups: relocateFiles({ source, target }), verify: verifyFile }, { filesystem, backupId, backupCovered: ({ from }) => copied && path.resolve(from).startsWith(target + path.sep) });
+        }
+        if (copied) {
+            const backupRoot = path.join(path.dirname(source), `.relocation-${backupId()}-backup`);
+            const backup = path.join(backupRoot, path.basename(source));
+            if (filesystem.existsSync(backup))
+                throw new Error(`Move backup target already exists: ${backup}`);
+            // The EXDEV original becomes a recovery folder before catalog commit, never a second live
+            // site at the old path if cleanup fails. An interrupted apply leaves explicit backups.
+            filesystem.mkdirSync(backupRoot);
+            filesystem.renameSync(source, backup);
+            retiredSource = backup;
+            const fd = filesystem.openSync(backupRoot, "r");
+            try {
+                filesystem.fsyncSync(fd);
+            }
+            finally {
+                filesystem.closeSync(fd);
+            }
+        }
+        // Persist directory-name changes for same-filesystem renames as well as EXDEV retirement.
+        for (const directory of new Set([path.dirname(source), path.dirname(target)])) {
+            const fd = filesystem.openSync(directory, "r");
+            try {
+                filesystem.fsyncSync(fd);
+            }
+            finally {
+                filesystem.closeSync(fd);
+            }
+        }
+        commit();
+    }
+    catch (error) {
+        if (retiredSource)
+            filesystem.renameSync(retiredSource, source);
+        staged?.rollback();
+        if (copied)
+            filesystem.rmSync(target, { recursive: true });
+        else
+            filesystem.renameSync(target, source);
+        throw error;
+    }
+    // If deletion fails after commit, the verified target and registry remain usable; old DB live
+    // names were already retired before commit. Never roll back a registry whose commit succeeded.
+    staged?.finalize();
+    // Keep the retired EXDEV recovery folder; it is never a registered/live site path.
+}
+//# sourceMappingURL=verified-directory-move.js.map

package/dist/fs/verified-file-relocation.d.ts

@@ -0,0 +1,27 @@
+import fs from "node:fs";
+export interface VerifiedFileGroup {
+    from: string;
+    to: string;
+    sidecars: readonly string[];
+}
+/** Stage related files together while both directory identities are reserved by the host. Raw
+ * sources remain intact through inspection so even WAL/SHM bytes are retained. Verification opens only
+ * stopped databases through an injected read-only inspector; the filesystem owner never uses SQL.
+ * @complexity O(total bytes + verification cost), bounded memory via native file copies.
+ */
+export declare function stageVerifiedFileRelocation({ groups, verify }: {
+    groups: readonly VerifiedFileGroup[];
+    verify: (required: {
+        path: string;
+    }) => string;
+}, { filesystem, backupCovered, backupId }?: {
+    filesystem?: typeof fs;
+    backupCovered?: (required: {
+        from: string;
+    }) => boolean;
+    backupId?: () => string;
+}): {
+    rollback: () => void;
+    finalize: () => void;
+};
+//# sourceMappingURL=verified-file-relocation.d.ts.map

package/dist/fs/verified-file-relocation.js

@@ -0,0 +1,115 @@
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+/** Stage related files together while both directory identities are reserved by the host. Raw
+ * sources remain intact through inspection so even WAL/SHM bytes are retained. Verification opens only
+ * stopped databases through an injected read-only inspector; the filesystem owner never uses SQL.
+ * @complexity O(total bytes + verification cost), bounded memory via native file copies.
+ */
+export function stageVerifiedFileRelocation({ groups, verify }, { filesystem = fs, backupCovered = () => false, backupId = randomUUID } = {}) {
+    const created = [], retired = [], markers = [], redundantBackups = [];
+    const backupSuffix = `.relocation-${backupId()}-backup`;
+    const copyExclusive = (from, to) => {
+        // Reserve before copying so a disk-full failure is still ours to clean up. COPYFILE_EXCL
+        // alone may create a partial file before throwing, which cannot be tracked after the fact.
+        const fd = filesystem.openSync(to, "wx");
+        created.push(to);
+        filesystem.closeSync(fd);
+        filesystem.copyFileSync(from, to);
+        const copied = filesystem.openSync(to, "r+");
+        try {
+            filesystem.fsyncSync(copied);
+        }
+        finally {
+            filesystem.closeSync(copied);
+        }
+        syncParent(to);
+    };
+    const syncParent = (file) => {
+        // Directory fsync persists retirement/marker ordering before the host commits its catalog.
+        const fd = filesystem.openSync(path.dirname(file), "r");
+        try {
+            filesystem.fsyncSync(fd);
+        }
+        finally {
+            filesystem.closeSync(fd);
+        }
+    };
+    const rollback = () => {
+        for (const item of [...retired].reverse()) {
+            filesystem.renameSync(item.backup, item.from);
+            syncParent(item.from);
+        }
+        for (const file of [...created].reverse()) {
+            filesystem.rmSync(file, { force: true });
+            syncParent(file);
+        }
+    };
+    try {
+        for (const group of groups) {
+            const pairs = ["", ...group.sidecars].filter((suffix) => filesystem.existsSync(group.from + suffix))
+                .map((suffix) => ({ from: group.from + suffix, to: group.to + suffix }));
+            for (const pair of pairs)
+                if (!filesystem.lstatSync(pair.from).isFile())
+                    throw new Error(`Database move requires a regular file: ${pair.from}`);
+            filesystem.mkdirSync(path.dirname(group.to), { recursive: true });
+            const moving = path.resolve(group.from) !== path.resolve(group.to);
+            // A directory rename already carries unchanged DB paths atomically; verify those bytes
+            // without copying them. For a file move the original inode becomes the sole backup after
+            // verification: another full destination backup doubles storage without rollback benefit.
+            // Cross-volume directory moves already retain the untouched original directory. A copied
+            // DB inside that destination needs no second full backup of the same bytes.
+            if (moving) {
+                const marker = group.from + ".home2-relocation.json";
+                const fd = filesystem.openSync(marker, "wx");
+                created.push(marker);
+                markers.push(marker);
+                try {
+                    filesystem.writeFileSync(fd, JSON.stringify({ to: group.to, backup: group.from + backupSuffix }));
+                    filesystem.fsyncSync(fd);
+                }
+                finally {
+                    filesystem.closeSync(fd);
+                }
+                syncParent(marker);
+            }
+            const before = verify({ path: group.from });
+            for (const pair of pairs) {
+                if (path.resolve(pair.from) === path.resolve(pair.to))
+                    continue;
+                // A destination collision aborts; never overwrite another site's data or an old move.
+                copyExclusive(pair.from, pair.to);
+            }
+            if (verify({ path: group.to }) !== before)
+                throw new Error(`Database row counts changed while moving ${path.basename(group.to)}.`);
+            // Retire old live names BEFORE commit. Finalization removes recovery markers and redundant copies covered by the retained original: a crash
+            // or cleanup failure cannot leave two independently writable database names after commit.
+            if (moving)
+                for (const pair of pairs) {
+                    const backup = pair.from + backupSuffix;
+                    if (filesystem.existsSync(backup))
+                        throw new Error(`Database backup target already exists: ${backup}`);
+                    filesystem.renameSync(pair.from, backup);
+                    retired.push({ from: pair.from, backup });
+                    if (backupCovered({ from: pair.from }))
+                        redundantBackups.push(backup);
+                    syncParent(pair.from);
+                }
+        }
+    }
+    catch (error) {
+        rollback();
+        throw error;
+    }
+    return { rollback, finalize: () => {
+            for (const backup of redundantBackups) {
+                filesystem.rmSync(backup);
+                syncParent(backup);
+            }
+            for (const marker of markers) {
+                filesystem.rmSync(marker);
+                syncParent(marker);
+            }
+        } };
+}
+//# sourceMappingURL=verified-file-relocation.js.map

package/dist/fs/workspace-directory.d.ts

@@ -0,0 +1,19 @@
+import type { DirectoryRecord } from "./directory-registry.js";
+/** Shared selection policy for CLI/dev hosts. A registry ID disambiguates adopted paths;
+ * a basename selects the home first. No initialized home site preserves the supplied fallback.
+ * @complexity O(n) registered/child directories and validation probes.
+ */
+export declare function selectWorkspaceDirectory({ home, entries, fallback, selected, roots, listDirectories, isInitialized }: {
+    home: string;
+    entries: readonly DirectoryRecord[];
+    fallback: string;
+    selected?: string | undefined;
+    roots?: readonly string[];
+    listDirectories: (required: {
+        root: string;
+    }) => readonly string[];
+    isInitialized: (required: {
+        path: string;
+    }) => boolean;
+}, _options?: {}): string;
+//# sourceMappingURL=workspace-directory.d.ts.map

package/dist/fs/workspace-directory.js

@@ -0,0 +1,23 @@
+import path from "node:path";
+/** Shared selection policy for CLI/dev hosts. A registry ID disambiguates adopted paths;
+ * a basename selects the home first. No initialized home site preserves the supplied fallback.
+ * @complexity O(n) registered/child directories and validation probes.
+ */
+export function selectWorkspaceDirectory({ home, entries, fallback, selected, roots = [home], listDirectories, isInitialized }, _options = {}) {
+    if (selected !== undefined) {
+        const byId = entries.find((entry) => entry.id === selected);
+        if (byId)
+            return byId.path;
+        const inHome = path.join(home, selected);
+        if (isInitialized({ path: inHome }))
+            return inHome;
+        const matches = [...new Set([...entries.filter((entry) => path.basename(entry.path) === selected).map((entry) => entry.path),
+                ...roots.filter((root) => root !== home).map((root) => path.join(root, selected)).filter((dir) => isInitialized({ path: dir }))])];
+        if (matches.length > 1)
+            throw new Error("More than one registered directory has this name. Select its registry ID.");
+        return matches[0] ?? path.join(path.dirname(fallback), selected);
+    }
+    const candidates = [...entries.filter((entry) => path.dirname(entry.path) === home).sort((a, b) => (b.lastOpened ? Date.parse(b.lastOpened) : 0) - (a.lastOpened ? Date.parse(a.lastOpened) : 0)).map((entry) => entry.path), ...roots.flatMap((root) => listDirectories({ root }))];
+    return candidates.find((dir) => isInitialized({ path: dir })) ?? fallback;
+}
+//# sourceMappingURL=workspace-directory.js.map