@jini-ai/platform 0.5.9 → 0.6.10

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

@@ -6,18 +6,32 @@ import { execFileSync } from "node:child_process";
  * 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 } = {}) {
+export function resolveUserDataDirectories({ homeDir, appName }, options = {}) {
+    const { platform, env, appDataDir, readText, windowsDocuments } = withNativeDefaults(options);
     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") };
-    }
+    assertProfileDirectory({ appDataDir, paths });
+    const context = { homeDir, appName, env, appDataDir, paths };
+    if (platform === "win32")
+        return windowsDirectories(context, { windowsDocuments });
     if (platform === "darwin")
         return { appData: appDataDir ?? paths.join(homeDir, "Library", "Application Support", appName), documents: paths.join(homeDir, "Documents") };
+    return xdgDirectories(context, { readText });
+}
+function withNativeDefaults({ platform = process.platform, env = process.env, appDataDir, readText = (file) => readOptionalText({ file }), windowsDocuments = readWindowsDocuments }) {
+    return { platform, env, appDataDir, readText, windowsDocuments };
+}
+function assertProfileDirectory({ appDataDir, paths }) {
+    // A blank or whitespace-only value is never absolute, so one check refuses both.
+    if (appDataDir !== undefined && !paths.isAbsolute(appDataDir))
+        throw new Error("appDataDir must be an absolute profile directory.");
+}
+/** Unknown %VARS% stay literal rather than collapsing to an unintended path. */
+function windowsDirectories({ homeDir, appName, env, appDataDir, paths }, { windowsDocuments }) {
+    const documents = windowsDocuments()?.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") };
+}
+function xdgDirectories({ homeDir, appName, env, appDataDir, paths }, { readText }) {
     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),
@@ -35,12 +49,14 @@ export function readOptionalText({ file }, _options = {}) {
     }
 }
 function readWindowsDocuments() {
+    // eslint-disable-next-line sonarjs/no-os-command-from-path -- Fixed Windows registry utility/argv intentionally uses the desktop operator's trusted PATH, not request input.
     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 {
+        // eslint-disable-next-line sonarjs/no-os-command-from-path -- Fixed Windows registry utility/argv intentionally uses the desktop operator's trusted PATH, not request input.
         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());
     }

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

@@ -10,16 +10,7 @@ export declare function directoryFingerprint({ dir }: {
     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, platform }?: {
+interface MoveDirectoryOptions {
     excluded?: readonly string[];
     filesystem?: typeof fs;
     prepareDestination?: (required: {
@@ -34,5 +25,16 @@ export declare function moveDirectoryVerified({ from, to, commit }: {
     }) => string;
     backupId?: () => string;
     platform?: NodeJS.Platform;
-}): void;
+}
+/** 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;
+}, options?: MoveDirectoryOptions): void;
+export {};
 //# sourceMappingURL=verified-directory-move.d.ts.map

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

@@ -15,7 +15,7 @@ export function directoryFingerprint({ dir }, { excluded = [], filesystem = fs }
                 continue;
             const name = path.join(relative, entry.name), absolute = path.join(dir, name);
             const stat = filesystem.lstatSync(absolute);
-            const kind = stat.isSymbolicLink() ? "link" : stat.isDirectory() ? "directory" : stat.isFile() ? "file" : "unsupported";
+            const kind = entryKind(stat);
             if (kind === "unsupported")
                 throw new Error(`Cannot move special filesystem entry: ${name}`);
             digest.update(JSON.stringify([name, kind, stat.mode & 0o777]));
@@ -23,32 +23,70 @@ export function directoryFingerprint({ dir }, { excluded = [], filesystem = fs }
                 visit(name);
             else if (kind === "link")
                 digest.update(JSON.stringify(filesystem.readlinkSync(absolute)));
-            else {
-                const fileDigest = createHash("sha256"), buffer = Buffer.allocUnsafe(64 * 1024);
-                const descriptor = filesystem.openSync(absolute, "r");
-                try {
-                    let bytes;
-                    while ((bytes = filesystem.readSync(descriptor, buffer, 0, buffer.length, null)) > 0)
-                        fileDigest.update(buffer.subarray(0, bytes));
-                }
-                finally {
-                    filesystem.closeSync(descriptor);
-                }
-                digest.update(fileDigest.digest());
-            }
+            else
+                digest.update(fileDigest({ absolute, filesystem }));
         }
     }
     visit("");
     return digest.digest("hex");
 }
+function entryKind(stat) {
+    if (stat.isSymbolicLink())
+        return "link";
+    if (stat.isDirectory())
+        return "directory";
+    return stat.isFile() ? "file" : "unsupported";
+}
+function fileDigest({ absolute, filesystem }) {
+    const digest = createHash("sha256"), buffer = Buffer.allocUnsafe(64 * 1024);
+    const descriptor = filesystem.openSync(absolute, "r");
+    try {
+        let bytes;
+        while ((bytes = filesystem.readSync(descriptor, buffer, 0, buffer.length, null)) > 0)
+            digest.update(buffer.subarray(0, bytes));
+    }
+    finally {
+        filesystem.closeSync(descriptor);
+    }
+    return digest.digest();
+}
+function withMoveDefaults({ excluded = [], filesystem = fs, prepareDestination, relocateFiles, verifyFile, backupId = randomUUID, platform = process.platform }) {
+    return { excluded, filesystem, prepareDestination, relocateFiles, verifyFile, backupId, platform };
+}
 /** Move only into an absent target. Verify before registry commit or source deletion.
  * EXDEV uses copy/verify/retire/commit; failure restores the source and removes only our new copy.
  * Same-filesystem failures roll the rename back. Commit must atomically update the host registry.
  * @complexity O(bytes + entries log entries), with two verification passes.
  */
-export function moveDirectoryVerified({ from, to, commit }, { excluded = [], filesystem = fs, prepareDestination, relocateFiles, verifyFile, backupId = randomUUID, platform = process.platform } = {}) {
+export function moveDirectoryVerified({ from, to, commit }, options = {}) {
+    const resolved = withMoveDefaults(options), { excluded, filesystem } = resolved;
     const source = filesystem.realpathSync(from);
     const target = path.resolve(to);
+    assertAbsentTarget({ source, target }, { filesystem });
+    const before = directoryFingerprint({ dir: source }, { excluded, filesystem });
+    const copied = placeAtTarget({ source, target }, resolved);
+    const progress = {};
+    try {
+        if (directoryFingerprint({ dir: target }, { excluded, filesystem }) !== before)
+            throw new Error("Moved directory verification failed.");
+        progress.staged = stageRelocation({ source, target, copied }, resolved);
+        if (copied)
+            retireCopiedSource({ source, progress }, resolved);
+        // Where supported, persist directory-name changes for same-filesystem renames as well as EXDEV retirement.
+        for (const directory of new Set([path.dirname(source), path.dirname(target)]))
+            syncDirectory({ directory }, resolved);
+        commit();
+    }
+    catch (error) {
+        rollbackMove({ source, target, copied, ...progress }, resolved);
+        throw error;
+    }
+    // If deletion fails after commit, the verified target and registry remain usable; old DB live
+    // names were already retired before commit. Never roll back a registry whose commit succeeded.
+    progress.staged?.finalize();
+    // Keep the retired EXDEV recovery folder; it is never a registered/live site path.
+}
+function assertAbsentTarget({ source, target }, { filesystem }) {
     if (target === source || target.startsWith(source + path.sep))
         throw new Error("A directory cannot be moved into itself.");
     try {
@@ -59,69 +97,68 @@ export function moveDirectoryVerified({ from, to, commit }, { excluded = [], fil
         if (error.code !== "ENOENT")
             throw error;
     }
-    const before = directoryFingerprint({ dir: source }, { excluded, filesystem });
-    let copied = false;
+}
+/** Same-filesystem rename, or an EXDEV copy into a freshly created target. Returns whether it copied. */
+function placeAtTarget({ source, target }, { filesystem, excluded, prepareDestination }) {
     try {
         filesystem.renameSync(source, target);
+        return false;
     }
     catch (error) {
         if (error.code !== "EXDEV")
             throw error;
-        filesystem.mkdirSync(target);
-        copied = true;
-        try {
-            // The host may reserve the empty destination before any commit marker or database is copied.
-            prepareDestination?.({ path: target });
-            filesystem.cpSync(source, target, { recursive: true, force: false, errorOnExist: true, preserveTimestamps: true, verbatimSymlinks: true,
-                filter: (candidate) => candidate === source || !excluded.includes(path.relative(source, candidate).split(path.sep)[0]),
-            });
-        }
-        catch (failure) {
-            filesystem.rmSync(target, { recursive: true });
-            throw failure;
-        }
     }
-    let retiredSource;
-    let staged;
+    filesystem.mkdirSync(target);
     try {
-        if (directoryFingerprint({ dir: target }, { excluded, filesystem }) !== before)
-            throw new Error("Moved directory verification failed.");
-        if (relocateFiles) {
-            if (!verifyFile)
-                throw new Error("File relocation requires a verification port.");
-            staged = stageVerifiedFileRelocation({ groups: relocateFiles({ source, target }), verify: verifyFile }, { filesystem, backupId, platform, backupCovered: ({ from }) => copied && path.resolve(from).startsWith(target + path.sep) });
-        }
-        if (copied) {
-            const backupRoot = path.join(path.dirname(source), `.relocation-${backupId()}-backup`);
-            const backup = path.join(backupRoot, path.basename(source));
-            if (filesystem.existsSync(backup))
-                throw new Error(`Move backup target already exists: ${backup}`);
-            // The EXDEV original becomes a recovery folder before catalog commit, never a second live
-            // site at the old path if cleanup fails. An interrupted apply leaves explicit backups.
-            filesystem.mkdirSync(backupRoot);
-            filesystem.renameSync(source, backup);
-            retiredSource = backup;
-            syncDirectoryBestEffort({ directory: backupRoot, open: filesystem.openSync, sync: filesystem.fsyncSync, close: filesystem.closeSync }, { platform });
-        }
-        // Where supported, persist directory-name changes for same-filesystem renames as well as EXDEV retirement.
-        for (const directory of new Set([path.dirname(source), path.dirname(target)])) {
-            syncDirectoryBestEffort({ directory, open: filesystem.openSync, sync: filesystem.fsyncSync, close: filesystem.closeSync }, { platform });
+        // The host may reserve the empty destination before any commit marker or database is copied.
+        prepareDestination?.({ path: target });
+        // MOVE: Copy entries into the reserved root so exclusive copy never collides with that root.
+        for (const entry of filesystem.readdirSync(source)) {
+            if (excluded.includes(entry))
+                continue;
+            filesystem.cpSync(path.join(source, entry), path.join(target, entry), {
+                recursive: true, force: false, errorOnExist: true, preserveTimestamps: true, verbatimSymlinks: true,
+            });
         }
-        commit();
     }
-    catch (error) {
-        if (retiredSource)
-            filesystem.renameSync(retiredSource, source);
-        staged?.rollback();
-        if (copied)
-            filesystem.rmSync(target, { recursive: true });
-        else
-            filesystem.renameSync(target, source);
-        throw error;
+    catch (failure) {
+        filesystem.rmSync(target, { recursive: true });
+        throw failure;
     }
-    // If deletion fails after commit, the verified target and registry remain usable; old DB live
-    // names were already retired before commit. Never roll back a registry whose commit succeeded.
-    staged?.finalize();
-    // Keep the retired EXDEV recovery folder; it is never a registered/live site path.
+    return true;
+}
+function stageRelocation({ source, target, copied }, { relocateFiles, verifyFile, filesystem, backupId, platform }) {
+    if (!relocateFiles)
+        return undefined;
+    if (!verifyFile)
+        throw new Error("File relocation requires a verification port.");
+    return stageVerifiedFileRelocation({ groups: relocateFiles({ source, target }), verify: verifyFile }, { filesystem, backupId, platform, backupCovered: ({ from }) => copied && path.resolve(from).startsWith(target + path.sep) });
+}
+/** Records the retired path in `progress` right after the rename, before the directory sync, so a
+ * failed fsync still lets rollback restore the source before it removes the copied target. */
+function retireCopiedSource({ source, progress }, resolved) {
+    const { filesystem, backupId } = resolved;
+    const backupRoot = path.join(path.dirname(source), `.relocation-${backupId()}-backup`);
+    const backup = path.join(backupRoot, path.basename(source));
+    if (filesystem.existsSync(backup))
+        throw new Error(`Move backup target already exists: ${backup}`);
+    // The EXDEV original becomes a recovery folder before catalog commit, never a second live
+    // site at the old path if cleanup fails. An interrupted apply leaves explicit backups.
+    filesystem.mkdirSync(backupRoot);
+    filesystem.renameSync(source, backup);
+    progress.retiredSource = backup;
+    syncDirectory({ directory: backupRoot }, resolved);
+}
+function syncDirectory({ directory }, { filesystem, platform }) {
+    syncDirectoryBestEffort({ directory, open: filesystem.openSync, sync: filesystem.fsyncSync, close: filesystem.closeSync }, { platform });
+}
+function rollbackMove({ source, target, copied, retiredSource, staged }, { filesystem }) {
+    if (retiredSource)
+        filesystem.renameSync(retiredSource, source);
+    staged?.rollback();
+    if (copied)
+        filesystem.rmSync(target, { recursive: true });
+    else
+        filesystem.renameSync(target, source);
 }
 //# sourceMappingURL=verified-directory-move.js.map

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

@@ -14,7 +14,7 @@ export declare function stageVerifiedFileRelocation({ groups, verify }: {
     verify: (required: {
         path: string;
     }) => string;
-}, { filesystem, backupCovered, backupId, platform }?: {
+}, options?: {
     filesystem?: typeof fs;
     backupCovered?: (required: {
         from: string;

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

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

package/dist/http/guarded/client.d.ts

@@ -1,10 +1,9 @@
+import { classifyIpAddress } from "../../net/address.js";
 import type { HttpClientPort } from "@jini-ai/core/primitives";
 import type { GuardedHttpRequired } from "./ports.js";
-export type AddressClass = "public" | "private" | "loopback" | "link-local" | "reserved";
+export type { AddressClass } from "../../net/address.js";
 /** Uses the canonical net address validator; labels preserve the guarded refusal contract. */
-export declare function classifyAddress({ ip }: {
-    ip: string;
-}): AddressClass;
+export declare const classifyAddress: typeof classifyIpAddress;
 /** Builds an adapter-friendly outbound port. Every hop is resolved, checked, and pinned before I/O.
  * Socket idle time is bounded on every hop. An optional totalDeadlineMs includes DNS,
  * redirect hops and decoded body reads; it is never inferred from the idle budget.