@openclaw/fs-safe 0.16.0 → 0.18.0

package/dist/windows-path-alias.js

@@ -1,43 +1,9 @@
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
-const COLON = 0x3a;
-const FORWARD_SLASH = 0x2f;
-const BACKSLASH = 0x5c;
-const DOT = 0x2e;
-const QUESTION_MARK = 0x3f;
-function isAsciiLetter(code) {
-    return (code >= 0x41 && code <= 0x5a) || (code >= 0x61 && code <= 0x7a);
-}
-function isSeparator(code) {
-    return code === FORWARD_SLASH || code === BACKSLASH;
-}
-function rootedDriveColonIndex(value) {
-    if (value.length >= 3 &&
-        isAsciiLetter(value.charCodeAt(0)) &&
-        value.charCodeAt(1) === COLON &&
-        isSeparator(value.charCodeAt(2))) {
-        return 1;
-    }
-    if (value.length >= 7 &&
-        isSeparator(value.charCodeAt(0)) &&
-        isSeparator(value.charCodeAt(1)) &&
-        (value.charCodeAt(2) === QUESTION_MARK || value.charCodeAt(2) === DOT) &&
-        isSeparator(value.charCodeAt(3)) &&
-        isAsciiLetter(value.charCodeAt(4)) &&
-        value.charCodeAt(5) === COLON &&
-        isSeparator(value.charCodeAt(6))) {
-        return 5;
-    }
-    return -1;
-}
+import { hasWindowsDrivePrefix, rootedWindowsDriveColonIndex, windowsNamespaceMarker, } from "./windows-path-syntax.js";
 function isBareWindowsNamespaceDrive(value) {
-    return (value.length === 6 &&
-        isSeparator(value.charCodeAt(0)) &&
-        isSeparator(value.charCodeAt(1)) &&
-        (value.charCodeAt(2) === QUESTION_MARK || value.charCodeAt(2) === DOT) &&
-        isSeparator(value.charCodeAt(3)) &&
-        isAsciiLetter(value.charCodeAt(4)) &&
-        value.charCodeAt(5) === COLON);
+    return value.length === 6 && windowsNamespaceMarker(value) !== undefined &&
+        hasWindowsDrivePrefix(value, 4);
 }
 /**
  * Capture an ordinary Windows drive-relative path without normalizing its raw
@@ -47,9 +13,7 @@ function isBareWindowsNamespaceDrive(value) {
 export function anchorWindowsDriveRelativePath(value) {
     if (process.platform !== "win32" || path.isAbsolute(value))
         return value;
-    if (value.length < 2 ||
-        !isAsciiLetter(value.charCodeAt(0)) ||
-        value.charCodeAt(1) !== COLON) {
+    if (!hasWindowsDrivePrefix(value)) {
         return value;
     }
     const drive = value.slice(0, 2);
@@ -64,7 +28,7 @@ export function anchorWindowsDriveRelativePath(value) {
 export function resolvePathPreservingWindowsRoot(value) {
     if (value.length === 7 &&
         process.platform === "win32" &&
-        rootedDriveColonIndex(value) === 5) {
+        rootedWindowsDriveColonIndex(value) === 5) {
         return value.includes("/") ? value.replaceAll("/", "\\") : value;
     }
     const resolved = path.resolve(value);
@@ -110,7 +74,7 @@ export function resolvePathFromBasePreservingWindowsRoot(base, ...segments) {
  */
 export function pathForWindowsFilesystem(value) {
     if (process.platform !== "win32" ||
-        rootedDriveColonIndex(value) !== 5) {
+        rootedWindowsDriveColonIndex(value) !== 5) {
         return value;
     }
     if (value.length === 7) {
@@ -132,7 +96,7 @@ export function hasWindowsPathAlias(value, kind, platform = process.platform) {
         return false;
     if (kind === "relative")
         return true;
-    return firstColon !== rootedDriveColonIndex(value) || value.indexOf(":", firstColon + 1) !== -1;
+    return firstColon !== rootedWindowsDriveColonIndex(value) || value.indexOf(":", firstColon + 1) !== -1;
 }
 export function assertNoWindowsPathAliasForPlatform(value, kind, message, platform) {
     if (hasWindowsPathAlias(value, kind, platform)) {

package/dist/windows-path-syntax.d.ts

@@ -0,0 +1,5 @@
+export declare function isWindowsSeparator(value: string, offset: number): boolean;
+export declare function hasWindowsDrivePrefix(value: string, offset?: number): boolean;
+/** Classify a raw prefix without normalizing any path components. */
+export declare function windowsNamespaceMarker(value: string): "." | "?" | undefined;
+export declare function rootedWindowsDriveColonIndex(value: string): number;

package/dist/windows-path-syntax.js

@@ -0,0 +1,21 @@
+export function isWindowsSeparator(value, offset) {
+    const code = value.charCodeAt(offset);
+    return code === 0x2f || code === 0x5c;
+}
+export function hasWindowsDrivePrefix(value, offset = 0) {
+    const letter = value.charCodeAt(offset) | 0x20;
+    return letter >= 0x61 && letter <= 0x7a && value.charCodeAt(offset + 1) === 0x3a;
+}
+/** Classify a raw prefix without normalizing any path components. */
+export function windowsNamespaceMarker(value) {
+    const marker = value[2];
+    return (marker === "." || marker === "?") &&
+        isWindowsSeparator(value, 0) && isWindowsSeparator(value, 1) &&
+        isWindowsSeparator(value, 3) ? marker : undefined;
+}
+export function rootedWindowsDriveColonIndex(value) {
+    const colon = hasWindowsDrivePrefix(value)
+        ? 1
+        : windowsNamespaceMarker(value) !== undefined && hasWindowsDrivePrefix(value, 4) ? 5 : -1;
+    return colon >= 0 && isWindowsSeparator(value, colon + 1) ? colon : -1;
+}

package/dist/windows-security-command.d.ts

@@ -23,4 +23,3 @@ export declare function protectPrivateWindowsFileCommand(fd: number, targetPath:
 }>;
 export declare function verifyPrivateWindowsFileCommandSync(fd: number, targetPath: string, expectedFileIdentity: string, expectedParentIdentity: string, expectedLinks?: number): void;
 export declare function verifyPrivateWindowsFileCommand(fd: number, targetPath: string, expectedFileIdentity: string, expectedParentIdentity: string, expectedLinks?: number): Promise<void>;
-//# sourceMappingURL=windows-security-command.d.ts.map

package/dist/windows-security-facts.d.ts

@@ -3,4 +3,3 @@ import type { NativeWindowsSecurityFacts } from "./native-binding.js";
 export declare function parseWindowsSecurityCommandFacts(value: unknown): NativeWindowsSecurityFacts;
 /** Native and command observations share the same fail-closed admission policy. */
 export declare function validateSecureWindowsSecurityFacts(value: unknown): NativeWindowsSecurityFacts;
-//# sourceMappingURL=windows-security-facts.d.ts.map

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

@@ -1,7 +1,13 @@
 import type { FileHandle } from "node:fs/promises";
+export type WriteFileWindowOptions = {
+    signal?: AbortSignal;
+    /** Synchronous authority check immediately before every write, including short-write retries. */
+    assertBeforeMutation?: () => void;
+};
+/** Write borrowed bytes completely; null advances the cursor, an explicit position preserves it. */
+export declare function writeFileWindowFully(handle: FileHandle, bytes: Uint8Array, position: number | null, options?: WriteFileWindowOptions): Promise<void>;
 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.js

@@ -1,6 +1,29 @@
 import fs from "node:fs";
+import { snapshotByteView } from "./byte-view.js";
 import { FsSafeError } from "./errors.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
 const WRITE_CHUNK_BYTES = 512 * 1024;
+/** Write borrowed bytes completely; null advances the cursor, an explicit position preserves it. */
+export async function writeFileWindowFully(handle, bytes, position, options = {}) {
+    const payload = snapshotByteView(bytes);
+    if (position !== null && (!Number.isSafeInteger(position) || position < 0 ||
+        !Number.isSafeInteger(position + payload.byteLength))) {
+        throw new RangeError("write position and window end must be non-negative safe integers");
+    }
+    const signal = options.signal;
+    const assertion = options.assertBeforeMutation;
+    signal?.throwIfAborted();
+    await writeAllToFile(handle, payload, {
+        position: position === null ? undefined : position,
+        assertBeforeMutation: () => {
+            signal?.throwIfAborted();
+            assertSynchronousCallbackResult(assertion === undefined ? undefined : Reflect.apply(assertion, options, []), "assertBeforeMutation");
+            signal?.throwIfAborted();
+        },
+    });
+    // A pending write must settle before cancellation releases the caller's buffer and handle.
+    signal?.throwIfAborted();
+}
 export async function writeAllToFile(target, data, options = {}) {
     const buffer = typeof data === "string" ? Buffer.from(data, options.encoding ?? "utf8") : data;
     let offset = 0;

package/dist/write-open-flags.d.ts

@@ -2,4 +2,3 @@ import fsSync from "node:fs";
 export declare function resolveNonblockingWriteFlag(constants?: Partial<Pick<typeof fsSync.constants, "O_NONBLOCK">>): number;
 export declare function isNonRegularWriteOpenError(error: unknown, filePath: string, flags: number): Promise<boolean>;
 export declare function isNonRegularWriteOpenErrorSync(error: unknown, filePath: string, flags: number): boolean;
-//# sourceMappingURL=write-open-flags.d.ts.map

package/dist/write-open-flags.js

@@ -13,14 +13,7 @@ function isNonblockingWriteEnxio(error, flags) {
 // A no-reader FIFO rejects a nonblocking write-only open before fstat is possible.
 // Reclassify only a confirmed non-regular path; inconclusive races keep the errno.
 export async function isNonRegularWriteOpenError(error, filePath, flags) {
-    if (!isNonblockingWriteEnxio(error, flags))
-        return false;
-    try {
-        return !fsSync.lstatSync(filePath).isFile();
-    }
-    catch {
-        return false;
-    }
+    return isNonRegularWriteOpenErrorSync(error, filePath, flags);
 }
 export function isNonRegularWriteOpenErrorSync(error, filePath, flags) {
     if (!isNonblockingWriteEnxio(error, flags))

package/dist/write-queue.d.ts

@@ -1,2 +1 @@
 export declare function serializePathWrite<T>(key: string, run: () => Promise<T>): Promise<T>;
-//# sourceMappingURL=write-queue.d.ts.map

package/dist/write-queue.js

@@ -1,10 +1,7 @@
 const writeQueues = new Map();
 export async function serializePathWrite(key, run) {
     const previous = writeQueues.get(key) ?? Promise.resolve();
-    const task = (async () => {
-        await previous.catch(() => undefined);
-        return await run();
-    })();
+    const task = previous.then(() => run());
     const done = task.then(() => undefined, () => undefined);
     writeQueues.set(key, done);
     try {

package/docs/advanced.md

@@ -19,7 +19,7 @@ import {
 
 ## What lives here
 
-The exports group into a handful of themes. Each documented helper has its own page; everything else is reference-only and tracked here.
+The exports group into a handful of themes. Documented helpers link to their contract below or a dedicated page; everything else is reference-only and tracked here.
 
 ### Path scopes and root paths
 
@@ -71,7 +71,9 @@ 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. |
 | `createDirectory`, `createDirectorySync`, `createFileSync` | [Exclusive leaf creation](creation.md) | Create one exclusive entry under an existing trusted parent, optionally with private permissions; file creation returns an owned disposable descriptor. |
 | `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. |
+| `writeFileWindowFully`, `WriteFileWindowOptions` | [Borrowed-handle writes](#borrowed-handle-writes) | Write all supplied bytes at an explicit position or the current cursor, completing short writes with cancellation and per-write authority checks. |
 | `copyFileHandle`, `copyFileDescriptorSync`, `CopyFileHandleOptions` | [copy.md](copy.md#borrowed-filehandle-transfers) | Copy caller-owned regular files through async handles or sync descriptors from position zero with byte limits and synchronous callbacks; preserves cursors and leaves publication and cleanup to the caller. |
+| `sameFileContentsSync`, `SameFileContentsOptions` | [Exact file comparison](file-contents.md) | Compare borrowed regular-file descriptors byte for byte through EOF with bounded memory and an optional per-file byte limit, preserving both cursors and lifetimes. |
 | `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. |
@@ -151,6 +153,71 @@ component is followed by another segment, both helpers throw
 `FsSafeError("not-file")` before the platform can expose that state as POSIX
 `ENOTDIR` or Windows `ENOENT`.
 
+#### Borrowed-handle writes
+
+Use `writeFileWindowFully()` when you already own a writable file handle and
+need to complete a byte-window write, including positive short writes.
+
+```ts
+import { root } from "@openclaw/fs-safe";
+import { writeFileWindowFully } from "@openclaw/fs-safe/advanced";
+
+const workspace = await root("/srv/workspace");
+await using opened = await workspace.openWritable("record.bin", { writeMode: "update" });
+await writeFileWindowFully(opened.handle, Buffer.from([1, 2, 3]), 16);
+```
+
+```ts
+type WriteFileWindowOptions = {
+  signal?: AbortSignal;
+  assertBeforeMutation?: () => void;
+};
+
+function writeFileWindowFully(
+  handle: import("node:fs/promises").FileHandle,
+  bytes: Uint8Array,
+  position: number | null,
+  options?: WriteFileWindowOptions,
+): Promise<void>;
+```
+
+A numeric `position` writes at that offset without moving the handle's cursor.
+It and the exclusive window end (`position + bytes.byteLength`) must be
+non-negative safe integers; invalid ranges throw `RangeError` before mutation.
+Bounds come from the intrinsic byte view, ignoring shadowed metadata properties.
+Pass `null` to write at and advance the current cursor. Each syscall writes at
+most 512 KiB. A write that makes no progress throws
+`FsSafeError("helper-failed")`; filesystem errors propagate unchanged.
+Empty input still validates the range and checks cancellation, but performs no
+I/O and does not call `assertBeforeMutation`.
+
+The caller must supply a writable regular-file handle, opened **without append
+mode** for numeric positions. Some operating systems ignore positioned-write
+offsets on append handles, and this helper does not inspect file type or open
+flags. Opening, path admission, identity checks, and closing remain the caller's
+responsibility. Keep the handle open and the borrowed bytes unchanged, attached,
+and accessible until the promise settles; avoid concurrent I/O when it can change
+the intended contents or shared cursor. The helper does not acquire a lock.
+
+`assertBeforeMutation` runs synchronously immediately before every write,
+including short-write retries. A thrown value propagates unchanged; a Promise or
+thenable return rejects with `TypeError` before that write. The callback must not
+modify the payload or handle. It does not run as a final completion check; the
+caller owns any authority check before later publication or other mutations.
+
+`signal` is checked at admission, before and after each authority callback, and
+after each pending write settles. Cancellation waits for an in-flight write and
+then rejects with the signal's reason without starting another syscall. If that
+write fails, its filesystem error or zero-progress failure takes precedence over cancellation. Already
+written bytes remain changed; there is no rollback or hidden write after the
+promise settles.
+
+The helper neither truncates an existing suffix nor changes permissions,
+synchronizes, or closes the handle. Callers retain those responsibilities and
+any wider transaction policy. For complete replacement with best-effort
+rollback, use [`overwriteFileHandle()`](in-place-write.md); for root-bounded
+atomic replacement, use [`Root.write()`](writing.md).
+
 ### Local roots and file URLs
 
 | Export | Page | Notes |

package/docs/archive.md

@@ -11,6 +11,14 @@ These TAR routes work with all optional dependencies omitted and need no
 runtime interpreter, download, install script, or consumer compiler toolchain.
 ZIP fallback still requires optional `jszip`.
 
+The shared TAR parser reuses the already-validated owned path for ordinary
+members. Original header names and USTAR prefixes still undergo validation
+even when PAX or GNU metadata supplies an override; effective override paths
+retain their separate checks. Empty USTAR prefixes retain field decoding and
+padding checks; path validation applies to nonempty prefixes. Joining an
+admitted prefix and name with a separator preserves their checked components,
+so the parser does not repeat the same component validation on the joined path.
+
 `auto` prefers an available native binding; a native operation failure is
 terminal and never retries through WASM. `require` rejects a missing binding
 with `FsSafeError("helper-unavailable")`, including for zstd/bzip2 suffix
@@ -31,6 +39,7 @@ await extractArchive({
   timeoutMs: 15_000,                  // hard budget; active destination mutation is joined
   stripComponents: 0,                 // tar-style strip-leading-dirs
   entryModes: "clamp",                // default; use "preserve" for archive rwx bits
+  entryUmask: 0,                      // default; remove these bits from final modes
   entryFilter: ({ path, kind, size }) => "extract",
   onFiltered: "reject-archive",        // default; opt into "skip-entry" explicitly
   limits: {
@@ -50,7 +59,7 @@ await extractArchive({
 type ExtractArchiveOptions = {
   archivePath: string;          // absolute path to the archive
   destDir: string;              // absolute destination directory; must already exist
-  timeoutMs: number;            // positive wall-clock budget; <= 0/non-finite disables it
+  timeoutMs: number;            // positive elapsed-time budget; <= 0/non-finite disables it
   durable?: boolean;            // false; opt into syncing published files and directories before completion
   kind?: ArchiveKind;           // "zip" | "tar" | "tar-zstd" | "tar-bzip2"
   stripComponents?: number;     // strip N leading dirs from entry paths
@@ -58,6 +67,7 @@ type ExtractArchiveOptions = {
   limits?: ArchiveExtractLimits;
   logger?: ArchiveLogger;       // { info?, warn? }
   entryModes?: "clamp" | "preserve";
+  entryUmask?: number;          // integer 0..0o777; defaults to 0
   entryFilter?: (entry: { path: string; kind: ArchiveEntryKind; size: number }) =>
     "extract" | "skip";
   onFiltered?: "reject-archive" | "skip-entry";
@@ -71,6 +81,12 @@ once, deepest first, and finally the destination directory. All work stays insid
 the extraction deadline; active syncs are joined before rejection. File sync
 failures use the same error surface as `Root.copyIn()`; directory I/O failures
 also reject, with the existing platform limitations on directory flushing.
+
+Deadline checks use a monotonic clock, including before queued mutations start
+and before reporting success. Synchronous caller code can delay the timer, but
+cannot permit the next operation after the budget expires. This does not
+interrupt a callback halfway through execution or replace its own thrown error;
+active destination mutations are still joined before timeout rejection.
 Files whose final mode prevents reading, including `0o000` and write-only files,
 sync once through the copy's retained descriptor during publication. Permissions
 are never widened to reopen them. Directory modes are finalized after the file
@@ -103,6 +119,15 @@ including a mode containing only stripped special bits, stays zero under
 directories; ZIP UNIX creator records with zero attributes are explicit zero,
 while non-UNIX ZIP records use the absent-metadata defaults.
 
+`entryUmask` removes permission bits after the selected mode policy: final modes
+are the policy result `& ~entryUmask`. It applies to files, explicit directories,
+and implicit parent directories, including existing destination directories.
+The destination root and private staging modes are unchanged. The default `0`
+preserves existing behavior; invalid masks reject before extraction begins.
+fs-safe neither reads nor changes the process umask. Pass
+`entryUmask: process.umask()` explicitly when that is the caller's policy.
+Windows retains the POSIX-mode limitations described below.
+
 TAR mode fields containing only NUL/ASCII-space padding use absent defaults.
 Both backends recognize GNU binary modes, including signed values,
 within JavaScript's safe-integer range before masking permission bits.
@@ -116,7 +141,7 @@ stay `0o600` and directories `0o700` until publication. Files receive their fina
 mode through the guarded copy's owned writer descriptor. Directories are pinned
 before descending and finalized after their children, including empty and
 restrictive directories. Explicit accepted directory modes win regardless of
-archive order; implicit parents receive `0o755`. Existing destination directories
+archive order; implicit parents receive `0o755 & ~entryUmask`. Existing destination directories
 also receive the requested final mode. They are never temporarily widened to
 allow child writes; insufficient write/search access still rejects.
 
@@ -154,6 +179,13 @@ between native and JavaScript paths rather than reimplementing it in Rust.
 
 ZIP extraction and bounded reads admit every physical central-directory record and its referenced local header before either decoder can normalize or collapse names. Raw names and valid Unicode Path names must pass traversal checks before stripping, filtering, or selecting a requested member; duplicate or colliding names reject with `entry-path`, even in unrelated or skipped members. Materially conflicting local/central or Unicode interpretations, malformed critical metadata, and ambiguous framing reject with `ArchiveFormatError`. Harmless internal separator and dot-component equivalence is allowed only after validation; every raw and Unicode interpretation must also agree on whether its name ends in `/` or `\`. Ordinary legacy filename decoding remains backend-selected. Native ZIP extraction groups nearby metadata reads into at most two 4 KiB read-ahead buffers per admission pass; larger records retain separately bounded reads. Buffered record views remain stable across eviction, and cached work periodically yields for deadline checks.
 
+ZIP end-record admission searches the bounded comment window for signatures
+while retaining complete comment-length and ambiguity checks. Dense signature
+sequences fall back to the bounded byte scan.
+The separate `readZipCentralDirectoryEntryCount(buffer)` hint uses bounded
+reverse searches for comments and retains its latest-valid-record selection;
+it does not replace strict archive admission.
+
 ZIP admission establishes each entry's kind before callbacks: a high-word UNIX
 symlink type takes precedence regardless of creator, followed by the DOS directory
 bit, the exact UNIX directory type, or a terminal slash/backslash. Native manifests
@@ -185,6 +217,10 @@ decoded validation. Unicode Path admission is shared only when both the raw name
 and the complete Unicode fields match; different fields still verify their own
 CRC and interpretation. Shared backing memory is checked independently. Decoded
 name validation is not reused across entries or archives.
+UTF-8-flagged ASCII names in nonshared backing memory reuse their raw-path
+validation, and an identical decoded spelling reuses its canonical key. Shared
+name bytes still undergo independent decoding and validation; Unicode Path
+fields retain their own CRC and interpretation checks.
 
 `stripComponents` removes leading nonempty, non-`.` path components after
 normalizing separators. For example, `./pkg/hello.txt` with
@@ -202,6 +238,9 @@ directory paths. For example, `./pkg//state\cache/value` is presented as
 `pkg/state/cache/value`, even with `stripComponents: 1`. Case and Unicode
 spelling are preserved. Local PAX `path`, GNU long-name, and supported ZIP
 Unicode Path names use the same canonicalization.
+Callbacks follow physical archive order, including ZIP names that look like
+integer object keys. The public ZIP loader's `files` object retains ordinary
+JavaScript object enumeration and mutation behavior.
 
 Raw paths undergo traversal, absolute/drive-path, and NUL validation **before**
 canonicalization; normalization cannot turn an unsafe path into an accepted

package/docs/atomic.md

@@ -16,7 +16,7 @@ import {
 
 Write `content` to a sibling temp file in the destination directory, apply the parent-directory and final file modes through verified descriptors, optionally `fsync` the file descriptor, optionally `fsync` the parent directory after rename, then atomically rename over the destination. No permission change follows a caller-supplied pathname.
 
-On POSIX, the parent is opened with no-follow and directory-only flags, checked against its pre-open identity, and mode-adjusted through that descriptor. A replacement symlink is rejected rather than followed. If the directory cannot be opened for descriptor access, the operation fails closed instead of retrying by pathname. Windows does not enforce POSIX directory modes and Node cannot consistently open directory descriptors there, so `dirMode` is passed only to `mkdir`; no pathname `chmod` fallback is attempted.
+On POSIX, the parent is opened with no-follow and directory-only flags, checked against its exact pre-open device/inode identity, and mode-adjusted through that descriptor. A replacement symlink is rejected rather than followed. If the directory cannot be opened for descriptor access, the operation fails closed instead of retrying by pathname. Windows does not enforce POSIX directory modes and Node cannot consistently open directory descriptors there, so `dirMode` is passed only to `mkdir`; no pathname `chmod` fallback is attempted.
 
 Async replacements to the same destination are serialized inside the current process, so two overlapping `replaceFileAtomic()` calls do not interleave their temp-write/rename phases. Use a sidecar lock when multiple processes may write the same target.
 
@@ -92,10 +92,13 @@ await replaceFileAtomic({
 
 If `beforeRename` throws, the rename is skipped and the owned temp file is removed — the destination is unchanged. Cleanup unlinks only the exact admitted single-link file; a substitute observed at the temp name is preserved and removed from cleanup authority. The same identity is rechecked before every rename retry, when entering copy fallback, and at the final name after rename. A post-rename verification failure reports the race without rolling back or deleting the published name.
 
-JavaScript permits `beforeRename` callbacks to throw any value, including
+JavaScript permits `beforeRename` callbacks and filesystem adapters to throw any value, including
 `undefined`, `null`, `false`, signed zero, `0n`, an empty string, and `NaN`.
-Once such an operation failure reaches temp-owner settlement, atomic replacement
-preserves that value when cleanup and close succeed. With
+Atomic replacement preserves such operational failures when cleanup and close
+succeed, including rename and post-rename verification failures. Rename retry
+and copy-fallback classification reads the error code once without coercion;
+missing or unreadable codes preserve the original failure. A rejected call has
+no success receipt even if an adapter committed its rename before throwing. With
 `throwOnCleanupError: true`, an additional owned-temp cleanup failure keeps the
 existing cleanup wrapper whose `cause` is the original thrown value. A later
 descriptor-close failure is reported in an `AggregateError`, in operation/cleanup
@@ -150,6 +153,28 @@ must not have aliases. The policy reads `nlink` from a pinned destination
 descriptor, not pathname metadata, before rename and rechecks it in the copy
 fallback.
 
+The asynchronous helper closes a successfully admitted hardlink-check pin
+best-effort, including synchronous adapter throws and rejected close promises.
+The synchronous helper reports a close failure after successful admission.
+
+Source and pinned destination admission compare exact bigint device/inode
+observations, so distinct identities that round to the same JavaScript number
+cannot authorize a copy. Unknown Windows identities get one bounded reinspection
+of the same descriptor or path; incomplete or inconsistent observations fail
+closed without reopening. Injected filesystem adapters must honor the
+`{ bigint: true }` stat option. Source admission reuses that exact pair instead
+of immediately repeating it with numeric metadata.
+
+Copy-source close is best-effort. A failed pinned-destination admission also
+preserves its selected failure when close fails. These cleanup rules include
+synchronous throws and rejected promises from custom asynchronous adapters.
+
+The best-effort parent-directory synchronization helper also ignores either form
+of close failure. Parent-directory mode admission and its close remain fail-closed.
+A compatibility-publication handle that was not adopted also receives one
+best-effort close, preserving the selected verification or previous-handle close
+failure. The retained owner's close failures remain reportable.
+
 The default `copyFallbackRestore: "none"` preserves the existing fallback
 contract: a failed copy can leave a partial destination. For state files where
 preserving the old bytes is more important, choose `"restore-original"` and set
@@ -349,7 +374,10 @@ the preflight cap fails with `FsSafeError("too-large")`.
 If another writer changes source entries during the fallback, the staged copy
 throws `ESTALE` before commit when possible. If the destination has already
 been committed, cleanup still preserves the changed source entries and throws
-`ESTALE`. Directory manifests retain an exact bigint device/inode receipt from
+`ESTALE`. Copied file and symlink manifests retain exact bigint identities and
+nanosecond timestamps, so rounded file IDs cannot authorize copying or removal
+of a different entry. Hardlink groups also use exact identities. Directory
+manifests retain an exact bigint device/inode receipt from
 copy admission. Each directory is rechecked after traversal, and the source root
 is checked again before publication. Cleanup checks the same receipt before
 removing children, then invokes mutation authority and rechecks the receipt and
@@ -366,6 +394,11 @@ unlink is verified through a remaining manifested alias and its exact resulting
 identity becomes the next cleanup receipt. This accounts for the operation's
 own link-count and ctime changes without suppressing unexpected external
 mutations.
+On Windows, opening a regular source may advance its ctime while all other
+fingerprint fields match. That exception applies only to opening; post-copy
+verification and cleanup retain their full fingerprint checks.
+Copied aliases share each verified open-time update. Changes observed between
+copies still reject instead of being mistaken for an owned open transition.
 
 ### Mutation authority and publication receipts
 
@@ -404,6 +437,11 @@ thenable, or any other value fails with a `TypeError`; rejected asynchronous
 results are consumed. Perform asynchronous policy checks before calling the
 helper and use the authority callback to recheck the current owner at each
 mutation boundary. All callbacks are captured before the first await.
+Copied source leaves are checked again immediately after authority returns and
+before unlink is submitted. Supplying any of the three callbacks also
+retains the original source-parent route and renews copied-directory ancestry
+before cleanup. Substituted entries are preserved; pathname checks and unlink
+remain a best-effort sequence, not atomic.
 
 `onDestinationPublished` runs exactly once after a successful rename resolves,
 before awaited post-rename directory checks or source cleanup. It receives a

package/docs/contributing.md

@@ -157,6 +157,10 @@ pnpm archive:producer-smoke ./consumer require
 This uses a child bound to canonical cwd/device/inode running `/usr/bin/tar -czf - .`
 with unchanged stdout, and npm tar, on synthetic Unicode/newline/long-name files,
 then the installed package API for exact payload hashes and bounded reads.
+The consumer must be separate from the source checkout; package resolution must
+stay within its own `node_modules`, including pnpm's local `.pnpm` layout.
+Workspace self-resolution, upward resolution, and external package links reject
+before package imports or archive fixture creation.
 It also rejects a valid PAX override attached to an invalid raw UTF-8 field.
 The `require` command must resolve the freshly packed native binding; the
 `off` command uses the installed WASM asset. No live user files are read.

package/docs/copy.md

@@ -178,6 +178,8 @@ These are low-level operations on caller-owned absolute paths, not Root-relative
 
 An already aborted signal prevents dispatch. In-flight cancellation stops cancellable traversal and waits for admitted native writes to finish before rejecting. APFS and Btrfs bulk operations cannot be interrupted once dispatched. An aborted or failed call can therefore leave a destination, including a complete bulk clone. It remains caller-owned; after settlement, the caller decides whether to retain or remove it. Do not start cleanup by racing the cloning promise against an abort promise.
 
+Tree copying preserves caller abort handlers and receives cancellation even when a caller handler stops event propagation, including native cloning and byte-copy fallbacks.
+
 Completion is not a crash-durability guarantee. The API is suitable for reconstructible templates and checkouts; it does not sync every file or replace application-level publication and recovery rules.
 
 A close-only rejection reports descriptor settlement, not whether bytes reached stable storage. The destination can already be complete when a close fails, just as other failed or cancelled calls can leave caller-owned output. Inspect or remove that output only after the copying promise settles and under the same source and destination authority assumptions.

package/docs/creation.md

@@ -42,12 +42,16 @@ POSIX creation requests `0700` for directories and `0600` for files by default;
 the umask may restrict those permissions further. Existing directory privacy
 checks never broaden permissions.
 
-Native private file creation checks the retained descriptor's actual owner and
+Private POSIX `Root.create()` and `createJson()` writes check the retained descriptor's actual owner and
 permissions before writing payload bytes, after producer and authority callbacks,
-and at publication. A successful `chmod` is insufficient: filesystems that do not
+and at publication, including JavaScript fallback writes. Payload writes require
+the temporary `0600` mode even when the requested final mode differs.
+Private ownership, permissions and ACLs are checked before preparing that mode,
+including after authority callbacks; valid restrictive initial modes remain supported.
+A successful `chmod` is insufficient: filesystems that do not
 enforce owner-only permissions reject before payload writes. The requested final
 mode is verified too; a failure after publication preserves the completed file
-and reports its published outcome.
+and staged creation reports its published outcome.
 
 On macOS (Darwin), private creation also requires an ACL-free result. The native
 helper must provide `inspectDarwinAcl`; native `off`, a missing helper, or an
@@ -113,7 +117,7 @@ thenables reject before mutation. Parent and file identity checks are repeated
 after the callback. Final permission checks, descriptor settlement and cleanup
 retain the operation's cleanup ownership after publication.
 
-Failure does not always mean the final path is absent. Private-file errors
+Failure does not always mean the final path is absent. Staged private-file errors
 after publication or ambiguous publication preserve the destination and carry
 `details.publication.status` (`published` or `indeterminate`), the target path and
 staging cleanup outcome. Cleanup and close failures retain the original error

package/docs/durability.md

@@ -89,6 +89,29 @@ or reconstructed numeric identity is accepted only when both components are
 safe integers and, on Windows, nonzero. Rounded or unknown caller identities
 fail with `path-mismatch` rather than authorizing a different directory.
 
+Caller-supplied receipts may use `DirectoryReceipt<BigIntStats>` with the result
+of `lstat(path, { bigint: true })`. `pinDirectory()`, `syncDirectory()`,
+`syncDirectorySync()`, `publishFileExclusive()`'s `parentReceipt`, and
+`stageFileInDirectory()` accept both numeric and bigint receipt inputs.
+`DirectoryReceipt` without a type argument and all returned durability receipts
+still expose numeric `Stats`, including working type predicates and Date
+properties. Bigint metadata is projected from the supplied observation, retaining
+fractional timestamps and the private exact device/inode identity.
+
+```ts
+import { lstatSync, realpathSync, type BigIntStats } from "node:fs";
+import { syncDirectorySync, type DirectoryReceipt } from "@openclaw/fs-safe/durability";
+
+const directoryPath = "/srv/backups/sqlite";
+const receipt: DirectoryReceipt<BigIntStats> = {
+  path: directoryPath,
+  realPath: realpathSync(directoryPath),
+  identity: lstatSync(directoryPath, { bigint: true }),
+};
+// Keep this receipt across the application's publication operation.
+const outcome = syncDirectorySync(receipt);
+```
+
 Call `close()` in `finally`. Closing is idempotent; using a closed pin fails.
 
 These checks intentionally reject a moved or replaced pathname. For one file's
@@ -276,6 +299,11 @@ pathname without reopening the file and repeat the symlink and file-type checks.
 POSIX opens are nonblocking, so a raced FIFO or device is rejected after
 descriptor inspection rather than waiting for a writer.
 
+A pathname hash reports failure to close its owned descriptor after successful
+hashing. If hashing, admission, or cancellation already failed, that original
+failure remains primary even when close also fails. This also applies to
+`sha256FileSync()`; borrowed handles and descriptors remain caller-owned.
+
 When the optional binding is active, hashing runs as an async native task and
 does not occupy the JavaScript event loop with digest updates. With native mode
 `off`, or in `auto` when no binding loads, the fallback performs asynchronous
@@ -347,6 +375,13 @@ this receipt instead of inferring ownership from path existence. The original
 failure remains available as `cause`. Failures before target creation retain
 their existing error shape and do not claim a cleanup result.
 
+Source and target identities are checked again after successful or unsupported
+directory synchronization, while their descriptors remain owned. A late
+verification failure retains its strategy's verification phase and is not a
+directory-sync failure. Completed copied targets stay pinned during conditional
+cleanup; substituted entries remain untouched. Returned numeric metadata comes
+from the retained target descriptor and grants no continuing pathname authority.
+
 ### Directory-sync failure policy
 
 `onSyncFailure` applies only after target creation and content/identity fencing