@openclaw/fs-safe 0.5.6 → 0.7.0

package/dist/sidecar-lock-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock-policy.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEvE,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAOjG;AASD,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGnF;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,OAAO,CAGT;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAU7E;AAED,wBAAsB,+BAA+B,CAAC,MAAM,EAAE;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,OAAO,CAAC,CAQnB"}
+{"version":3,"file":"sidecar-lock-policy.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAQvE,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI,CAkBpF;AAED,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAGhF;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAQjG;AASD,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGnF;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,OAAO,CAGT;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAU7E;AAED,wBAAsB,+BAA+B,CAAC,MAAM,EAAE;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,OAAO,CAAC,CAQnB"}

package/dist/sidecar-lock-policy.js

@@ -1,5 +1,34 @@
 import fs from "node:fs/promises";
+function assertFiniteNonNegative(value, label) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new RangeError(`${label} must be a finite non-negative number`);
+    }
+}
+export function validateSidecarLockRetryOptions(retry) {
+    if (retry.retries !== undefined && (!Number.isSafeInteger(retry.retries) || retry.retries < 0)) {
+        throw new RangeError("lock retry.retries must be a non-negative safe integer");
+    }
+    if (retry.factor !== undefined)
+        assertFiniteNonNegative(retry.factor, "lock retry.factor");
+    if (retry.minTimeout !== undefined) {
+        assertFiniteNonNegative(retry.minTimeout, "lock retry.minTimeout");
+    }
+    if (retry.maxTimeout !== undefined) {
+        assertFiniteNonNegative(retry.maxTimeout, "lock retry.maxTimeout");
+    }
+    if (retry.minTimeout !== undefined &&
+        retry.maxTimeout !== undefined &&
+        retry.minTimeout > retry.maxTimeout) {
+        throw new RangeError("lock retry.minTimeout must not exceed retry.maxTimeout");
+    }
+}
+export function validateSidecarLockTimeoutMs(timeoutMs) {
+    if (timeoutMs === undefined || timeoutMs === Number.POSITIVE_INFINITY)
+        return;
+    assertFiniteNonNegative(timeoutMs, "lock timeoutMs");
+}
 export function computeSidecarLockDelayMs(retry, attempt) {
+    validateSidecarLockRetryOptions(retry);
     const minTimeout = retry.minTimeout ?? 50;
     const maxTimeout = retry.maxTimeout ?? 1000;
     const factor = retry.factor ?? 1;

package/dist/sidecar-lock-reclaim.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock-reclaim.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-reclaim.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sidecar-lock-reclaim.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-reclaim.ts"],"names":[],"mappings":"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"}

package/dist/sidecar-lock-reclaim.js

@@ -5,6 +5,7 @@ import path from "node:path";
 import { readFileDescriptorBoundedSync, readFileHandleBounded } from "./bounded-read.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 const MAX_LOCK_PAYLOAD_BYTES = 1024 * 1024;
 const SIDECAR_LOCK_OWNERSHIP_TOKEN_BYTES = 16;
@@ -59,7 +60,25 @@ export async function readSidecarLockSnapshot(lockPath, options = {}) {
     let handle;
     try {
         if (options.lockRoot) {
-            const opened = await options.lockRoot.open(relativeSidecarLockPath(options.lockRoot, lockPath));
+            const lockRoot = options.lockRoot;
+            const relative = relativeSidecarLockPath(lockRoot, lockPath);
+            const opened = await lockRoot.open(relative).catch(async (error) => {
+                if (error instanceof FsSafeError && error.code === "path-mismatch") {
+                    // An owner can unlink after open. Prove absence through the same root;
+                    // acquisition retries create-only, so a later replacement stays guarded.
+                    try {
+                        await lockRoot.stat(relative);
+                    }
+                    catch (probeError) {
+                        if (probeError instanceof FsSafeError && probeError.code === "not-found") {
+                            return null;
+                        }
+                    }
+                }
+                throw error;
+            });
+            if (!opened)
+                return null;
             try {
                 const raw = (await readFileHandleBounded(opened.handle, MAX_LOCK_PAYLOAD_BYTES)).toString("utf8");
                 return {
@@ -132,11 +151,14 @@ export function readSidecarLockSnapshotSync(lockPath, parsePayload, options = {}
             }
             return null;
         }
-        const noFollow = process.platform !== "win32" && typeof fsSync.constants.O_NOFOLLOW === "number"
-            ? fsSync.constants.O_NOFOLLOW
-            : 0;
-        fd = fsSync.openSync(lockPath, fsSync.constants.O_RDONLY | noFollow);
+        fd = fsSync.openSync(lockPath, resolveReadOpenFlags());
         const opened = fsSync.fstatSync(fd);
+        if (!opened.isFile()) {
+            if (options.rejectNonFile) {
+                throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`);
+            }
+            return null;
+        }
         const raw = readFileDescriptorBoundedSync(fd, MAX_LOCK_PAYLOAD_BYTES).toString("utf8");
         const after = fsSync.lstatSync(lockPath);
         if (!sameFileIdentity(before, opened) || !sameFileIdentity(opened, after))
@@ -191,10 +213,10 @@ export async function removeSidecarLockIfUnchanged(lockPath, observed, options =
         return false;
     }
     if (options.lockRoot) {
-        await options.lockRoot.remove(relativeSidecarLockPath(options.lockRoot, lockPath)).catch(() => undefined);
+        await options.lockRoot.remove(relativeSidecarLockPath(options.lockRoot, lockPath));
     }
     else {
-        await fs.rm(lockPath, { force: true }).catch(() => undefined);
+        await fs.rm(lockPath, { force: true });
     }
     return true;
 }

package/dist/sidecar-lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,YAAY,EACV,yBAAyB,EACzB,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAmLjC,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM;cAS3B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACpD,yBAAyB,CAAC,QAAQ,CAAC,KAC3C,OAAO,CAAC,iBAAiB,CAAC;eAYL,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACxD,yBAAyB,CAAC,QAAQ,CAAC,MACxC,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAC;iBASW,OAAO,CAAC,IAAI,CAAC;iBAQnB,IAAI;uBAIE,oBAAoB,EAAE;EAW/C;AAED,wBAAsB,eAAe,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAMZ"}
+{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,YAAY,EACV,yBAAyB,EACzB,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAsLjC,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM;cAS3B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACpD,yBAAyB,CAAC,QAAQ,CAAC,KAC3C,OAAO,CAAC,iBAAiB,CAAC;eAYL,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACxD,yBAAyB,CAAC,QAAQ,CAAC,MACxC,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAC;iBAqBW,OAAO,CAAC,IAAI,CAAC;iBAQnB,IAAI;uBAIE,oBAAoB,EAAE;EAW/C;AAED,wBAAsB,eAAe,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAMZ"}

package/dist/sidecar-lock.js

@@ -3,6 +3,7 @@ import { sameFileIdentity } from "./file-identity.js";
 import { removeSidecarLockIfUnchanged, sidecarLockSnapshotMatches, } from "./sidecar-lock-reclaim.js";
 import { acquireSidecarLock } from "./sidecar-lock-acquire.js";
 import { createHeldSidecarLockHandle } from "./sidecar-lock-handle.js";
+import { createSuppressedError } from "./suppressed-error.js";
 const GLOBAL_STATE_KEY = Symbol.for("fsSafe.sidecarLockManagers");
 const GLOBAL_CLEANUP_KEY = Symbol.for("fsSafe.sidecarLockCleanupRegistered");
 const GLOBAL_CLEANUP_HANDLER_KEY = Symbol.for("fsSafe.sidecarLockCleanupHandler");
@@ -121,23 +122,18 @@ async function releaseHeldLock(state, normalizedTargetPath, held, options = {})
     if (current !== held) {
         return false;
     }
+    if (held.releasePromise) {
+        await held.releasePromise;
+        return true;
+    }
     if (options.force) {
         held.refCount = 0;
     }
-    else {
+    else if (!options.retry && held.refCount > 0) {
         held.refCount -= 1;
-        if (held.refCount > 0) {
-            return false;
-        }
-    }
-    if (held.releasePromise) {
-        await held.releasePromise.catch(() => undefined);
-        return true;
     }
-    state.held.delete(normalizedTargetPath);
-    if (held.compromiseTimer) {
-        clearInterval(held.compromiseTimer);
-        held.compromiseTimer = undefined;
+    if (held.refCount > 0) {
+        return false;
     }
     held.releasePromise = (async () => {
         await held.handle.close().catch(() => undefined);
@@ -145,6 +141,13 @@ async function releaseHeldLock(state, normalizedTargetPath, held, options = {})
             lockRoot: held.lockRoot,
             parsePayload: held.parsePayload,
         });
+        if (state.held.get(normalizedTargetPath) === held) {
+            state.held.delete(normalizedTargetPath);
+        }
+        if (held.compromiseTimer) {
+            clearInterval(held.compromiseTimer);
+            held.compromiseTimer = undefined;
+        }
     })();
     try {
         await held.releasePromise;
@@ -158,7 +161,7 @@ function handleForHeldLock(state, normalizedTargetPath, held) {
     return createHeldSidecarLockHandle({
         normalizedTargetPath,
         held,
-        release: async () => await releaseHeldLock(state, normalizedTargetPath, held),
+        release: async (options) => await releaseHeldLock(state, normalizedTargetPath, held, { retry: options?.retry }),
     });
 }
 export function createSidecarLockManager(key) {
@@ -179,12 +182,21 @@ export function createSidecarLockManager(key) {
     }
     async function withLock(options, fn) {
         const lock = await acquire(options);
+        let result;
         try {
-            return await fn();
+            result = await fn();
         }
-        finally {
-            await lock.release();
+        catch (bodyError) {
+            try {
+                await lock.release();
+            }
+            catch (releaseError) {
+                throw createSuppressedError(releaseError, bodyError, "file lock callback and release both failed");
+            }
+            throw bodyError;
         }
+        await lock.release();
+        return result;
     }
     async function drain() {
         for (const [normalizedTargetPath, held] of Array.from(state.held.entries())) {

package/dist/staged-directory.d.ts

@@ -0,0 +1,16 @@
+import type { DirectoryReceipt } from "./directory-durability.js";
+import type { FileIdentityStat } from "./file-identity.js";
+import type { StagedFileReceipt } from "./staged-file-types.js";
+type DirectorySnapshot = StagedFileReceipt["directory"];
+export declare function exactIdentityMatches(expected: FileIdentityStat, actual: Readonly<{
+    dev: bigint;
+    ino: bigint;
+}>): boolean;
+export declare function describeStagedDirectory(fd: number, pathname: string): DirectorySnapshot;
+export declare function assertStagedDirectoryCurrent(receipt: DirectorySnapshot): void;
+export declare function openStagedDirectory(directory: string | DirectoryReceipt): {
+    fd: number;
+    receipt: DirectorySnapshot;
+};
+export {};
+//# sourceMappingURL=staged-directory.d.ts.map

package/dist/staged-directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staged-directory.d.ts","sourceRoot":"","sources":["../src/staged-directory.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,KAAK,iBAAiB,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;AAExD,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,OAAO,CAKT;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAYvF;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAQ7E;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,iBAAiB,CAAC;CAC5B,CA+BA"}

package/dist/staged-directory.js

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+export function exactIdentityMatches(expected, actual) {
+    return ["dev", "ino"].every((key) => {
+        const value = expected[key];
+        return (typeof value === "bigint" || Number.isSafeInteger(value)) && BigInt(value) === actual[key];
+    });
+}
+export function describeStagedDirectory(fd, pathname) {
+    const identity = fs.fstatSync(fd, { bigint: true });
+    if (!identity.isDirectory()) {
+        throw new FsSafeError("not-file", "staging parent must be a directory");
+    }
+    const receipt = Object.freeze({
+        path: path.resolve(pathname),
+        realPath: fs.realpathSync(pathname),
+        identity: Object.freeze({ dev: identity.dev, ino: identity.ino }),
+    });
+    assertStagedDirectoryCurrent(receipt);
+    return receipt;
+}
+export function assertStagedDirectoryCurrent(receipt) {
+    const current = fs.lstatSync(receipt.path, { bigint: true });
+    if (!current.isDirectory() || !exactIdentityMatches(receipt.identity, current) ||
+        fs.realpathSync(receipt.path) !== receipt.realPath) {
+        throw new FsSafeError("path-mismatch", "staging directory pathname changed");
+    }
+}
+export function openStagedDirectory(directory) {
+    // Copy supplied facts before any asynchronous work; receipts are not authority.
+    const pathname = path.resolve(typeof directory === "string" ? directory : directory.path);
+    const expected = typeof directory === "string" ? undefined : {
+        realPath: directory.realPath, dev: directory.identity.dev, ino: directory.identity.ino,
+    };
+    const before = fs.lstatSync(pathname, { bigint: true });
+    if (!before.isDirectory()) {
+        throw new FsSafeError("not-file", "staging parent must be a real directory");
+    }
+    if (expected && (!exactIdentityMatches(expected, before) || fs.realpathSync(pathname) !== expected.realPath)) {
+        throw new FsSafeError("path-mismatch", "stale staging directory receipt");
+    }
+    const fd = fs.openSync(pathname, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    try {
+        const receipt = describeStagedDirectory(fd, pathname);
+        if (!exactIdentityMatches(before, receipt.identity)) {
+            throw new FsSafeError("path-mismatch", "staging directory changed while opening");
+        }
+        return { fd, receipt };
+    }
+    catch (error) {
+        try {
+            fs.closeSync(fd);
+        }
+        catch (closeError) {
+            throw new AggregateError([error, closeError], "staging directory admission and close failed");
+        }
+        throw error;
+    }
+}

package/dist/staged-file-types.d.ts

@@ -0,0 +1,56 @@
+export type StagedFileReceipt = Readonly<{
+    directory: Readonly<{
+        path: string;
+        realPath: string;
+        identity: Readonly<{
+            dev: bigint;
+            ino: bigint;
+        }>;
+    }>;
+    temporaryBasename: string;
+    /** Preparation-time metadata of the private stage, not a final-file fingerprint. */
+    identity: Readonly<{
+        dev: bigint;
+        ino: bigint;
+        mode: number;
+        nlink: bigint;
+        size: bigint;
+        uid: number;
+        gid: number;
+        mtimeNs: bigint;
+        ctimeNs: bigint;
+    }>;
+}>;
+export type PublishedFileReceipt = Readonly<{
+    status: "published";
+    staged: StagedFileReceipt;
+    basename: string;
+    overwrite: boolean;
+}>;
+export type StagedFilePublication = Readonly<{
+    status: "not-published";
+}> | PublishedFileReceipt | Readonly<{
+    status: "indeterminate";
+    basename: string;
+    overwrite: boolean;
+}>;
+export type StagedFileCleanupReceipt = Readonly<{
+    temporaryBasename: string;
+    publication: StagedFilePublication;
+    status: "removed" | "name-absent" | "preserved" | "failed" | "not-needed";
+    resources: "closed" | "close-failed";
+}>;
+export type StagedFileFailureDetails = Readonly<{
+    phase: "prepare" | "publish" | "cleanup";
+    publication: StagedFilePublication;
+    cleanup?: StagedFileCleanupReceipt;
+}>;
+export interface StagedFile extends AsyncDisposable {
+    readonly receipt: StagedFileReceipt;
+    assertCurrent(): Promise<void>;
+    publish(basename: string, options: {
+        overwrite: boolean;
+    }): Promise<PublishedFileReceipt>;
+    cleanup(): Promise<StagedFileCleanupReceipt>;
+}
+//# sourceMappingURL=staged-file-types.d.ts.map

package/dist/staged-file-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staged-file-types.d.ts","sourceRoot":"","sources":["../src/staged-file-types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,SAAS,EAAE,QAAQ,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,QAAQ,CAAC;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAClD,CAAC,CAAC;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,QAAQ,EAAE,QAAQ,CAAC;QACjB,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ,CAAC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAC7B,QAAQ,CAAC;IAAE,MAAM,EAAE,eAAe,CAAA;CAAE,CAAC,GACrC,oBAAoB,GACpB,QAAQ,CAAC;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAEhF,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,qBAAqB,CAAC;IACnC,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,QAAQ,GAAG,YAAY,CAAC;IAC1E,SAAS,EAAE,QAAQ,GAAG,cAAc,CAAC;CACtC,CAAC,CAAC;AAEH,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IACzC,WAAW,EAAE,qBAAqB,CAAC;IACnC,OAAO,CAAC,EAAE,wBAAwB,CAAC;CACpC,CAAC,CAAC;AAEH,MAAM,WAAW,UAAW,SAAQ,eAAe;IACjD,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC1F,OAAO,IAAI,OAAO,CAAC,wBAAwB,CAAC,CAAC;CAC9C"}

package/dist/staged-file-types.js

@@ -0,0 +1 @@
+export {};

package/dist/staged-file.d.ts

@@ -0,0 +1,10 @@
+import type { DirectoryReceipt } from "./directory-durability.js";
+import type { StagedFile } from "./staged-file-types.js";
+export type { PublishedFileReceipt, StagedFile, StagedFileCleanupReceipt, StagedFileFailureDetails, StagedFilePublication, StagedFileReceipt, } from "./staged-file-types.js";
+export declare function stageFileInDirectory(options: {
+    directory: string | DirectoryReceipt;
+    content: string | Uint8Array;
+    /** Published mode; the unpublished stage stays at 0600. Defaults to 0600. */
+    mode?: number;
+}): Promise<StagedFile>;
+//# sourceMappingURL=staged-file.d.ts.map

package/dist/staged-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staged-file.d.ts","sourceRoot":"","sources":["../src/staged-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAKlE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,YAAY,EACV,oBAAoB,EAAE,UAAU,EAAE,wBAAwB,EAAE,wBAAwB,EACpF,qBAAqB,EAAE,iBAAiB,GACzC,MAAM,wBAAwB,CAAC;AAEhC,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAClD,SAAS,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACrC,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,UAAU,CAAC,CAUtB"}

package/dist/staged-file.js

@@ -0,0 +1,15 @@
+import { FsSafeError } from "./errors.js";
+import { assertNativeStaging, createNativeStage } from "./native-staged-file.js";
+import { requireNativeBinding } from "./native.js";
+import { openStagedDirectory } from "./staged-directory.js";
+export async function stageFileInDirectory(options) {
+    if (process.platform !== "linux" && process.platform !== "darwin") {
+        throw new FsSafeError("unsupported-platform", "retained-directory staging requires Linux or macOS");
+    }
+    const binding = requireNativeBinding();
+    assertNativeStaging(binding);
+    const input = { kind: "buffer", data: Buffer.from(options.content) };
+    const mode = options.mode ?? 0o600;
+    const parent = openStagedDirectory(options.directory);
+    return await createNativeStage(binding, parent.fd, parent.receipt, input, mode);
+}

package/dist/strict-file-identity.d.ts

@@ -0,0 +1,6 @@
+import type { BigIntStats } from "node:fs";
+type ExactFileIdentity = Pick<BigIntStats, "dev" | "ino">;
+export declare function inspectFileIdentity<T extends ExactFileIdentity>(inspect: () => Promise<T>, expected?: ExactFileIdentity, platform?: NodeJS.Platform): Promise<T>;
+export declare function inspectFileIdentitySync<T extends ExactFileIdentity>(inspect: () => T, expected?: ExactFileIdentity, platform?: NodeJS.Platform): T;
+export {};
+//# sourceMappingURL=strict-file-identity.d.ts.map

package/dist/strict-file-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strict-file-identity.d.ts","sourceRoot":"","sources":["../src/strict-file-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAG3C,KAAK,iBAAiB,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;AA6B1D,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,iBAAiB,EACnE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,iBAAiB,EACjE,OAAO,EAAE,MAAM,CAAC,EAChB,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,CAAC,CAOH"}

package/dist/strict-file-identity.js

@@ -0,0 +1,48 @@
+import { FsSafeError } from "./errors.js";
+function identityMismatch() {
+    return new FsSafeError("path-mismatch", "file identity changed or could not be verified");
+}
+function identityCheck(expected, platform) {
+    const known = {};
+    const check = (stat) => {
+        let complete = true;
+        for (const field of ["dev", "ino"]) {
+            const value = stat[field];
+            // Numeric receipts cannot recover identity bits already lost to rounding.
+            if (typeof value !== "bigint")
+                throw identityMismatch();
+            if (platform === "win32" && value === 0n) {
+                complete = false;
+            }
+            else {
+                if (known[field] !== undefined && known[field] !== value)
+                    throw identityMismatch();
+                known[field] = value;
+            }
+        }
+        return complete;
+    };
+    if (expected && !check(expected))
+        throw identityMismatch();
+    return check;
+}
+// Retry only unknown Windows identities, retaining every known component so a
+// later observation cannot erase a definite mismatch. Never reopen the file.
+export async function inspectFileIdentity(inspect, expected, platform = process.platform) {
+    const check = identityCheck(expected, platform);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const stat = await inspect();
+        if (check(stat))
+            return stat;
+    }
+    throw identityMismatch();
+}
+export function inspectFileIdentitySync(inspect, expected, platform = process.platform) {
+    const check = identityCheck(expected, platform);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const stat = inspect();
+        if (check(stat))
+            return stat;
+    }
+    throw identityMismatch();
+}

package/dist/suppressed-error.d.ts

@@ -0,0 +1,6 @@
+export type SuppressedErrorLike = Error & {
+    error: unknown;
+    suppressed: unknown;
+};
+export declare function createSuppressedError(error: unknown, suppressed: unknown, message: string): SuppressedErrorLike;
+//# sourceMappingURL=suppressed-error.d.ts.map

package/dist/suppressed-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suppressed-error.d.ts","sourceRoot":"","sources":["../src/suppressed-error.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG;IACxC,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;CACrB,CAAC;AAQF,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,OAAO,EACnB,OAAO,EAAE,MAAM,GACd,mBAAmB,CAgBrB"}

package/dist/suppressed-error.js

@@ -0,0 +1,15 @@
+export function createSuppressedError(error, suppressed, message) {
+    const constructor = globalThis.SuppressedError;
+    if (constructor) {
+        return new constructor(error, suppressed, message);
+    }
+    const combined = new Error(message, {
+        cause: error instanceof Error ? error : undefined,
+    });
+    combined.name = "SuppressedError";
+    Object.defineProperties(combined, {
+        error: { configurable: true, value: error },
+        suppressed: { configurable: true, value: suppressed },
+    });
+    return combined;
+}

package/dist/temp-cleanup.d.ts

@@ -6,6 +6,8 @@ export type TempPathRegistration = (() => void) & {
 export declare function registerTempPathForExit(tempPath: string, options?: {
     recursive?: boolean;
     identity?: FileIdentityStat;
+    singleLinkFile?: boolean;
+    cleanupSync?: () => unknown;
 }): TempPathRegistration;
 export declare function __cleanupRegisteredTempPathsForTest(): void;
 export declare function __cleanupRegisteredTempPathForTest(tempPath: string): void;

package/dist/temp-cleanup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-cleanup.d.ts","sourceRoot":"","sources":["../src/temp-cleanup.ts"],"names":[],"mappings":"AACA,OAAO,EAA8B,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEvF,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,CAAC;AAEvD,MAAM,MAAM,oBAAoB,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG;IAChD,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC/C,CAAC;AAsCF,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAA;CAAE,GAC7D,oBAAoB,CAyBtB;AAED,wBAAgB,mCAAmC,IAAI,IAAI,CAE1D;AAED,wBAAgB,kCAAkC,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAYzE"}
+{"version":3,"file":"temp-cleanup.d.ts","sourceRoot":"","sources":["../src/temp-cleanup.ts"],"names":[],"mappings":"AACA,OAAO,EAA8B,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEvF,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,CAAC;AAEvD,MAAM,MAAM,oBAAoB,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG;IAChD,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC/C,CAAC;AAkDF,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IACR,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;CAC7B,GACA,oBAAoB,CA2BtB;AAED,wBAAgB,mCAAmC,IAAI,IAAI,CAE1D;AAED,wBAAgB,kCAAkC,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAUzE"}

package/dist/temp-cleanup.js

@@ -7,18 +7,32 @@ function pathStillMatchesReceipt(entry) {
         return false;
     }
     try {
-        return sameFileIdentityForCleanup(fsSync.lstatSync(entry.path, { bigint: true }), entry.identity);
+        const current = fsSync.lstatSync(entry.path, { bigint: true });
+        return (!entry.singleLinkFile || (current.isFile() && current.nlink === 1n)) &&
+            sameFileIdentityForCleanup(current, entry.identity);
     }
     catch (error) {
-        return error.code === "ENOENT";
+        return !entry.singleLinkFile && error.code === "ENOENT";
+    }
+}
+function removeRegisteredPathSync(entry) {
+    if (entry.singleLinkFile)
+        fsSync.unlinkSync(entry.path);
+    else
+        fsSync.rmSync(entry.path, { force: true, recursive: entry.recursive });
+}
+function cleanupEntrySync(entry) {
+    if (entry.cleanupSync) {
+        entry.cleanupSync();
+    }
+    else if (pathStillMatchesReceipt(entry)) {
+        removeRegisteredPathSync(entry);
     }
 }
 function cleanupRegisteredTempPathsSync() {
     for (const entry of tempCleanupEntries.values()) {
         try {
-            if (pathStillMatchesReceipt(entry)) {
-                fsSync.rmSync(entry.path, { force: true, recursive: entry.recursive });
-            }
+            cleanupEntrySync(entry);
         }
         catch {
             // Process-exit cleanup is best-effort.
@@ -35,8 +49,10 @@ export function registerTempPathForExit(tempPath, options) {
         path: tempPath,
         recursive: options?.recursive === true,
         identity: options?.identity,
+        singleLinkFile: options?.singleLinkFile,
+        cleanupSync: options?.cleanupSync,
     };
-    if (!entry.identity) {
+    if (!entry.identity && !entry.cleanupSync) {
         try {
             entry.identity = fsSync.lstatSync(tempPath, { bigint: true });
         }
@@ -46,7 +62,8 @@ export function registerTempPathForExit(tempPath, options) {
     }
     tempCleanupEntries.set(tempPath, entry);
     const unregister = (() => {
-        tempCleanupEntries.delete(tempPath);
+        if (tempCleanupEntries.get(tempPath) === entry)
+            tempCleanupEntries.delete(tempPath);
     });
     unregister.setIdentity = (identity) => {
         entry.identity = identity;
@@ -62,9 +79,7 @@ export function __cleanupRegisteredTempPathForTest(tempPath) {
         return;
     }
     try {
-        if (pathStillMatchesReceipt(entry)) {
-            fsSync.rmSync(entry.path, { force: true, recursive: entry.recursive });
-        }
+        cleanupEntrySync(entry);
     }
     finally {
         tempCleanupEntries.delete(tempPath);

package/dist/temp-workspace-owner.d.ts

@@ -0,0 +1,23 @@
+import { type FileIdentityStat } from "./file-identity.js";
+import { type NativeBinding } from "./native.js";
+import { openStagedDirectory } from "./staged-directory.js";
+export type TempWorkspaceCleanupResult = "removed" | "missing" | "identity-mismatch" | "indeterminate";
+export type TempWorkspaceCleanupSafety = "compatible" | "require-bounded";
+type RetainedDirectory = ReturnType<typeof openStagedDirectory>;
+export declare class TempWorkspaceCleanupCapability {
+    #private;
+    readonly binding: NativeBinding | undefined;
+    readonly parent: RetainedDirectory | undefined;
+    constructor(root: string, safety: TempWorkspaceCleanupSafety);
+    get canRemoveOwnedTree(): boolean;
+    assertCurrent(): void;
+    close(): void;
+}
+export declare class TempWorkspaceCleanupOwner {
+    #private;
+    constructor(dir: string, identity: FileIdentityStat, capability: TempWorkspaceCleanupCapability);
+    cleanup(): Promise<TempWorkspaceCleanupResult>;
+    cleanupSync(): TempWorkspaceCleanupResult;
+}
+export {};
+//# sourceMappingURL=temp-workspace-owner.d.ts.map

package/dist/temp-workspace-owner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temp-workspace-owner.d.ts","sourceRoot":"","sources":["../src/temp-workspace-owner.ts"],"names":[],"mappings":"AAMA,OAAO,EAA8B,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEvF,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEnE,OAAO,EAAgC,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAG1F,MAAM,MAAM,0BAA0B,GAAG,SAAS,GAAG,SAAS,GAAG,mBAAmB,GAAG,eAAe,CAAC;AACvG,MAAM,MAAM,0BAA0B,GAAG,YAAY,GAAG,iBAAiB,CAAC;AAE1E,KAAK,iBAAiB,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAoBhE,qBAAa,8BAA8B;;IACzC,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAI/C,YAAY,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,0BAA0B,EAiC3D;IAED,IAAI,kBAAkB,IAAI,OAAO,CAEhC;IAED,aAAa,IAAI,IAAI,CASpB;IAED,KAAK,IAAI,IAAI,CAIZ;CACF;AAED,qBAAa,yBAAyB;;IAWpC,YAAY,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,UAAU,EAAE,8BAA8B,EAe9F;IAuLD,OAAO,IAAI,OAAO,CAAC,0BAA0B,CAAC,CAM7C;IAED,WAAW,IAAI,0BAA0B,CAexC;CACF"}