@openclaw/fs-safe 0.9.0 → 0.11.0

package/dist/windows-owner.js

@@ -23,65 +23,28 @@ function windowsOwnerQueryCommand(targetPath) {
         "$driveRoot=if($extendedDrive){$p.Substring(4,3)}else{$root}",
         "$namespacePath=$p.StartsWith('\\\\')",
         "$remote=($namespacePath -and -not $extendedDrive) -or ([IO.DriveInfo]::new($driveRoot).DriveType -eq [IO.DriveType]::Network)",
-        "$rules=$acl.GetAccessRules($true,$true,[System.Security.Principal.SecurityIdentifier])",
-        "$principalSids=@($rules|ForEach-Object {$identity=$_.IdentityReference;$sid=$identity.Value;@{name=$sid;sid=$sid};try{@{name=$identity.Translate([System.Security.Principal.NTAccount]).Value;sid=$sid}}catch{}})",
-        "@{ownerSid=$ownerSid;currentUserSid=$currentSid;principalSids=$principalSids;principalTranslationFailed=$false;remote=$remote}|ConvertTo-Json -Depth 4 -Compress",
+        // Emit only ASCII SID and numeric facts: console encodings can replace both
+        // Unicode pathnames and account names before JavaScript receives the bytes.
+        "$raw=[System.Security.AccessControl.RawSecurityDescriptor]::new($acl.GetSecurityDescriptorBinaryForm(),0)",
+        "$dacl=$raw.DiscretionaryAcl;$complete=$true",
+        "$aces=@(foreach($ace in $dacl){if($ace -isnot [System.Security.AccessControl.CommonAce] -or $ace.IsCallback -or [int]$ace.AceType -notin @(0,1)){$complete=$false;continue};@{sid=$ace.SecurityIdentifier.Value;mask=([long]$ace.AccessMask -band 4294967295);deny=([int]$ace.AceType -eq 1);inheritOnly=([int]$ace.AceFlags -band 8) -ne 0}})",
+        "@{ownerSid=$ownerSid;currentUserSid=$currentSid;daclPresent=($null -ne $dacl);aces=$aces;complete=$complete;remote=$remote}|ConvertTo-Json -Depth 4 -Compress",
     ].join(";");
 }
-function windowsPrincipalQueryCommand(principals) {
-    const encodedPrincipals = Buffer.from(JSON.stringify(principals), "utf8").toString("base64");
-    return [
-        "$ErrorActionPreference='Stop'",
-        `$names=[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodedPrincipals}'))|ConvertFrom-Json`,
-        "$rows=@($names|ForEach-Object {@{name=$_;sid=(New-Object System.Security.Principal.NTAccount($_)).Translate([System.Security.Principal.SecurityIdentifier]).Value}})",
-        "ConvertTo-Json -InputObject $rows -Compress",
-    ].join(";");
-}
-function parsePrincipalSidRows(value) {
-    const rows = Array.isArray(value) ? value : value ? [value] : [];
-    const result = {};
-    for (const row of rows) {
-        if (!row || typeof row !== "object") {
-            continue;
-        }
-        const name = "name" in row && typeof row.name === "string" ? row.name.trim() : "";
-        const sid = "sid" in row && typeof row.sid === "string" ? normalizeSid(row.sid) : "";
-        if (name && SID_RE.test(sid)) {
-            result[name.toLowerCase()] = sid;
-        }
-    }
-    return result;
-}
-export async function resolveWindowsPrincipalSids(params) {
-    const principals = [...new Set(params.principals.map((value) => value.trim()).filter(Boolean))];
-    const known = Object.fromEntries(Object.entries(params.known ?? {}).map(([name, sid]) => [name.toLowerCase(), normalizeSid(sid)]));
-    const unresolved = principals.filter((principal) => !known[principal.toLowerCase()]);
-    if (unresolved.length === 0) {
-        return known;
+function parseWindowsAclFacts(parsed) {
+    if (parsed.complete !== true || typeof parsed.daclPresent !== "boolean" || !Array.isArray(parsed.aces)) {
+        return { aclError: "Windows ACL query returned incomplete descriptor data" };
     }
-    const command = resolveWindowsSystemCommand(String.raw `WindowsPowerShell\v1.0\powershell.exe`, params.env);
-    const { stdout } = await params.exec(command, [
-        "-NoLogo",
-        "-NoProfile",
-        "-NonInteractive",
-        "-EncodedCommand",
-        encodePowerShellCommand(windowsPrincipalQueryCommand(unresolved)),
-    ]);
-    const resolved = { ...known, ...parsePrincipalSidRows(JSON.parse(stdout.trim())) };
-    if (principals.some((principal) => !resolved[principal.toLowerCase()])) {
-        throw new Error("Windows ACL principal translation returned incomplete SID data");
-    }
-    return resolved;
-}
-export async function resolveWindowsCurrentUserSid(params) {
-    try {
-        const { stdout, stderr } = await params.exec(resolveWindowsSystemCommand("whoami.exe", params.env), ["/user", "/fo", "csv", "/nh"]);
-        const match = `${stdout}\n${stderr}`.match(/\*?S-\d+-\d+(?:-\d+)+/i);
-        return match ? normalizeSid(match[0]) : null;
-    }
-    catch {
-        return null;
+    const aces = [];
+    for (const row of parsed.aces) {
+        if (!row || typeof row !== "object" || typeof row.sid !== "string" || !SID_RE.test(row.sid) ||
+            typeof row.mask !== "number" || !Number.isInteger(row.mask) || row.mask < 0 || row.mask > 0xffff_ffff ||
+            typeof row.deny !== "boolean" || typeof row.inheritOnly !== "boolean") {
+            return { aclError: "Windows ACL query returned invalid access-rule data" };
+        }
+        aces.push({ sid: normalizeSid(row.sid), mask: row.mask, deny: row.deny, inheritOnly: row.inheritOnly });
     }
+    return { daclPresent: parsed.daclPresent, aces };
 }
 export async function inspectWindowsOwner(params) {
     let command = "";
@@ -96,7 +59,11 @@ export async function inspectWindowsOwner(params) {
             "-EncodedCommand",
             encodePowerShellCommand(windowsOwnerQueryCommand(params.targetPath)),
         ]);
-        const parsed = JSON.parse(stdout.trim());
+        const value = JSON.parse(stdout.trim());
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            return { error: "Windows owner query returned invalid SID data" };
+        }
+        const parsed = value;
         const ownerSid = typeof parsed.ownerSid === "string" && SID_RE.test(parsed.ownerSid)
             ? normalizeSid(parsed.ownerSid)
             : undefined;
@@ -110,8 +77,7 @@ export async function inspectWindowsOwner(params) {
         return {
             sid: ownerSid,
             currentUserSid,
-            principalSids: parsePrincipalSidRows(parsed.principalSids),
-            principalTranslationFailed: parsed.principalTranslationFailed === true,
+            ...parseWindowsAclFacts(parsed),
             remote,
             trusted: !remote && (ownerSid === currentUserSid || TRUSTED_OWNER_SIDS.has(ownerSid)),
         };

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

@@ -0,0 +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

@@ -0,0 +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,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

@@ -0,0 +1,26 @@
+import fs from "node:fs";
+import { FsSafeError } from "./errors.js";
+const WRITE_CHUNK_BYTES = 512 * 1024;
+export async function writeAllToFile(target, data, options = {}) {
+    const buffer = typeof data === "string" ? Buffer.from(data, options.encoding ?? "utf8") : data;
+    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, position, (error, bytesWritten) => {
+                    if (error)
+                        reject(error);
+                    else
+                        resolve(bytesWritten);
+                });
+            })
+            : (await target.write(buffer, offset, length, position)).bytesWritten;
+        if (written <= 0) {
+            throw new FsSafeError("helper-failed", "file write made no progress");
+        }
+        offset += written;
+    }
+}

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 }`.
@@ -65,9 +66,13 @@ Operational filesystem failures such as permissions or I/O errors are rethrown.
 | Export | Page | Notes |
 |---|---|---|
 | `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. |
-| `openRootFile`, `openRootFileSync`, `canUseRootFileOpen`, `matchRootFileOpenFailure`, related types | – | Low-level root-bounded open; rejects every symlink component by default, with `rejectSymlinks: false` for explicit in-root following. |
+| `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. |
@@ -79,6 +84,19 @@ receipts remain numeric. Custom `ioFs` adapters must honor `{ bigint: true }` fo
 Windows identities receive one re-inspection without reopening, then fail
 validation if still unknown.
 
+The explicit `symlinks` policy takes precedence over the existing `rejectSymlinks`
+boolean. Without `symlinks`, `rejectSymlinks: false` retains its existing behavior
+of following contained links, and omission still rejects all symlink components.
+
+The bounded descriptor helpers cap their initial speculative allocation at
+16 MiB plus the overflow-probe byte, even when a file reports a much larger
+size. Regular files up to that size can return from one read without copying
+chunks; larger files and short reads continue incrementally under the same
+byte limit. Continuation buffers grow only after filling with actual bytes,
+up to the byte budget plus its probe; file-size hints cannot force that growth.
+Unknown-size inputs start with at most 64 KiB. This avoids per-chunk copies and
+a final concatenation when a file exceeds the initial allocation.
+
 The bounded descriptor helpers start at the descriptor's current offset and
 leave ownership with the caller. They are intended for the second half of a
 safe read: first open and validate the path using the boundary appropriate to
@@ -117,7 +135,7 @@ component is followed by another segment, both helpers throw
 |---|---|---|
 | `safeDirName`, `safePathSegmentHashed`, `resolveSafeInstallDir`, `assertCanonicalPathWithinBase` | [install-path.md](install-path.md) | Build install-target directories from caller-supplied identifiers. |
 | `sanitizeUntrustedFileName` | [filename.md](filename.md) | Coerce an untrusted string into a safe filename. |
-| `resolveHomeRelativePath` | – | Expand `~`-prefixed paths. |
+| `resolveHomeRelativePath` | – | Expand a leading `~` before resolving `.` and `..`; tildes inside relative paths stay literal. |
 
 ### Temp targets and sibling-temp writes
 
@@ -139,7 +157,7 @@ component is followed by another segment, both helpers throw
 | Export | Page | Notes |
 |---|---|---|
 | `createAsyncLock` | – | In-process async lock (separate from cross-process file locks). |
-| `withTimeout` | [timing.md](timing.md) | Wrap a promise with a timeout that raises `FsSafeError("timeout")`. |
+| `withTimeout` | [timing.md](timing.md) | Wrap a promise with a timeout that raises `Error` by default, or an error supplied by `createError`. |
 | `movePathToTrash`, `MovePathToTrashOptions` | – | Best-effort move to the platform trash. |
 
 ## Stability
@@ -149,5 +167,5 @@ Items in this surface can change shape between minor versions if a higher-level
 ## Related pages
 
 - [Root API](root.md) — built on top of these helpers.
-- [Errors](errors.md) — every helper here surfaces failures as `FsSafeError`.
+- [Errors](errors.md) — shared filesystem error codes; generic timing helpers retain their documented error types.
 - [Security model](security-model.md) — what the underlying boundary checks promise.

package/docs/archive.md

@@ -126,6 +126,12 @@ untrusted authority rejects explicitly instead of silently accepting a wrong
 mode. Other unsupported search-only routes also fail closed. Windows retains
 its existing bounded lack of POSIX mode enforcement.
 
+Extraction and TAR inspection first copy the admitted source into a private
+staging file. This copy reuses at most 512 KiB of scratch space, reduced for
+small inputs and capped by the archive byte limit plus one overflow-probe byte.
+Each read stays within the remaining budget plus that probe; deadline checks
+surround reads, and short writes finish before the buffer is reused.
+
 Native extraction is deliberately split into two phases. Rust first reports an
 entry manifest without creating paths. TypeScript validates paths, applies
 `stripComponents`, filters, limits, and mode policy, then passes an explicit
@@ -133,7 +139,7 @@ accepted-entry plan back to Rust. Rust owns raw-stream admission, decompression,
 and fd-relative `mkdirBeneath`/exclusive-open writes. This keeps filter policy identical
 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 separator and dot-component equivalence is allowed only after validation. Ordinary legacy filename decoding remains backend-selected.
+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 separator and dot-component equivalence is allowed only after validation. 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.
 
 `stripComponents` removes leading nonempty, non-`.` path components after
 normalizing separators. For example, `./pkg/hello.txt` with
@@ -222,14 +228,23 @@ record and are then cleared; local PAX on unsupported types and GNU sparse
 
 If `kind` is omitted, the helper calls `resolveArchiveKind(archivePath)` and throws if the extension is not recognized. Pass `kind` explicitly when the archive name doesn't carry the type (e.g. content-addressed names). Archive inputs must remain regular files from preview through descriptor admission; POSIX opens are no-follow and nonblocking, so a FIFO swap cannot stall before deadline checks resume. A positive finite `timeoutMs` is a wall-clock budget; zero, negative, `NaN`, and infinity disable the deadline. Non-mutating work rejects promptly when the budget expires. If a live destination mutation is already in flight, rejection waits only for that mutation and any rollback to finish; no later destination mutation can begin.
 
+Extraction captures the destination's lossless filesystem identity before any
+entry filter runs and retains that capability through final publication. If a
+filter or concurrent actor renames or replaces the destination, extraction
+rejects with `destination-symlink-traversal` before publishing into the
+replacement. This check uses bigint device and inode identities so large native
+identifiers cannot compare equal after JavaScript number rounding.
+
 The destination merge is nontransactional: each file is published atomically,
 but completed files and directories can remain when a later copy, post-copy
 check, mode application, or deadline fails. This also applies to
-`mergeExtractedTreeIntoDestination()`. Guarded `Root.copyIn()` owns cleanup for
-its operation; the archive merge does not unlink the current destination name
-on error because it has no publication receipt proving ownership. A failure
-before publication preserves a pre-existing file, and rejection does not grant
-authority to delete a substituted file or alias. Failed extraction does not
+`mergeExtractedTreeIntoDestination()`. Guarded `Root.copyIn()` owns unpublished
+stage cleanup and preserves completed publications. The archive merge never
+acquires rollback authority over the current destination name. Replacing a
+source path after publication rejects the merge with `path-mismatch` while
+preserving the admitted bytes already published, or any later destination edit.
+A failure before publication preserves a pre-existing file, and rejection does
+not grant authority to delete a substituted file or alias. Failed extraction does not
 restore overwritten contents. Active destination mutations and their guarded
 cleanup still finish before rejection; no later destination mutation begins.
 New directories whose finalization was never reached can retain their
@@ -352,7 +367,9 @@ bypass validation. Decompression remains streaming; no complete decoded archive
 is retained in memory or written to a decoded spool.
 
 The WASM transport has a fixed 64 KiB input buffer, one pending member event,
-and a 256 MiB maximum linear memory per isolated parser instance. Metadata is
+and a 256 MiB maximum linear memory per isolated parser instance. JavaScript
+gzip decoding emits chunks of at most 64 KiB for both staged files and buffered
+inputs, matching that input window. Metadata is
 bounded before allocation; allocation failure rejects. Stream backpressure
 bounds queued chunks, and completion/error destroys the instance's parser
 state. The manifest retains the existing charged budget below; linear memory
@@ -555,8 +572,8 @@ await extractArchive({
 ## `readArchiveEntry`
 
 `readArchiveEntry(archivePath, entryPath, { maxBytes, kind? })` reads one
-regular-file entry into a bounded `Buffer` without extracting a tree. It pins
-and privately stages the archive input, rejects link, directory, and duplicate
+regular-file entry into a bounded `Buffer` without extracting a tree. It reads
+the input through an identity-checked descriptor, rejects link, directory, and duplicate
 entries, verifies ZIP CRC and declared size,
 and throws `ArchiveLimitError` if the requested entry's output exceeds
 `maxBytes`. ZIP output within that cap must match the declared uncompressed
@@ -571,6 +588,24 @@ limits. It does not apply payload budgets to unrequested members. ZIP
 inputs retain the archive subpath's 256 MiB compressed-input ceiling.
 With a native binding it uses the same Rust decoders as extraction, including
 zstd and bzip2 TAR. Without native it retains the JS ZIP/TAR/gzip implementation.
+Archive member reads retain their private in-memory input without a disk
+snapshot. JavaScript ZIP member reads reuse their completed physical admission
+when loading the decoder, which still checks its decoded names and entry count.
+The native ZIP reader retains the private allocation and parsed directory across worker-thread
+inspection and reading without an extra archive-byte copy.
+Decompression still allocates its bounded output; Node receives that native
+allocation without another copy where external buffers are supported.
+Native TAR retains the fully admitted member offsets alongside the same input
+allocation. Plain TAR copies only the selected payload range after full archive
+validation. Gzip, zstd, and bzip2 replay bounded decompression and still validate
+all framing, trailers, and physical padding before returning. The JavaScript
+TAR/gzip fallback copies each input window into WASM once, consuming member
+events at offsets within that window. After full admission, plain TAR copies the
+selected range directly from its private snapshot; gzip still replays bounded
+decompression through the parser. WASM transport and selected output still
+require copies.
+Returned buffers own their bytes, so changing a result cannot modify an archive
+reader or retain an unrelated part of the input through its backing ArrayBuffer.
 
 Requested paths and effective member names use extraction's canonical pre-strip
 identity: backslashes become `/`, and repeated separators and `.` components

package/docs/atomic.md

@@ -40,7 +40,7 @@ type ReplaceFileAtomicOptions = {
   content: string | Uint8Array;
   dirMode?: number;                 // parent-directory mode (POSIX; default 0o700)
   mode?: number;                    // new-file mode (default 0o600)
-  preserveExistingMode?: boolean;   // copy existing mode; default false
+  preserveExistingMode?: boolean;   // inherit existing regular-file rwx bits; default false
   tempPrefix?: string;              // default ".fs-safe-replace"
   renameMaxRetries?: number;        // EBUSY retries; default 0
   renameRetryBaseDelayMs?: number;  // exponential base; default 50
@@ -57,6 +57,17 @@ type ReplaceFileAtomicOptions = {
 };
 ```
 
+`preserveExistingMode` snapshots only the ordinary rwx bits (`0o777`) from an
+existing non-symlink regular destination. A final symlink fails with
+`FsSafeError("symlink")`; a directory or other non-regular destination fails
+with `FsSafeError("not-file")`. Set-user-ID, set-group-ID, and sticky bits are
+never inherited. Mode inheritance does not copy ownership, ACLs, extended
+attributes, or exact destination identity. Rename publication creates a new
+inode; an in-place copy fallback can retain metadata already attached to its
+pinned destination. The snapshot does not make replacement a compare-and-swap
+operation, so the destination parent must still be protected from untrusted
+concurrent namespace mutation.
+
 ### `beforeRename`
 
 Runs after the temp file is fully written and before the rename. Use it to take a backup snapshot, capture the about-to-be-replaced contents, or notify an observer. The helper retains the staged descriptor and exact bigint identity across the hook; replacing, deleting, hardlinking, or changing the temp entry to a non-regular file is rejected before publication:
@@ -135,6 +146,11 @@ than `maxRestoreBytes` fails with `too-large` before mutation. A missing
 destination has no original to restore and follows the exclusive-create copy
 fallback.
 
+Restore snapshots use the pinned file's size as an allocation hint, with an
+initial allocation capped at 16 MiB plus the overflow byte. Reads continue
+through short reads and EOF, grow only as data arrives, and enforce the same
+`maxRestoreBytes` budget even if the destination grows after its size was read.
+
 ### Sync variant
 
 `replaceFileAtomicSync` accepts the same base options, a synchronous
@@ -207,6 +223,13 @@ directory mode. Staged file modes are applied through their still-open handles.
 If descriptor-bound mode application fails, the staged path is removed and the
 move fails before publication. A transient staged-path cleanup failure retains
 an identity-bound process-exit cleanup retry.
+The staging entry's initially admitted identity is checked before publication
+and cleanup; a later substituted entry is preserved. Regular files are admitted
+through their new descriptor. Node provides no creation descriptor for directories
+or symlinks, so their first identity comes from an immediate pathname observation.
+Replacement before that observation remains a best-effort detection gap: use a
+parent protected from concurrent untrusted mutation or OS isolation. A copy write
+that makes no progress rejects instead of looping indefinitely.
 On POSIX, staged directory modes are applied through no-follow directory
 descriptors; on Windows, Node cannot portably open those descriptors and no
 pathname `chmod` fallback is attempted, so directory modes remain subject to

package/docs/config.md

@@ -65,6 +65,7 @@ type FsSafeLockConfig = {
 Set process-wide defaults for sidecar lock options. This does **not** turn locking on globally; callers still need to pass `lock: true` or a lock options object for the specific JSON store/resource that needs cross-process coordination.
 
 `staleRecovery` defaults to `"fail-closed"`. The opt-in `"remove-if-unchanged"` mode requires caller approval and serializes the final snapshot check and unlink with an exclusive `.reclaim` guard. A reclaim guard left by a killed reclaimer fails closed and requires externally coordinated cleanup.
+`staleMs` must be non-negative and not `NaN`; `Infinity` disables age-based staleness.
 
 For a daemon that should wait briefly for normal contention but never delete a
 stale owner without per-lock approval:

package/docs/contributing.md

@@ -42,6 +42,32 @@ Vitest. Tests live in `test/` and follow `*.test.ts`. Run a single file with:
 pnpm test test/archive.test.ts
 ```
 
+Guest filesystem tests and package smoke also need `python3` on Linux and
+macOS. They execute the exported source on synthetic files; Windows checks
+the import surface and leaves POSIX execution to the Linux/macOS lanes.
+After building on Linux, `node scripts/check-pack.mjs --guest-cross-device`
+also proves an installed-package directory move from temporary storage to
+`/dev/shm`; the command requires those locations to be different filesystems.
+
+With Bun 1.4.2 installed, build the host addon and run the native compatibility
+lane in real Bun workers, then exercise the built package with JIT disabled:
+
+```bash
+pnpm native:build
+pnpm test:bun:native
+bun --jitless scripts/bun-native-proof.mjs
+```
+
+Keep the Node/pnpm build toolchain above. CI runs the native compatibility lane
+on Linux, macOS, and Windows. The built-package proof checks `auto`/`require`,
+native-off loading policy, and a separate installation without the addon.
+
+`pnpm test:bun` runs the entire Node-oriented suite as a diagnostic. On released
+Bun, its explicit native-off and missing-helper cases include unsupported
+permission/path behavior described in [install](install.md#bun-runtime); this
+command is not a passing compatibility gate. Node CI retains every fallback
+assertion. Neither lane rewrites `off` to `auto` or marks defects as expected passes.
+
 Use `vi.mock` sparingly. Most tests should drive real disk operations in a `mkdtemp`-created scratch directory, asserting on observable behavior. The library has [test hooks](testing.md) for the rare cases where you need to inject a TOCTOU race deterministically.
 
 Vitest timeouts do not cancel filesystem promises. Shared fixtures with expensive
@@ -68,6 +94,13 @@ pnpm check
 This runs the filesystem boundary checks, build, tests, and package
 tarball/import validation.
 
+### Method benchmarks
+
+`pnpm benchmark:methods` measures the callable library surface against synthetic
+fixtures and fails on uncovered exports or returned methods. See the
+[benchmark guide](https://github.com/openclaw/fs-safe/tree/main/benchmarks) for native/fallback runs, per-call
+timings, exclusions, and comparison methodology. Run `pnpm build` first.
+
 ### Real TAR producers
 
 After installing the freshly packed root (and optionally its freshly built host
@@ -116,7 +149,9 @@ collection uses the actual seven collected native tarballs instead. Run it with
 `pnpm package:collect` after assembling all seven real bindings; missing targets
 fail collection. `pnpm package:collect --allow-host-only` exercises the same
 lifecycle boundary locally but proves only the host. Both collection commands
-require the pnpm lifecycle CLI path; direct `node` invocation is unsupported. Archive
+require the pnpm lifecycle CLI path; JavaScript CLIs run through Node and standalone
+`@pnpm/exe` binaries run directly. Shell/cmd shims and PATH fallback are not used;
+direct `node` invocation without lifecycle metadata is unsupported. Archive
 codecs and their dependencies are packed from the installed dependency graph.
 
 PR CI builds and executes four host targets: Linux x64 glibc, Linux x64 musl

package/docs/copy.md

@@ -0,0 +1,155 @@
+# Directory copying and cloning
+
+`@openclaw/fs-safe/copy` materializes independent, caller-owned directory trees. `copyTree` prefers native copy-on-write operations by default, can require cloning, or can copy regular file bytes without cloning or copy offload.
+
+```ts
+import { copyTree, createCloneSource, probeTreeClone } from "@openclaw/fs-safe/copy";
+
+const parent = "/srv/worktrees";
+const backend = probeTreeClone(parent);
+if (backend) {
+  const template = `${parent}/template`;
+  await createCloneSource(template);
+  // Populate this caller-owned template, then keep its contents unchanged.
+  await copyTree(template, `${parent}/checkout`, {
+    clone: "always",
+    signal: AbortSignal.timeout(60_000),
+  });
+}
+```
+
+## Filesystems
+
+| Backend | Operation                                                  | Source preparation                                                                                                          |
+| ------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `apfs`  | Native bulk clone, then directory timestamp repair         | `createCloneSource` creates an empty directory.                                                                             |
+| `btrfs` | One native writable subvolume snapshot                     | `createCloneSource` creates a subvolume; an ordinary directory is not a snapshot source. No `btrfs` executable is required. |
+| `refs`  | Native directory traversal with parallel file block clones | `createCloneSource` creates an empty directory on ReFS, including Dev Drive volumes.                                        |
+| `xfs`   | Native directory traversal with parallel file reflinks     | `createCloneSource` creates an empty directory. The XFS volume must support reflinks.                                       |
+| `zfs`   | Native directory traversal with parallel file reflinks     | `createCloneSource` creates an empty directory. Requires Linux OpenZFS file reflinks and the pool block-cloning feature. |
+
+Native cloning requires source and destination filesystems that support cloning between them. Automatic and ordinary copying can cross filesystems. The source repository used to populate a template can live elsewhere. ReFS, XFS, and ZFS share file data rather than the whole directory metadata tree, so creating many small files still has a cost.
+
+ZFS uses strict file reflinks within one dataset, not dataset snapshots. The installed Linux OpenZFS version must implement `FICLONE`, and the pool must enable `feature@block_cloning`. The probe identifies ZFS even when that feature is unavailable; `clone: "always"` then fails and `"auto"` can copy bytes. Native cloning was verified on OpenZFS 2.4.1 with POSIX ACLs. See the [OpenZFS block-cloning contract](https://openzfs.github.io/openzfs-docs/Basic%20Concepts/Data%20Storage/Block%20Cloning.html) for filesystem limits and pool sharing counters.
+
+Btrfs preserves native subvolume snapshot semantics: nested subvolume contents are not included. Prepare source-only templates without nested subvolumes. This API does not recursively snapshot a hierarchy of subvolumes.
+
+### APFS permissions
+
+APFS directory cloning does not guarantee descendant ACL preservation. With the `CLONE_ACL` flag used here, live macOS testing preserved the source root's ACL but dropped an explicit ACL on a source descendant. Destination ACL inheritance was also omitted below the cloned root. `probeTreeClone` checks filesystem support only; neither it nor `copyTree` checks whether these ACL semantics meet the caller's permission policy. A successful clone is not proof of source ACL preservation or normal file-creation inheritance throughout the tree.
+
+Callers that require source ACL preservation or destination ACL inheritance must use a creation path that preserves their permission policy. For example, a private Git template cache can prohibit custom descendant ACLs and decline cloning when the destination parent has inheritable ACL entries, the template root carries ACLs, or ACL inspection fails; it must also account for policy changes during cloning. Checking only the source root cannot establish that an arbitrary tree has no descendant ACLs. This library does not inspect or repair ACLs after a clone.
+
+Apple [strongly discourages general directory cloning](https://github.com/apple-oss-distributions/xnu/blob/f6217f891ac0bb64f3d375211650a4c1ff8ca1ea/bsd/man/man2/clonefile.2). The [XNU directory-clone authorizer notes unfinished descendant ACL inheritance](https://github.com/apple-oss-distributions/xnu/blob/f6217f891ac0bb64f3d375211650a4c1ff8ca1ea/bsd/vfs/vfs_subr.c#L8879); this is one verified limitation, not Apple's stated complete rationale. The bulk operation remains useful for controlled, immutable templates whose callers accept its metadata semantics.
+
+## API
+
+`TreeCloneBackend` is the `"apfs" | "btrfs" | "refs" | "xfs" | "zfs"` union returned by the probe. `CopyTreeOptions` contains the optional `clone`, `signal`, and `concurrency` arguments. `CopyCloneMode` is the `"auto" | "always" | "never"` strategy shared with [`Root.copyIn`](root.md#writes); tree copies default to `"auto"`, while guarded file copies default to `"never"`.
+
+`probeTreeClone(parentPath)` synchronously inspects an existing directory and returns its supported backend name or `undefined`. It creates no probe artifacts. A filesystem name identifies a candidate backend; for example, an older XFS volume may have reflinks disabled. The actual operation determines availability. An unavailable native binding produces `undefined` in automatic mode; the package's explicit native `require` mode still reports a missing binding as an error.
+
+`createCloneSource(destination, { signal? })` creates an empty cloneable source. Its parent must already exist and the destination must be absent.
+
+`copyTree(source, destination, { clone?, signal?, concurrency? })` copies a directory into an absent destination. Existing destinations are never merged or overwritten. The destination must be outside the source tree.
+
+| `clone` policy     | Behavior                                                                                                                                     |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"auto"` (default) | Prefer native cloning; copy bytes when the binding or filesystem capability is unavailable, or cloning cannot cross the filesystem boundary. |
+| `"always"`         | Require native cloning. Unsupported operations fail without a byte-copy fallback.                                                            |
+| `"never"`          | Copy regular file bytes using reads and writes. No native cloning or copy-offload calls. Works without a native binding.                     |
+
+Automatic copying does not recover from permission errors, I/O errors, cancellation, or rejected source contents such as ReFS named streams. A failed clone must leave the destination absent before fallback can create it; otherwise copying fails rather than merging into a partial tree.
+
+`concurrency` accepts integers from 1 through 32 and bounds active file copies. ReFS, XFS, and ZFS cloning default to 16 workers. Byte copying defaults to four concurrent files on Windows and one elsewhere. Btrfs uses its bulk operation. APFS uses a bulk clone followed by native directory-entry enumeration to restore directory timestamps; known regular files and symbolic links need no additional stat or open.
+
+On Windows, automatic byte copying uses the native binding when available to transfer data between the already-checked file handles in chunks of at most 1 MiB, with smaller buffers for small files. This accelerates NTFS and cross-volume copies without reopening source or destination pathnames. The native worker finishes before its descriptors are closed or cancellation is reported. `clone: "never"` and native-disabled copies use JavaScript read/write loops with reusable buffers: at most 1 MiB per active file on Windows, or 128 KiB elsewhere. Both paths share the file-worker budget across sibling directories, wait for all admitted writes after cancellation or failure, and restore directory timestamps after their descendants finish. Completed directory traversals awaiting writes or metadata are bounded by concurrency; ancestors remain pinned while traversing their children.
+
+On Linux, automatic byte copying also uses the native binding when available. It reads in 1 MiB chunks and leaves leading and trailing zero-filled portions of each chunk unwritten in the new file, avoiding their allocation on filesystems that support sparse files. A final size update preserves trailing holes and all-zero files. This path uses reads and writes, without cloning or copy offload; it still reads the full logical contents and does not promise identical sparse extent layout. `clone: "never"` retains the JavaScript byte-copy path.
+
+Clones preserve file contents, empty directories, timestamps, executable modes where supported, and literal symbolic links. Editing a clone does not modify its source. Unsupported filesystem operations fail; callers may choose their own copy or checkout fallback after the failed operation has settled.
+
+Native Windows byte copies can store large zero-filled chunks as sparse ranges when the destination is initially empty and its filesystem supports sparse files. This still reads every source byte and creates an independent copy.
+
+The ReFS backend rejects files with alternate data streams and unsupported reparse-point types instead of silently losing their contents. Symbolic links and junctions are preserved.
+
+XFS and ZFS preserve regular-file and directory modes, timestamps, extended attributes, and ACLs. They reject special files, symlink extended attributes, non-UTF-8 names, and directory nesting deeper than 128 levels. Hardlinked source files become independent reflinked files. Portable byte copying preserves file contents, empty directories, modes where supported, file and directory timestamps, and literal symbolic links; it does not promise ownership, ACL, extended-attribute, alternate-stream, or sparse-layout preservation. On Windows, byte copying rejects unresolved symbolic links because Node does not expose their file/directory link type; resolved links keep their literal target and source type. POSIX dangling links are preserved. Choose a copying policy that meets the caller's metadata requirements; automatic copying can select either path.
+
+`readCloneFileMetadata(files)` asynchronously reads APFS data-stream identities and file metadata in one native batch. Results correspond to input order; missing or unsupported entries return `undefined`. The returned `CloneFileMetadata` includes clone ID, device/inode, size, mode, ownership, and timestamps. These are point-in-time observations, not authorization or proof that later reads remain unchanged. Consumers such as Git index adapters must validate their own content and timestamp invariants. The reader does not follow leaf symbolic links.
+
+## Borrowed FileHandle transfers
+
+`copyFileHandle` from `@openclaw/fs-safe/advanced` copies bytes between two
+already-open regular files. Use it when a snapshot or materialization owner
+has admitted the source and opened its own destination:
+
+```ts
+import { createHash } from "node:crypto";
+import { copyFileHandle } from "@openclaw/fs-safe/advanced";
+
+const digest = createHash("sha256");
+const bytes = await copyFileHandle(sourceHandle, targetHandle, {
+  maxBytes: expectedSize,
+  signal: AbortSignal.timeout(30_000),
+  onChunk: (chunk) => { digest.update(chunk); },
+  assertBeforeMutation: assertSnapshotOwnerCurrent,
+});
+```
+
+`CopyFileHandleOptions` contains optional `maxBytes`, `signal`, `onChunk`, and
+`assertBeforeMutation`. The result is the actual byte count copied through EOF.
+The byte limit is not a prefix length: excess data rejects with `too-large`,
+including data added after admission. Omitted limits are unlimited; Root's
+default read cap does not apply. Zero accepts only an empty source. Invalid
+limits reject before descriptor inspection.
+
+The source and target must be distinct regular files; exact device/inode
+aliases, including two handles to hardlinked names, reject before writing.
+Both reads and writes start at position zero and preserve the handles' current
+cursors. Existing destination bytes beyond the copied prefix remain intact.
+The target must have been opened **without append mode**: some platforms ignore
+positional writes on append handles, and Node exposes no portable open-flags
+query. Keep both handles open and free of concurrent I/O through settlement.
+
+The synchronous `onChunk` observer sees each source chunk before any target
+write for that chunk. It receives a borrowed view reused by later reads; consume
+it immediately without retaining or mutating it. This supports source hashing;
+it does not verify bytes persisted by the destination. Callers that require a
+destination digest must still hash the destination handle afterward. Observer
+and authority callbacks may throw; thenable returns reject with `TypeError`
+before the affected write. `assertBeforeMutation` runs immediately before every
+partial-write submission and must inspect current authority each time.
+
+The helper reuses Root copying's bounded read buffer and completes positive
+short reads and writes. JavaScript file transfers use at most 512 KiB of scratch
+space, reduced for smaller source-size hints and capped by a finite byte budget
+plus its one-byte overflow probe. A zero-progress write rejects with `helper-failed`.
+Cancellation is checked before I/O, after source reads, and before each write;
+admitted reads and writes settle before rejection. A rejected operation can
+leave a copied prefix. There is no rollback or pathname cleanup.
+
+This helper never opens or closes a file, truncates, chmods, syncs, renames, or
+publishes it. Source admission, immutability checks, destination preparation,
+durability, publication, and failure recovery stay with the caller. Initial
+descriptor inspection does not prove that the source remained unchanged while
+copying. Keep existing source-fingerprint and publication checks around the
+transfer when building snapshot operations.
+
+## Ownership and cancellation
+
+These are low-level operations on caller-owned absolute paths, not Root-relative methods. The source and destination parent must be real directories. The library pins their descriptors and verifies their identities; it does not establish the caller's authorization to use them. Keep the source immutable for the operation, including writes through other aliases, and keep the destination namespace under the caller's control. Literal symlinks in the cloned contents are preserved rather than followed or sanitized.
+
+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.
+
+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.
+
+Byte copying retains fractional file and directory access/modification timestamps to the precision supported by Node's timestamp APIs and the destination filesystem. This includes dates before 1970 on Unix. On Windows, [Node's unsigned stat seconds](https://github.com/nodejs/node/blob/v26.8.2/src/node_file-inl.h#L93-L104) can report pre-1970 timestamps as dates about 136 years later; byte copying inherits that upstream limitation.
+
+## Platform tests and benchmarks
+
+After building the host native binding, run `pnpm test test/clone.test.ts test/copy-tree.test.ts`. APFS tests can use the normal macOS temporary directory. For Btrfs, ReFS, XFS, or ZFS, set `FS_SAFE_CLONE_TEST_ROOT` to an existing writable directory on that filesystem. The test creates and cleans only its own temporary children. An explicitly configured unsupported directory fails the test rather than silently skipping platform proof. XFS and ZFS metadata tests require the `attr` and `acl` utilities.
+
+Run `node scripts/clone-xfs-proof.mjs MOUNT` on a real XFS volume to verify the public API, hashes, independent writes, and shared physical extents. It requires `filefrag` from `e2fsprogs`. Add `no-reflink` for an XFS fixture formatted with reflinks disabled; strict copying must fail and automatic copying must succeed through byte copying.
+
+Run `node scripts/clone-zfs-proof.mjs MOUNT POOL` on a dedicated, otherwise idle Linux ZFS pool with compression and deduplication disabled. It verifies both `copyTree` and `Root.copyIn` through hashes and changes in the documented `bclonesaved` pool counter. It requires `zfs`, `zpool`, and `findmnt`, including permission to run `zpool sync`. Add `no-reflink` for a pool without block cloning to verify strict refusal and automatic byte fallback. The script creates and removes only its temporary directory; it does not create pools or change their properties.
+
+Run `node benchmarks/clone.mjs SOURCE DESTINATION_PARENT` after `pnpm build` to compare one, four, and 16 workers on the same immutable source. Add `3 auto` or `3 never` to measure three samples of ordinary copying, including NTFS destinations. It records copying time separately from fixture preparation and full file-hash verification, and retains its uniquely named output directory for inspection. Prepare Btrfs sources with `createCloneSource` first.