@openclaw/fs-safe 0.9.0 → 0.10.0

package/docs/root.md

@@ -18,6 +18,7 @@ const fs = await root("/srv/workspace", {
 function root(rootDir: string, defaults?: RootDefaults): Promise<Root>;
 
 type RootDefaults = {
+  assertBeforeMutation?: () => void; // synchronous caller authority check at mutation dispatch
   durable?: boolean;               // fsync write/create/writeJson/createJson/append/copyIn; default true
   hardlinks?: "reject" | "allow";  // refuse files with nlink > 1 on read; defaults to "reject"
   denyMutations?: DenyMutationPolicy; // absolute paths/prefixes mutation methods may not change
@@ -26,7 +27,8 @@ type RootDefaults = {
   mode?: number;                   // file mode applied to new writes; per-call override available
   nonBlockingRead?: boolean;       // compatibility hint; safe opens are already nonblocking where supported
   renameIdentity?: "strict" | "verify-content-with-lock"; // default "strict"
-  symlinks?: "reject" | "follow-within-root"; // policy when a path component is a symlink
+  symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root"; // read policy
+  mutationSymlinks?: "reject" | "follow-parents-within-root"; // opt-in mutation policy
 };
 
 type DenyMutationPolicy = {
@@ -37,7 +39,9 @@ type DenyMutationPolicy = {
 
 `root()` resolves the directory through the real filesystem. A symlinked input becomes the canonical path; a non-existent root throws `FsSafeError` with code `not-found`, and malformed or non-directory roots throw `invalid-path`.
 
-`defaults` apply to every method on the returned handle. Per-call options on individual methods override the defaults for that call only, except `denyMutations`: root and per-call deny entries are merged so a call cannot clear a root-level deny.
+The root directory is pinned with exact bigint device/inode identities. A changed root rejects subsequent operations; an unknown Windows identity that remains unverifiable after bounded reinspection rejects construction with `path-mismatch`.
+
+`defaults` apply to every method on the returned handle. Per-call options on individual methods override the defaults for that call only, except `denyMutations` and `assertBeforeMutation`: deny entries are merged, and the root assertion runs before the per-call assertion. A call cannot clear either root-level restriction.
 
 Every `maxBytes` value must be a non-negative safe integer or positive `Infinity`. Zero is an active zero-byte cap; `Infinity` explicitly disables the cap. An omitted or explicitly `undefined` per-call value preserves the configured Root default instead of clearing it.
 
@@ -60,7 +64,12 @@ fs.walk(rel, options)          // root-bounded AsyncIterable<{ relativePath, kin
 
 `walk()` is the incremental, root-bounded recursive scan. It supports entry and
 depth budgets, cancellation, and `symlinkPolicy: "skip" |
-"follow-within-root"`. Budget exhaustion yields a `"truncated"` marker by
+"follow-within-root"`. With an entry budget, sorted walks prepare small metadata
+batches within the remaining budget; unbounded sorted walks reuse the full
+directory snapshot.
+The default `order: "sorted"` enumerates and sorts each directory's names;
+`order: "filesystem"` streams names in filesystem order for bounded work in
+wide directories. Budget exhaustion yields a `"truncated"` marker by
 default or throws `FsSafeError("too-large")` with `limitBehavior: "throw"`.
 Use `entryFilter(entry)` to return `"include"`, `"skip"`, or
 `"skip-subtree"`. `"skip"` omits the current entry but still descends into a
@@ -111,6 +120,10 @@ fs.ensureRoot(options?)                  // accepts "" / "." as the root itself
 
 `write`, `create`, `append`, `writeJson`, and `createJson` accept `mode?: number`; use `0o600` for credentials and other private state. `writeJson` also accepts the same options as `JSON.stringify` plus `trailingNewline?: boolean` (defaults `true` so the file ends in `\n`).
 
+`append` accepts `prependNewlineIfNeeded: true` to separate text from existing
+content when neither side supplies a newline. String data uses its `encoding`
+for the newline check, including UTF-16LE; Buffer data uses a single LF byte.
+
 These five methods and `copyIn` also accept `durable?: boolean`: the per-call value overrides
 `Root.defaults.durable`, which defaults to `true` when omitted. An explicitly
 `undefined` per-call value preserves the root default. `durable: false` keeps
@@ -119,7 +132,76 @@ and parent-directory fsync calls. Use it only for reconstructible data: a crash
 may lose the write or leave the previous file. See [Writing](writing.md#write-options)
 for platform details.
 
-`copyIn` is a one-shot ingest from a trusted absolute source path: it streams the source through the boundary, atomically renames into the root, and respects `maxBytes`.
+`copyIn` accepts a `RootCopySource`: a trusted absolute source path or a file
+within another Root. The guarded form supplies `root` with only its `open` and
+`stat` read capabilities, plus `relativePath`:
+
+```ts
+const source = await root("/srv/templates");
+const destination = await root("/srv/workspace");
+await destination.copyIn("config/settings.json", {
+  root: source,
+  relativePath: "config/settings.json",
+}, {
+  overwrite: false,
+  clone: "auto",
+  mode: 0o600,
+  signal: AbortSignal.timeout(30_000),
+});
+```
+
+The source Root applies its read policies, including confinement and symlink
+handling. `sourceHardlinks` overrides its hardlink policy only when supplied;
+otherwise the source Root default is retained. The admitted source
+descriptor stays open through copying and source-identity verification; copying
+does not consume its current file position. Both forms enforce `maxBytes` while
+reading, including when a file grows after admission, and use bounded buffers.
+Copies have independent file data; changing either file cannot change the other.
+Set `preserveSourceMode: true` to select the mode from the admitted source
+descriptor. An explicit numeric `mode`, including `Root.defaults.mode`, takes
+precedence. By default, copying retains the existing destination-mode rules.
+The operation verifies source identity, not a coherent snapshot of concurrent
+in-place edits. Keep the source unchanged when snapshot consistency is required.
+
+`overwrite` defaults to `true`, preserving the existing replacement behavior.
+With `overwrite: false`, an existing destination produces `already-exists` and
+is never altered. Copying prepares a private sibling file before publishing its
+completed contents. Native mode uses no-replace rename. The guarded JavaScript
+fallback links the completed stage and removes its temporary name in the same
+JavaScript turn; the filesystem must support hardlinks. Other processes can
+briefly observe both names. The source is never hardlinked to the destination.
+
+`clone` chooses the file-data transfer strategy through `CopyCloneMode`, shared
+with [`copyTree`](copy.md#api). File copies default to `"never"`; tree copies
+default to `"auto"`:
+
+| Value | Behavior |
+| --- | --- |
+| `never` | Copy regular file bytes using reads and writes, without explicit cloning or copy offload. |
+| `auto` | Try native file cloning, then copy offload or ordinary byte copying when cloning is unavailable. |
+| `always` | Require native cloning; fail when the binding or filesystem cannot provide it. |
+
+Native file cloning supports APFS and supported Linux filesystems. Windows
+currently uses byte copying for `never` and `auto`; `always` fails. Clone choice
+does not change modes, durability, root confinement, or source and publication
+identity checks. The shared strategy does not replace Root's guarded regular-file
+contract with `copyTree`'s caller-owned immutable-tree and metadata contract.
+
+An already aborted `signal` prevents I/O. Cancellation during copying waits for
+admitted reads and native work to settle, then cleans only the owned unpublished
+stage. The final authority check runs before publication. Once publication has
+occurred, later cancellation or verification failure preserves the destination.
+The synchronous optional `onDestinationPublished` callback receives a frozen
+`RootCopyPublicationReceipt` containing `{ path, dev, ino }`, with exact bigint identity immediately after
+publication, before later checks can fail. Callback errors also preserve the
+published file. This receipt records an outcome; it does not authorize removing
+a file that another actor may have edited. Application recovery and cooperative
+locking remain caller-owned.
+
+Existing `copyIn` callers must account for completed destinations retained after
+a post-publication source-verification failure, even without the new options.
+Recovery must inspect current destination state rather than assume a rejected
+copy left no file.
 
 Root operations that choose a new destination reject a leading Windows
 drive-relative spelling such as `C:name` on every platform. This applies to
@@ -131,8 +213,59 @@ basename first.
 
 `openWritable` opens a writable file with options `mode?: number` and `writeMode?: "replace" | "append" | "update"`. `replace` truncates existing files and is the default; `update` keeps existing contents. Use it for streaming output. Prefer `await using` for cleanup.
 
+### Live mutation authority
+
+All mutation methods accept `assertBeforeMutation?: () => void`. Use it when a
+lease, operation owner, or cancellation state can expire while filesystem
+preparation is awaiting I/O:
+
+```ts
+const controller = new AbortController();
+await fs.write("config.json", "{}\n", {
+  assertBeforeMutation: () => controller.signal.throwIfAborted(),
+});
+```
+
+The callback runs synchronously after awaited preparation, immediately before
+each Root-owned mutation is dispatched: parent creation, file creation and
+content writes (including private staging and streamed chunks), publication,
+truncation, append, move, and removal. Buffered writes use bounded chunks and
+recheck before every partial-write submission; file removal submits a direct
+unlink request. Native calls that perform multiple filesystem steps are one
+dispatch. No asynchronous wait separates the check
+from that dispatch. A thrown value rejects the operation unchanged; an async
+or thenable-returning callback rejects with `TypeError` before that mutation.
+Synchronous return values are ignored. Callbacks can run multiple times and
+must inspect current authority each time.
+
+Already dispatched I/O cannot be revoked. Identity-checked cleanup, final
+permissions, and durability finish under the existing operation owner even
+after authority expires. Sidecar lock acquisition, recovery, and release for
+`renameIdentity: "verify-content-with-lock"` are lock bookkeeping outside this
+callback; content mutations still recheck after the lock is acquired. An
+operation may leave already-created parent directories when a later check
+rejects. A no-op such as `ensureRoot()` on the existing root does not require a
+callback invocation. This is a dispatch fence, not a filesystem transaction or
+a replacement for root confinement.
+
+If cleanup also fails or cannot prove ownership of an entry, the existing
+structured cleanup error takes precedence and retains the authority refusal
+as its cause.
+
+For `openWritable()`, the callback covers the library's parent creation,
+exclusive creation, and truncation. The returned raw `FileHandle` belongs to
+the caller, which must check authority before its own later writes.
+
 All mutation methods accept `denyMutations?: { paths?: string[]; prefixes?: string[] }`. Entries must be absolute paths. `paths` blocks those exact paths; `prefixes` blocks those paths and their descendants. fs-safe preserves path strings exactly and canonicalizes through existing ancestors before comparing, so a symlinked ancestor to a denied location is still denied. Denied mutations throw `FsSafeError` with code `denied-path`. Use this for caller-specific sensitive paths, not as a replacement for the root boundary, symlink, or hardlink checks.
 
+All mutation methods also accept `mutationSymlinks`. `"reject"` rejects symlink
+components; `"follow-parents-within-root"` resolves contained parent directory
+aliases but rejects the final component if it is a symlink, including a dangling
+link. Missing parent directories can still be created through a contained alias.
+`move()` applies the policy to both source and destination. An omitted value
+preserves existing behavior, including `remove()` unlinking a final symlink.
+The read-only `symlinks` default does not change mutation behavior.
+
 ### Inspection (advisory)
 
 ```ts
@@ -218,6 +351,35 @@ await fs.readText("config.toml");
 await fs.readText("links/current.log", { symlinks: "follow-within-root" });
 ```
 
+With `follow-within-root`, parent components after a symlink are applied to the
+symlink's resolved target. Reads use that checked canonical path, including
+after home expansion and through `readAbsolute` and `reader`; the default policy still rejects a symlink
+even when a later `..` would hide it in a purely lexical normalization.
+
+Use `follow-parents-within-root` when directory aliases are allowed but a final
+file symlink should fail. Set each policy at the root to share that contract
+between reads and mutations:
+
+```ts
+const workspace = await root("/srv/workspace", {
+  symlinks: "follow-parents-within-root",
+  mutationSymlinks: "follow-parents-within-root",
+});
+await workspace.readText("directory-alias/notes.txt");
+await workspace.write("directory-alias/notes.txt", "updated\n");
+```
+
+The library uses the resolved parent for the operation and checks the final
+component again before publication or removal. These checks preserve the existing
+[platform containment guarantees](security-model.md#symlinks-write-side);
+they do not make check-and-rename atomic against another process. Callers do not
+need a separate `realpath()` or final `lstat()` preflight.
+
+For methods that accept absolute paths, the same final-component rule applies
+when a path enters the root through an alias outside its lexical spelling. A directory alias may
+lead to a regular file inside the root; an absolute final file or directory
+symlink is rejected before its canonical target replaces the original path.
+
 Text helpers default to UTF-8. Pass `encoding` per call to `readText`, `readJson`, `write`, `create`, or `append` when you need another encoding.
 
 ## Common patterns

package/docs/security-model.md

@@ -53,6 +53,11 @@ Every path is resolved against the canonicalized real path of the root, then che
 
 Per-call `symlinks: "follow-within-root"` allows symlinks whose final target is still inside the root. The default is `"reject"`.
 
+`symlinks: "follow-parents-within-root"` allows contained parent directory aliases
+while rejecting a final symlink, including dangling links. Reads open the checked
+canonical parent plus the final basename with the usual no-follow and identity
+checks, so callers do not need their own parent canonicalization.
+
 Guarded root reads compare lossless bigint identities from before open, the opened
 descriptor, the input path, and the canonical target; numeric public `Stats`
 receipts are not used as identity evidence. Unknown Windows device/inode values
@@ -70,6 +75,15 @@ directory descriptors. Replacement uses descriptor-relative rename just like
 no-replace publication, so replacing the parent pathname does not divert the
 mutation.
 
+The opt-in `mutationSymlinks` policy applies independently of read policy.
+`"reject"` rejects symlink components; `"follow-parents-within-root"` resolves
+contained directory aliases and rejects final symlinks. Publication checks the
+final component again after awaited staging and parent fences, immediately before
+the rename or exclusive open. These are best-effort symlink checks, not an atomic
+expected-entry/CAS replacement: a concurrent process can still replace the final
+entry between its check and rename. Existing parent containment guarantees remain
+as described below. Omitting `mutationSymlinks` preserves existing mutation behavior.
+
 The JavaScript fallback used by `off`, by `auto` when no binding loads, and by
 the explicit `renameIdentity: "verify-content-with-lock"` compatibility policy
 cannot provide that guarantee because Node exposes no `mkdirat` or `renameat`.

package/docs/timing.md

@@ -22,6 +22,8 @@ function withTimeout<T>(
 
 If `timeoutMs` is `0`, negative, `Infinity`, or `NaN`, the helper is a no-op and simply awaits the original promise.
 
+Finite delays above Node's single-timer limit (2,147,483,647 ms, about 24.9 days) are scheduled in bounded intervals without expiring early. The timer is still cleared if the wrapped promise settles first.
+
 ## Examples
 
 ### Simple ceiling

package/docs/types.md

@@ -99,6 +99,7 @@ type ReadResult = {
 type RenameIdentityPolicy = "strict" | "verify-content-with-lock";
 
 type RootDefaults = {
+  assertBeforeMutation?: () => void;
   denyMutations?: DenyMutationPolicy;
   durable?: boolean; // default true for write/create/writeJson/createJson/append
   hardlinks?: "reject" | "allow";
@@ -107,7 +108,8 @@ type RootDefaults = {
   mode?: number;
   nonBlockingRead?: boolean;
   renameIdentity?: RenameIdentityPolicy;
-  symlinks?: "reject" | "follow-within-root";
+  symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root";
+  mutationSymlinks?: MutationSymlinkPolicy;
 };
 
 type DenyMutationPolicy = {
@@ -121,20 +123,20 @@ type RootOptions = {
 };
 ```
 
-`RootDefaults` is what `root(rootDir, defaults)` accepts. See [`root()`](root.md) for the per-method options that override these. `denyMutations` is the exception: root and per-call deny entries are merged.
+`RootDefaults` is what `root(rootDir, defaults)` accepts. See [`root()`](root.md) for the per-method options that override these. `denyMutations` and `assertBeforeMutation` are exceptions: deny entries are merged, and the root authority assertion runs before the per-call assertion.
 
 ## `RootReadOptions` / `RootWriteOptions` / `RootCopyOptions`
 
 ```ts
 type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "nonBlockingRead" | "symlinks">;
-type RootWriteOptions = Pick<RootDefaults, "denyMutations" | "durable" | "mkdir" | "mode" | "renameIdentity"> & {
+type RootWriteOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "durable" | "mkdir" | "mode" | "renameIdentity" | "mutationSymlinks"> & {
   encoding?: BufferEncoding;
   overwrite?: boolean;
 };
-type RootCopyOptions = Pick<RootDefaults, "denyMutations" | "maxBytes" | "mkdir" | "mode"> & {
+type RootCopyOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "durable" | "maxBytes" | "mkdir" | "mode" | "mutationSymlinks"> & {
   sourceHardlinks?: "reject" | "allow";
 };
-type RootOpenWritableOptions = Pick<RootDefaults, "denyMutations" | "mkdir" | "mode"> & {
+type RootOpenWritableOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mkdir" | "mode" | "mutationSymlinks"> & {
   writeMode?: "replace" | "append" | "update";
 };
 type RootWriteJsonOptions = RootWriteOptions & {
@@ -145,23 +147,28 @@ type RootWriteJsonOptions = RootWriteOptions & {
 type RootAppendOptions = RootWriteOptions & {
   prependNewlineIfNeeded?: boolean;
 };
-type RootMoveOptions = Pick<RootDefaults, "denyMutations"> & {
+type RootMoveOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks"> & {
   overwrite?: boolean;
 };
-type RootRemoveOptions = Pick<RootDefaults, "denyMutations">;
-type RootMkdirOptions = Pick<RootDefaults, "denyMutations">;
+type RootRemoveOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks">;
+type RootMkdirOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks">;
 ```
 
 Per-method option shapes. Each picks the `RootDefaults` keys that apply, plus method-specific extras.
 
-## `SymlinkPolicy` / `HardlinkPolicy`
+## `SymlinkPolicy` / `MutationSymlinkPolicy` / `HardlinkPolicy`
 
 ```ts
-type SymlinkPolicy = "reject" | "follow-within-root";
+type SymlinkPolicy = "reject" | "follow-within-root" | "follow-parents-within-root";
+type MutationSymlinkPolicy = "reject" | "follow-parents-within-root";
 type HardlinkPolicy = "reject" | "allow";
 ```
 
-The two policy unions you'll see throughout. `"reject"` is conservative; `"follow-within-root"` allows symlinks whose final target is still inside the root; `"allow"` (hardlinks only) is permissive. Defaults for both symlinks and hardlinks are `"reject"`; switch hardlinks to `"allow"` only when you intentionally accept hardlink aliases.
+`"reject"` is conservative; `"follow-within-root"` allows symlinks whose final target is still inside the root; `"allow"` (hardlinks only) is permissive. Defaults for read symlinks and hardlinks are `"reject"`; switch hardlinks to `"allow"` only when you intentionally accept hardlink aliases.
+
+`"follow-parents-within-root"` allows contained parent directory aliases while
+rejecting final symlinks. Mutation policy is opt-in and independent of read
+policy; omission preserves each mutation method's existing behavior.
 
 ## `FsSafeErrorCode` / `FsSafeErrorCategory`
 

package/docs/walk.md

@@ -72,10 +72,57 @@ Unreadable directories are skipped rather than throwing, but every skipped direc
 `Root.walk(rel, options)` is the root-bounded counterpart to these standalone
 inventory helpers. It yields `{ relativePath, kind, size }` incrementally and
 accepts `maxDepth`, `maxEntries`, `symlinkPolicy: "skip" |
-"follow-within-root"`, and an `AbortSignal`. The default budget behavior yields
+"follow-within-root"`, `order: "sorted" | "filesystem"`, and an `AbortSignal`. The default budget behavior yields
 one `kind: "truncated"` marker and ends; pass `limitBehavior: "throw"` for a
 typed `FsSafeError("too-large")` instead.
 
+For followed symlinks, both `kind` and `size` describe the resolved target.
+
+The default `order: "sorted"` visits each directory's names in lexicographic
+order before descending depth first. It reads and sorts all names in each
+visited directory. With `maxEntries`, it prepares small metadata batches capped
+by the remaining global entry budget. Every batch stops at the first directory
+or symlink, so recursive descent cannot spend a budget already used by later
+siblings. An early `break` may leave metadata from the current batch unused;
+the total still stays within `maxEntries`. Filtering requires metadata and
+consumes the entry budget, including entries skipped by the filter.
+
+Without `maxEntries`, sorted walks reuse a full directory metadata snapshot
+from the `Root.list()` owner. This preserves the existing fast complete-scan
+behavior and its snapshot semantics: changes made after a directory is listed
+do not alter its already-captured entries. Supply an entry budget or use
+filesystem order when metadata work must remain incremental. Sorted entries
+describe the observations captured in their directory snapshot or batch.
+
+Use `order: "filesystem"` when a wide directory must not be fully enumerated:
+
+```ts
+for await (const entry of capability.walk("", {
+  order: "filesystem",
+  maxEntries: 128,
+  symlinkPolicy: "skip",
+})) {
+  consume(entry);
+}
+```
+
+This order follows the filesystem's directory stream and is not deterministic.
+It reads one entry at a time, including one name of lookahead to distinguish an
+exactly exhausted budget from truncation. The lookahead does not request full
+entry metadata from fs-safe, and an early `break` does not prefetch later child
+metadata. If a filesystem does not supply directory-entry
+types, Node may classify that one extra entry with a synchronous `lstat`.
+Handles close on completion, truncation, cancellation, errors, or an
+early `break`. Both orders keep the same depth-first traversal, entry filtering,
+and truncation rules. Cancellation is checked between entries, with event-loop
+handoffs between budgeted sorted batches. Root and directory checks and admitted
+child metadata reads are synchronous; no mode can interrupt a filesystem
+syscall already in progress or the sorted mode's name sorting.
+
+If a thrown walk failure and directory close both fail, disposal throws a
+`SuppressedError` with the close failure in `error` and the original failure in
+`suppressed`, preserving both causes.
+
 `entryFilter` is evaluated for each resolved file, directory, or other entry:
 
 ```ts
@@ -109,10 +156,12 @@ Every examined directory entry consumes `maxEntries` before filtering, so
 `"truncated"` markers describe already-reached state and do not authorize
 further descent.
 
-The pure-Node path validates every directory canonically inside the root,
-revalidates each listing through the normal `Root.list()` boundary, and tracks
-canonical directories to stop symlink cycles. It does not hold a descriptor
-for the entire tree, so it is not a process sandbox against a hostile peer that
+The pure-Node path validates every directory through the Root boundary, pins
+its exact identity, and rechecks it and the Root identity around each metadata
+batch or individual filesystem-order observation. Sorted batches contain no
+await or caller code between their before/after checks. It tracks canonical
+directories to stop symlink cycles.
+Neither mode holds a descriptor for every path component, so it is not a process sandbox against a hostile peer that
 can continuously swap and restore directories. Each individual lookup retains
 the documented Node `Root` boundary checks.
 

package/docs/writing.md

@@ -38,6 +38,12 @@ await fs.mkdir("snapshots/2026/05");
 Private sibling temporary names are independent of the destination basename,
 so staging does not add a suffix to an otherwise valid long filename.
 
+Write paths reject `path-alias` when symlinks and parent components select a
+different target before and after lexical normalization, such as `link/../file`
+where `link` points into a deeper directory. This avoids silently modifying the
+wrong file. Resolve an intended alias explicitly with `Root.resolve()` before
+passing its canonical path to a mutation.
+
 A failure before the final rename leaves the destination at its previous
 contents. A successful rename publishes the complete replacement. This
 old-or-new guarantee does not apply to `append()` or `openWritable()`, which
@@ -48,6 +54,10 @@ Post-publication verification can still reject after a complete replacement has
 been committed. Rejection does not promise that a successful rename was rolled
 back; the published file or a raced replacement may remain at the destination.
 
+Failed-write cleanup compares exact parent and file identities, including large
+Windows file indexes. Replaced paths and paths whose ownership cannot be verified
+are preserved.
+
 ## Denying mutations
 
 All mutation verbs accept `denyMutations?: DenyMutationPolicy`, either as a root default or per-call option:
@@ -99,8 +109,9 @@ writes but skips file and parent-directory fsync calls. Create-only and append
 publication behavior, permissions, identity checks, and error codes are unchanged.
 Use it only for reconstructible data: a crash may lose the write or leave the
 previous file. `move` and streaming `openWritable` do not use this option.
-The existing pure-JavaScript Windows writer performs no fsync calls in either
-setting; native Windows writes honor the option. Directory sync remains best-effort.
+Native and pure-JavaScript Windows writers honor the option. Replacement writes
+sync staged content before rename and the final mode through the retained file
+handle. Directory sync remains best-effort.
 
 POSIX modes without read permission, including `0o000` and `0o200`, succeed:
 final verification uses a descriptor retained by the writer rather than reopening
@@ -202,10 +213,17 @@ await fs.move("incoming/foo.txt", "archive/foo.txt", { overwrite: true });
 
 Both `from` and `to` are bounded; `..` in either is rejected.
 
+The JavaScript fallback checks both parent directories before and after the
+rename. A failed post-operation check rejects even though the rename may
+already have completed; rejection does not imply rollback.
+
 ### `fs.remove(rel)`
 
 Unlink a file or `rmdir` an empty directory. Non-empty directories throw `not-empty`. For atomic directory replacement, use [`replaceDirectoryAtomic`](atomic.md#replacedirectoryatomic).
 
+The JavaScript fallback reports failed parent-directory checks after removal.
+The entry may already have been removed when this verification rejects.
+
 ```ts
 await fs.remove("logs/yesterday.log");
 await fs.remove("snapshots/empty-dir"); // ok

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -46,6 +46,10 @@
       "types": "./dist/root.d.ts",
       "default": "./dist/root.js"
     },
+    "./copy": {
+      "types": "./dist/copy.d.ts",
+      "default": "./dist/copy.js"
+    },
     "./config": {
       "types": "./dist/config.d.ts",
       "default": "./dist/config.js"
@@ -126,6 +130,7 @@
   },
   "scripts": {
     "benchmark": "node scripts/benchmark.mjs",
+    "benchmark:methods": "node benchmarks/runner.mjs",
     "benchmark:publish": "pnpm build && node scripts/bench-publish.mjs",
     "build": "node scripts/prepack-build.mjs",
     "lint:file-size": "node scripts/check-file-size.mjs",
@@ -156,13 +161,13 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.9.0",
-    "@openclaw/fs-safe-darwin-x64": "0.9.0",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.9.0",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.9.0",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.9.0",
-    "@openclaw/fs-safe-linux-x64-musl": "0.9.0",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.9.0",
+    "@openclaw/fs-safe-darwin-arm64": "0.10.0",
+    "@openclaw/fs-safe-darwin-x64": "0.10.0",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.10.0",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.10.0",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.10.0",
+    "@openclaw/fs-safe-linux-x64-musl": "0.10.0",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.10.0",
     "jszip": "^3.10.2"
   },
   "devDependencies": {