@openclaw/fs-safe 0.10.0 → 0.12.0

package/docs/root.md

@@ -100,7 +100,9 @@ The read methods also accept an absolute spelling that already resolves inside
 the root. `readAbsolute()` and `reader()` make that intent explicit and accept
 both the configured root spelling and its canonical real path when the Root was
 created through a directory symlink or Windows junction. An absolute path
-outside the root is still rejected.
+outside the root is still rejected. On Windows, alternate casing is accepted
+only when the differently cased Root prefix has the Root's exact directory
+identity; the operation then continues under the trusted Root spelling.
 
 ### Writes
 
@@ -113,13 +115,21 @@ fs.append(rel, data, options?)           // append text/buffer; syncs before clo
 fs.copyIn(rel, sourceAbsPath, options?)  // copy from outside the root, atomically, with size cap
 fs.openWritable(rel, options?)           // FileHandle for streaming writes; supports await using
 fs.move(from, to, options?)              // rename within the root; defaults to no clobber
-fs.remove(rel, options?)                 // unlink file or rmdir empty directory
+fs.remove(rel, options?)                 // unlink file, rmdir, or bounded recursive removal
 fs.mkdir(rel, options?)                  // mkdir -p (creates missing parents)
 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`).
 
+`create` also accepts `AsyncIterable<Uint8Array>` with `RootCreateStreamOptions`:
+the same path, authority, mode, and durability options, plus `maxBytes` and
+`signal`, without `encoding` or `renameIdentity`. It consumes one chunk at a
+time and publishes the completed file exclusively. The byte cap inherits an
+explicit `Root.defaults.maxBytes`; without either cap, consumption is unlimited.
+See [streamed creation](writing.md#streamed-creation) for cancellation,
+cleanup, and filesystem requirements.
+
 `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.
@@ -213,6 +223,18 @@ 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.
 
+`remove` leaves non-empty directories unchanged unless `recursive: true` is
+provided. Recursive removal defaults to streaming entries in filesystem order;
+`order: "sorted"` processes each directory's children lexicographically. The
+`maxEntries` (100,000 by default) and `maxDepth` (64 by default) budgets accept
+explicit `Infinity` when the caller needs unlimited traversal. It never
+follows discovered symlinks; an explicit `mutationSymlinks` policy rejects them,
+while the omitted policy unlinks them. `force: true` ignores missing targets,
+and `signal` stops further work after admitted I/O and resource cleanup settle.
+Removal is not transactional: a budget, cancellation, policy, or identity
+failure can leave a partially removed tree. See [removal](writing.md)
+for the full counting and failure contract.
+
 ### Live mutation authority
 
 All mutation methods accept `assertBeforeMutation?: () => void`. Use it when a
@@ -273,14 +295,22 @@ fs.exists(rel)                   // boolean
 fs.stat(rel)                     // PathStat
 fs.list(rel)                     // string[]
 fs.list(rel, { withFileTypes })  // DirEntry[]
+fs.entries(rel, options?)        // nonrecursive AsyncIterable<DirEntry>, including symlinks
 fs.resolve(rel)                  // absolute path inside the root, after canonicalization
 ```
 
 These do not pin a later operation. They are safe to expose to UIs and decision points; for the actual read or write, use the verb methods so the operation pins identity at the point of use.
 
+`entries()` streams immediate children in filesystem order by default. It
+supports cancellation, a physical-entry limit that throws on overflow, and
+bounded sorted-name collection. It reports child symlinks without following
+them; its `symlinks` option applies only to the selected directory path.
+See [Directory entries](entries.md) for ordering, identity, and partial-result
+semantics.
+
 `resolve()` is the exception to the existing-object rule: because it selects a
 location for later use, it rejects a leading drive-relative spelling. Reads,
-`stat`, `exists`, `list`, `walk`, `remove`, and the source argument of `move`
+`stat`, `exists`, `list`, `entries`, `walk`, `remove`, and the source argument of `move`
 accept an existing POSIX filename such as `c:notes.txt`. For `move`, only the
 new destination name is subject to the portable guard.
 

package/docs/secure-file.md

@@ -21,14 +21,17 @@ The helper:
 - rejects every non-regular preview and, by default, symlink paths
 - opens POSIX paths no-follow and nonblocking before reading, then verifies the opened fd still matches the path and realpath; a FIFO swap cannot block before `timeoutMs` owns the byte read
 - optionally requires the real path to live under one of `trust.trustedDirs`
+- rejects hardlink aliases using descriptor, pathname, and realpath link counts, then rechecks the descriptor after reading before returning bytes
 - rejects hard-to-verify or unsafe permissions unless `permissions.allowInsecure` is set
 - rejects files owned by another POSIX uid
 - enforces `maxBytes` before and after reading
 - closes the handle on success, error, and timeout
 
-On POSIX, unsafe permissions mean group/world writable, and group/world readable unless `permissions.allowReadableByOthers` is true. On Windows, the helper uses the ACL inspection helpers from [`permissions`](permissions.md) and refuses the read if ACLs cannot be verified.
+On POSIX, unsafe permissions mean group/world writable, and group/world readable unless `permissions.allowReadableByOthers` is true. On Windows, the helper queries owner, DACL, and locality from the same open descriptor that supplies the bytes. The native query returns the 32-bit volume serial and 64-bit file-index projection used by Node, which must equal Node's bigint descriptor receipt before its ACL facts are trusted. This avoids JavaScript number rounding but does not represent the full 128-bit file identity available on ReFS. Only the current user, LocalSystem, and built-in Administrators are trusted owner classes.
 
-Descriptor, pathname, and realpath identity checks use lossless bigint stats internally. The returned `stat` remains a normal Node `Stats` object with numeric fields. A zero Windows device or inode is unverified, never a match: the helper re-inspects that identity once using the same descriptor or pathname, then rejects persistent ambiguity with `path-mismatch`. A definite mismatch rejects immediately; retries retain known identity components and still enforce symlink policy.
+Windows secure reads require the matching current optional native package. A missing or stale helper, fd-to-handle conversion failure, denied `READ_CONTROL`, remote handle, incomplete descriptor, or unsupported ACE form rejects with `permission-unverified` before content is read. A malformed or different handle identity rejects with `path-mismatch`. There is no pathname-command fallback for `readSecureFile()`; the standalone reporting APIs in [`permissions`](permissions.md) retain their documented fallbacks. `permissions.allowInsecure` remains the explicit escape hatch and bypasses the ACL query.
+
+Descriptor, pathname, and realpath identity checks use bigint stats internally to avoid JavaScript number rounding. The returned `stat` remains a normal Node `Stats` object with numeric fields. A zero Windows device or inode is unverified, never a match: the helper re-inspects that identity once using the same descriptor or pathname, then rejects persistent ambiguity with `path-mismatch`. A definite mismatch rejects immediately; retries retain known identity components and still enforce symlink policy.
 
 ## Options
 
@@ -61,6 +64,8 @@ type SecureFileReadOptions = {
 
 `permissions.allowInsecure` is a migration escape hatch. Prefer fixing permissions and using [`formatPermissionRemediation`](permissions.md) to show the user what to run. `trust.allowNetworkPath` is off by default because UNC paths are remote authority, not local filesystem input. `inject` is for tests and platform adapters; production callers usually leave it unset.
 
+On an actual Windows process with effective `platform: "win32"`, `inject.env` and `inject.exec` do not replace descriptor inspection. They remain available to simulated Windows checks on non-Windows hosts.
+
 `permissions.allowInsecure` bypasses only permission checks. Neither it nor `inject.platform` changes filesystem identity verification, which always uses the actual process platform. `trust.allowSymlink` permits an alias but still requires its target and realpath to match the opened descriptor.
 
 ## Errors
@@ -73,25 +78,23 @@ type SecureFileReadOptions = {
 | `not-found` | The path could not be stat'd before open. |
 | `not-file` | The opened target is not a regular file. |
 | `symlink` | The path is a symlink and `trust.allowSymlink` is false. |
+| `hardlink` | The descriptor, pathname, or realpath has more than one link. |
 | `path-mismatch` | The path or realpath changed between open and verification, or filesystem identity could not be verified after bounded re-inspection. |
 | `outside-workspace` | `realPath` is outside `trust.trustedDirs`. |
-| `permission-unverified` | Required mode/ACL checks could not be completed. |
+| `permission-unverified` | Required mode/ACL checks could not be completed, including when descriptor-bound Windows inspection is unavailable. |
 | `insecure-permissions` | Mode bits or ACLs grant broader access than allowed. |
 | `not-owned` | POSIX owner uid is not the current process uid. |
 | `too-large` | File size or bytes read exceeded `maxBytes`. |
 | `timeout` | `timeoutMs` elapsed while reading. |
 
-Windows inspection failures remain operational `permission-unverified` errors
-and still refuse the read. Their message includes the underlying reason when
-available. `details` includes `ownerError` for owner-query failures and, when
-command diagnostics are available, `command`, `durationMs`, `timedOut`,
-`exitCode`, `signal`, and `stderr`. Reasons and stderr are control-character
-escaped and limited to 400 characters each (including a truncation marker).
-No stdout or target file contents are copied into these display diagnostics.
-The original inspection exception is retained as `cause`; built-in command
-errors also retain their original execFile exception in the cause chain.
-Treat causes as restricted local diagnostic data. No retries are performed,
-and verification order and rejection conditions are unchanged.
+Windows descriptor-inspection failures are operational `permission-unverified`
+errors and refuse the read. The original native exception is retained as
+`cause`; treat causes as restricted local diagnostic data. No pathname or ACL
+content is copied into the display message. Test adapters that simulate Windows
+on another operating system retain the standalone pathname inspector's
+structured command diagnostics (`ownerError`, `command`, `durationMs`,
+`timedOut`, `exitCode`, `signal`, and bounded escaped `stderr`). Actual Windows
+secure reads do not start those commands. No retries are performed.
 
 ## See also
 

package/docs/security-model.md

@@ -45,7 +45,7 @@ If you need full sandboxing, run the worker under reduced privileges (uid, conta
 
 ### Path traversal and absolute paths
 
-Every path is resolved against the canonicalized real path of the root, then checked with `isPathInside`. Alias resolution walks components before applying a later `..`, so a symlink cannot change what that parent segment means after validation. Parent traversal, an absolute spelling, or any alias whose canonical result is outside the root throws `outside-workspace`; absolute spellings that remain inside the root are accepted.
+Every path is resolved against the canonicalized real path of the root, then checked at that boundary. On Windows, an exact-case structural Root prefix stays on the lexical fast path; a prefix accepted only by case folding must have the Root's exact directory identity and is rebased onto the trusted Root spelling before use. Alias resolution walks components before applying a later `..`, so a symlink cannot change what that parent segment means after validation. Parent traversal, an absolute spelling, or any alias whose canonical result is outside the root throws `outside-workspace`; absolute spellings that remain inside the root are accepted.
 
 ### Symlinks (read side)
 

package/docs/sidecar-lock.md

@@ -2,6 +2,8 @@
 
 `acquireFileLock()` and `withFileLock()` provide a cross-process file lock with retry and process-exit cleanup. The lock is implemented as a sidecar file (e.g. `state.json` ↔ `state.json.lock`) — only one acquirer can create the sidecar with `O_CREAT | O_EXCL` at a time.
 
+JavaScript raw-sidecar creation passes mode `0o600` to that exclusive open. On POSIX, the process umask may further restrict the new file but cannot add group or other access. No pathname `chmod` fallback is used.
+
 ```ts
 import { acquireFileLock } from "@openclaw/fs-safe/file-lock";
 
@@ -61,7 +63,7 @@ function withFileLockSync<T, TPayload>(targetPath: string, options: FileLockSync
 type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
   managerKey?: string;                   // optional in-process manager namespace
   lockPath?: string;                     // override; defaults to `${targetPath}.lock`
-  staleMs?: number;                      // default 30_000
+  staleMs?: number;                      // non-negative or Infinity; default 30_000
   timeoutMs?: number;                    // overall acquire deadline; default unbounded
   retry?: FileLockRetryOptions;
   staleRecovery?: "fail-closed" | "remove-if-unchanged"; // default "fail-closed"
@@ -86,7 +88,7 @@ type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
   lockRoot?: Root;
   retainOnExit?: boolean;               // keep the sidecar across process exit (default false)
   onCompromised?: (info: { lockPath: string; normalizedTargetPath: string }) => void;
-  compromiseCheckIntervalMs?: number;
+  compromiseCheckIntervalMs?: number;    // 0/omitted disables; otherwise 1..2_147_483_647
 };
 
 type FileLockRetryOptions = {
@@ -245,7 +247,14 @@ type FileLockHandle = {
 captured at acquisition. Set `compromiseCheckIntervalMs` together with
 `onCompromised` for a cheap periodic check; the callback fires once after the
 sidecar no longer matches or after a verification I/O failure. This is
-detection, not revocation of work already in progress.
+detection, not revocation of work already in progress. Asynchronous checks are
+serialized, so a slow verification never overlaps the next timer tick.
+
+The compromise-check interval is validated before payload evaluation or
+filesystem acquisition. Omit it or pass `0` to disable monitoring; enabled
+intervals must be finite and between 1 and 2,147,483,647 milliseconds. Values
+outside that range are rejected instead of being clamped by Node.js to an
+unexpectedly tight polling loop.
 
 ## Synchronous locks
 

package/docs/store.md

@@ -72,12 +72,33 @@ Loading serializes consumers for one ID through a sidecar lock, then creates `pr
 
 Queue and failed directory creation fsyncs every newly-created parent edge from the leaf toward the trusted root. Enqueue and migration writes fsync the temp file and parent; claim, acknowledgement, quarantine, delivered-marker cleanup, and retirement transitions fsync every affected directory and propagate real sync failures. A transition may already be visible when a post-mutation sync fails, so retry the same operation to complete its crash-recovery state. Acknowledgement retries resync the queue directory even when both `.processing` and `.delivered` marker names are already absent, before reporting completion or rejecting a newer pending generation; quarantine retries with only failed evidence resync that destination before repairing the vanished queue source.
 
-`writeJsonDurableQueueEntry()` and migrations share strict parent synchronization inside the atomic writer's retained descriptor and per-path serialization lifetime, followed by published-file identity verification. If sync fails after publication, the write rejects without rolling back the published JSON; retrying writes the entry again and must complete its own sync. This is not a rollback, deduplication, or exactly-once guarantee. The generic `replaceFileAtomic({ syncParentDir: true })` option remains best-effort.
+`writeJsonDurableQueueEntry()` and migrations share strict parent synchronization inside the atomic writer's retained descriptor and per-path serialization lifetime, followed by published-file identity verification. If sync fails after publication, the write rejects without rolling back the published JSON; retrying `writeJsonDurableQueueEntry()` writes the entry again and must complete its own sync. Loader retries resync an existing processing claim's parent under the transfer lock before calling `read`, even when a version-dependent callback would no longer request migration. Fresh claims and same-directory source retirement already complete that sync. This is not a rollback, deduplication, or exactly-once guarantee. The generic `replaceFileAtomic({ syncParentDir: true })` option remains best-effort.
 
 Batch loading skips invalid entry names, malformed, oversized, or unreadable entry content, and caller `read` callback failures. Initially unowned pending entries (hardlinks or unverifiable identities), symlinks, non-files, and absent pending entries are also skipped. Claim, transfer-lock, retirement, and migration write/publication/durability failures reject the batch with the original error, even if earlier entries succeeded. Migration in both loaders strictly syncs the parent directory after successful publication. Visible transitions and earlier processing claims remain for retry; a rejected batch does not acknowledge or roll them back.
 
 Failed destinations are create-only. Quarantine publishes the claimed file by hardlink, so the queue and failed directories must share a filesystem with hardlink support. If `failed/<id>.json` already exists, quarantine rejects while preserving both that earlier evidence and the current claimed entry instead of overwriting either file. The `read` callback continues to receive the logical `.json` path even though bytes are read and migrations are written through the claimed path.
 
+Migrations stay bound to the exact processing file opened for that load. The
+read descriptor remains pinned while the callback runs outside the transfer
+lock; after the callback returns, migration reacquires the lock and rechecks the
+claim before publication. If another consumer acknowledged, quarantined, or
+replaced that claim, the migration rejects with `FsSafeError("path-mismatch")`
+and leaves the newer generation or failed evidence intact. A stale migration
+rejects both single and batch loads; ordinary callback failures retain their
+existing single-load rejection and batch-skip behavior.
+
+On Windows, migration releases its read pin once at this publication boundary
+because an open target can block replacement. It rechecks the exact pathname
+identity after the asynchronous close while still holding the transfer lock.
+POSIX retains the read pin through publication. Other readers keep ownership
+of their handles; Windows sharing denials still reject and can be retried after
+those readers close.
+
+Generation arbitration requires consumers to use the transfer lock. As with
+[atomic writes](atomic.md#beforerename), identity checks and pathname replacement
+are separate operations; use a trusted writable parent or OS isolation against
+processes that ignore the lock and mutate queue paths concurrently.
+
 Queue entry reads verify lossless file identities before opening, on the opened
 descriptor, and at the current pathname before reading bytes. POSIX opens are
 nonblocking, so a raced FIFO is rejected rather than stalling a consumer. On Windows, an

package/docs/temp.md

@@ -262,13 +262,17 @@ const result = await writeSiblingTempFile<string>({
 // result.filePath, result.result (returned by writeTemp)
 ```
 
-`writeSiblingTempFile` chooses a random, initially absent sibling name in `dir`
-and calls `writeTemp()`. After the callback succeeds, it validates the produced
+By default, `writeSiblingTempFile` chooses a random, initially absent sibling
+name in `dir` and calls `writeTemp()`. After the callback succeeds, it validates the produced
 regular file before taking ownership: symlinks, directories, other non-regular
 files, hardlinks, and changes between the pre-open pathname, opened descriptor,
 and current pathname are rejected. The callback must finish and close its
 writer before returning. Its return value is preserved as `result`.
 
+Generated temp filenames suffix Windows reserved-device basenames on every
+platform. A completed sibling staging component that still resolves as a
+Windows device alias rejects with `invalid-path` before hooks or producers run.
+
 The helper retains one descriptor through requested mode application, opt-in
 file synchronization, rename, and publication verification. It opens read-only
 unless file synchronization is requested, so closed read-only producer output
@@ -292,12 +296,40 @@ Omitting either option or passing `false` skips that sync, never the identity
 checks. Parent synchronization can be unsupported or fail without rejecting
 the write, so success is not a strict crash-durability receipt.
 
-Cleanup only unlinks an admitted file while the parent, pathname identity, and
-single-link regular-file checks still agree. Observed substitutes are preserved,
+Without producer isolation, cleanup only unlinks an admitted file while the
+parent, pathname identity, and single-link regular-file checks still agree.
+Observed substitutes are preserved,
 including during process-exit cleanup. Operational cleanup failures retain an
 identity-bound exit retry. If the callback throws or admission fails, no file
 has been adopted: even a regular partial file is left for caller-directed
-recovery. The helper never recursively removes a sibling temp.
+recovery. The helper never recursively removes a sibling temp file path.
+
+Set `producerIsolation: "private-directory"` in `WriteSiblingTempFileOptions`
+when the producer can leave partial output before throwing. The callback then
+receives an initially absent file path inside a private child workspace under
+`dir`, on the same filesystem as the final target. fs-safe captures directory
+cleanup ownership before invoking the callback. A callback exception triggers
+owned workspace cleanup, including partial output, subject to directory
+identity checks and I/O failures. The callback must still finish and close its
+writer before returning.
+
+After the callback succeeds, `Root.move` checks source aliases and moves the
+output to the ordinary sibling path before file admission. An escaping symlink
+can fail with `path-alias` at this step. Rejected output still inside the owned
+workspace follows its cleanup contract. Once output moves to the sibling path,
+failures before file adoption retain it for caller-directed recovery, as above.
+File admission, requested modes, sync options, and final rename keep their
+existing contracts; `resolveFinalPath(result)` still names a direct child of `dir`.
+
+The isolated path retains exact bigint identities for both the parent and the
+workspace and rechecks them before moving output to the sibling path. An
+observed replacement is rejected. Cleanup uses the existing
+[`withTempFile` ownership contract](#withtempfile), backed by [`tempFile`](#tempfile):
+moving or replacing the parent or workspace can leave the original or
+replacement paths in place. This option does not promise cleanup through a
+retained directory after a rename, stronger permissions, or additional crash
+durability. Omitting it preserves the direct sibling callback path and
+unadmitted partial-file retention.
 
 On POSIX, admission uses no-follow and nonblocking open flags, so a FIFO swap
 does not block the helper. Windows retains Node's guarded pathname-open behavior
@@ -345,7 +377,7 @@ If `replaceFileAtomic` does what you need, prefer that. Use
 the final destination still needs root-boundary checks.
 Its private workspace uses the same identity-aware directory cleanup as
 `tempFile()`: moving and replacing the workspace preserves the replacement.
-The callback staging component is capped at 255 bytes under NFC and NFD by
+The callback staging component is capped at 255 bytes as written and under NFC and NFD by
 shortening only an overlong embedded destination tail, while preserving an
 extension when possible. Short callback paths and the final target stay
 unchanged. This workspace owns its contents, unlike the unadmitted sibling
@@ -440,6 +472,7 @@ import fs from "node:fs/promises";
 
 const r = await writeSiblingTempFile({
   dir: "/srv/cache",
+  producerIsolation: "private-directory",
   writeTemp: async (tempPath) => {
     const handle = await fs.open(tempPath, "w");
     try {

package/docs/types.md

@@ -45,7 +45,7 @@ type DirEntry = PathStat & {
 };
 ```
 
-Returned by `Root.list(rel, { withFileTypes: true })`. Includes every
+Returned by `Root.list(rel, { withFileTypes: true })` and [`Root.entries()`](entries.md). Includes every
 `PathStat` field plus the entry's `name`.
 
 ## `BasePathOptions`

package/docs/writing.md

@@ -154,6 +154,61 @@ try {
 }
 ```
 
+### 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 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.
+
+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.
@@ -230,6 +285,101 @@ 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.
@@ -265,9 +415,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -50,6 +50,10 @@
       "types": "./dist/copy.d.ts",
       "default": "./dist/copy.js"
     },
+    "./guest": {
+      "types": "./dist/guest.d.ts",
+      "default": "./dist/guest.js"
+    },
     "./config": {
       "types": "./dist/config.d.ts",
       "default": "./dist/config.js"
@@ -137,6 +141,8 @@
     "lint:fs-boundary": "node scripts/check-fs-boundary-primitives.mjs",
     "prepack": "node scripts/prepack-build.mjs",
     "test": "vitest run",
+    "test:bun": "bun node_modules/vitest/vitest.mjs run --config scripts/bun-vitest.config.ts",
+    "test:bun:native": "bun scripts/bun-native-proof.mjs && bun node_modules/vitest/vitest.mjs run --config scripts/bun-native-vitest.config.ts",
     "test:coverage": "vitest run --coverage",
     "test:coverage:collect": "pnpm build && vitest run --coverage --coverage.reporter=json --coverage.thresholds.lines=0 --coverage.thresholds.functions=0 --coverage.thresholds.statements=0 --coverage.thresholds.branches=0",
     "test:coverage:merge": "node scripts/merge-coverage.mjs",
@@ -161,13 +167,13 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@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",
+    "@openclaw/fs-safe-darwin-arm64": "0.12.0",
+    "@openclaw/fs-safe-darwin-x64": "0.12.0",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.12.0",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.12.0",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.12.0",
+    "@openclaw/fs-safe-linux-x64-musl": "0.12.0",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.12.0",
     "jszip": "^3.10.2"
   },
   "devDependencies": {