@jini-ai/platform 0.5.2 → 0.5.3

package/dist/fs/directory-user-config.js

@@ -0,0 +1,183 @@
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { resolveDirectoryHome } from "./directory-home.js";
+import { resolveUserDataDirectories } from "./user-data-directories.js";
+import { detectDirectorySync } from "./directory-sync.js";
+/** One atomic settings owner for multiple processes. Existing DB files always win over preferences:
+ * changing placement controls new databases, never silently moves or abandons existing ones.
+ * @complexity O(n) canonicalizations for n roots; DB lookup probes three fixed locations.
+ */
+export function createDirectoryUserConfig({ homeDir, defaultFolder, envName, policy, fileAt, canonicalPath, exists, isDirectory, removeFile }, { env = process.env, cwd = process.cwd(), report = console.warn, ...directoryOptions } = {}) {
+    const directories = resolveUserDataDirectories({ homeDir, appName: policy.appName }, { ...directoryOptions, env });
+    const paths = directoryOptions.platform === "win32" ? path.win32 : path;
+    const defaultHome = paths.join(directories.documents, defaultFolder, policy.defaultSubfolder ?? "");
+    const localHome = paths.join(homeDir, defaultFolder, policy.defaultSubfolder ?? "");
+    const legacyHomePaths = policy.defaultSubfolder ? [paths.join(directories.documents, defaultFolder), paths.join(homeDir, defaultFolder)] : [];
+    const filePath = paths.join(directories.appData, "config.json"), file = fileAt(filePath);
+    const expand = (value) => canonicalPath({ path: resolveDirectoryHome({ homeDir, defaultFolder, envName, env: {}, setting: value }, { cwd, ...(directoryOptions.platform ? { platform: directoryOptions.platform } : {}) }) });
+    const distinct = (values) => [...new Set(values.map(expand))];
+    const legacyHomes = distinct(legacyHomePaths);
+    function stored(locked = false) {
+        const result = file.read({});
+        if (result.state === "missing")
+            return {};
+        if (result.state === "ok") {
+            try {
+                return validateDirectoryUserConfig({ value: result.value });
+            }
+            catch { /* preserve invalid settings too */ }
+        }
+        // Bad settings must not stop boot, and read-only discovery/dry-run must not mutate settings.
+        // Preserve the original on reads; the next mutation quarantines it under the existing lock.
+        if (!locked) {
+            report(`User config is unreadable: ${filePath}. Using defaults; the original was left untouched.`);
+            return {};
+        }
+        if (!file.quarantine({ notice: { label: "user config", consequence: "Using default settings; existing databases keep their locations." } })) {
+            throw new Error(`User config is unreadable: ${filePath}. Nothing was overwritten.`);
+        }
+        return {};
+    }
+    const syncProvider = (sitesHome) => detectDirectorySync({ dir: sitesHome, homeDir, documents: directories.documents }, { ...directoryOptions, env, canonicalPath });
+    function read(_required, _options = {}) {
+        const saved = stored();
+        // Old default pointers follow the owner-selected nesting rule; arbitrary custom homes and
+        // explicit environment overrides keep their contracts. Reading never moves user folders.
+        const savedHome = saved.sitesHome === undefined ? defaultHome : expand(saved.sitesHome);
+        const nestedHome = legacyHomes.includes(savedHome) ? paths.join(savedHome, policy.defaultSubfolder) : savedHome;
+        const sitesHome = expand(env[envName] ?? nestedHome);
+        const sync = syncProvider(sitesHome);
+        return {
+            sitesHome,
+            siteRoots: distinct(env[policy.rootsEnvName] !== undefined ? env[policy.rootsEnvName].split(",").map((root) => root.trim()).filter(Boolean) : saved.siteRoots ?? policy.sourceRoots ?? []),
+            databases: saved.databases ?? (sync && sync !== "iCloud" ? "appData" : "inSite"),
+        };
+    }
+    function update({ patch }, { transform } = {}) {
+        // Compute incremental root changes inside the same lock as the write: a sibling process's
+        // added root must not disappear because this caller previously read an older array.
+        file.withLock({ critical: () => {
+                const previous = stored(true);
+                const checked = validateDirectoryUserConfig({ value: transform ? transform(read({}), previous) : patch });
+                // Prefer explicit settings, never coerce an existing regular file into a directory.
+                for (const directory of [checked.sitesHome, ...(checked.siteRoots ?? [])]) {
+                    if (directory === undefined)
+                        continue;
+                    const expanded = expand(directory);
+                    if (exists(expanded) && !isDirectory(expanded))
+                        throw new Error(`Sites folder is not a directory: ${directory}`);
+                }
+                if (checked.sitesHome !== undefined && env[envName] !== undefined)
+                    throw new Error(`${envName} overrides this setting. Unset it before changing the directory home.`);
+                if (checked.siteRoots !== undefined && env[policy.rootsEnvName] !== undefined)
+                    throw new Error(`${policy.rootsEnvName} overrides this setting. Unset it before changing site roots.`);
+                const next = { ...previous, ...checked,
+                    ...(checked.sitesHome !== undefined ? { sitesHome: expand(checked.sitesHome) } : {}),
+                    ...(checked.siteRoots !== undefined ? { siteRoots: distinct(checked.siteRoots) } : {}),
+                };
+                // Empty incremental extras restore implicit defaults instead of persisting those defaults.
+                if (transform && checked.siteRoots?.length === 0)
+                    delete next.siteRoots;
+                // With no other saved settings, removing the final extra also restores an absent config.
+                // The Node assembly supplies removal; non-Node adapters may retain the equivalent {}.
+                if (transform && Object.keys(next).length === 0 && removeFile)
+                    removeFile({ filePath });
+                else
+                    file.write({ value: next });
+            } });
+        return read({});
+    }
+    function updateRoots({ add = [], remove = [] }, _options = {}) {
+        return update({ patch: {} }, { transform: (current, saved) => {
+                const protectedRoots = new Set(distinct([current.sitesHome, ...(policy.sourceRoots ?? [])]));
+                const excluded = new Set(distinct(remove));
+                return { siteRoots: distinct([...(saved.siteRoots ?? []), ...add]).filter((root) => !excluded.has(root) && !protectedRoots.has(root)) };
+            } });
+    }
+    function databasePath({ dir, id, filename, placement }, _options = {}) {
+        if (path.basename(filename) !== filename || !filename.endsWith(".db"))
+            throw new Error("A database filename must be a .db basename.");
+        const inSite = path.join(dir, "data.nosync", filename), legacy = path.join(dir, filename);
+        if (!/^[a-zA-Z0-9_-]+$/.test(id)) {
+            if (!placement && exists(legacy))
+                return legacy;
+            throw new Error("A database directory requires a safe, stable site identity.");
+        }
+        const appData = path.join(directories.appData, "databases", id, filename);
+        if (placement)
+            return placement === "inSite" ? inSite : appData;
+        const candidates = [legacy, inSite, appData];
+        // A move journal is written before copying; the old name stays authoritative until verification
+        // retires it. Recovery never guesses from two DB sizes/timestamps or asks users to delete data.
+        for (const source of candidates) {
+            const markerPath = source + ".home2-relocation.json", marker = fileAt(markerPath).read({});
+            if (marker.state === "missing")
+                continue;
+            const target = marker.state === "ok" ? marker.value?.to : undefined;
+            if (typeof target !== "string" || !candidates.includes(target))
+                throw new Error(`Interrupted database move has an invalid recovery marker: ${markerPath}. Restore the pre-move backup before starting.`);
+            const namedBackup = marker.state === "ok" ? marker.value?.backup : undefined;
+            // Old markers use the fixed home2 name; new moves identify their unique backup. Admit
+            // only a sibling of this source so malformed metadata cannot supply unrelated evidence.
+            if (namedBackup !== undefined && (typeof namedBackup !== "string" || path.dirname(namedBackup) !== path.dirname(source) || !namedBackup.startsWith(source + ".relocation-") || !namedBackup.endsWith("-backup")))
+                throw new Error(`Interrupted database move has an invalid recovery marker: ${markerPath}. Restore the pre-move backup before starting.`);
+            const backup = typeof namedBackup === "string" ? namedBackup : source + ".home2-backup";
+            const authoritative = exists(source) ? source : exists(backup) && exists(target) ? target : undefined;
+            if (!authoritative)
+                throw new Error(`Interrupted database move needs recovery: ${markerPath}. Restore the pre-move backup before starting.`);
+            report(`Recovered interrupted database move using ${authoritative}. Keep the backup files (${backup}); finish the move before changing database placement.`);
+            return authoritative;
+        }
+        const present = candidates.filter(exists);
+        if (present.length > 1)
+            throw new Error(`Multiple copies of ${filename} exist for this site. Choose the authoritative database before starting it.`);
+        if (present[0])
+            return present[0];
+        // A missing chat DB follows an existing content DB even after the user changes preferences.
+        if (filename !== "content.db") {
+            const content = databasePath({ dir, id, filename: "content.db" });
+            return path.join(path.dirname(content), filename);
+        }
+        return read({}).databases === "inSite" ? inSite : appData;
+    }
+    return { read, update, updateRoots, databasePath, filePath, ...directories,
+        // Discovery/catalog callers list real old homes. Pointer normalization and creation admission
+        // may inspect the supported spellings even before their directories have been created.
+        legacyHomes: (_required, { includeMissing = false } = {}) => distinct(legacyHomes).filter((root) => includeMissing || (exists(root) && isDirectory(root))),
+        defaultRoots: (_required, _options = {}) => distinct(policy.sourceRoots ?? []),
+        extraRoots: (_required, _options = {}) => distinct(env[policy.rootsEnvName] !== undefined ? read({}).siteRoots : stored().siteRoots ?? []),
+        roots: (_required, _options = {}) => {
+            const config = read({}), parent = paths.dirname(config.sitesHome);
+            // Discover only the selected home's existing former level. Scanning another old home
+            // crosses the local/synced boundary and admits broad or absent roots at every boot.
+            const formerRoots = legacyHomes.includes(parent) && exists(parent) && isDirectory(parent) ? [parent] : [];
+            return distinct([config.sitesHome, ...formerRoots, ...(policy.sourceRoots ?? []), ...config.siteRoots]);
+        },
+        runningPath: ({ dir }, _options = {}) => path.join(directories.appData, "running", createHash("sha256").update(canonicalPath({ path: dir })).digest("hex") + ".json"),
+        syncWarning: (_required, _options = {}) => {
+            const config = read({});
+            const sync = syncProvider(config.sitesHome);
+            if (!sync || sync === "iCloud")
+                return null;
+            return { provider: sync, message: config.databases === "appData" ? `${sync} syncs the sites folder. New databases use OS app-data for safety. Site folders are not self-contained: include their app-data databases when transferring them.` : `${sync} syncs the sites folder. It does not honor data.nosync; syncing live SQLite databases can corrupt them. Use app-data databases or a local sites folder.`, localHome };
+        },
+    };
+}
+/** Validate only the three public settings; reject arrays, unknown fields and invalid enums.
+ * @complexity O(n) root strings. No I/O or mutation.
+ */
+export function validateDirectoryUserConfig({ value }, _options = {}) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("User config must be an object.");
+    const row = value;
+    if (Object.keys(row).some((key) => !["sitesHome", "siteRoots", "databases"].includes(key)))
+        throw new Error("Unknown user config setting.");
+    if (row.sitesHome !== undefined && (typeof row.sitesHome !== "string" || !row.sitesHome.trim()))
+        throw new Error("sitesHome must name a directory.");
+    if (row.siteRoots !== undefined && (!Array.isArray(row.siteRoots) || !row.siteRoots.every((root) => typeof root === "string" && root.trim())))
+        throw new Error("siteRoots must be an array of directory paths.");
+    if (row.databases !== undefined && row.databases !== "inSite" && row.databases !== "appData")
+        throw new Error('databases must be "inSite" or "appData".');
+    return row;
+}
+//# sourceMappingURL=directory-user-config.js.map

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

@@ -0,0 +1,132 @@
+import { type DurableJsonPorts, type DurableJsonChange } from "./durable-json.js";
+import { type DirectoryUserConfigPolicy, type DirectoryUserConfig } from "./directory-user-config.js";
+import type { UserDirectoryOptions } from "./user-data-directories.js";
+import { type DirectoryRegistry } from "./directory-registry.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 declare function createNodeDirectoryWorkspace({ homeDir, defaultFolder, envName, settingsFile, registryName, runningName, userConfig, registryRecovery }: {
+    homeDir: string;
+    defaultFolder: string;
+    envName: string;
+    settingsFile: string;
+    registryName: string;
+    runningName: string;
+    userConfig?: DirectoryUserConfigPolicy;
+    /** Opt-in host recovery of known test pollution; missing user directories alone never qualify. */
+    registryRecovery?: {
+        fixtureIdPattern: RegExp;
+        temporaryRoots?: readonly string[];
+    };
+}, { env, cwd, ports, canonicalPath, ...directoryOptions }?: UserDirectoryOptions & {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    ports?: DurableJsonPorts;
+    canonicalPath?: (required: {
+        path: string;
+    }) => string;
+}): {
+    homeDir: string;
+    config: (_required: Record<string, never>, _options?: {}) => {
+        defaultRoots: string[];
+        extraRoots: string[];
+        configPath: string;
+        appData: string;
+        warning: {
+            provider: "OneDrive" | "Dropbox" | "Google Drive";
+            message: string;
+            localHome: string;
+        } | null;
+        overrides: {
+            sitesHome: boolean;
+            siteRoots: boolean;
+        };
+        sitesHome: string;
+        siteRoots: string[];
+        databases: "inSite" | "appData";
+    };
+    updateConfig: (required: {
+        patch: Partial<DirectoryUserConfig>;
+    }, options?: {}) => {
+        defaultRoots: string[];
+        extraRoots: string[];
+        configPath: string;
+        appData: string;
+        warning: {
+            provider: "OneDrive" | "Dropbox" | "Google Drive";
+            message: string;
+            localHome: string;
+        } | null;
+        overrides: {
+            sitesHome: boolean;
+            siteRoots: boolean;
+        };
+        sitesHome: string;
+        siteRoots: string[];
+        databases: "inSite" | "appData";
+    };
+    updateRoots: (required: {
+        add?: readonly string[];
+        remove?: readonly string[];
+    }, options?: {}) => {
+        defaultRoots: string[];
+        extraRoots: string[];
+        configPath: string;
+        appData: string;
+        warning: {
+            provider: "OneDrive" | "Dropbox" | "Google Drive";
+            message: string;
+            localHome: string;
+        } | null;
+        overrides: {
+            sitesHome: boolean;
+            siteRoots: boolean;
+        };
+        sitesHome: string;
+        siteRoots: string[];
+        databases: "inSite" | "appData";
+    };
+    roots: (_required: Record<string, never>, _options?: {}) => string[];
+    databasePath: (required: {
+        dir: string;
+        id: string;
+        filename: string;
+        placement?: DirectoryUserConfig["databases"];
+    }, options?: {}) => string;
+    /** 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: Record<string, never>, _options?: {}) => boolean;
+    legacyHomes: (_required: Record<string, never>, _options?: {}) => string[];
+    /** 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 }: {
+        from: string;
+        to: string;
+        entry: import("./directory-registry.js").DirectoryRecord;
+        references?: readonly DurableJsonChange[];
+    }, _options?: {}): void;
+    home: (_required: Record<string, never>, _options?: {}) => string;
+    setHome({ path: dir }: {
+        path: string;
+    }, _options?: {}): string;
+    registry: (_required: Record<string, never>, _options?: {}) => DirectoryRegistry;
+    running: ({ path: dir }: {
+        path: string;
+    }, _options?: {}) => import("./directory-running-lock.js").DirectoryRunningLock;
+    claim({ path: dir, app, port, scheme }: {
+        path: string;
+        app: string;
+        port?: number;
+        scheme?: "http" | "https";
+    }, _options?: {}): {
+        acquired: boolean;
+        record: import("./directory-running-lock.js").DirectoryRunningRecord;
+    };
+};
+//# sourceMappingURL=directory-workspace.d.ts.map

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