@openclaw/fs-safe 0.8.6 → 0.10.0

package/docs/archive.md

@@ -43,6 +43,7 @@ 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
+  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
   tarGzip?: boolean;            // when archive is .tar.gz/.tgz
@@ -55,6 +56,36 @@ type ExtractArchiveOptions = {
 };
 ```
 
+`durable` defaults to `false`. Private staging never fsyncs, and publication copies
+defer opted-in durability until the complete merge succeeds. With `durable: true`, the final pass syncs each
+published file once (at most eight concurrently), then each published directory
+once, deepest first, and finally the destination directory. All work stays inside
+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.
+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
+pass, with a descriptor pinned before chmod for syncing restrictive directories.
+Existing inaccessible directories are never widened; an existing search-only
+directory must become readable in its final mode if no readable sync descriptor
+can be acquired before chmod.
+
+The default suits extractions into temporary or reconstructible locations.
+It skips all file and directory syncs while preserving atomic file publication,
+mode enforcement, identity checks, and containment checks. Successful `durable: true`
+extraction syncs file contents and directory entries before returning; failures
+can leave a partially published tree as described below.
+
+For a crash-safe install workflow, extract with the default into a scratch
+directory, then apply the caller's durability policy: sync the staged files and
+directories before publishing with [`replaceDirectoryAtomic`](atomic.md#replacedirectoryatomic),
+and sync the affected parent directories afterward. The directory swap alone
+does not sync the staged tree. Alternatively, pass `durable: true` when extracted
+files must be on stable storage before the extraction call returns, subject to
+the platform's flushing guarantees. A plain fsync on macOS does not flush the
+drive cache.
+
 `entryModes` defaults to `"clamp"`: directories become `0o755`; files become
 `0o644`, or `0o755` when the archived owner-execute bit is set. `"preserve"`
 keeps archived read/write/execute bits. Both policies strip setuid, setgid, and
@@ -194,18 +225,22 @@ If `kind` is omitted, the helper calls `resolveArchiveKind(archivePath)` and thr
 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 postorder finalization was never reached can retain their
+New directories whose finalization was never reached can retain their
 private working mode after failure. Failure cleanup closes retained descriptors;
-it does not run a final chmod sweep or roll back the archive. The public merge
+it does not run a cleanup chmod sweep or roll back the archive. The public merge
 helper still derives modes from its external source tree and must be able to
 read that source; it never chmods an unreadable external source to admit it.
+That helper retains per-copy durability and immediate postorder directory-mode
+finalization; the deferred pass described above belongs to `extractArchive()`.
 
 ### Limits
 
@@ -522,8 +557,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
@@ -538,6 +573,19 @@ 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. 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 streams views of the private input into the shared WASM parser
+for admission and replay; 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

@@ -207,6 +207,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/contributing.md

@@ -68,6 +68,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

package/docs/copy.md

@@ -0,0 +1,86 @@
+# 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.                                       |
+
+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 and XFS share file data rather than the whole directory metadata tree, so creating many small files still has a cost.
+
+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"` 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 and XFS 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 1 MiB chunks. 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 wait for all admitted writes after cancellation or failure and restore directory timestamps only after their file copies finish.
+
+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.
+
+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 preserves regular-file and directory modes, timestamps, extended attributes, and ACLs. It rejects 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.
+
+## 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.
+
+## 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, or XFS, 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 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 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.

package/docs/durability.md

@@ -199,7 +199,7 @@ import { sha256File } from "@openclaw/fs-safe/durability";
 const snapshot = await open(stagedArchive, "r");
 try {
   const before = await snapshot.stat();
-  const hash = await sha256File(snapshot);
+  const hash = await sha256File(snapshot, { maxBytes: before.size });
   if (hash.bytes !== before.size || hash.digest !== manifest.sha256) {
     throw new Error("staged backup does not match its manifest");
   }
@@ -209,6 +209,21 @@ try {
 ```
 
 The result is `{ bytes, digest }`, where `digest` is lowercase hexadecimal.
+The optional `Sha256FileOptions` argument supports `maxBytes` and `signal`.
+`maxBytes` accepts a non-negative safe integer (including zero), or
+`Infinity` for no limit, which is also the default. Oversized files reject with
+`FsSafeError("too-large")`; reads stay bounded to at most `maxBytes + 1` bytes,
+even if the file grows after its initial size check. Hashing never silently
+truncates to the limit.
+
+Pass `signal` to cancel. A pre-aborted signal rejects before file I/O or native
+loading. In-flight cancellation is cooperative between reads and rejects with
+the signal's original reason only after the pending read or native task stops.
+Callers may close their handle after awaiting rejection; do not close it while
+the operation is pending. A signal can be shared by successive or concurrent
+hashes. Neither mode provides a snapshot of concurrently modified contents;
+callers requiring stable content must also fence identity and metadata.
+
 The handle overload never closes the caller's descriptor and uses positioned
 reads, so it does not alter the descriptor's current offset. The path overload
 rejects symbolic links and non-regular files, compares lossless bigint identities
@@ -226,7 +241,7 @@ descriptor inspection rather than waiting for a writer.
 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
-positioned reads in 64 KiB chunks but updates Node's `Hash` on the JavaScript
+positioned reads in chunks of up to 256 KiB but updates Node's `Hash` on the JavaScript
 thread. Both paths stream constant-size buffers rather than loading the file
 into memory. Native mode `require` keeps its usual fail-closed loader semantics.
 

package/docs/errors.md

@@ -132,7 +132,7 @@ type FsSafeErrorCode =
 | `symlink` | Path component is a symlink, policy is `reject`. | Caller followed a symlink they shouldn't have, or `symlinks: "reject"` is set. |
 | `timeout` | An operation with a wall-clock budget overran. | Secure file read or timed operation exceeded `timeoutMs`. |
 | `too-large` | A read or bounded walk exceeded its configured budget. | Caller gave a too-permissive file or traversal limit. |
-| `unsupported-platform` | Reserved compatibility code for a platform-specific operation. | No current public helper emits this `FsSafeError` code. Platform-specific APIs currently return a typed unsupported result or use `helper-unavailable`; keep the union member when exhaustively switching across supported package versions. |
+| `unsupported-platform` | The platform or filesystem cannot perform the requested operation. | `createCloneSource` and `copyTree({ clone: "always" })` require native cloning support. The default `copyTree({ clone: "auto" })` selects portable byte copying when cloning is unavailable; unsupported source contents or metadata still fail. See [directory copying](copy.md) for backend limits and fallback behavior. |
 
 Secret writes reject invalid `mode` / `dirMode` values with `invalid-path` before directory creation. Existing secret directories with a mode different from the requested `dirMode` report `insecure-permissions` without chmod; a created directory whose descriptor ownership no longer matches its initializing effective user reports `not-owned`.
 

package/docs/file-store.md

@@ -28,9 +28,18 @@ const cache = fileStore({
   dirMode: 0o700,     // mode for parent directories created on demand (default 0o700)
   maxBytes: 64 * 1024 * 1024, // optional: refuse writes/reads larger than this
   private: true,      // use secret-file atomic writes for private state
+  durable: true,      // sync file and parent directory (default true)
 });
 ```
 
+| `FileStoreOptions` option | Default | Purpose |
+|---|---|---|
+| `rootDir` | Required | Store directory. |
+| `private` | `false` | Use the secret-file atomic path. |
+| `mode` / `dirMode` | `0o600` / `0o700` | File and parent-directory modes. |
+| `maxBytes` | Unset | Store read/write byte limit. |
+| `durable` | `true` | Sync the written file and its parent directory; see method support below. |
+
 Store and per-call `maxBytes` values must be non-negative safe integers or positive `Infinity`. Zero is an active zero-byte cap; `Infinity` disables the cap. An omitted or explicitly `undefined` per-call value preserves the store-level limit. The same rule applies to buffer writes, streams, copies, async reads, and synchronous reads/writes.
 
 Use `private: true` for credentials, auth profiles, tokens, and other private
@@ -101,7 +110,22 @@ therefore does not imply that no filesystem access or serialization occurred.
 
 ## Writes
 
-Every write goes through `writeSiblingTempFile` — temp + rename, mode applied to file and parent dir, both `fsync`'d.
+Writes use guarded sibling-temp publication: apply file and directory modes,
+then rename into place. By default, the file and parent directory are synced
+where supported by the platform and writer.
+
+`durable: false` keeps the sibling-temp replace/rename behavior but skips the
+temp-file and parent-directory `fsync` calls. Use it only for reconstructible
+metadata where lower latency matters more than crash-durability. Per-call
+`durable` overrides the store option, which defaults to `true`; an omitted or
+`undefined` override preserves the store default. Modes, path confinement,
+and publication identity checks are unchanged.
+
+| Method | Durability support |
+|---|---|
+| `write`, `writeText`, `writeJson` (async and sync) | Per-call option overrides store default. |
+| `writeStream`, `copyIn` (either private mode) | Per-call option overrides store default. |
+| JSON `write`, `update`, `updateOr` | JSON handle option overrides file-store default. |
 
 ### `write(rel, data, options?)`
 
@@ -118,7 +142,7 @@ Convenience wrappers over `write`. `writeJson` pretty-prints with a trailing new
 ### `json<T>(rel, options?)`
 
 Returns a typed single-file JSON state helper for a file under this store. It
-inherits the store's root, mode, max-size, and private-write policy, then adds
+inherits the store's root, mode, max-size, durability, and private-write policy, then adds
 `readOr`, `readRequired`, `update`, `updateOr`, and optional sidecar locking:
 
 ```ts
@@ -129,6 +153,9 @@ await state.updateOr(defaultState, (current) => ({ ...current, enabled: true }))
 Use this when one JSON file owns one piece of state. `jsonStore({ filePath })`
 is the absolute-path convenience wrapper for the same primitive.
 
+Pass `{ durable: false }` or `{ durable: true }` to `json()` to override the
+parent store's durability for all mutations of that JSON handle.
+
 ### `writeStream(rel, stream, options?)`
 
 ```ts
@@ -138,6 +165,9 @@ const path = await cache.writeStream("downloads/blob.bin", Readable.from(remoteF
 
 Streams into a sibling temp with a running byte budget. Aborts the source stream with `too-large` if `maxBytes` is exceeded mid-stream — partial writes are cleaned up.
 
+Streams honor `durable` in both private modes. Non-private streams stage their
+input and forward the resolved durability option to Root `copyIn` for publication.
+
 ### `copyIn(rel, sourcePath, options?)`
 
 ```ts
@@ -146,12 +176,16 @@ const path = await cache.copyIn("ingest/upload.bin", "/tmp/upload.bin");
 
 One-shot ingest from an absolute source path. Source is checked for symlink/non-regular before copy. Same mode rules as `write`.
 
+`copyIn` honors per-call and store-level `durable` values in both private modes,
+with the same precedence as `write`.
+
 ### `FileStoreWriteOptions`
 
 Per-call overrides for the store-level defaults:
 
 ```ts
 type FileStoreWriteOptions = {
+  durable?: boolean;   // store default, otherwise true
   dirMode?: number;
   mode?: number;
   maxBytes?: number;
@@ -159,6 +193,17 @@ type FileStoreWriteOptions = {
 };
 ```
 
+| `FileStoreWriteOptions` option | Default |
+|---|---|
+| `durable` | Store option, otherwise `true`. |
+| `dirMode` / `mode` | Store directory/file modes. |
+| `maxBytes` | Store byte limit. |
+| `tempPrefix` | Writer-specific temporary prefix. |
+
+The same durability precedence applies to `fileStoreSync().write`,
+`writeText`, and `writeJson`. The synchronous store has no `writeStream` or
+`copyIn` methods.
+
 ## Reads
 
 `open`, `read`, `readBytes`, `readText`, and `readJson` delegate to a fresh `Root` with `hardlinks: "reject"` and the store's `maxBytes`. Same return shapes as `Root`.
@@ -254,5 +299,5 @@ await root.move(`pending/${id}`, `done/${id}`);
 
 - [`root()`](root.md) — the boundary `FileStore` is built on; reach for it when you need move/list/append.
 - [JSON store](json-store.md) — the JSON-state-file equivalent of this surface.
-- [Atomic writes](atomic.md) — `writeSiblingTempFile` is what every write goes through.
+- [Atomic writes](atomic.md) — lower-level sibling-temp publication helpers.
 - [Temp workspaces](temp.md) — private scratch directories backed by `FileStore`.

package/docs/json-store.md

@@ -45,6 +45,7 @@ type JsonStoreOptions<T> = {
   filePath: string;
   dirMode?: number;                                // default 0o700
   mode?: number;                                   // default 0o600
+  durable?: boolean;                              // default true
   trailingNewline?: boolean;                       // default true
   lock?: boolean | JsonStoreLockOptions;           // false / undefined = no lock
 };
@@ -71,6 +72,15 @@ type JsonStore<T> = {
 `jsonStore({ filePath })` resolves `rootDir = dirname(filePath)` and calls
 `fileStore({ rootDir, private: true }).json(basename(filePath), options)`.
 
+`durable: false` keeps sibling-temp replace/rename behavior but skips the
+temp-file and parent-directory `fsync` calls. Use it only for reconstructible
+metadata where lower latency matters more than crash-durability. The default
+is `true`, subject to platform sync support. This store-level policy applies
+to `write`, `update`, and `updateOr`; these methods have no per-call options.
+For `fileStore(...).json(rel, options)`, `options.durable` overrides the parent
+file store's durability, while omission or `undefined` inherits it. Modes,
+identity checks, mutation serialization, and sidecar locking are unchanged.
+
 The store does **not** validate the parsed value against `T` at runtime — the cast is unchecked. Wrap with a schema (zod/valibot) if the file might be hand-edited or written by another process you don't control.
 
 ## `read()`

package/docs/local-roots.md

@@ -71,6 +71,13 @@ component that does not exist: dangling symlinks, descendants of dangling
 symlinks, and candidates whose existing ancestors cannot be canonicalized are
 rejected rather than treated as safe missing paths.
 
+Filesystem path inputs retain symlinks and parent components until boundary
+resolution, including after home expansion. A followed `link/../file` resolves
+the parent of the link's target; default reads reject the link instead of
+normalizing it away. File URLs retain the URL parser's normal path semantics.
+An existing non-directory component cannot be traversed further, including by
+`..`; the helpers reject that input instead of selecting a different file.
+
 ## `readLocalFileFromRoots(options)`
 
 The asynchronous helper opens the candidate through the matched [`Root`](root.md),
@@ -82,7 +89,7 @@ type ReadLocalFileFromRootsOptions = LocalRootsInputOptions & {
   hardlinks?: "reject" | "allow";
   maxBytes?: number;
   nonBlockingRead?: boolean;
-  symlinks?: "reject" | "follow-within-root";
+  symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root";
 };
 
 type LocalRootsReadResult = ReadResult & {

package/docs/native.md

@@ -59,6 +59,19 @@ whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
 
 ## Archives
 
+Native ZIP and TAR entry reads retain a private, unpooled input Buffer in
+the async reader. ZIP reuses its parsed directory; TAR retains admitted member
+offsets. TypeScript validates and selects the requested member before reading. The internal binding borrows that allocation: it must never be
+mutated or detached while the reader or a read task exists. The public API only
+accepts a pathname and owns this buffer exclusively. An N-API reference keeps
+the bytes alive; a mutex serializes access to the retained ZIP cursor. Plain
+TAR copies only the selected range after complete admission, while gzip, zstd,
+and bzip2 replay bounded decompression and validate the full physical stream.
+Concurrent TAR reads share immutable input and own separate decoder state.
+Each output owns a new vector, which N-API transfers to Node without a second
+payload copy on runtimes supporting external buffers. No entry-read path
+requires temporary-file staging. Extraction retains its private staged input.
+
 Rust streams ZIP and TAR payloads, including gzip, zstd, and bzip2. It first
 returns a bounded manifest. TypeScript applies the shared path, filter, strip,
 mode, and byte policies and returns an index-bound extraction plan. Rust then
@@ -165,7 +178,7 @@ remain TypeScript-owned. What changes is the syscall strength or availability:
 | Zstd/bzip2 TAR | Supported. | Unsupported; typed `helper-unavailable`. |
 | Publication copy | Clone, Linux `copy_file_range`, async native SHA-256. | Exclusive `wx` byte loop and Node SHA-256 with the same content/identity fences. |
 | `rename-noreplace` | Atomic platform no-replace rename. | Unsupported; no emulation by check-then-rename. |
-| Windows DACL read | Direct `GetSecurityInfo`; the public facts API exposes ordered basic allow/deny ACE SIDs, masks, and decoded flags without trust policy. | Established .NET/`icacls` inspection fallback for coarse permission checks; raw ACE facts are native-only. |
+| Windows DACL read | Direct `GetSecurityInfo`; the public facts API exposes ordered basic allow/deny ACE SIDs, masks, and decoded flags without trust policy. | Structured .NET owner/DACL inspection for coarse permission checks; the public raw ACE facts API remains native-only. |
 | Windows private directory | Creation-time protected DACL. | Unsupported; no weaker pathname-only substitute. |
 
 Use `off` in CI to keep the fallback contract exercised. Use `require` when a

package/docs/permissions.md

@@ -68,11 +68,18 @@ createIcaclsResetCommand(targetPath, { isDir, env });
 resolveWindowsUserPrincipal(env);
 ```
 
-The fallback Windows inspector calls `icacls.exe <path>` using its supported
-path-only inspection syntax and classifies principals as trusted, world, or
-group. Trusted defaults include the current user, SYSTEM, and Administrators.
-Built-in PowerShell, `icacls.exe`, and `whoami.exe` invocations have a fixed
-30-second per-process deadline. A command failure or timeout returns an
+The fallback Windows inspector reads the owner and DACL together through one
+built-in Windows PowerShell/.NET query. It returns canonical SIDs and numeric
+access masks, so Unicode paths and account names do not pass through lossy
+console display text. `inspectWindowsAcl()` uses the same query and returns
+canonical SIDs in its `principal` fields, with normalized rights tokens.
+The advanced options retain `currentUserSid` as an explicit classification
+override and `principalTranslationFailed: true` as an immediate unverified
+result. The optional `principalSids` translation cache is still accepted but
+is no longer needed because the query returns SIDs directly.
+The existing classifier assigns principals to trusted, world, or group;
+trusted defaults include the current user, SYSTEM, and Administrators.
+The built-in query has a fixed 30-second process deadline. A command failure or timeout returns an
 unverified result (`source: "unknown"`) so callers fail closed. Advanced callers
 that inject a custom `exec` implementation own that executor's deadline.
 Failed owner and ACL inspections retain `error` text and an optional
@@ -86,15 +93,18 @@ characters, including a trailing `…` when truncated. Diagnostics do not copy
 stdout or read target file contents. The separate `errorCause` retains the
 original exception for restricted local diagnosis; do not serialize or expose
 it as display text.
-The parser is on the advanced surface so tests and CLIs can process captured
-`icacls` output without spawning a process.
+The parser and remediation command builders remain on the advanced surface for
+CLIs processing captured `icacls` output or presenting an explicit repair.
+Runtime inspection does not parse that display text. A null DACL reports
+unrestricted access; an empty DACL grants nothing. Inherit-only ACEs do not
+apply to the inspected object, and deny ACEs never subtract coarse grants or
+claim effective-access evaluation. Unsupported ACE layouts remain unverified.
 
 When the native binding is available, `inspectPathPermissions()`
 reads the owner and DACL directly with Windows security APIs. It classifies the
 current user, LocalSystem, and built-in Administrators as trusted and reports
 the world/group read/write facts consumed by secure reads. Descriptor forms it
-cannot classify equivalently fall back to the established owner/.NET and
-`icacls` path; `mode: "off"` exercises that fallback deterministically.
+cannot classify equivalently fall back to the structured .NET query; `mode: "off"` exercises that fallback deterministically.
 
 ## Policy-free owner and DACL facts
 
@@ -164,7 +174,7 @@ This API is Windows-only and native-only; it fails closed with
 or when the binding is unavailable. POSIX callers should create private
 directories through their existing trusted-root creation policy rather than a
 pathname-only compatibility shim. Existing Windows permission inspection still
-retains its .NET/`icacls` compatibility fallback.
+retains its structured .NET compatibility fallback.
 
 Use `createIcaclsResetCommand()` when you need a structured command and argv pair. Use `formatIcaclsResetCommand()` when you only need a remediation string for a user-facing message.
 

package/docs/positional-read.md

@@ -0,0 +1,63 @@
+# Positional reads
+
+Use `readFileWindowFully()` and `readFileWindowFullySync()` to read a bounded
+window from an already-open file. They fill a caller-owned `Buffer`, completing
+short reads until the buffer is full or the file reaches EOF, and return the
+number of bytes read. They never allocate a payload buffer, close the descriptor,
+or change its current offset.
+
+```ts
+import { root } from "@openclaw/fs-safe";
+import { readFileWindowFully } from "@openclaw/fs-safe/advanced";
+
+const workspace = await root("/srv/workspace");
+await using opened = await workspace.open("large.log");
+const buffer = Buffer.allocUnsafe(4096);
+const bytesRead = await readFileWindowFully(opened.handle, buffer, 8192);
+const window = buffer.subarray(0, bytesRead);
+```
+
+## Signatures
+
+```ts
+type ReadFileWindowOptions = { signal?: AbortSignal };
+
+function readFileWindowFully(
+  handle: import("node:fs/promises").FileHandle,
+  buffer: Buffer,
+  position: number,
+  options?: ReadFileWindowOptions,
+): Promise<number>;
+
+function readFileWindowFullySync(
+  fd: number,
+  buffer: Buffer,
+  position: number,
+): number;
+```
+
+`position` and the exclusive window end (`position + buffer.length`) must be
+non-negative safe integers. Invalid ranges throw `RangeError` before reading.
+A zero-length buffer returns zero without I/O. Reading at or beyond EOF also
+returns zero. If EOF occurs within the window, only the returned prefix is
+written; the remaining buffer bytes stay unchanged. Always slice by the returned
+count before using an unsafe-allocated buffer.
+
+These helpers use the caller's open descriptor directly. They do not establish
+path containment, file identity, file-type admission, or a snapshot of concurrently
+modified contents. Use [`Root.open()`](root.md#reads) to admit untrusted paths,
+and keep the handle open and the buffer available until the operation settles.
+Underlying I/O errors propagate unchanged.
+
+## Cancellation
+
+The async variant accepts `signal`. A pre-aborted signal rejects before I/O.
+In-flight cancellation is checked after the pending read settles and before
+another read starts, preserving the signal's reason. Bytes already read remain
+in the buffer; cancellation does not roll them back. Once the promise settles,
+the caller can reuse the buffer or close its handle without a hidden read still
+running.
+
+For a whole-file read that rejects files exceeding a byte limit, use the
+[bounded descriptor readers](advanced.md#files-and-identity) instead. Positional
+reads stop successfully at the requested window and do not probe for extra data.

package/docs/reading.md

@@ -14,6 +14,12 @@ const opened = await fs.open("large.log");               // FileHandle for strea
 
 Identity and containment checks use brief synchronous metadata calls, like Node's module resolution, while file data is read asynchronously. Canonical paths retain Node's native realpath spelling, including expansion of Windows short paths.
 
+The same observation rule applies to archive extraction, copy, publication, move,
+directory modes, and supporting lock, queue, and secret-file operations. Opens,
+data transfers, durability syncs, filesystem mutations, and closes retain their
+existing asynchronous behavior. Custom filesystem adapters retain their async
+metadata interface.
+
 Regardless of shape, every read goes through the same boundary checks:
 
 1. Resolve the input lexically against the canonical real root.