@jini-ai/platform 0.5.2 → 0.5.4

package/dist/fs/directory-workspace.js

@@ -0,0 +1,266 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { createDurableJsonFile, createNodeDurableJsonPorts, updateDurableJsonFiles } from "./durable-json.js";
+import { createDirectoryUserConfig, validateDirectoryUserConfig } from "./directory-user-config.js";
+import { resolveDirectoryHome } from "./directory-home.js";
+import { createDirectoryRegistry } from "./directory-registry.js";
+import { createDirectoryRunningLock } from "./directory-running-lock.js";
+/** Node assembly only. Policy modules receive explicit filesystem, clock and process ports.
+ * Settings live outside the selected home so changing the setting never loses the pointer.
+ * Reading a missing home/catalog does not create it. Opt-in registry recovery may prune known
+ * pollution on load; read-only hosts omit that policy. Mutations use the durable JSON owner.
+ * @complexity O(n) registry records, O(1) settings/lease operations.
+ */
+export function createNodeDirectoryWorkspace({ homeDir, defaultFolder, envName, settingsFile, registryName, runningName, userConfig, registryRecovery }, { env = process.env, cwd = process.cwd(), ports = createNodeDurableJsonPorts({}), canonicalPath = canonicalNodeDirectory, ...directoryOptions } = {}) {
+    const fileAt = (filePath) => createDurableJsonFile({ ...ports, filePath, notices: {
+            prefix: "Directory workspace", lockTimeout: ({ lockPath }) => `Timed out waiting for file lock: ${lockPath}`,
+        } }, { staleMs: Infinity });
+    const config = userConfig ? createDirectoryUserConfig({ homeDir, defaultFolder, envName, policy: userConfig,
+        fileAt, canonicalPath, removeFile: ({ filePath }) => ports.filesystem.rmSync(filePath, { force: true }), isDirectory: (file) => ports.filesystem.statSync(file).isDirectory(), exists: (file) => { try {
+            ports.filesystem.statSync(file);
+            return true;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return false;
+            throw error;
+        } },
+    }, { env, cwd, report: (message) => ports.report.error({ message }), ...directoryOptions }) : undefined;
+    const settings = fileAt(config?.filePath ?? settingsFile);
+    function readSetting() {
+        const read = settings.read({});
+        if (read.state === "missing")
+            return undefined;
+        if (read.state !== "ok" || typeof read.value?.home !== "string")
+            throw new Error("The directory home setting is unreadable.");
+        return read.value.home;
+    }
+    const legacyHome = () => canonicalPath({ path: resolveDirectoryHome({ homeDir, defaultFolder, envName, env, setting: env[envName] === undefined ? readSetting() : undefined }, { cwd }) });
+    const home = () => config?.read({}).sitesHome ?? legacyHome();
+    const fixturePattern = registryRecovery ? new RegExp(registryRecovery.fixtureIdPattern.source, registryRecovery.fixtureIdPattern.flags.replace(/[gy]/g, "")) : undefined;
+    const atHome = () => createDirectoryRegistry({ file: fileAt(path.join(config?.appData ?? home(), registryName)), canonicalPath }, registryRecovery ? {
+        discard: ({ entry }) => {
+            const absolute = canonicalPath({ path: entry.path });
+            // HOME may itself be under tmp (desktop E2E), and a selected sites home may live there.
+            // Neither is pollution, including temporarily unavailable descendants and symlink aliases.
+            const protectedPath = [homeDir, home()].some((root) => {
+                const relative = path.relative(canonicalPath({ path: root }), absolute);
+                return relative === "" || (!relative.startsWith(".." + path.sep) && relative !== ".." && !path.isAbsolute(relative));
+            });
+            if (protectedPath)
+                return false;
+            const temporary = (registryRecovery.temporaryRoots ?? ["/private/tmp", "/tmp", os.tmpdir()]).some((root) => {
+                const relative = path.relative(canonicalPath({ path: root }), absolute);
+                return relative === "" || (!relative.startsWith(".." + path.sep) && relative !== ".." && !path.isAbsolute(relative));
+            });
+            if (!temporary && !fixturePattern.test(entry.id))
+                return false;
+            // A live temp-path folder is a real site. Only ENOENT proves this candidate is stale.
+            try {
+                ports.filesystem.statSync(entry.path);
+                return false;
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return true;
+                throw error;
+            }
+        },
+        reportDiscarded: ({ entries }) => ports.report.error({ message: `Directory workspace: removed ${entries.length} test/temporary catalog entries: ${entries.map((entry) => entry.id).join(", ")}` }),
+    } : {});
+    // Read old catalogs without modifying sites. Import only under the settings lane on a mutation;
+    // dry-run and startup discovery can inspect the old state without creating app-data files.
+    const oldCatalogs = () => {
+        // An explicit host profile is an isolation boundary. Importing HOME's legacy settings/catalog
+        // would silently enroll the owner's sites (and potentially read real app-data) into QA profiles.
+        if (directoryOptions.appDataDir !== undefined)
+            return [];
+        if (!config || !userConfig?.legacySettingsFile)
+            return [];
+        const legacy = fileAt(userConfig.legacySettingsFile).read({});
+        if (legacy.state === "unreadable")
+            throw new Error("Legacy directory setting is unreadable; nothing was overwritten.");
+        const oldHome = legacy.state === "ok" ? legacy.value?.home : path.join(homeDir, userConfig.legacyDefaultFolder ?? defaultFolder);
+        if (typeof oldHome !== "string")
+            throw new Error("Legacy directory setting has an invalid home.");
+        return [...new Set([oldHome, ...config.legacyHomes({}), home()])].map((root) => createDirectoryRegistry({ file: fileAt(path.join(root, registryName)), canonicalPath }));
+    };
+    const importOldCatalog = () => {
+        const current = atHome();
+        if (!config || current.hasMigration({ migration: "app-data-catalog-v1" }))
+            return;
+        const previous = oldCatalogs();
+        current.merge({ entries: previous.flatMap((catalog) => catalog.list({})), migrations: previous.flatMap((catalog) => catalog.migrations({})), migration: "app-data-catalog-v1" });
+    };
+    const mutate = (operation) => settings.withLock({ critical: () => { importOldCatalog(); return operation(); } });
+    // Serialize pointer changes with catalog mutations. A caller that obtained a registry before
+    // settings changed must still write into the current home, never strand a late registration.
+    const registry = {
+        list: (required, options = {}) => {
+            const current = atHome();
+            if (!config || current.hasMigration({ migration: "app-data-catalog-v1" }))
+                return current.list(required, options);
+            const rows = [...oldCatalogs().flatMap((catalog) => catalog.list(required, options)), ...current.list(required, options)];
+            return [...new Map(rows.map((row) => [canonicalPath({ path: row.path }), row])).values()];
+        },
+        hasMigration: (required, options = {}) => atHome().hasMigration(required, options),
+        migrations: (required, options = {}) => atHome().migrations(required, options),
+        merge: (required, options = {}) => mutate(() => atHome().merge(required, options)),
+        opened: (required, options = {}) => mutate(() => atHome().opened(required, options)),
+        remove: (required, options = {}) => mutate(() => atHome().remove(required, options)),
+        relocate: (required, options = {}) => mutate(() => atHome().relocate(required, options)),
+    };
+    return {
+        homeDir,
+        config: (_required, _options = {}) => thisConfig(),
+        updateConfig: (required, options = {}) => {
+            if (!config)
+                throw new Error("User config policy is not configured.");
+            config.update(required, options);
+            return thisConfig();
+        },
+        updateRoots: (required, options = {}) => {
+            if (!config)
+                throw new Error("User config policy is not configured.");
+            config.updateRoots(required, options);
+            return thisConfig();
+        },
+        roots: (_required, _options = {}) => config?.roots({}) ?? [home()],
+        databasePath: (required, options = {}) => {
+            if (!config)
+                return path.join(required.dir, required.filename);
+            return config.databasePath(required, options);
+        },
+        /** Only the implicit nested home may create its application parent below mounted Documents.
+         * Custom homes still require their immediate parent, so an absent volume is never fabricated.
+         */
+        homeAvailable: (_required, _options = {}) => {
+            const selected = home();
+            const parent = config?.legacyHomes({}, { includeMissing: true }).includes(path.dirname(selected)) ? path.dirname(path.dirname(selected)) : path.dirname(selected);
+            try {
+                return ports.filesystem.statSync(parent).isDirectory();
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return false;
+                throw error;
+            }
+        },
+        legacyHomes: (_required, _options = {}) => config?.legacyHomes({}) ?? [],
+        /** Commit a verified move's catalog and every injected path reference as one locked unit.
+         * Uses the registry owner to preserve identity/collision rules; settings retain env precedence.
+         * @complexity O(total catalog/reference bytes), with rollback snapshots in memory.
+         */
+        relocate({ from, to, entry, references = [] }, _options = {}) {
+            if (!config)
+                throw new Error("Relocation requires user config policy.");
+            const repoint = (dir) => {
+                const current = canonicalPath({ path: dir });
+                if (current === path.dirname(home()) && config.legacyHomes({}).includes(current))
+                    return home();
+                return current === from || current.startsWith(from + path.sep) ? path.join(to, path.relative(from, current)) : dir;
+            };
+            updateDurableJsonFiles({ fileAt, remove: ({ filePath }) => ports.filesystem.rmSync(filePath, { force: true }), changes: [
+                    { filePath: config.filePath, transform: (value) => {
+                            if (value === undefined)
+                                return undefined;
+                            const saved = validateDirectoryUserConfig({ value });
+                            // Persist only the saved pointer's nesting transition. Environment overrides belong
+                            // to this process and must never become another host's permanent configuration.
+                            const savedHome = saved.sitesHome === undefined ? undefined : resolveDirectoryHome({ homeDir, defaultFolder, envName, env: {}, setting: saved.sitesHome }, { cwd, ...(directoryOptions.platform ? { platform: directoryOptions.platform } : {}) });
+                            const paths = directoryOptions.platform === "win32" ? path.win32 : path;
+                            return { ...saved, ...(saved.sitesHome && savedHome && config.legacyHomes({}, { includeMissing: true }).includes(canonicalPath({ path: savedHome })) ? { sitesHome: paths.join(saved.sitesHome, userConfig.defaultSubfolder) } : {}),
+                                ...(saved.siteRoots ? { siteRoots: [...new Set(saved.siteRoots.map(repoint))] } : {}) };
+                        } },
+                    { filePath: path.join(config.appData, registryName), transform: (value) => {
+                            // A transaction-local file adapter lets the registry's existing validation and merge
+                            // own this schema without re-acquiring the physical lock already held above.
+                            let state = value;
+                            const staged = createDirectoryRegistry({ canonicalPath, file: {
+                                    read: () => state === undefined ? { state: "missing" } : { state: "ok", value: state },
+                                    write: ({ value: next }) => { state = next; }, withLock: ({ critical }) => critical(),
+                                    tempPath: () => "", quarantine: () => false,
+                                } });
+                            if (!staged.hasMigration({ migration: "app-data-catalog-v1" })) {
+                                const previous = oldCatalogs();
+                                staged.merge({ entries: previous.flatMap((catalog) => catalog.list({})), migrations: previous.flatMap((catalog) => catalog.migrations({})), migration: "app-data-catalog-v1" });
+                            }
+                            const existing = staged.list({}).find((row) => row.path === from || row.id === entry.id);
+                            if (existing && existing.path !== from && existing.path !== to)
+                                throw new Error("Site identity is registered at an unrelated path.");
+                            if (!existing)
+                                staged.merge({ entries: [{ ...entry, path: from }] });
+                            staged.relocate({ from, to });
+                            return state;
+                        } }, ...references,
+                ] });
+        },
+        home: (_required, _options = {}) => home(),
+        setHome({ path: dir }, _options = {}) {
+            if (env[envName] !== undefined)
+                throw new Error(`${envName} overrides this setting. Unset it before changing the directory home.`);
+            if (config) {
+                config.update({ patch: { sitesHome: dir } });
+                return home();
+            }
+            const selected = canonicalPath({ path: resolveDirectoryHome({ homeDir, defaultFolder, envName, env: {}, setting: dir }, { cwd }) });
+            settings.withLock({ critical: () => {
+                    const previous = createDirectoryRegistry({ file: fileAt(path.join(home(), registryName)), canonicalPath });
+                    const target = createDirectoryRegistry({ file: fileAt(path.join(selected, registryName)), canonicalPath });
+                    target.merge({ entries: previous.list({}), migrations: previous.migrations({}) });
+                    settings.write({ value: { home: selected } });
+                } });
+            return home();
+        },
+        registry: (_required, _options = {}) => registry,
+        running: ({ path: dir }, _options = {}) => {
+            const filePath = config?.runningPath({ dir }) ?? path.join(canonicalPath({ path: dir }), runningName);
+            const current = createDirectoryRunningLock({ file: fileAt(filePath), isAlive: ports.process.isAlive,
+                remove: () => ports.filesystem.rmSync(filePath, { force: true }) }, { ...(ports.process.bootIdentity ? { bootIdentity: ports.process.bootIdentity } : {}) });
+            if (!config)
+                return current;
+            const legacyPath = path.join(canonicalPath({ path: dir }), runningName);
+            const legacy = createDirectoryRunningLock({ file: fileAt(legacyPath), isAlive: ports.process.isAlive,
+                remove: () => ports.filesystem.rmSync(legacyPath, { force: true }) }, { ...(ports.process.bootIdentity ? { bootIdentity: ports.process.bootIdentity } : {}) });
+            return { ...current,
+                // Older servers may still own a site-local lease. Observe it without moving/editing it;
+                // claim serializes against new clients and refuses the old live owner.
+                peek: (_required, _options = {}) => legacy.peek({}) ?? current.peek({}),
+                read: (_required, _options = {}) => legacy.peek({}) ?? current.read({}),
+                claim: (required, options = {}) => settings.withLock({ critical: () => {
+                        const existing = legacy.peek({});
+                        if (existing)
+                            return { acquired: false, record: existing };
+                        return current.claim(required, options);
+                    } }),
+            };
+        },
+        claim({ path: dir, app, port = 0, scheme = "http" }, _options = {}) {
+            const lock = this.running({ path: dir });
+            return lock.claim({ record: { pid: ports.process.pid, port, app, scheme, started: new Date(ports.clock.nowMs()).toISOString(), token: randomUUID() } });
+        },
+    };
+    function thisConfig() {
+        if (!config)
+            throw new Error("User config policy is not configured.");
+        return { ...config.read({}), defaultRoots: config.defaultRoots({}), extraRoots: config.extraRoots({}), configPath: config.filePath, appData: config.appData, warning: config.syncWarning({}),
+            overrides: { sitesHome: env[envName] !== undefined, siteRoots: env[userConfig.rootsEnvName] !== undefined } };
+    }
+}
+/** Canonicalize existing ancestors without creating the selected directory. */
+function canonicalNodeDirectory({ path: dir }, _options = {}) {
+    try {
+        return fs.realpathSync(dir);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        // Resolve the nearest existing ancestor too: a not-yet-created home may sit below a
+        // symlink (notably /var on macOS) and must compare equal before and after creation.
+        const absolute = path.resolve(dir), parent = path.dirname(absolute);
+        return parent === absolute ? absolute : path.join(canonicalNodeDirectory({ path: parent }), path.basename(absolute));
+    }
+}
+//# sourceMappingURL=directory-workspace.js.map

package/dist/fs/durable-json.d.ts

@@ -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 { type BootIdentity } from "./boot-identity.js";
 import nodeFs from "node:fs";
 import type { Clock } from "@jini-ai/core/primitives";
 export type JsonFileRead = {
@@ -36,6 +37,7 @@ export interface DurableJsonPorts {
         isAlive(required: {
             pid: number;
         }): boolean;
+        bootIdentity?: () => BootIdentity | undefined;
     };
     random: {
         token(_required: Record<string, never>): string;
@@ -86,4 +88,23 @@ export declare function salvageJsonPrefix({ text }: {
 }, { maxAttempts }?: {
     maxAttempts?: number;
 }): unknown;
+export interface DurableJsonChange {
+    filePath: string;
+    /** Missing optional references stay missing; transforms must reject unreadable schemas. */
+    transform: (value: unknown | undefined) => unknown | undefined;
+}
+/** 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 declare function updateDurableJsonFiles({ changes, fileAt, remove }: {
+    changes: readonly DurableJsonChange[];
+    fileAt: (path: string) => DurableJsonFile;
+    remove: (required: {
+        filePath: string;
+    }) => void;
+}, _options?: {}): void;
 //# sourceMappingURL=durable-json.d.ts.map

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