@jini-ai/platform 0.5.8 → 0.5.10

package/dist/fs/atomic-write.js

@@ -17,59 +17,163 @@ export function createNodeAtomicFilesystem(_required, { filesystem = fs } = {})
         remove: ({ path }) => filesystem.rmSync(path, { force: true }),
     };
 }
+const DIRECTORY_SYNC_UNSUPPORTED = ["EPERM", "EISDIR", "EINVAL", "EACCES", "ENOTSUP"];
+function hasErrorCode(error, codes) {
+    return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" && codes.includes(error.code);
+}
 function isMissing(error) {
-    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+    return hasErrorCode(error, ["ENOENT"]);
+}
+/** Runs a probe where only ENOENT means absent; every other failure propagates. */
+function ignoreMissing(probe) {
+    try {
+        return probe();
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+        return undefined;
+    }
+}
+async function ignoreMissingAsync(probe) {
+    try {
+        return await probe();
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+        return undefined;
+    }
+}
+/** Cleanup must never mask the failure that triggered it. */
+function attempt(action) {
+    try {
+        action();
+    }
+    catch { /* preserve the original failure */ }
+}
+async function attemptAsync(action) {
+    try {
+        await action();
+    }
+    catch { /* preserve the original failure */ }
+}
+function messagesFor(options) {
+    return options.messages ?? defaultPlatformMessages;
 }
 function validateMode(mode, options) {
     if (!Number.isInteger(mode) || mode < 0 || mode > 0o777)
-        throw new RangeError((options.messages ?? defaultPlatformMessages).atomicModeInvalid());
+        throw new RangeError(messagesFor(options).atomicModeInvalid());
     return mode;
 }
-function temporaryPath({ filePath }, options) {
-    const { tempName = () => `${process.pid}.${randomUUID()}` } = options;
-    if (options.tempPath) {
-        const temporary = options.tempPath({ filePath });
-        if (path.resolve(path.dirname(temporary)) !== path.resolve(path.dirname(filePath)) || path.resolve(temporary) === path.resolve(filePath) || temporary.includes("\0"))
-            throw new RangeError((options.messages ?? defaultPlatformMessages).atomicTempPathInvalid());
-        return temporary;
-    }
-    const token = tempName({ filePath });
+/** Explicit mode wins, then the preserved destination mode, then the store default, then 0600. */
+function resolveMode({ existingMode }, options) {
+    return validateMode(options.mode ?? existingMode ?? options.defaultMode ?? 0o600, options);
+}
+function defaultTempName() {
+    return `${process.pid}.${randomUUID()}`;
+}
+function checkedTempPath({ filePath, temporary }, options) {
+    if (path.resolve(path.dirname(temporary)) !== path.resolve(path.dirname(filePath)) || path.resolve(temporary) === path.resolve(filePath) || temporary.includes("\0"))
+        throw new RangeError(messagesFor(options).atomicTempPathInvalid());
+    return temporary;
+}
+function tokenTempPath({ filePath, token }, options) {
     if (!token || token === "." || token === ".." || /[/\\\x00]/.test(token))
-        throw new RangeError((options.messages ?? defaultPlatformMessages).atomicTempNameInvalid());
+        throw new RangeError(messagesFor(options).atomicTempNameInvalid());
     return path.join(path.dirname(filePath), `.${path.basename(filePath)}.${token}.tmp`);
 }
+function temporaryPath({ filePath }, options) {
+    if (options.tempPath)
+        return checkedTempPath({ filePath, temporary: options.tempPath({ filePath }) }, options);
+    return tokenTempPath({ filePath, token: (options.tempName ?? defaultTempName)({ filePath }) }, options);
+}
 function assertNotSymlink(info, options) {
     if (info.isSymbolicLink())
-        throw new Error((options.messages ?? defaultPlatformMessages).atomicSymlinkRefused());
+        throw new Error(messagesFor(options).atomicSymlinkRefused());
 }
-function assertOwnerOnly(mode, options) {
+function assertOwnerOnly(mode, options, platform) {
     // Windows has no POSIX group/other bits; secret stores skip this verification there.
-    if (options.verifyOwnerOnly && (options.platform ?? process.platform) !== "win32" && (mode & 0o077) !== 0)
-        throw new Error((options.messages ?? defaultPlatformMessages).atomicPermissionsRefused());
+    if (options.verifyOwnerOnly && platform !== "win32" && (mode & 0o077) !== 0)
+        throw new Error(messagesFor(options).atomicPermissionsRefused());
 }
-/** Same-directory rename; preserve existing mode exactly, default new files to 0600.
- * Only ENOENT means absent. Stat/write/chmod failures propagate before any rename.
- * Flush file bytes before rename so metadata cannot precede content; then flush the parent dir.
- * A directory-sync failure is reported after replacement, because rename cannot be rolled back safely.
+function isDirectorySyncUnsupported(error) {
+    return hasErrorCode(error, DIRECTORY_SYNC_UNSUPPORTED);
+}
+/** Destination mode with optional symlink refusal; ENOENT handling is left to the caller. */
+function destinationModeSync({ filePath, filesystem }, options) {
+    if (!options.refuseSymlink)
+        return filesystem.stat({ path: filePath }).mode & 0o777;
+    const info = filesystem.lstat({ path: filePath });
+    assertNotSymlink(info, options);
+    return info.mode & 0o777;
+}
+async function destinationModeAsync({ filePath, filesystem }, options) {
+    if (!options.refuseSymlink)
+        return (await filesystem.stat(filePath)).mode & 0o777;
+    const info = await filesystem.lstat(filePath);
+    assertNotSymlink(info, options);
+    return info.mode & 0o777;
+}
+function serializeJson({ data }, options) {
+    const content = JSON.stringify(data, null, 2);
+    if (content === undefined)
+        throw new TypeError(messagesFor(options).atomicJsonUnserializable());
+    return content;
+}
+/** Flush directory metadata where supported; Windows cannot fsync directory handles.
+ * Unsupported open/sync errors are ignored because replacement has already landed.
+ * Other failures propagate, and an opened descriptor is always closed.
+ * @complexity O(1) filesystem calls and space.
  */
-export function writeFileAtomic(required, options = {}) {
-    const { filePath, content, fs: filesystem } = required;
-    let existingMode;
+export function syncDirectoryBestEffort({ directory, open, sync, close }, { platform }) {
+    if (platform === "win32")
+        return;
+    let descriptor;
     try {
-        if (options.refuseSymlink) {
-            const info = filesystem.lstat({ path: filePath });
-            assertNotSymlink(info, options);
-            existingMode = info.mode & 0o777;
-        }
-        else {
-            existingMode = filesystem.stat({ path: filePath }).mode & 0o777;
-        }
+        descriptor = open(directory, "r");
+        sync(descriptor);
     }
     catch (error) {
-        if (!isMissing(error))
+        if (!isDirectorySyncUnsupported(error))
             throw error;
     }
-    const mode = validateMode(options.mode ?? existingMode ?? options.defaultMode ?? 0o600, options);
+    finally {
+        if (descriptor !== undefined)
+            close(descriptor);
+    }
+}
+/** Async directory flush with the same unsupported-error and handle-ownership contract.
+ * @complexity O(1) filesystem calls and space.
+ */
+export async function syncDirectoryBestEffortAsync({ directory, open }, { platform }) {
+    if (platform === "win32")
+        return;
+    let handle;
+    try {
+        handle = await open(directory, "r");
+        await handle.sync();
+    }
+    catch (error) {
+        if (!isDirectorySyncUnsupported(error))
+            throw error;
+    }
+    finally {
+        if (handle !== undefined)
+            await handle.close();
+    }
+}
+/** Same-directory rename; preserve existing mode exactly, default new files to 0600.
+ * Only ENOENT means absent. Stat/write/chmod failures propagate before any rename.
+ * Flush file bytes before rename so metadata cannot precede content; directory flush is best-effort:
+ * skip Windows and ignore unsupported-code failures (EPERM/EISDIR/EINVAL/EACCES/ENOTSUP).
+ * Other directory-flush failures are reported after replacement, because rename cannot be rolled back safely.
+ */
+export function writeFileAtomic(required, options = {}) {
+    const { filePath, content, fs: filesystem } = required;
+    const platform = options.platform ?? process.platform;
+    const existingMode = ignoreMissing(() => destinationModeSync({ filePath, filesystem }, options));
+    const mode = resolveMode({ existingMode }, options);
     const temporary = temporaryPath(required, options);
     // A failed exclusive create does not grant ownership of an existing temporary file.
     let descriptor = filesystem.open({ path: temporary, flags: "wx", mode });
@@ -77,73 +181,44 @@ export function writeFileAtomic(required, options = {}) {
     try {
         filesystem.write({ descriptor, content });
         filesystem.chmod({ path: temporary, mode });
-        assertOwnerOnly(filesystem.stat({ path: temporary }).mode, options);
+        assertOwnerOnly(filesystem.stat({ path: temporary }).mode, options, platform);
         filesystem.sync({ descriptor });
         const fileDescriptor = descriptor;
         descriptor = undefined;
         filesystem.close({ descriptor: fileDescriptor });
-        if (options.refuseSymlink) {
-            try {
-                assertNotSymlink(filesystem.lstat({ path: filePath }), options);
-            }
-            catch (error) {
-                if (!isMissing(error))
-                    throw error;
-            }
-        }
+        if (options.refuseSymlink)
+            ignoreMissing(() => assertNotSymlink(filesystem.lstat({ path: filePath }), options));
         filesystem.rename({ from: temporary, to: filePath });
         renamed = true;
-        const directory = filesystem.open({ path: path.dirname(filePath), flags: "r" });
-        try {
-            filesystem.sync({ descriptor: directory });
-        }
-        finally {
-            filesystem.close({ descriptor: directory });
-        }
+        syncDirectoryBestEffort({ directory: path.dirname(filePath),
+            open: (path, flags) => filesystem.open({ path, flags }),
+            sync: descriptor => filesystem.sync({ descriptor }), close: descriptor => filesystem.close({ descriptor }),
+        }, { platform });
     }
     catch (error) {
-        if (descriptor !== undefined) {
-            try {
-                filesystem.close({ descriptor });
-            }
-            catch { /* preserve the original failure */ }
-        }
-        if (!renamed) {
-            try {
-                filesystem.remove({ path: temporary });
-            }
-            catch { /* preserve the original failure */ }
-        }
+        const openDescriptor = descriptor;
+        if (openDescriptor !== undefined)
+            attempt(() => filesystem.close({ descriptor: openDescriptor }));
+        if (!renamed)
+            attempt(() => filesystem.remove({ path: temporary }));
         throw error;
     }
 }
 /** Pretty JSON delegates to the same mode-preserving atomic primitive. */
 export function writeJsonFileAtomic(required, options = {}) {
     const { data, ...writer } = required;
-    const content = JSON.stringify(data, null, 2);
-    if (content === undefined)
-        throw new TypeError((options.messages ?? defaultPlatformMessages).atomicJsonUnserializable());
-    writeFileAtomic({ ...writer, content }, options);
+    writeFileAtomic({ ...writer, content: serializeJson({ data }, options) }, options);
 }
 /** Async counterpart with the same ownership, permission and durability guarantees.
  * Parent creation supports runtime-state and secret stores without another writer implementation. */
 export async function writeFileAtomicAsync(required, options = {}) {
     const { filePath, content } = required;
+    const platform = options.platform ?? process.platform;
     const filesystem = options.fs ?? fsPromises;
     if (options.createParent)
         await filesystem.mkdir(path.dirname(filePath), { recursive: true });
-    let existingMode;
-    try {
-        const info = options.refuseSymlink ? await filesystem.lstat(filePath) : await filesystem.stat(filePath);
-        if (options.refuseSymlink)
-            assertNotSymlink(info, options);
-        existingMode = info.mode & 0o777;
-    }
-    catch (error) {
-        if (!isMissing(error))
-            throw error;
-    }
-    const mode = validateMode(options.mode ?? existingMode ?? options.defaultMode ?? 0o600, options);
+    const existingMode = await ignoreMissingAsync(() => destinationModeAsync({ filePath, filesystem }, options));
+    const mode = resolveMode({ existingMode }, options);
     const temporary = temporaryPath(required, options);
     // Keep the exclusive create outside cleanup: EEXIST belongs to a different writer.
     const handle = await filesystem.open(temporary, "wx", mode);
@@ -151,51 +226,27 @@ export async function writeFileAtomicAsync(required, options = {}) {
     try {
         await handle.writeFile(content, "utf8");
         await handle.chmod(mode);
-        assertOwnerOnly((await handle.stat()).mode, options);
+        assertOwnerOnly((await handle.stat()).mode, options, platform);
         await handle.sync();
         await handle.close();
         closed = true;
-        if (options.refuseSymlink) {
-            try {
-                assertNotSymlink(await filesystem.lstat(filePath), options);
-            }
-            catch (error) {
-                if (!isMissing(error))
-                    throw error;
-            }
-        }
+        if (options.refuseSymlink)
+            await ignoreMissingAsync(async () => assertNotSymlink(await filesystem.lstat(filePath), options));
         await filesystem.rename(temporary, filePath);
         renamed = true;
-        const directory = await filesystem.open(path.dirname(filePath), "r");
-        try {
-            await directory.sync();
-        }
-        finally {
-            await directory.close();
-        }
+        await syncDirectoryBestEffortAsync({ directory: path.dirname(filePath), open: (path, flags) => filesystem.open(path, flags) }, { platform });
     }
     catch (error) {
-        if (!closed) {
-            try {
-                await handle.close();
-            }
-            catch { /* preserve the original failure */ }
-        }
-        if (!renamed) {
-            try {
-                await filesystem.rm(temporary, { force: true });
-            }
-            catch { /* preserve the original failure */ }
-        }
+        if (!closed)
+            await attemptAsync(() => handle.close());
+        if (!renamed)
+            await attemptAsync(() => filesystem.rm(temporary, { force: true }));
         throw error;
     }
 }
 /** Pretty JSON can retain a state-store's trailing newline without changing its serialization. */
 export async function writeJsonFileAtomicAsync(required, options = {}) {
     const { data, ...writer } = required;
-    const content = JSON.stringify(data, null, 2);
-    if (content === undefined)
-        throw new TypeError((options.messages ?? defaultPlatformMessages).atomicJsonUnserializable());
-    await writeFileAtomicAsync({ ...writer, content: content + (options.trailingNewline ? "\n" : "") }, options);
+    await writeFileAtomicAsync({ ...writer, content: serializeJson({ data }, options) + (options.trailingNewline ? "\n" : "") }, options);
 }
 //# sourceMappingURL=atomic-write.js.map

package/dist/fs/boot-identity.d.ts

@@ -7,4 +7,20 @@ export interface BootIdentity {
  * Native calls are bounded and cached once per process. @complexity O(1) bounded OS reads.
  */
 export declare function readBootIdentity(_required: Record<string, never>, _options?: {}): BootIdentity | undefined;
+/** Darwin/Windows identities are wall-clock boot times the OS re-derives when it steps the clock, so
+ * processes that cached the same boot at different times can disagree by seconds (kern.boottime drops
+ * usec, so a sub-second step flips the id). Exact comparison let a long-lived observer delete a live
+ * owner's lease. Two real boots are separated by the earlier boot's uptime plus a restart, so only a gap
+ * beyond this tolerance proves an earlier boot; shorter gaps fall back to the PID probe.
+ */
+export declare const BOOT_CLOCK_TOLERANCE_MS: number;
+/** True only when a recorded holder provably predates this boot. Linux boot_id is a random UUID and is
+ * compared exactly; numeric (time-derived) ids and legacy timestamps get the tolerance above. A record
+ * from a "later" boot is clock skew, never proof of death. @complexity O(1).
+ */
+export declare function fromEarlierBoot({ boot, bootId, atMs }: {
+    boot: BootIdentity | undefined;
+    bootId: string | undefined;
+    atMs: number;
+}, _options?: {}): boolean;
 //# sourceMappingURL=boot-identity.d.ts.map

package/dist/fs/boot-identity.js

@@ -1,6 +1,26 @@
 import fs from "node:fs";
 import { execFileSync } from "node:child_process";
 let cached;
+const NATIVE_TIMEOUT_MS = 3000;
+function linuxBootIdentity() {
+    const id = fs.readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+    const startedAtMs = Number(/^btime (\d+)$/m.exec(fs.readFileSync("/proc/stat", "utf8"))?.[1]) * 1000;
+    return id && Number.isFinite(startedAtMs) ? { id, startedAtMs } : null;
+}
+/** Platforms without a kernel boot id use the boot timestamp itself as the identity. */
+function timestampIdentity(startedAtMs) {
+    return Number.isFinite(startedAtMs) ? { id: String(startedAtMs), startedAtMs } : null;
+}
+function darwinBootIdentity() {
+    const text = execFileSync("/usr/sbin/sysctl", ["-n", "kern.boottime"], { encoding: "utf8", timeout: NATIVE_TIMEOUT_MS });
+    return timestampIdentity(Number(/sec\s*=\s*(\d+)/.exec(text)?.[1]) * 1000);
+}
+function windowsBootIdentity() {
+    // eslint-disable-next-line sonarjs/no-os-command-from-path -- Fixed OS utility with fixed argv, resolved through the desktop operator's trusted PATH; no request controls the executable.
+    const text = execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", "(Get-CimInstance Win32_OperatingSystem).LastBootUpTime.ToUniversalTime().ToString('o')"], { encoding: "utf8", timeout: NATIVE_TIMEOUT_MS, windowsHide: true });
+    return timestampIdentity(Date.parse(text.trim()));
+}
+const PLATFORM_READERS = { linux: linuxBootIdentity, darwin: darwinBootIdentity, win32: windowsBootIdentity };
 /** Kernel boot identity distinguishes a recycled PID across reboots. Unknown identity fails safe
  * to the existing liveness probe; no age timeout is used to evict a potentially live owner.
  * Native calls are bounded and cached once per process. @complexity O(1) bounded OS reads.
@@ -10,25 +30,26 @@ export function readBootIdentity(_required, _options = {}) {
         return cached ?? undefined;
     cached = null;
     try {
-        let startedAtMs;
-        if (process.platform === "linux") {
-            const id = fs.readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
-            startedAtMs = Number(/^btime (\d+)$/m.exec(fs.readFileSync("/proc/stat", "utf8"))?.[1]) * 1000;
-            if (id && Number.isFinite(startedAtMs))
-                cached = { id, startedAtMs };
-        }
-        else {
-            const text = process.platform === "darwin"
-                ? execFileSync("/usr/sbin/sysctl", ["-n", "kern.boottime"], { encoding: "utf8", timeout: 3000 })
-                : process.platform === "win32"
-                    ? execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", "(Get-CimInstance Win32_OperatingSystem).LastBootUpTime.ToUniversalTime().ToString('o')"], { encoding: "utf8", timeout: 3000, windowsHide: true })
-                    : "";
-            startedAtMs = process.platform === "darwin" ? Number(/sec\s*=\s*(\d+)/.exec(text)?.[1]) * 1000 : Date.parse(text.trim());
-            if (Number.isFinite(startedAtMs))
-                cached = { id: String(startedAtMs), startedAtMs };
-        }
+        cached = PLATFORM_READERS[process.platform]?.() ?? null;
     }
     catch { /* Permission/OS failure is unknown identity, never proof of death. */ }
     return cached ?? undefined;
 }
+/** Darwin/Windows identities are wall-clock boot times the OS re-derives when it steps the clock, so
+ * processes that cached the same boot at different times can disagree by seconds (kern.boottime drops
+ * usec, so a sub-second step flips the id). Exact comparison let a long-lived observer delete a live
+ * owner's lease. Two real boots are separated by the earlier boot's uptime plus a restart, so only a gap
+ * beyond this tolerance proves an earlier boot; shorter gaps fall back to the PID probe.
+ */
+export const BOOT_CLOCK_TOLERANCE_MS = 10 * 60_000;
+/** True only when a recorded holder provably predates this boot. Linux boot_id is a random UUID and is
+ * compared exactly; numeric (time-derived) ids and legacy timestamps get the tolerance above. A record
+ * from a "later" boot is clock skew, never proof of death. @complexity O(1).
+ */
+export function fromEarlierBoot({ boot, bootId, atMs }, _options = {}) {
+    if (!boot)
+        return false;
+    const recordedAtMs = bootId === undefined ? atMs : /^\d+$/.test(bootId) ? Number(bootId) : undefined;
+    return recordedAtMs === undefined ? bootId !== boot.id : recordedAtMs < boot.startedAtMs - BOOT_CLOCK_TOLERANCE_MS;
+}
 //# sourceMappingURL=boot-identity.js.map

package/dist/fs/directory-home.js

@@ -8,6 +8,12 @@ export function resolveDirectoryHome({ homeDir, defaultFolder, envName, env, set
     const selected = env[envName] ?? setting ?? paths.join(homeDir, defaultFolder);
     if (!selected.trim())
         throw new Error(`${envName} must name a directory`);
+    return resolveSelected({ selected, homeDir, cwd, paths });
+}
+/** Expand a leading `~`, `~/` or `~\` against the supplied home; anything else resolves from cwd.
+ * `~user` forms are deliberately not expanded (no shell, no user database lookup).
+ */
+function resolveSelected({ selected, homeDir, cwd, paths }) {
     if (selected === "~")
         return paths.resolve(homeDir);
     if (selected.startsWith("~/") || selected.startsWith("~\\"))

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

@@ -35,7 +35,7 @@ export interface DirectoryRegistry {
  * @complexity O(n + m) records for merge, O(n) for other mutations, plus file I/O/lock wait.
  */
 export declare function createDirectoryRegistry({ file, canonicalPath }: {
-    file: DurableJsonFile;
+    file: Pick<DurableJsonFile, "read" | "write" | "withLock">;
     canonicalPath: (required: {
         path: string;
     }) => string;

package/dist/fs/directory-registry.js

@@ -3,7 +3,10 @@
  * Optional host admission prunes rejected entries on list under that same lock, then reports once.
  * @complexity O(n + m) records for merge, O(n) for other mutations, plus file I/O/lock wait.
  */
-export function createDirectoryRegistry({ file, canonicalPath }, { discard, reportDiscarded = () => { } } = {}) {
+export function createDirectoryRegistry(
+// The catalog only reads, writes and locks; it never quarantines or stages temp files, so
+// transaction-local adapters need not stub those members.
+{ file, canonicalPath }, { discard, reportDiscarded = () => { } } = {}) {
     function read() {
         const result = file.read({});
         if (result.state === "missing")
@@ -23,7 +26,7 @@ export function createDirectoryRegistry({ file, canonicalPath }, { discard, repo
             if (JSON.stringify(next) !== JSON.stringify(previous))
                 file.write({ value: next });
         } });
-    const registry = {
+    return {
         hasMigration: ({ migration }, _optional = {}) => read().migrations.includes(migration),
         migrations: (_required, _optional = {}) => read().migrations,
         list: (_required, _optional = {}) => {
@@ -52,19 +55,8 @@ export function createDirectoryRegistry({ file, canonicalPath }, { discard, repo
                 }
                 const byPath = new Map(state.entries.map((entry) => [canonical(entry.path), { ...entry, path: canonical(entry.path) }]));
                 const byId = new Map([...byPath.values()].map((entry) => [entry.id, entry.path]));
-                for (const entry of entries) {
-                    if (!validRecord(entry))
-                        throw new Error("Cannot register an invalid directory record.");
-                    const dir = canonical(entry.path);
-                    const previous = byPath.get(dir);
-                    if (byId.has(entry.id) && byId.get(entry.id) !== dir)
-                        throw new Error(`Directory identity ${entry.id} is already registered at another path.`);
-                    // Reopening a site cannot reset who originally created it or its stable identity.
-                    const lastOpened = [previous?.lastOpened, entry.lastOpened].filter((at) => typeof at === "string").sort((a, b) => Date.parse(a) - Date.parse(b)).at(-1) ?? null;
-                    const next = previous ? { ...previous, name: entry.name, lastOpened } : { ...entry, path: dir };
-                    byPath.set(dir, next);
-                    byId.set(next.id, dir);
-                }
+                for (const entry of entries)
+                    mergeEntry({ entry, byPath, byId }, { canonical });
                 result = [...byPath.values()];
                 return { ...state, entries: result, migrations: [...new Set([...state.migrations, ...migrations, ...(migration ? [migration] : [])])] };
             });
@@ -87,7 +79,22 @@ export function createDirectoryRegistry({ file, canonicalPath }, { discard, repo
             });
         },
     };
-    return registry;
+}
+/** Fold one incoming record into the canonical path/identity maps of a merge in progress.
+ * Refusals throw before either map changes, so the caller's update writes nothing.
+ */
+function mergeEntry({ entry, byPath, byId }, { canonical }) {
+    if (!validRecord(entry))
+        throw new Error("Cannot register an invalid directory record.");
+    const dir = canonical(entry.path);
+    const previous = byPath.get(dir);
+    if (byId.has(entry.id) && byId.get(entry.id) !== dir)
+        throw new Error(`Directory identity ${entry.id} is already registered at another path.`);
+    // Reopening a site cannot reset who originally created it or its stable identity.
+    const lastOpened = [previous?.lastOpened, entry.lastOpened].filter((at) => typeof at === "string").sort((a, b) => Date.parse(a) - Date.parse(b)).at(-1) ?? null;
+    const next = previous ? { ...previous, name: entry.name, lastOpened } : { ...entry, path: dir };
+    byPath.set(dir, next);
+    byId.set(next.id, dir);
 }
 function validRecord(entry) {
     if (!entry || typeof entry !== "object")

package/dist/fs/directory-running-lock.d.ts

@@ -1,4 +1,4 @@
-import type { BootIdentity } from "./boot-identity.js";
+import { type BootIdentity } from "./boot-identity.js";
 import type { DurableJsonFile } from "./durable-json.js";
 export interface DirectoryRunningRecord {
     pid: number;

package/dist/fs/directory-running-lock.js

@@ -1,10 +1,12 @@
+import { fromEarlierBoot } from "./boot-identity.js";
 /** A process lease is distinct from the brief file lock protecting its read/modify/write.
  * Only proven process death permits stale cleanup. Release/update require the unique claim token.
  * A zero port means boot is in progress and must still prevent a second database owner.
  * @complexity O(1) bounded JSON I/O and one liveness probe, plus the file lock wait.
  */
 export function createDirectoryRunningLock({ file, isAlive, remove }, { bootIdentity } = {}) {
-    function readLive(cleanup = true) {
+    /** Validate before any mutation; corrupt or unreadable records fail closed. O(1) JSON I/O. */
+    function readRecord() {
         const result = file.read({});
         if (result.state === "missing")
             return null;
@@ -13,9 +15,14 @@ export function createDirectoryRunningLock({ file, isAlive, remove }, { bootIden
         const record = result.value;
         if (!validRunningRecord(record))
             throw new Error("The running lock is invalid; refusing to open this directory's database.");
-        const boot = bootIdentity?.();
-        const sameBoot = !boot || (record.bootId !== undefined ? record.bootId === boot.id : Date.parse(record.started) >= boot.startedAtMs);
-        if (sameBoot && isAlive({ pid: record.pid }))
+        return record;
+    }
+    function readLive(cleanup = true) {
+        const record = readRecord();
+        if (!record)
+            return null;
+        const earlierBoot = fromEarlierBoot({ boot: bootIdentity?.(), bootId: record.bootId, atMs: Date.parse(record.started) });
+        if (!earlierBoot && isAlive({ pid: record.pid }))
             return record;
         if (cleanup)
             remove();
@@ -50,7 +57,8 @@ export function createDirectoryRunningLock({ file, isAlive, remove }, { bootIden
         release({ token }, _optional = {}) {
             if (file.read({}).state === "missing")
                 return;
-            file.withLock({ critical: () => { if (readLive()?.token === token)
+            // Release removes only its own record; stale cleanup of a different owner belongs to read/claim.
+            file.withLock({ critical: () => { if (readRecord()?.token === token)
                     remove(); } });
         },
     };
@@ -60,7 +68,10 @@ function validRunningRecord(value) {
         return false;
     const record = value;
     return Number.isSafeInteger(record.pid) && record.pid > 0 && Number.isInteger(record.port) && record.port >= 0 && record.port <= 65535 &&
-        typeof record.app === "string" && record.app.length > 0 && typeof record.token === "string" && record.token.length > 0 &&
-        (record.bootId === undefined || typeof record.bootId === "string") && typeof record.started === "string" && Number.isFinite(Date.parse(record.started)) && ["http", "https"].includes(record.scheme);
+        validRunningIdentity({ record }) && ["http", "https"].includes(record.scheme);
+}
+function validRunningIdentity({ record }, _options = {}) {
+    return typeof record.app === "string" && record.app.length > 0 && typeof record.token === "string" && record.token.length > 0 &&
+        (record.bootId === undefined || typeof record.bootId === "string") && typeof record.started === "string" && Number.isFinite(Date.parse(record.started));
 }
 //# sourceMappingURL=directory-running-lock.js.map

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

@@ -5,7 +5,7 @@ export type DirectorySyncProvider = "iCloud" | "OneDrive" | "Dropbox" | "Google
  * Dropbox publishes info.json paths; macOS File Provider mounts identify their provider.
  * @complexity O(a + p) small account/mount lists and ancestor probes, no recursive site scan.
  */
-export declare function detectDirectorySync({ dir, homeDir, documents }: {
+export declare function detectDirectorySync(required: {
     dir: string;
     homeDir: string;
     documents: string;