@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/docs/walk.md

@@ -47,6 +47,10 @@ type WalkDirectoryFailure = {
 
 `depth` starts at `1` for direct children of `rootDir`. `relativePath` is always relative to the supplied root. `scannedEntryCount` counts directory entries examined, including entries filtered out by `include`.
 
+Each entry's `path` is absolute and retains the normalized spelling of the
+supplied root, including followed directory aliases. Paths do not switch to
+the canonical symlink target during descent.
+
 `walkDirectory()` and `walkDirectorySync()` always return `failedDirs`; the property remains optional on the exported `WalkDirectoryResult` type so existing callers that manually construct the legacy result shape remain source-compatible. It lists every directory whose `realpath`/`readdir` threw, so its contents are absent from `entries`. `error` is the thrown value (a `NodeJS.ErrnoException` at runtime), so callers can distinguish a benign missing-directory race (`ENOENT`) from a real read failure (`EACCES`, `EIO`, `ESTALE`, …). The walk-root failure has an empty `relativePath` and `depth: 0`. Failures resolving a symlink's target kind are not reported here.
 
 ## Options
@@ -59,12 +63,43 @@ type WalkDirectoryOptions = {
   include?: (entry: WalkDirectoryEntry) => boolean;
   descend?: (entry: WalkDirectoryEntry) => boolean;
 };
+
+type AsyncWalkDirectoryOptions = Omit<WalkDirectoryOptions, "include" | "descend"> & {
+  include?: (entry: WalkDirectoryEntry) => boolean | Promise<boolean>;
+  descend?: (entry: WalkDirectoryEntry) => boolean | Promise<boolean>;
+};
 ```
 
 `symlinks` defaults to `"skip"`. `"include"` returns symlink entries without following them. `"follow"` resolves symlinks with `stat()` and may descend into linked directories, so use it only when that is intentional. Already-visited real directories are skipped so symlink cycles do not recurse forever.
 
+Before descending into a child directory, `skip` and `include` recheck whether
+that entry has become a symlink, including changes made while a filter waits.
+The explicitly supplied walk root may still be a symlink. This best-effort
+child check does not turn the standalone walker into a confinement boundary;
+use `Root.walk()` when root confinement is required.
+
 `include` controls which entries are returned. `descend` controls which directory entries are traversed. A skipped directory can still be returned if `include` accepts it.
 
+The asynchronous `walkDirectory()` accepts `AsyncWalkDirectoryOptions`. It resolves each `include` decision before calling `descend`, and resolves descent before reading the directory's children. Decisions run serially in the existing filesystem-order depth-first traversal. Both callbacks retain the supplied options object as their `this` receiver.
+
+Absent callbacks and primitive results keep the synchronous selection path. Object and function results are awaited directly, including promises and thenables. For JavaScript callers, nullish results retain the default `true`; other resolved values use their existing truthiness. Return booleans or promises of booleans for the typed API.
+
+```ts
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const scan = await walkDirectory("/safe/workspace", {
+  include: (entry) => entry.kind === "file",
+  descend: async (entry) => {
+    const marked = await fs.access(path.join(entry.path, "SKILL.md"))
+      .then(() => true, () => false);
+    return !marked;
+  },
+});
+```
+
+This prunes a directory after finding its marker without listing that directory's children. Callback throws and promise rejections reject the walk; they are not directory failures in `failedDirs`. Filtering still consumes the examined-entry budget. `WalkDirectoryOptions` and `walkDirectorySync()` remain synchronous; the async options do not add confinement or cancellation to the standalone walker.
+
 Unreadable directories are skipped rather than throwing, but every skipped directory is recorded in `failedDirs`. This keeps the helper suitable for best-effort inventories while letting pruning jobs tell an incomplete scan from an empty one: a destructive reconcile that deletes state for paths missing from `entries` must first confirm `failedDirs` holds no real read failures, or a transient `EIO`/`EACCES` blip would be mistaken for mass deletion. Use a stricter root-bounded operation when every entry must be accounted for.
 
 ## Root-bounded async iteration
@@ -72,11 +107,60 @@ 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.
 
-`entryFilter` is evaluated for each resolved file, directory, or other entry:
+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.
+The `RootWalkEntryFilter` callback returns a `RootWalkEntryFilterResult`
+or a `Promise<RootWalkEntryFilterResult>`:
 
 ```ts
 for await (const entry of capability.walk("", {
@@ -100,19 +184,57 @@ The result values are `"include"`, `"skip"`, and `"skip-subtree"`. Plain
 `"skip-subtree"` omits that directory and prunes its descendants. Returning
 `"skip-subtree"` for a non-directory is equivalent to `"skip"`.
 
+An asynchronous filter can inspect a marker before deciding whether to prune:
+
+```ts
+for await (const entry of capability.walk("", {
+  symlinkPolicy: "skip",
+  entryFilter: async (entry) => {
+    if (
+      entry.kind === "directory" &&
+      await capability.exists(`${entry.relativePath}/SKILL.md`)
+    ) {
+      return "skip-subtree";
+    }
+    return "include";
+  },
+})) {
+  consume(entry);
+}
+```
+
+Filters run serially outside metadata batches and retain the supplied options
+object as their `this` receiver. When an awaited filter resolves, the walk
+checks cancellation and revalidates the current listing directory and Root
+identities before using the decision. These checks do not refresh the entry's
+captured metadata or pin a later operation.
+
+Cancellation and iterator disposal wait for a pending filter to settle. The
+walk does not race the callback against the abort signal or close its directory
+while the callback is running; callbacks must settle their own work for
+cancellation to finish. Callback throws and promise rejections reject the walk
+through its normal cleanup path, even with `onDirectoryError: "skip-and-report"`.
+
 `onDirectoryError` defaults to `"throw"`, preserving the original fail-fast
 contract. `"skip-and-report"` yields a discriminated
 `{ kind: "directory-error", relativePath, size: 0, error }` marker for a
 directory that cannot be resolved or listed, then continues with its siblings.
+This policy also applies when the directory or Root identity recheck after an
+awaited filter fails; callback failures themselves are not directory errors.
 Every examined directory entry consumes `maxEntries` before filtering, so
 `"skip"` cannot turn the iterator into an unbounded traversal. Reporting and
 `"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.
+Directory rechecks retain exact identities while using ordinary numeric metadata
+when it represents those identities without rounding. Large identities and
+Windows unknown-identity retries keep the bigint inspection path.
+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/node_modules/@openclaw/fs-safe/docs/writing.md

@@ -6,11 +6,11 @@ half-written replacement appears at the destination. Create-only writes
 (`create`, `createJson`, and `write` with `overwrite: false`) use sibling-temp
 staging with an atomic no-replace rename only on backends that provide one —
 the native binding, which `require` mode guarantees and `auto` mode uses when
-the binding loads. The pure-JavaScript fallback has no atomic no-clobber
-rename and does not stage: it claims the final name exclusively with `O_EXCL`
-and writes content in place, so a concurrent observer can see the new file
-before its content is complete. Use `require` mode when that visibility window
-matters.
+the binding loads. Ordinary buffered creation in the pure-JavaScript fallback
+claims the final name exclusively with `O_EXCL` and writes content in place, so
+a concurrent observer can see the new file before its content is complete.
+Buffered `create` and `createJson` accept `atomic: true` to stage complete content
+on this fallback too. Streamed creation already stages before publication.
 `append` and `openWritable` intentionally modify an opened file in place;
 `move`, `remove`, and `mkdir` mutate directory entries rather than file bytes.
 Each verb applies the boundary checks appropriate to its operation.
@@ -29,8 +29,8 @@ await fs.mkdir("snapshots/2026/05");
 ## What replacement writes do
 
 1. Resolve the relative target against the canonical root and reject anything that escapes (`outside-workspace`).
-2. If `mkdir: true`, create missing parent directories relative to a pinned parent fd in the native path, or with per-component identity guards in the JavaScript fallback.
-3. Pin or guard the parent directory for the selected mechanism. Native operations use a parent fd; guarded JavaScript verifies directory identity before and after mutation. The JavaScript check cannot make the intervening pathname syscall atomic, so a same-privilege peer that can replace the parent may cause an out-of-root side effect before detection. Use native `require` mode for that threat model; see the [security model](security-model.md#symlinks-write-side).
+2. If `mkdir: true`, create missing parent directories relative to a pinned parent fd in the native path, or with per-component identity guards in the JavaScript fallback. When `denyMutations` or an explicit `mutationSymlinks` policy is present, each missing POSIX-native component is authorized before creation and its opened descriptor is authorized again before descent.
+3. Pin or guard the parent directory for the selected mechanism. Native operations use a parent fd and reapply configured mutation policy to the actual canonical destination selected by that descriptor; the pinned JavaScript fallback verifies directory identity before and after mutation and performs the same policy revalidation before its pathname dispatch. The JavaScript check cannot make the intervening pathname syscall atomic, so a same-privilege peer that can replace the parent may cause an out-of-root side effect before detection. Use native `require` mode for that threat model; see the [security model](security-model.md#symlinks-write-side).
 4. Write data to a sibling temp file in the same directory.
 5. Atomically rename the temp file over the destination.
 6. Stat the resulting fd and verify identity.
@@ -38,9 +38,21 @@ 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
+contents. A successful rename publishes the complete replacement. Buffered
+Windows replacement writes also keep a missing destination absent while staging;
+they do not reserve an empty file at the final name. An ordinary writable file created
+concurrently may be replaced under `overwrite: true`. Immediately before rename,
+the writer rechecks the selected destination's type and link count, admits a raced
+file's access, and verifies retained file/parent identities and mutation policy.
+
+The old-or-new guarantee does not apply to `append()` or `openWritable()`, which
 write in place, or to lower-level atomic helpers when their explicitly
 non-atomic permission-error copy fallback is enabled.
 
@@ -48,6 +60,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:
@@ -64,7 +80,7 @@ await fs.write(".env", "x");       // throws FsSafeError code "denied-path"
 await fs.remove(".ssh/id_rsa");    // throws FsSafeError code "denied-path"
 ```
 
-`paths` blocks exact absolute paths. `prefixes` blocks absolute paths and everything below them. fs-safe preserves path strings exactly and canonicalizes through existing ancestors before comparing, so a mutation through a symlinked ancestor to a denied path is still denied. Root-level and per-call policies are additive; per-call policy can add denies, but cannot clear root defaults.
+`paths` blocks exact absolute paths. `prefixes` blocks absolute paths and everything below them. For POSIX pinned `write`, `create`, and `copyIn`, an existing exact-path directory does not implicitly deny a mutation to its descendants, but creating a missing directory at that exact path is itself denied. fs-safe preserves path strings exactly and canonicalizes through existing ancestors before comparing, so a mutation through a symlinked ancestor to a denied path is still denied. Root-level and per-call policies are additive; per-call policy can add denies, but cannot clear root defaults. Those POSIX pinned operations snapshot the merged policy before their first path observation, then authorize the actual descriptor-selected parent before staging or publication. A caller mutation of the original arrays, or a contained parent redirect after preflight, cannot clear that admission check.
 
 ## Write verbs
 
@@ -91,16 +107,25 @@ await fs.write("notes/today.txt", "hello\n", { encoding: "utf8" });
 | `overwrite` | `boolean` | `true`; `false` is create-only. |
 | `renameIdentity` | `RenameIdentityPolicy` | `"strict"`. |
 
-`write`, `create`, `writeJson`, `createJson`, and `append` accept `durable`.
+`write`, `create`, `writeJson`, `createJson`, `append`, and `copyIn` accept `durable`.
 Precedence is per-call option, then `Root.defaults.durable`, then `true`;
 an explicitly `undefined` call option preserves the root default.
 `durable: false` keeps the sibling-temp replace/rename behavior of replacement
 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. `copyIn`, `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.
+previous file. `move` and streaming `openWritable` do not use this option.
+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.
+
+For `create` and `createJson`, `durable: "file"` requires each file sync to succeed,
+including on `EPERM`; it overrides a disabled Root durability default. Parent
+directory synchronization retains the existing best-effort policy. This also
+applies to streamed creation and is independent of publication strategy. Boolean
+durability options keep their existing behavior, including compatibility paths
+that tolerate `EPERM`. A failed file sync before staged publication prevents
+publication; a failure after publication can leave the complete file present.
 
 POSIX modes without read permission, including `0o000` and `0o200`, succeed:
 final verification uses a descriptor retained by the writer rather than reopening
@@ -135,14 +160,122 @@ claimed exclusively first and content is written afterward, so observers can
 briefly see an empty file; failure cleanup removes a claimed file only when its
 identity is unchanged.
 
+After a successful create-only write, failure to close its owned file handle
+rejects the operation and leaves the complete file present. Ordinary buffered
+creation in the JavaScript fallback preserves an earlier write or verification
+failure if close also fails. Native, atomic, and streamed creation retain their
+existing publication and cleanup diagnostics.
+
 ```ts
 try {
   await fs.create("config/seed.json", initial);
 } catch (err) {
-  if (err instanceof FsSafeError && err.code !== "already-exists") throw err;
+  if (!(err instanceof FsSafeError) || err.code !== "already-exists") throw err;
+}
+```
+
+### Atomic buffered creation
+
+```ts
+await fs.create("config/seed.json", initial, { atomic: true });
+await fs.createJson("config/settings.json", { enabled: true }, { atomic: true });
+await fs.create("config/flushed.json", initial, { atomic: true, durable: "file" });
+```
+
+`atomic: true` keeps the destination absent until all bytes have been written.
+The native backend uses its no-replace rename; the JavaScript fallback hardlinks
+the completed stage and unlinks its temporary name in the same JavaScript turn.
+The fallback requires hardlink support and fails without publishing partial bytes
+when that mechanism is unavailable. Other processes can briefly observe both
+names. Existing and raced entries are preserved, including dangling symlinks;
+ordinary confinement, type, hardlink, and symlink-policy rejections still apply.
+`assertBeforeMutation` retains its live checks through content writes and publication.
+
+Omitted or `false` preserves the existing buffered behavior. The option belongs
+to buffered `create` and `createJson`, not replacement writes or Root defaults.
+Streamed creation has no atomic opt-out. `atomic` changes visibility, not the
+existing `durable` file/directory synchronization policy; it does not turn
+best-effort synchronization into a strict crash-durability guarantee or strengthen
+JavaScript pathname containment.
+
+Wider option objects do not enable create-only `atomic` or `private` behavior on
+`write` or `writeJson`. Buffered Root writes and creates also ignore an extra
+`maxBytes` property; that byte limit belongs to streamed creation and `copyIn`.
+File synchronization follows each method's documented `durable` option.
+
+Atomic and streamed creates settle owned cleanup and close operations before
+returning. Failed or unverifiable cleanup is reported rather than silently
+discarded. Errors after publication and incomplete-settlement errors carry the
+existing `StagedFileFailureDetails` publication/cleanup receipts where the writer
+can establish them; native disposal can retain them inside a `SuppressedError`
+cause. Preserve those details when handling errors: a rejection can follow
+complete publication, and an indeterminate link or native rename must preserve names for
+recovery. A cleanup or close failure also retains the original operation failure.
+No later verification, mode, or synchronization failure authorizes deleting an
+already published complete destination. See [receipt meanings](staged-file.md).
+
+### Streamed creation
+
+Pass an `AsyncIterable<Uint8Array>` to `create()` when bytes come from a database,
+network response, or another incremental producer. Buffers are accepted chunks.
+The writer borrows `Uint8Array` slices without copying their payloads and counts
+their actual byte bounds. It consumes each chunk completely before requesting the next one; it
+does not collect the full input in memory or expose a writable descriptor.
+
+```ts
+async function* snapshotChunks(): AsyncGenerator<Uint8Array> {
+  yield Buffer.from("first stored chunk\n");
+  yield Buffer.from("second stored chunk\n");
 }
+
+await fs.create("restored/config.txt", snapshotChunks(), {
+  mode: 0o600,
+  maxBytes: 8 * 1024 * 1024,
+  durable: false,
+  signal: AbortSignal.timeout(30_000),
+});
 ```
 
+`RootCreateStreamOptions` keeps `mkdir`, `mode`, `durable`,
+`assertBeforeMutation`, `denyMutations`, and `mutationSymlinks` from buffered
+creation and adds `maxBytes` and `signal`. Byte chunks have no encoding option;
+streamed creation uses strict publication identity and does not support
+`renameIdentity: "verify-content-with-lock"`. Existing Root defaults apply,
+including explicit `maxBytes`; with no byte cap at either level, input size is
+unlimited. Zero permits an empty input only. Invalid limits reject before I/O.
+
+Unlike buffered creation's JavaScript fallback, streamed creation stages all
+chunks before publishing the final name. Native mode uses no-replace rename;
+the JavaScript fallback hardlinks the completed stage and removes its temporary
+name in the same JavaScript turn. That fallback requires a filesystem supporting
+hardlinks; other processes may briefly observe both names. An existing or
+concurrently created destination is preserved. Existing-target preflight does
+not consume the input. The final mode and durability policy use the same guarded
+writer as other Root operations.
+
+Cancellation checks run before and after producer pulls, before content writes,
+and before publication. `assertBeforeMutation` also rechecks current application
+authority after producer waits and before each partial write. The operation
+waits for any pending producer pull or filesystem write, then awaits the
+producer's `return()` and cleans only the owned unpublished stage. Pass the same
+signal into a producer that may stall: an arbitrary async iterator cannot be
+forcibly interrupted, so cancellation waits for its pending work and cleanup to
+settle. Do not mutate a yielded chunk until the next pull. Producer errors retain
+their original value when cleanup succeeds.
+
+Streamed creation retains the `signal` and `assertBeforeMutation` callback
+selected when the call starts. Replacing or deleting those options during a
+producer wait does not change the in-flight operation. Abort the original signal
+or update the live authority state checked by the original callback to revoke
+it; the callback continues to receive the original options object as `this`.
+
+An aborted or failed operation can leave created parent directories. If a
+stage's identity or parent cannot be verified during cleanup, the existing
+guarded cleanup preserves it. After publication, later verification or cleanup
+failures preserve the destination; rejection does not prove that no file was
+created. Cancellation arriving after publication does not undo the completed
+file. Application recovery remains caller-owned.
+
 ### `fs.writeJson(rel, value, options?)`
 
 `JSON.stringify(value, replacer, space)` + atomic write. Adds a trailing newline by default.
@@ -185,7 +318,9 @@ await fs.copyIn("inbox/upload.bin", "/tmp/incoming.bin", {
 });
 ```
 
-Options are `{ denyMutations?, maxBytes?, mkdir?, mode?, sourceHardlinks? }`.
+Options are `{ denyMutations?, durable?, maxBytes?, mkdir?, mode?, sourceHardlinks? }`.
+`durable` follows the root default and is `true` when omitted at both levels;
+set it to `false` to skip file and parent-directory syncs for reconstructible data.
 Use `sourceHardlinks: "reject"` to refuse if the source itself is a hardlinked
 alias. There is no encoding option: copying preserves source bytes.
 
@@ -200,16 +335,141 @@ await fs.move("incoming/foo.txt", "archive/foo.txt", { overwrite: true });
 
 Both `from` and `to` are bounded; `..` in either is rejected.
 
+Mutation policy is captured at call start; changes to caller-owned denial arrays
+apply to later moves. For live cancellation or revocation, throw from
+`assertBeforeMutation` immediately before dispatch.
+
+The default no-clobber mode requires the native helper. It admits both parent
+directory descriptors and performs a descriptor-relative no-replace rename, so
+a competitor that creates the target first is preserved and the source remains
+in place. If the helper or safe parent admission is unavailable, the call fails
+with `helper-unavailable`; it never falls back to a check followed by a
+replacing rename. After dispatch it rechecks both parent identities, so a
+post-operation rejection can mean the no-replace rename completed. Directory
+moves continue to require `overwrite: true`.
+
+Both selected canonical endpoints are admitted inside the retained Root after
+native parent admission. With `mutationSymlinks: "reject"`, both full operation
+paths are rechecked after the live mutation-authority callback and before
+dispatch. The Root and retained parents are fenced again after any such callback.
+These checks retain the documented final check-to-syscall race.
+
+For `{ overwrite: true }`, the JavaScript path 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).
 
+Before a nonrecursive JavaScript fallback removal, fs-safe retains exact
+Root-to-parent directory identities, with canonical endpoint checks at Root and
+the immediate parent. It rejects a parent redirected through a symlink or
+junction before `unlink` or `rmdir`, even with `force: true`, and rechecks the
+retained ancestry after the operation settles. The entry may already have been
+removed when that final verification rejects.
+
 ```ts
 await fs.remove("logs/yesterday.log");
 await fs.remove("snapshots/empty-dir"); // ok
 await fs.remove("snapshots/full-dir");  // throws not-empty
 ```
 
+For a tree, opt into bounded recursive removal:
+
+```ts
+await fs.remove("scratch/finished-job", {
+  recursive: true,
+  force: true,
+  maxEntries: 20_000,
+  maxDepth: 32,
+  mutationSymlinks: "reject",
+  signal: AbortSignal.timeout(30_000),
+  assertBeforeMutation: () => assertJobLeaseCurrent(),
+});
+```
+
+| Option | Default / behavior |
+| --- | --- |
+| `recursive` | `false`; opt in to removing non-empty directories. |
+| `force` | `false`; `true` tolerates missing targets and vanished child entries. Other errors still reject. |
+| `order` | `"filesystem"`; `"sorted"` collects and sorts child names lexicographically before descending. Requires `recursive: true`. |
+| `maxEntries` | `100_000` in recursive mode; counts the requested target and every encountered child, including directories and symlinks. |
+| `maxDepth` | `64` in recursive mode; the requested target has depth 0 and each child adds one. An empty directory at the limit can be removed. |
+| `signal` | Stops traversal and new mutations when aborted. Already dispatched work settles and directory handles close before rejection. |
+
+Budgets must be non-negative safe integers or explicit `Infinity`, and require
+`recursive: true`. Omitted budgets retain their finite defaults. An entry or
+depth limit throws `too-large` before processing the over-budget entry.
+
+The default filesystem order streams each directory once, using memory and open
+handles proportional to depth rather than directory width. Sorted order also
+enumerates each directory once, but collects its names before descending and
+deletes directories after their children. It uses JavaScript's default string
+sort, not locale collation. Collected names consume the shared entry budget,
+including sibling names still pending while an earlier directory is traversed.
+With a finite budget, collection overflow rejects before processing that
+directory's children; one extra name distinguishes an exact limit from overflow.
+An `Infinity` entry budget uses a bulk name read while retaining the opened
+directory handle and identity checks. Sorted mode retains collected names, so
+unlimited budgets also permit unlimited name storage.
+
+Sorted traversal preserves lexicographic processing, not the incidental syscall
+timing of a caller that repeatedly rescans parent directories. Each child is
+inspected when visited. Newly added entries can make the final `rmdir` fail with
+`not-empty`; the operation does not retry indefinitely.
+
+Recursive removal never follows a discovered symlink or junction. With an
+omitted `mutationSymlinks` policy it unlinks that entry, preserving the existing
+nonrecursive behavior. Both explicit mutation policies reject discovered links.
+`follow-parents-within-root` permits aliases only in the requested target's
+parents, and still rejects a final link. Root and per-call `denyMutations` policies
+remain additive; a denied descendant prevents removal of the enclosing requested
+tree before any entry is removed.
+
+The operation retains exact identities for the traversal directories and each
+observed target. Swapped or missing ancestors reject even with `force: true`;
+an abort reason or authority refusal carrying `ENOENT` is not treated as absence.
+Authority is rechecked immediately before each direct `unlink` or `rmdir`
+dispatch. Directory handles close before their directories are removed, including
+on Windows. If both traversal and close fail, `SuppressedError` retains both
+failures. Directory-stream filesystem errors use the same removal codes as
+`unlink` and `rmdir`, with the original error in `cause`; caller abort and
+authority refusals retain their original values.
+
+When `force: true` encounters a missing directory during an `opendir` or read,
+it closes any open stream and reaches the ordinary final target check. The
+surviving ancestors and original target identity are checked again; a replacement
+is never accepted as a missing directory. An actually vanished child does not
+prevent processing later siblings.
+
+Filesystem failures normalized by the recursive removal owner and its direct
+symlink rejections carry additional `FsSafeError.details` context:
+
+```ts
+type RemoveFailureDetails = {
+  operation: "remove";
+  phase: "enumerate" | "inspect" | "remove";
+  relativePath: string;
+};
+```
+
+`relativePath` is relative to the requested removal target, using host path
+separators: `""` identifies that target and `"nested/link"` identifies a child
+on POSIX. It does not replace caller spelling with the canonical Root path.
+`enumerate` covers directory stream operations, `inspect` covers initial child
+observations, and `remove` covers final identity checks and unlink/rmdir failures.
+The existing error codes, messages, and causes remain unchanged. Errors that
+already have their own identity, including caller authority and cancellation
+reasons, are propagated without adding or changing their details. Context is
+diagnostic; it is not permission to retry or mutate an entry.
+
+Removal is incremental, not atomic. A later budget, cancellation, identity, or
+filesystem failure does not restore already removed entries. As with existing
+`remove`, this is a guarded JavaScript operation in every native mode: pathname
+checks are best-effort against a hostile concurrent process and do not create
+an atomic check-and-delete syscall. Use OS isolation for that threat model.
+
 ### `fs.mkdir(rel)`
 
 `mkdir -p`. Creates missing parents.
@@ -218,6 +478,19 @@ await fs.remove("snapshots/full-dir");  // throws not-empty
 await fs.mkdir("snapshots/2026/05");
 ```
 
+Pass `{ private: true }` to create missing components with private permissions.
+An existing requested directory must already satisfy that policy; fs-safe does
+not repair it or change existing ancestor permissions. Concurrent creators may
+reuse the winner only after it passes the same checks.
+
+Buffered, streamed, and JSON `create` calls also accept `private: true`.
+New POSIX directories default to `0700` and files to `0600`; conflicting
+group/world or privilege bits are rejected before creation. Restrictive
+owner-only file modes remain available through `mode`. On Windows, creation
+uses protected ACLs rather than interpreting POSIX mode bits as access rules.
+This does not change `create`'s no-overwrite behavior or select its durability
+policy. See [creation](creation.md) for supported backends and owned descriptors.
+
 ### `fs.ensureRoot()`
 
 Treats `""` / `"."` as the root itself. Useful when a generic helper computes a relative directory and might end up at the root.
@@ -245,9 +518,9 @@ try {
 Options are `{ denyMutations?, mkdir?, mode?, writeMode? }`, where `writeMode`
 is `"replace"` (default), `"append"`, or `"update"`. `replace` truncates existing
 files; `update` keeps existing contents. Streaming writes go directly to the
-destination — there is no atomic-rename step. If you need both streaming and
-atomicity, write to a sibling temp yourself and rename when done; the
-[`atomic`](atomic.md) helpers can do this for you.
+destination — there is no atomic-rename step. For exclusive publication of a
+complete stream, use [`create()`](#streamed-creation). For streamed replacement,
+the [`atomic`](atomic.md) helpers provide a staged writer.
 
 On POSIX, existing-target opens use `O_NONBLOCK` as an admission safeguard so
 a no-reader FIFO cannot stall regular-file validation. This does not change
@@ -256,6 +529,13 @@ opens, including for mode `0o200` files; replacement truncation happens only
 after type, identity, and boundary checks pass. Rejected existing paths are
 never cleanup-owned or unlinked.
 
+Identity admission uses bigint descriptor and pathname receipts even though the
+public `stat` field remains a numeric Node `Stats` object. Windows retries an
+unknown device or file index once while retaining known components, then rejects
+persistent ambiguity. If admission of a newly created file fails, cleanup only
+unlinks a pathname that still has the exact created identity; rounded aliases,
+symlinks, and unknown identities are preserved.
+
 ## Write defaults vs per-call options
 
 Set `mkdir: true` once on `root()`; pass text encodings per call when needed:
@@ -305,7 +585,11 @@ for (const file of files) await fs.write(`${stagingDir}/${file.name}`, file.body
 await fs.move(stagingDir, "snapshots/2026-05-05", { overwrite: true });
 ```
 
-For a true commit-or-rollback over a *directory*, use [`replaceDirectoryAtomic`](atomic.md#replacedirectoryatomic).
+For guarded whole-directory publication, use
+[`replaceDirectoryAtomic`](atomic.md#replacedirectoryatomic). Replacing an
+existing target is a two-rename protocol with a temporary target-absence
+interval and conditional no-replace rollback, not a transactional
+commit-or-rollback.
 
 ### Rotate logs
 
@@ -337,6 +621,16 @@ await fs.write("state.json", body); // succeeds on rclone FUSE
 
 **Security note.** `verify-content-with-lock` proves that the bytes observed after rename match the requested write and prevents *cooperating* writers from interleaving. It does **not** prove that the destination still names the temp-file object, retain fd-relative parent pinning, or stop a same-UID process that ignores the advisory lock. Do not use this option on directories writable by untrusted same-UID processes. Strict identity verification remains the default.
 
+Windows `Root.write()` and `Root.writeJson()` honor this policy both as a Root default and as a per-call option. The Windows buffered writer acquires the same Root compatibility lock before creating parents or staging content. It keeps staging writable until publication, then applies the final mode through the retained destination descriptor. When content verification accepts a changed rename identity, that destination remains pinned through file sync, parent sync, and final strict identity checks.
+
+The Windows buffered compatibility path resolves permitted in-root aliases before choosing its lock and binds publication to that effective destination. With the existing lock protocol, effective path components beneath the Root must contain only lower-case ASCII letters, digits, `.`, `_`, or `-`, with no trailing `.`. Unsupported spellings, including missing upper-case or non-ASCII names, fail with `path-alias` before mutation; no filesystem case-sensitivity or Unicode-folding behavior is guessed. This restriction does not apply to strict writes. Opaque Windows pathname identities still use strict verification against the retained original descriptor: they never, by themselves, authorize content-based acceptance of a replacement.
+
+The library's own lock-destination check permits the writer to reuse parent
+admission within that operation. The lock key and destination checks remain
+unchanged, and evidence is revoked when the locked operation finishes. Supplying
+an `assertBeforeMutation` callback retains full parent admission because caller
+code can change the filesystem before dispatch.
+
 Lock recovery is fail-closed. If a process crashes and leaves the root-level `.fs-safe-write-<sha256>.lock`, a later write reports the stale lock instead of deleting it based on a host-local PID. Recover only under external authority that excludes every competing writer; see [File lock](sidecar-lock.md#stale-recovery-guarded-remove-if-unchanged).
 
 ## See also