@openclaw/fs-safe 0.10.0 → 0.11.0

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

@@ -1 +1 @@
-{"version":3,"file":"sibling-staged-file.d.ts","sourceRoot":"","sources":["../src/sibling-staged-file.ts"],"names":[],"mappings":"AAmCA,wBAAsB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACxC,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;CACxB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,CAyG3C"}
+{"version":3,"file":"sibling-staged-file.d.ts","sourceRoot":"","sources":["../src/sibling-staged-file.ts"],"names":[],"mappings":"AAuEA,wBAAsB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACxC,iBAAiB,CAAC,EAAE,mBAAmB,CAAC;IACxC,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;CACxB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,CA+G3C"}

package/dist/sibling-staged-file.js

@@ -2,12 +2,14 @@ import { syncFileBestEffort } from "./file-sync.js";
 import fsSync, {} from "node:fs";
 import fs, {} from "node:fs/promises";
 import path from "node:path";
-import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
+import { assertAsyncDirectoryGuard, assertDirectoryIdentitySync, createAsyncDirectoryGuard, } from "./directory-guard.js";
 import { syncDirectoryBestEffort } from "./directory-durability.js";
 import { FsSafeError } from "./errors.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { root } from "./root.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
+import { createOwnedTempFile } from "./temp-target.js";
 import { serializePathWrite } from "./write-queue.js";
 function assertRegularFile(stat) {
     if (stat.isSymbolicLink()) {
@@ -27,17 +29,39 @@ async function inspectStage(inspect, expected) {
         return stat;
     }, expected);
 }
+// Own the workspace before the producer can leave partial output. The finished
+// file still enters the ordinary sibling admission and publication lifecycle.
+async function writeIsolatedProducer(params) {
+    const targetRoot = await root(path.dirname(params.tempPath));
+    const { target, identity } = await createOwnedTempFile({
+        rootDir: targetRoot.rootReal,
+        prefix: "fs-safe-output",
+        fileName: path.basename(params.tempPath),
+    });
+    const assertCurrent = () => {
+        params.assertParent();
+        assertDirectoryIdentitySync(target.dir, { ...identity, realPath: target.dir });
+    };
+    try {
+        assertCurrent();
+        const result = await params.write(target.path);
+        assertCurrent();
+        await targetRoot.move(path.relative(targetRoot.rootReal, target.path), path.basename(params.tempPath), {
+            assertBeforeMutation: assertCurrent,
+        });
+        return result;
+    }
+    finally {
+        await target.cleanup();
+    }
+}
 // Callback paths are not owned until all three admission observations agree.
 // Keep one descriptor and one exact identity through mode, sync, rename and cleanup.
 // Read/write access is needed only when the caller requests file synchronization.
 export async function writeCallbackSibling(params) {
     const parent = path.dirname(params.tempPath);
-    const guard = await createAsyncDirectoryGuard(parent);
-    const parentIdentity = await inspectFileIdentity(() => fsSync.lstatSync(parent, { bigint: true }));
-    const assertParent = async () => {
-        await assertAsyncDirectoryGuard(guard);
-        await inspectFileIdentity(() => fsSync.lstatSync(parent, { bigint: true }), parentIdentity);
-    };
+    const guard = await createAsyncDirectoryGuard(parent, { bigint: true });
+    const assertParent = () => assertAsyncDirectoryGuard(guard);
     let handle;
     let identity;
     let unregister;
@@ -54,7 +78,17 @@ export async function writeCallbackSibling(params) {
         }
     };
     try {
-        const result = await params.write(params.tempPath);
+        const result = params.producerIsolation === "private-directory"
+            ? await writeIsolatedProducer({
+                tempPath: params.tempPath,
+                write: params.write,
+                assertParent: () => assertDirectoryIdentitySync(parent, {
+                    dev: guard.stat.dev,
+                    ino: guard.stat.ino,
+                    realPath: guard.realPath,
+                }),
+            })
+            : await params.write(params.tempPath);
         await assertParent();
         const before = await inspectPath(params.tempPath);
         try {

package/dist/sibling-temp.d.ts

@@ -1,6 +1,8 @@
 export type WriteSiblingTempFileOptions<T> = {
     dir: string;
     writeTemp: (tempPath: string) => Promise<T>;
+    /** Own a private sibling workspace before invoking the producer. */
+    producerIsolation?: "private-directory";
     resolveFinalPath: (result: T) => string;
     tempPrefix?: string;
     dirMode?: number;

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

@@ -1 +1 @@
-{"version":3,"file":"sibling-temp.d.ts","sourceRoot":"","sources":["../src/sibling-temp.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5C,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uGAAuG;IACvG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yEAAyE;IACzE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AASF,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAoBxC;AAwBD,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6ChB"}
+{"version":3,"file":"sibling-temp.d.ts","sourceRoot":"","sources":["../src/sibling-temp.ts"],"names":[],"mappings":"AAeA,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5C,oEAAoE;IACpE,iBAAiB,CAAC,EAAE,mBAAmB,CAAC;IACxC,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uGAAuG;IACvG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yEAAyE;IACzE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AASF,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAqBxC;AAwBD,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6ChB"}

package/dist/sibling-temp.js

@@ -1,10 +1,11 @@
 import crypto, { randomUUID } from "node:crypto";
-import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
 import { fitFileNameToPortableComponent, sanitizeUntrustedFileName } from "./filename.js";
 import { applyDirectoryMode } from "./replace-file-descriptor.js";
+import { realpathSync } from "./realpath.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { root } from "./root.js";
 import { assertSafePathPrefix } from "./safe-path-segment.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
@@ -19,7 +20,7 @@ function buildTempPath(dir, tempPrefix) {
 }
 export async function writeSiblingTempFile(options) {
     const dir = path.resolve(options.dir);
-    await fs.mkdir(dir, { recursive: true, mode: options.dirMode ?? 0o700 });
+    await fs.mkdir(recursiveMkdirPath(dir), { recursive: true, mode: options.dirMode ?? 0o700 });
     if (options.chmodDir !== false) {
         await applyDirectoryMode({
             fsModule: fs,
@@ -31,6 +32,7 @@ export async function writeSiblingTempFile(options) {
     return await writeCallbackSibling({
         tempPath: buildTempPath(dir, options.tempPrefix),
         write: options.writeTemp,
+        producerIsolation: options.producerIsolation,
         resolveFinalPath: options.resolveFinalPath,
         mode: options.mode,
         ignoreModeError: true,
@@ -55,7 +57,7 @@ function buildSiblingTempPath(params) {
 export async function writeViaSiblingTempPath(params) {
     let rootDir;
     try {
-        rootDir = fsSync.realpathSync.native(path.resolve(params.rootDir));
+        rootDir = realpathSync.native(path.resolve(params.rootDir));
     }
     catch {
         rootDir = path.resolve(params.rootDir);
@@ -63,7 +65,7 @@ export async function writeViaSiblingTempPath(params) {
     const requestedTargetPath = path.resolve(params.targetPath);
     let targetPath;
     try {
-        const realDir = fsSync.realpathSync.native(path.dirname(requestedTargetPath));
+        const realDir = realpathSync.native(path.dirname(requestedTargetPath));
         targetPath = path.join(realDir, path.basename(requestedTargetPath));
     }
     catch {

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

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock-acquire.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-acquire.ts"],"names":[],"mappings":"AAQA,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAS3C,OAAO,EAWL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAI5F,KAAK,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAEvF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,eAAe,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;CAClC,CAAC;AAEF,KAAK,6BAA6B,GAAG;IACnC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACnC,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,2BAA2B,IAAI,IAAI,CAAC;IACpC,iBAAiB,CAAC,oBAAoB,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,iBAAiB,CAAC;IAC1F,eAAe,CACb,oBAAoB,EAAE,MAAM,EAC5B,IAAI,EAAE,eAAe,EACrB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC5B,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB,CAAC;AAqBF,wBAAsB,kBAAkB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,OAAO,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EAC5C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,iBAAiB,CAAC,CAqT5B"}
+{"version":3,"file":"sidecar-lock-acquire.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-acquire.ts"],"names":[],"mappings":"AAUA,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAW3C,OAAO,EAWL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAI5F,KAAK,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAEvF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,eAAe,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;CAClC,CAAC;AAEF,KAAK,6BAA6B,GAAG;IACnC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACnC,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,2BAA2B,IAAI,IAAI,CAAC;IACpC,iBAAiB,CAAC,oBAAoB,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,iBAAiB,CAAC;IAC1F,eAAe,CACb,oBAAoB,EAAE,MAAM,EAC5B,IAAI,EAAE,eAAe,EACrB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC5B,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB,CAAC;AAqBF,wBAAsB,kBAAkB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,OAAO,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EAC5C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,iBAAiB,CAAC,CA6T5B"}

package/dist/sidecar-lock-acquire.js

@@ -5,9 +5,11 @@ import { canonicalPathFromExistingAncestor } from "./absolute-path.js";
 import { FsSafeError } from "./errors.js";
 import { fileObservation } from "./file-observation.js";
 import { readFileHandleBounded } from "./bounded-read.js";
+import { realpathSync } from "./realpath.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { openSidecarRoot } from "./sidecar-lock-root.js";
 import { createNativeExclusiveFile } from "./native-operations.js";
-import { computeSidecarLockDelayMs, defaultSidecarLockShouldReclaim, isTransientLockFileDenial, maxTransientLockDenials, validateSidecarLockRetryOptions, validateSidecarLockTimeoutMs, } from "./sidecar-lock-policy.js";
+import { computeSidecarLockDelayMs, defaultSidecarLockShouldReclaim, isTransientLockFileDenial, maxTransientLockDenials, validateSidecarLockStaleMs, validateSidecarLockRetryOptions, validateSidecarLockCompromiseCheckIntervalMs, validateSidecarLockTimeoutMs, } from "./sidecar-lock-policy.js";
 import { readSidecarLockRawSnapshot, parseSidecarLockSnapshot, relativeSidecarLockPath, releaseSidecarReclaimGuard, removeSidecarLockIfUnchanged, removeStaleSidecarLockIfAllowed, serializeSidecarLockPayload, sidecarLockSnapshotStillPresent, sidecarReclaimGuardExists, tryAcquireSidecarReclaimGuard, } from "./sidecar-lock-reclaim.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { sleep } from "./timing.js";
@@ -22,9 +24,9 @@ async function resolveNormalizedTargetPath(targetPath, lockRoot) {
         await lockRoot.resolve(".");
         return path.join(parent, path.basename(resolved));
     }
-    await fs.mkdir(dir, { recursive: true });
+    await fs.mkdir(recursiveMkdirPath(dir), { recursive: true });
     try {
-        return path.join(fsSync.realpathSync.native(dir), path.basename(resolved));
+        return path.join(realpathSync.native(dir), path.basename(resolved));
     }
     catch {
         return resolved;
@@ -34,6 +36,8 @@ export async function acquireSidecarLock(options, context) {
     const retry = options.retry ?? {};
     validateSidecarLockRetryOptions(retry);
     validateSidecarLockTimeoutMs(options.timeoutMs);
+    validateSidecarLockStaleMs(options.staleMs);
+    validateSidecarLockCompromiseCheckIntervalMs(options.compromiseCheckIntervalMs);
     context.ensureExitCleanupRegistered();
     const normalizedTargetPath = await resolveNormalizedTargetPath(options.targetPath, options.lockRoot);
     const lockPath = options.lockPath ?? `${normalizedTargetPath}.lock`;
@@ -153,7 +157,7 @@ export async function acquireSidecarLock(options, context) {
                     try {
                         handle =
                             (await createNativeExclusiveFile(lockPath, 0o600)) ??
-                                (await fs.open(lockPath, "wx"));
+                                (await fs.open(lockPath, "wx", 0o600));
                     }
                     catch (createError) {
                         lockFileCreateDenied = isTransientLockFileDenial(createError, lockPath);
@@ -194,7 +198,11 @@ export async function acquireSidecarLock(options, context) {
                 const returnedHandle = context.handleForHeldLock(normalizedTargetPath, createdHeld);
                 const interval = options.compromiseCheckIntervalMs;
                 if (options.onCompromised && interval !== undefined && interval > 0) {
+                    let compromiseCheckInFlight = false;
                     createdHeld.compromiseTimer = setInterval(() => {
+                        if (compromiseCheckInFlight)
+                            return;
+                        compromiseCheckInFlight = true;
                         void returnedHandle
                             .verifyStillHeld()
                             .catch(() => false)
@@ -204,6 +212,9 @@ export async function acquireSidecarLock(options, context) {
                                 createdHeld.compromiseTimer = undefined;
                                 options.onCompromised?.({ lockPath, normalizedTargetPath });
                             }
+                        })
+                            .finally(() => {
+                            compromiseCheckInFlight = false;
                         });
                     }, interval);
                     createdHeld.compromiseTimer.unref();

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

@@ -1,6 +1,8 @@
 import type { SidecarLockRetryOptions } from "./sidecar-lock-types.js";
 export declare function validateSidecarLockRetryOptions(retry: SidecarLockRetryOptions): void;
 export declare function validateSidecarLockTimeoutMs(timeoutMs: number | undefined): void;
+export declare function validateSidecarLockStaleMs(staleMs: number | undefined): void;
+export declare function validateSidecarLockCompromiseCheckIntervalMs(intervalMs: number | undefined): void;
 export declare function computeSidecarLockDelayMs(retry: SidecarLockRetryOptions, attempt: number): number;
 export declare const maxTransientLockDenials = 8;
 export declare function isTransientLockFileDenial(error: unknown, lockPath: string): boolean;

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;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,CAUjG;AASD,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGnF;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;AAUvE,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI,CAkBpF;AAED,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAGhF;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAO5E;AAED,wBAAgB,4CAA4C,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAOjG;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAUjG;AASD,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGnF;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,4 +1,5 @@
 import fsSync from "node:fs";
+const MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
 function assertFiniteNonNegative(value, label) {
     if (!Number.isFinite(value) || value < 0) {
         throw new RangeError(`${label} must be a finite non-negative number`);
@@ -27,6 +28,22 @@ export function validateSidecarLockTimeoutMs(timeoutMs) {
         return;
     assertFiniteNonNegative(timeoutMs, "lock timeoutMs");
 }
+export function validateSidecarLockStaleMs(staleMs) {
+    // The lower-level sidecar manager historically treats an omitted threshold
+    // as disabling age-based reclamation. Its public type requires a number, but
+    // retain that fail-closed runtime behavior for JavaScript callers and older
+    // consumers.
+    if (staleMs === undefined || staleMs === Number.POSITIVE_INFINITY)
+        return;
+    assertFiniteNonNegative(staleMs, "lock staleMs");
+}
+export function validateSidecarLockCompromiseCheckIntervalMs(intervalMs) {
+    if (intervalMs === undefined || intervalMs === 0)
+        return;
+    if (!Number.isFinite(intervalMs) || intervalMs < 1 || intervalMs > MAX_TIMER_DELAY_MS) {
+        throw new RangeError(`lock compromiseCheckIntervalMs must be 0 or a finite number between 1 and ${MAX_TIMER_DELAY_MS}`);
+    }
+}
 export function computeSidecarLockDelayMs(retry, attempt) {
     validateSidecarLockRetryOptions(retry);
     const minTimeout = retry.minTimeout ?? 50;

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

@@ -1 +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"}
+{"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;AAE3D,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

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
+import { realpathSync } from "./realpath.js";
 export function exactIdentityMatches(expected, actual) {
     return ["dev", "ino"].every((key) => {
         const value = expected[key];
@@ -14,7 +15,7 @@ export function describeStagedDirectory(fd, pathname) {
     }
     const receipt = Object.freeze({
         path: path.resolve(pathname),
-        realPath: fs.realpathSync(pathname),
+        realPath: realpathSync(pathname),
         identity: Object.freeze({ dev: identity.dev, ino: identity.ino }),
     });
     assertStagedDirectoryCurrent(receipt);
@@ -23,7 +24,7 @@ export function describeStagedDirectory(fd, pathname) {
 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) {
+        realpathSync(receipt.path) !== receipt.realPath) {
         throw new FsSafeError("path-mismatch", "staging directory pathname changed");
     }
 }
@@ -37,7 +38,7 @@ export function openStagedDirectory(directory) {
     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)) {
+    if (expected && (!exactIdentityMatches(expected, before) || 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);

package/dist/temp-target.d.ts

@@ -1,3 +1,4 @@
+import fsSync from "node:fs";
 export type TempFile = {
     dir: string;
     path: string;
@@ -5,6 +6,12 @@ export type TempFile = {
     cleanup: () => Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
 };
+type TempFileOptions = {
+    rootDir?: string;
+    prefix: string;
+    fileName?: string;
+    onCleanupError?: (error: unknown) => void;
+};
 export declare function sanitizeTempFileName(fileName: string): string;
 export declare function buildRandomTempFilePath(params: {
     rootDir?: string;
@@ -13,16 +20,11 @@ export declare function buildRandomTempFilePath(params: {
     now?: number;
     uuid?: string;
 }): string;
-export declare function tempFile(params: {
-    rootDir?: string;
-    prefix: string;
-    fileName?: string;
-    onCleanupError?: (error: unknown) => void;
-}): Promise<TempFile>;
-export declare function withTempFile<T>(params: {
-    rootDir?: string;
-    prefix: string;
-    fileName?: string;
-    onCleanupError?: (error: unknown) => void;
-}, fn: (tmpPath: string) => Promise<T>): Promise<T>;
+export declare function createOwnedTempFile(params: TempFileOptions): Promise<{
+    target: TempFile;
+    identity: Readonly<Pick<fsSync.BigIntStats, "dev" | "ino">>;
+}>;
+export declare function tempFile(params: TempFileOptions): Promise<TempFile>;
+export declare function withTempFile<T>(params: TempFileOptions, fn: (tmpPath: string) => Promise<T>): Promise<T>;
+export {};
 //# sourceMappingURL=temp-target.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AA8DF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAaT;AAyCD,wBAAsB,QAAQ,CAAC,MAAM,EAAE;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,GAAG,OAAO,CAAC,QAAQ,CAAC,CAwBpB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE;IACN,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,EACD,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}
+{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AACA,OAAO,MAAM,MAAM,SAAS,CAAC;AAQ7B,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,CAAC;AA8DF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAaT;AAyCD,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC;IAC1E,MAAM,EAAE,QAAQ,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;CAC7D,CAAC,CA2BD;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAEzE;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE,eAAe,EACvB,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/temp-target.js

@@ -106,7 +106,7 @@ async function cleanupTempDir(dir, identity, onCleanupError) {
 function resolveTempRoot(rootDir) {
     return path.resolve(rootDir ?? resolveSecureTempRoot({ fallbackPrefix: "fs-safe" }));
 }
-export async function tempFile(params) {
+export async function createOwnedTempFile(params) {
     const rootDir = resolveTempRoot(params.rootDir);
     const prefix = `${sanitizePrefix(params.prefix)}-`;
     const dir = await fs.mkdtemp(path.join(rootDir, prefix));
@@ -124,13 +124,19 @@ export async function tempFile(params) {
         }
     };
     return {
-        dir,
-        path: file(),
-        file,
-        cleanup,
-        [Symbol.asyncDispose]: cleanup,
+        target: {
+            dir,
+            path: file(),
+            file,
+            cleanup,
+            [Symbol.asyncDispose]: cleanup,
+        },
+        identity: Object.freeze({ dev: identity.dev, ino: identity.ino }),
     };
 }
+export async function tempFile(params) {
+    return (await createOwnedTempFile(params)).target;
+}
 export async function withTempFile(params, fn) {
     const target = await tempFile(params);
     try {

package/dist/trash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trash.d.ts","sourceRoot":"","sources":["../src/trash.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACjC,CAAC;AAkLF,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,MAAM,CAAC,CAcjB"}
+{"version":3,"file":"trash.d.ts","sourceRoot":"","sources":["../src/trash.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACjC,CAAC;AAkLF,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,MAAM,CAAC,CAcjB"}

package/dist/trash.js

@@ -3,6 +3,8 @@ import os from "node:os";
 import path from "node:path";
 import { sameFileIdentity } from "./file-identity.js";
 import { guardedRenameSync, guardedRmSync } from "./guarded-mutation.js";
+import { realpathSync } from "./realpath.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 const TRASH_DESTINATION_COLLISION_CODES = new Set(["EEXIST", "ENOTEMPTY", "ERR_FS_CP_EEXIST"]);
 const TRASH_DESTINATION_RETRY_LIMIT = 4;
@@ -26,7 +28,7 @@ function resolveAllowedTrashRoots(allowedRoots) {
         try {
             // Keep both spellings: broken symlink targets cannot be realpathed and
             // may only compare equal to the caller's lexical allowed root.
-            return [path.resolve(fs.realpathSync.native(root)), lexicalRoot];
+            return [path.resolve(realpathSync.native(root)), lexicalRoot];
         }
         catch {
             return [lexicalRoot];
@@ -36,7 +38,7 @@ function resolveAllowedTrashRoots(allowedRoots) {
 }
 function resolveTrashTargetPath(targetPath) {
     try {
-        return { path: path.resolve(fs.realpathSync.native(targetPath)), resolved: true };
+        return { path: path.resolve(realpathSync.native(targetPath)), resolved: true };
     }
     catch {
         // Broken symlinks are valid trash targets. Fall back to the lexical path,
@@ -75,13 +77,13 @@ function assertTrashTargetGuard(guard) {
 function resolveTrashDir() {
     const homeDir = os.homedir();
     const trashDir = path.join(homeDir, ".Trash");
-    fs.mkdirSync(trashDir, { recursive: true, mode: 0o700 });
+    fs.mkdirSync(recursiveMkdirPath(trashDir), { recursive: true, mode: 0o700 });
     const trashDirStat = fs.lstatSync(trashDir);
     if (!trashDirStat.isDirectory() || trashDirStat.isSymbolicLink()) {
         throw new Error(`Refusing to use non-directory/symlink trash directory: ${trashDir}`);
     }
-    const realHome = path.resolve(fs.realpathSync.native(homeDir));
-    const resolvedTrashDir = path.resolve(fs.realpathSync.native(trashDir));
+    const realHome = path.resolve(realpathSync.native(homeDir));
+    const resolvedTrashDir = path.resolve(realpathSync.native(trashDir));
     if (resolvedTrashDir === realHome || !isSameOrChildPath(resolvedTrashDir, realHome)) {
         throw new Error(`Trash directory escaped home directory: ${trashDir}`);
     }

package/dist/unicode-path.d.ts

@@ -0,0 +1,3 @@
+export declare function lowerCaseNfc(value: string): string;
+export declare function maxNormalizedUtf8Bytes(value: string, includeRaw?: boolean): number;
+//# sourceMappingURL=unicode-path.d.ts.map

package/dist/unicode-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unicode-path.d.ts","sourceRoot":"","sources":["../src/unicode-path.ts"],"names":[],"mappings":"AAEA,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,UAAQ,GAAG,MAAM,CAUhF"}

package/dist/unicode-path.js

@@ -0,0 +1,13 @@
+const NON_ASCII = /[^\x00-\x7f]/;
+export function lowerCaseNfc(value) {
+    return NON_ASCII.test(value) ? value.normalize("NFC").toLowerCase().normalize("NFC") : value.toLowerCase();
+}
+export function maxNormalizedUtf8Bytes(value, includeRaw = false) {
+    const nfc = value.normalize("NFC");
+    const bytes = Buffer.byteLength(nfc, "utf8");
+    const maximum = includeRaw && nfc !== value ? Math.max(bytes, Buffer.byteLength(value, "utf8")) : bytes;
+    // ASCII NFC output also has identical NFD and one UTF-8 byte per code unit.
+    if (bytes === nfc.length)
+        return maximum;
+    return Math.max(maximum, Buffer.byteLength(value.normalize("NFD"), "utf8"));
+}

package/dist/walk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAI7B,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AACvE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;IACjD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IAGnB,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACrC,CAAC;AAEF,KAAK,+BAA+B,GAAG,mBAAmB,GAAG;IAC3D,UAAU,EAAE,oBAAoB,EAAE,CAAC;CACpC,CAAC;AAgFF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,+BAA+B,CAyDjC;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,+BAA+B,CAAC,CAyD1C"}
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAK7B,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AACvE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;IACjD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IAGnB,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACrC,CAAC;AAEF,KAAK,+BAA+B,GAAG,mBAAmB,GAAG;IAC3D,UAAU,EAAE,oBAAoB,EAAE,CAAC;CACpC,CAAC;AAgFF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,+BAA+B,CAyDjC;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,+BAA+B,CAAC,CAyD1C"}

package/dist/walk.js

@@ -1,6 +1,7 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { realpathSync } from "./realpath.js";
 function validateWalkBudget(name, value) {
     if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
         throw new RangeError(`${name} must be a non-negative safe integer`);
@@ -83,7 +84,7 @@ export function walkDirectorySync(rootDir, options = {}) {
             return;
         let realDir;
         try {
-            realDir = fsSync.realpathSync(dir);
+            realDir = realpathSync(dir);
         }
         catch (error) {
             recordFailedDir(result, root, dir, depth, error);
@@ -142,7 +143,7 @@ export async function walkDirectory(rootDir, options = {}) {
             return;
         let realDir;
         try {
-            realDir = fsSync.realpathSync.native(dir);
+            realDir = realpathSync.native(dir);
         }
         catch (error) {
             recordFailedDir(result, root, dir, depth, error);

package/dist/write-file-handle.d.ts

@@ -1,6 +1,7 @@
 import type { FileHandle } from "node:fs/promises";
 export declare function writeAllToFile(target: FileHandle | number, data: string | Uint8Array, options?: {
     encoding?: BufferEncoding;
+    position?: number;
     assertBeforeMutation?: () => void;
 }): Promise<void>;
 //# sourceMappingURL=write-file-handle.d.ts.map

package/dist/write-file-handle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-file-handle.d.ts","sourceRoot":"","sources":["../src/write-file-handle.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKnD,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,IAAI,EAAE,MAAM,GAAG,UAAU,EACzB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAAC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAA;CAAO,GAC7E,OAAO,CAAC,IAAI,CAAC,CAmBf"}
+{"version":3,"file":"write-file-handle.d.ts","sourceRoot":"","sources":["../src/write-file-handle.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKnD,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,IAAI,EAAE,MAAM,GAAG,UAAU,EACzB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAA;CAAO,GAChG,OAAO,CAAC,IAAI,CAAC,CAoBf"}

package/dist/write-file-handle.js

@@ -6,17 +6,18 @@ export async function writeAllToFile(target, data, options = {}) {
     let offset = 0;
     while (offset < buffer.byteLength) {
         const length = Math.min(WRITE_CHUNK_BYTES, buffer.byteLength - offset);
+        const position = options.position === undefined ? null : options.position + offset;
         options.assertBeforeMutation?.();
         const written = typeof target === "number"
             ? await new Promise((resolve, reject) => {
-                fs.write(target, buffer, offset, length, null, (error, bytesWritten) => {
+                fs.write(target, buffer, offset, length, position, (error, bytesWritten) => {
                     if (error)
                         reject(error);
                     else
                         resolve(bytesWritten);
                 });
             })
-            : (await target.write(buffer, offset, length, null)).bytesWritten;
+            : (await target.write(buffer, offset, length, position)).bytesWritten;
         if (written <= 0) {
             throw new FsSafeError("helper-failed", "file write made no progress");
         }

package/docs/advanced.md

@@ -32,6 +32,7 @@ The exports group into a handful of themes. Each documented helper has its own p
 | `resolveWritablePathWithinRoot` | – | Resolve a write target inside a root. |
 | `resolveRootPath`, `resolveRootPathSync`, `ResolvedRootPath`, `ROOT_PATH_ALIAS_POLICIES`, `RootPathAliasPolicy` | – | Resolve a root directory honoring alias policy. |
 | `resolvePathViaExistingAncestorSync` | – | Walk to an existing ancestor for paths whose tail does not yet exist. |
+| `probePathCaseInsensitiveSync`, `ProbePathCaseOptions` | [path-case.md](path-case.md) | Observe local ASCII-case behavior with explicit read-only mode and owned temporary-probe cleanup. |
 
 `ensureDirectoryWithinRoot({ rootDir, requestedPath, scopeLabel, defaultDirName?, mode? })`
 returns `{ ok: true, path }` or `{ ok: false, error: string, diagnostic?: FsSafeError }`.
@@ -66,9 +67,12 @@ Operational filesystem failures such as permissions or I/O errors are rethrown.
 |---|---|---|
 | `readFileDescriptorBounded`, `readFileDescriptorBoundedSync`, `readFileHandleBounded` | – | Incremental whole-file reads for already-open descriptors/handles. They consume at most `maxBytes + 1`, do not close the input, and throw `FsSafeError("too-large")` on overflow. |
 | `readFileWindowFully`, `readFileWindowFullySync`, `ReadFileWindowOptions` | [positional-read.md](positional-read.md) | Fill a caller-owned buffer at an explicit file position, completing short reads and returning the EOF count without moving or closing the descriptor. |
+| `copyFileHandle`, `CopyFileHandleOptions` | [copy.md](copy.md#borrowed-filehandle-transfers) | Copy caller-owned regular-file handles from position zero with byte limits, settled cancellation, and a synchronous source observer; preserves cursors and leaves publication and cleanup to the caller. |
+| `overwriteFileHandle`, `OverwriteFileHandleOptions` | [in-place-write.md](in-place-write.md) | Overwrite a borrowed read/write handle with prefix-only preparation and best-effort rollback; preserves its inode, cursor, and caller-owned lifetime. |
 | `openRootFile`, `openRootFileSync`, `canUseRootFileOpen`, `matchRootFileOpenFailure`, related types | – | Low-level root-bounded open; rejects every symlink component by default, with `symlinks: "follow-parents-within-root"` for contained parent aliases or `"follow-within-root"` for final links too. |
 | `appendRegularFile`, `appendRegularFileSync`, `readRegularFile`, `readRegularFileSync`, `statRegularFile`, `statRegularFileSync`, `resolveRegularFileAppendFlags`, `AppendRegularFileOptions`, `RegularFileStatResult` | [regular-file.md](regular-file.md) | Type-checked regular-file I/O. |
 | `sameFileIdentity`, `FileIdentityStat` | – | Compare two stats for same-inode equality. |
+| `readDirectoryIdentity`, `assertDirectoryIdentitySync`, `DirectoryIdentity` | [directory-identity.md](directory-identity.md) | Observe exact bigint directory identity and synchronously check a caller-selected path, optionally retaining its canonical path. |
 | `pathExists`, `pathExistsSync` | – | Boolean existence check that does not throw on `ENOENT`. |
 | `assertNoSymlinkParents`, `assertNoSymlinkParentsSync`, `AssertNoSymlinkParentsOptions` | – | Reject paths whose ancestor chain contains symlinks. |
 | `assertNoHardlinkedFinalPath`, `assertNoPathAliasEscape`, `PATH_ALIAS_POLICIES`, `PathAliasPolicy` | – | Hardlink/alias defense building blocks. |