@openclaw/fs-safe 0.16.0 → 0.17.0

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,14 @@ 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.
 
+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.
+
 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 +360,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 +380,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 +423,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/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

package/docs/file-contents.md

@@ -0,0 +1,68 @@
+# Exact file comparison
+
+`sameFileContentsSync()` compares the bytes of two already-open regular files,
+starting at offset zero. It uses bounded buffers and completes positive short
+reads independently on each descriptor. A `true` result requires matching bytes
+and observed EOF on both inputs; a difference can return `false` immediately.
+
+```ts
+import fs from "node:fs";
+import { sameFileContentsSync } from "@openclaw/fs-safe/advanced";
+
+const source = fs.openSync("/trusted/source.sqlite", "r");
+try {
+  const copy = fs.openSync("/trusted/copy.sqlite", "r");
+  try {
+    console.log(sameFileContentsSync(source, copy, { maxBytes: 256 * 1024 * 1024 }));
+  } finally {
+    fs.closeSync(copy);
+  }
+} finally {
+  fs.closeSync(source);
+}
+```
+
+## Signature
+
+```ts
+type SameFileContentsOptions = { maxBytes?: number };
+
+function sameFileContentsSync(
+  leftFd: number,
+  rightFd: number,
+  options?: SameFileContentsOptions,
+): boolean;
+```
+
+Both descriptors must be open regular files. Nonregular inputs throw
+`FsSafeError("not-file")`; underlying filesystem errors propagate unchanged.
+Passing the same descriptor twice is allowed, but does not bypass validation,
+the byte limit, or reads. File sizes are checked against the limit, but are not
+used as proof that contents match or that EOF has been reached.
+
+## Bounds and ownership
+
+`maxBytes` is a limit for each file, not their combined size. It accepts a
+non-negative safe integer or `Infinity`; omission imposes no caller-selected
+limit. Invalid limits throw `RangeError` before filesystem work. Comparisons
+cannot exceed `Number.MAX_SAFE_INTEGER` bytes because positions must remain
+exactly representable.
+
+A reported file size above the limit throws `FsSafeError("too-large")` before
+reading. At the limit, the comparison reads at most one additional byte from
+each input to prove EOF; any observed overflow throws the same error. A
+matching prefix is never reported as complete equality. An early mismatch
+does not scan the remaining bytes or promise to detect later errors or growth.
+A zero-byte limit admits two empty files. Memory use is at most two 1 MiB
+payload buffers, regardless of file size.
+
+The operation neither changes the descriptors' current offsets nor closes
+them, including on failure. It performs no writes, hashing, pathname lookup,
+or identity comparison. Callers retain path admission, hardlink policy,
+descriptor lifetime, and any before/after mutation-fingerprint checks. A
+comparison is not a snapshot of concurrently modified files; applications
+requiring stable contents must retain their existing coordination and checks.
+
+Use [`readFileWindowFullySync()`](positional-read.md) for a selected byte
+window and [bounded descriptor reads](advanced.md#files-and-identity) when the
+caller needs the file contents in memory.

package/docs/json.md

@@ -146,10 +146,11 @@ where lower latency matters more than crash-durability.
 
 Synchronous variant. It pretty-prints with two spaces, appends a newline,
 creates parents at `0o700`, writes at `0o600`, and synchronizes the parent
-directory best-effort. File-mode tightening carries the staged bigint identity
-through rename and applies `fchmod` only when the reopened descriptor and current
-pathname still name that same single-link regular file; a swap is preserved and
-skips this best-effort step. It has no options bag. On `EPERM`/`EEXIST`, its legacy
+directory best-effort. A retained staging descriptor carries the exact bigint
+identity through rename and file-mode tightening. Publication and cleanup never
+adopt a substituted temporary file: a changed identity, type or link count rejects
+the write and leaves the replacement untouched. A swap detected after publication
+also rejects without deleting or changing the replacement. It has no options bag. On `EPERM`/`EEXIST`, its legacy
 compatibility path removes the existing destination and retries the staged-file
 rename, so that fallback is temporarily non-atomic while retaining the staged
 file's `0600` mode; use the async `writeJson()`/`replaceFileAtomic()` surfaces

package/docs/local-roots.md

@@ -83,6 +83,8 @@ An existing non-directory component cannot be traversed further, including by
 The asynchronous helper opens the candidate through the matched [`Root`](root.md),
 so no-follow, identity, hardlink, device-path, and byte-limit checks happen at
 the read itself.
+Link policies are captured once before root initialization and reused for every
+candidate, so replacing options while a read is pending cannot weaken admission.
 
 ```ts
 type ReadLocalFileFromRootsOptions = LocalRootsInputOptions & {

package/docs/mutation-policy-proof.md

@@ -44,9 +44,11 @@ new placeholder, and before publishing to an existing symlink-selected destinati
 They verify alias binding, destination preservation, observed placeholder/stage
 states, and cleanup before fixture teardown. The default native-off and explicit
 `verify-content-with-lock` native-require configurations both select the existing
-Windows JS buffer writer. The compatibility route is expected not to load the
-addon; the receipt does not mislabel this as native publication or evidence that
-content-verification fallback or lock contention was exercised.
+Windows JS buffer writer. In native-require mode, the compatibility route loads
+the addon to publish its retained sidecar lock through `Root.create`; the payload
+writer remains JS. The receipt does not mislabel this as native payload
+publication or evidence that content-verification fallback or lock contention
+was exercised.
 
 ## Bounds and interpretation
 

package/docs/native.md

@@ -76,14 +76,14 @@ whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
   or add-on CRT descriptor namespace.
 
 The internal macOS `inspectDarwinAcl(fd)` capability reports `absent`, `empty`,
-or `present` for the opened object's extended ACL. It synchronously owns a
-close-on-exec duplicate for inspection, leaves the caller's descriptor and file
-position alone, and never reopens a pathname. Darwin's `acl_get_entry` returns
+or `present` for the opened object's extended ACL. It synchronously borrows the
+caller's descriptor, preserving its file position and POSIX record locks, and
+never reopens a pathname. Keep the descriptor open until inspection returns.
+Darwin's `acl_get_entry` returns
 zero for an entry; end-of-list is accepted only for the first entry of a valid,
 privately owned empty ACL. Unsupported, malformed, and failed inspection is not
-reported as absence. These facts do not classify individual ACE permissions,
-prove volume ownership enforcement, or add ACL enforcement to private writers
-and secure readers outside the clone path.
+reported as absence. These facts do not classify individual ACE permissions or
+prove volume ownership enforcement; each caller applies its own security policy.
 
 ## Archives
 
@@ -267,8 +267,9 @@ infer native loading from timing.
 ## Loader security
 
 Importing fs-safe never executes a child process. Linux libc selection uses
-the Node process report, conventional musl library filenames, and the ELF
-`PT_INTERP` field of `process.execPath`. If all probes are inconclusive, the
+the Node process report, then the ELF `PT_INTERP` field of `process.execPath`,
+then conventional musl library filenames. An installed compatibility loader
+does not override the running executable's interpreter. If all probes are inconclusive, the
 loader conservatively attempts the glibc package and lets normal module loading
 fail into `auto` fallback. The loader requires only the package selected from
 the detected target; it never probes unrelated packages, downloads code, or

package/docs/path.md

@@ -44,7 +44,7 @@ opened or mutated.
 
 ### `isPathInsideWithRealpath(rootDir, target, opts?)`
 
-Synchronous. Same as `isPathInside`, but resolves both inputs through `realpath` first. Use this when you want the canonical answer and either input might be a symlink.
+Synchronous. First requires lexical containment with `isPathInside`, then resolves both inputs through `realpath` and checks containment again. A lexically outside path is rejected even if its resolved target is inside the root.
 
 ```ts
 isPathInsideWithRealpath("/srv/uploads", "/srv/symlink-to-elsewhere"); // false
@@ -121,7 +121,7 @@ The check is intentionally not a normal consumer policy knob. Safe read APIs rej
 
 ### `isNotFoundPathError(err)`
 
-`true` if the error is a `NodeJS.ErrnoException` with code `ENOENT` (file or directory missing).
+`true` if the error has code `ENOENT` (file or directory missing) or `ENOTDIR` (a path component is not a directory).
 
 ```ts
 try {
@@ -207,8 +207,8 @@ import {
 } from "@openclaw/fs-safe/advanced";
 ```
 
-- `assertNoPathAliasEscape({ rootRealPath, candidatePath, policy })` — async. Asserts the candidate's resolved real path is inside the root. Configurable via `PATH_ALIAS_POLICIES` (which currently ships only the default `"strict"` policy).
-- `assertNoHardlinkedFinalPath({ filePath })` — async. Throws if the file at `filePath` has `nlink > 1`.
+- `assertNoPathAliasEscape({ absolutePath, rootPath, boundaryLabel, policy? })` — async. Applies root path resolution and final hardlink checks. `policy` defaults to `PATH_ALIAS_POLICIES.strict`; `PATH_ALIAS_POLICIES.unlinkTarget` permits final symlink and hardlink aliases for unlink operations.
+- `assertNoHardlinkedFinalPath({ filePath, root, boundaryLabel, allowFinalHardlinkForUnlink? })` — async. Rejects a regular file with `nlink > 1`; missing paths and nonregular resolved entries are ignored. Setting `allowFinalHardlinkForUnlink: true` skips this check for unlink operations.
 
 Use these when writing a custom helper that wants the same guards `root()` uses but with different surrounding logic.
 

package/docs/public-api.md

@@ -20,6 +20,9 @@ The root subpath also exports `openLocalFileSafely`, `readLocalFileSafely`, and
 `resolveOpenedFileRealPathForHandle` for trusted absolute-file composition.
 They do not create a root boundary around arbitrary caller input; prefer
 `root()` for untrusted paths.
+The handle resolver verifies exact descriptor and pathname identities, with one
+bounded retry for unknown Windows observations. It borrows the handle without
+reading, reopening, closing it, or changing its cursor.
 
 The error helpers are `categorizeFsSafeError` and `FsSafeErrorDetails`. The
 deprecated native-configuration bridge retains the `FsSafePythonConfig` type.
@@ -135,6 +138,8 @@ The durability surface also exports the synchronous strict
 `Sha256FileSyncInput`, `Sha256FileOptions`, and `Sha256FileResult`.
 `sha256FileSync()` provides synchronous pathname or borrowed-descriptor hashing
 with the same byte-budget and digest-result contracts as `sha256File()`.
+`DirectoryReceipt<T>` accepts `Stats` or `BigIntStats` input metadata; its default
+type argument and returned durability receipts remain numeric `Stats`.
 
 ## Archives
 

package/docs/quickstart.md

@@ -60,7 +60,7 @@ await fs.move("notes/today.txt", "notes/archive/today.txt", { overwrite: true })
 await fs.remove("notes/archive/today.txt");
 ```
 
-`move()` defaults to no clobber. That mode requires the native helper so a concurrent target cannot be replaced between an absence check and the rename; without it, the call fails with `helper-unavailable`. Pass `{ overwrite: true }` when replacing the target is intentional. `remove()` works on files and empty directories. For non-empty directories, list and remove children first or use [`replaceDirectoryAtomic`](atomic.md#replacedirectoryatomic).
+`move()` defaults to no clobber. That mode requires the native helper so a concurrent target cannot be replaced between an absence check and the rename; without it, the call fails with `helper-unavailable`. Pass `{ overwrite: true }` when replacing the target is intentional. `remove()` removes files and empty directories by default. To remove a non-empty directory, pass `{ recursive: true }`; use `maxEntries`, `maxDepth`, and `signal` to bound the work. See [`root()`](root.md) for removal ordering, limits, and partial-removal semantics.
 
 ## 5. Inspect
 

package/docs/reading.md

@@ -28,7 +28,7 @@ Regardless of shape, every read goes through the same boundary checks:
 4. Reject `..` traversal and absolute spellings when they resolve outside the root. In-root absolute spellings remain accepted; `readAbsolute` makes that intent explicit.
 5. Open with `O_NOFOLLOW` where available. Any remaining symlink in the path triggers `symlink` unless the call's `symlinks` policy is `follow-within-root`.
 6. Compare the pre-open bigint path identity with the open fd, then perform one best-effort final admission: check the captured root identity, compare the policy-aware pathname with the fd, freshly canonicalize and re-admit that target inside the captured root, compare its exact bigint identity without following a final symlink with the fd, and check the root again. Both final pathname observations run even when their spellings match. An observed swap triggers `path-mismatch` or `outside-workspace`; a missing final path triggers `not-found`.
-7. If `hardlinks: "reject"`, refuse files with `nlink > 1` (`hardlink`).
+7. If `hardlinks: "reject"`, refuse files with `nlink > 1` (`hardlink`), including links introduced before either fresh final pathname observation. Root-file helpers apply the same final check when `rejectHardlinks` is enabled; directory admission is unaffected.
 8. If `maxBytes` is set, refuse reads larger than the cap (`too-large`).
 
 The final fence closes a rejected descriptor before any Root read consumes bytes or
@@ -100,7 +100,7 @@ type RootReadOptions = {
   hardlinks?: "reject" | "allow";   // override defaults.hardlinks
   maxBytes?: number;                // refuse reads larger than this many bytes
   nonBlockingRead?: boolean;        // compatibility hint; safe opens are already nonblocking where supported
-  symlinks?: "reject" | "follow-within-root"; // override defaults.symlinks
+  symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root"; // override defaults.symlinks
 };
 ```
 

package/docs/regular-file.md

@@ -110,6 +110,9 @@ descriptor, and current pathname identities remain exact bigints through the
 append boundary; rounded-equal replacements and persistent unknown Windows
 identities reject before chmod or writing bytes. With
 `rejectSymlinkParents: true`, it also rejects symlinked ancestor directories.
+Supported option values are captured once before filesystem work, so replacing
+the content, encoding, mode or cap cannot change an in-flight append. Byte-array
+contents remain caller-owned; leave them unchanged until the append completes.
 
 On POSIX, `O_NONBLOCK` prevents a no-reader FIFO substituted before open from
 stalling admission. A confirmed non-regular target is refused before chmod or