@openclaw/openshell-sandbox 2026.9.5 → 2026.9.7

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,44 @@ 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"`, `order: "sorted" | "filesystem"`, and an `AbortSignal`. The default budget behavior yields
+"follow-within-root" | "include"`, `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.
+With `symlinkPolicy: "include"`, links retain `kind: "symlink"` and their own
+size. Targets are neither resolved nor visited; dangling and outside-root links
+are included. Filters receive these entries, and links consume the same entry
+budget as other names. A directory replaced by a symlink after observation
+fails with `path-mismatch` before descent, or produces a `directory-error`
+entry when `onDirectoryError` is `"skip-and-report"`.
+The starting directory retains existing Root path resolution; include mode
+controls the entries beneath that directory.
+
+```ts
+for await (const entry of capability.walk("", { symlinkPolicy: "include" })) {
+  if (entry.kind === "symlink") reportLink(entry.relativePath);
+}
+```
+
+Existing skip/follow calls keep their result types without a symlink variant.
+For explicitly annotated include-mode values, use `RootWalkOptions<"include">`
+and `RootWalkEntry<"include">`. `RootWalkSymlinkPolicy` describes all
+three policies when the policy is selected dynamically; the unparameterized
+entry and options types retain their previous shapes. Use
+`RootWalkOptions<RootWalkSymlinkPolicy>` for a dynamically selected policy.
+
+The caller's starting path retains Root home shorthand: `~` and `~/dir` expand
+the home directory when iteration starts and must resolve inside the Root.
+Home-started walks report actual Root-relative paths, such as `home/dir/file`,
+rather than `~/dir/file`. Use `./~/dir` to start at a literal `~` directory.
+An alias within a home-started path is reported under its admitted canonical
+target; ordinary non-home starting aliases retain their caller-supplied spelling.
+
+Entry names remain literal filesystem data, including a directory named `~`
+and its descendants. To reuse an entry path in another Root method without
+home-directory expansion, prefix it with `./`, as in
+`capability.open("./" + entry.relativePath)`.
 
 The default `order: "sorted"` visits each directory's names in lexicographic
 order before descending depth first. It reads and sorts all names in each
@@ -123,7 +191,9 @@ 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:
+`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("", {
@@ -147,10 +217,43 @@ 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
@@ -161,6 +264,9 @@ 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/watch.md

@@ -0,0 +1,251 @@
+# Guarded filesystem observation
+
+`@openclaw/fs-safe/watch` observes literal paths under an admitted `Root`.
+Notifications are advisory invalidations, not a transaction log, stable content,
+or authority to read a reported pathname. Guarded metadata scans through the
+original Root determine what may be published. Use the Root again to read data.
+
+```ts
+import { root } from "@openclaw/fs-safe/root";
+import { watch } from "@openclaw/fs-safe/watch";
+
+const workspace = await root("/trusted/workspace");
+const subscription = watch(workspace, {
+  mode: "auto",
+  scopes: [
+    { path: "config.json", kind: "entry" },
+    { path: "skills", kind: "tree", depth: 8 },
+  ],
+  exclude: entry => entry.kind === "directory" && entry.path.endsWith("node_modules"),
+  onInvalidate(invalidation) {
+    // Schedule application-owned settling/reload work; this callback is synchronous.
+    console.log(invalidation.reason, invalidation.changes);
+  },
+});
+await subscription.ready;
+await subscription.setScopes([{ path: "skills", kind: "tree" }]);
+await subscription.reconcile();
+await subscription.close();
+```
+
+## Contract
+
+The subpath exports `watch` and the types `WatchScope`, `WatchEntry`,
+`WatchChange`, `WatchInvalidation`, `WatchFailure`, `WatchHealth`, `WatchOptions`,
+and `WatchSubscription`.
+
+An `entry` scope observes only that entry, including its identity and metadata.
+A `tree` also observes descendants to its depth (default 32, maximum 128).
+Depth zero observes only the entry. The empty string and `.` select the Root;
+trailing separators are accepted and normalized after validation. Scopes are
+literal names, never globs or home expansion. Absolute paths, traversal, NULs,
+and platform namespace aliases reject. Windows scopes also reject reserved
+device components and trailing dots/spaces that Win32 would silently alias. Filesystem identity determines ordinary
+case/Unicode aliases; names are not compared by lowercasing.
+
+Symlinks are observed as entries and never followed. A symbolic parent fails
+admission: separately admit a caller-trusted link target if needed. Missing
+entries and ordinary blocking files can become directories in later scans.
+Replacing, renaming, or losing the admitted Root fails observation; it never
+silently adopts a new Root. Directory entry scopes ignore child-only mtime/size
+changes, but include permission-mode changes to the directory itself.
+
+Each invalidation has `reason: "event" | "reconcile" | "overflow"` and optional
+bounded `changes: { path, type: "content" | "structural" }[]`. Missing detail
+means invalidate **every configured scope**. Initial admission and every
+successful `setScopes` publish one undetailed `reconcile` invalidation. A rename
+or identity replacement is structural; metadata changes to the same ordinary
+file may be content changes. Neither means the file is settled or readable.
+An admitted native hint can invalidate an entry even when its before/after scan
+metadata is identical: the path may have changed and been restored between scans
+(ABA), or content may have changed without a distinguishable metadata change.
+Structural hints remain conservative in that case.
+This does not promise delivery for a differently spelled alias that appears and
+disappears entirely between scans: without an observed identity, it cannot be
+admitted as the selected path. Observation is not a complete transient history.
+Raw event names remain private: detail comes from guarded scans, prior guarded
+snapshots, or explicitly configured targets. Unclassifiable hints inside selected,
+non-excluded territory lose detail. Hints for excluded or unselected paths are
+ignored. Exclusion callbacks are synchronous; excluded directories are recorded
+without descent. Bounded exclusion records recognize late deletion hints.
+Genuine backend event loss and detail-budget exhaustion still invalidate every
+scope, including when an excluded subtree caused the underlying event pressure.
+
+## Transport and mode
+
+| Platform/runtime | `auto` | Event transport / limitation |
+| --- | --- | --- |
+| Node.js on Linux with addon | `events` | One shared Rust thread and inotify instance; a nonrecursive watch per distinct directory inode. |
+| Node.js on macOS with addon | `events` | One FSEvents stream per subscription on a shared serial dispatch queue. Pathname activity after a swap remains advisory. |
+| Node.js on Windows with addon | `events` | One recursive ReadDirectoryChangesW Root handle per subscription on the shared IOCP hub; the open handle prevents ordinary renames of the Root's ancestors. |
+| Bun / other unsupported runtimes | `poll` | TSFN lifetime and shutdown have not been qualified; `events` rejects. |
+| Missing/disabled addon | `poll` | `events` rejects with `FsSafeError("helper-unavailable")`. |
+
+The shared hub sleeps until a filesystem event, command, or callback acknowledgement:
+Linux blocks on inotify plus eventfd, Windows on IOCP, and macOS on its command
+channel (FSEvents wakes it from the serial dispatch queue). There is no native
+polling timer; the independent JS reconciliation interval remains authoritative.
+
+`mode` is required. `poll` never starts or loads the watch hub; guarded scans
+may still use the existing addon. Existing `FS_SAFE_NATIVE_MODE=off` and
+`require` policies apply: `require` plus an unavailable event backend rejects
+`auto` too. Health reports the selected `events` or `poll` mode and failures
+from selection have `operation: "watch"`.
+
+Linux installs each watch **before** enumerating children. It opens directories
+beneath the Root using the shared guarded native open (openat2, or its checked
+openat fallback), checks exact identities, verifies the procfs namespace, and
+registers through `/proc/self/fd/N/.`. The final `/.` makes `IN_DONT_FOLLOW` apply
+to the directory instead of rejecting the procfs magic symlink. The descriptor
+closes immediately: inotify retains the inode reference. Reconciliation replaces
+registrations when the directory inventory changes. Queue overflow invalidates
+all owners; exhausted watch capacity reports `failure.code: "watch-limit"`.
+Nonblocking TSFN batches cannot block the hub on JavaScript, and per-owner
+pending detail and queued batches are bounded. The last removal stops and joins
+the native thread. No Worker threads, eval programs, or JS `fs.watch` are used.
+
+macOS uses FileEvents, NoDefer and WatchRoot with a 30 ms FSEvents latency.
+After guarded admission, streams use selected tree anchors and entry parents,
+falling back to the nearest admitted ancestor for missing paths. Nested anchors
+are deduplicated, with at most 128 paths. The eight shallowest non-overlapping
+excluded directories are also passed to `FSEventStreamSetExclusionPaths`.
+When the stream paths change, the old stream is stopped, invalidated and released
+on its dispatch queue, then its replacement starts before another guarded pass
+covers the handover. Native exclusions reduce traffic but cannot eliminate real
+FSEvents drops, including during recursive deletion.
+Absolute hints are reduced lexically against the admitted canonical Root;
+outside paths never become detail. Dropped/wrapped streams, RootChanged and
+Unmount trigger guarded reconciliation. Pathname hints can reflect activity
+after a swap, but the Root is never replaced and names require guarded admission.
+Removal synchronously stops, invalidates and releases the stream on its queue.
+
+Windows opens one identity-checked Root handle per subscription with
+READ/WRITE/DELETE sharing, backup semantics and overlapped I/O. Each handle
+observes the entire subtree; guarded scans filter hints to configured scopes.
+No descendant watch handles are retained, so directories inside the Root can be
+renamed while watching, including directories containing selected scopes.
+Completed buffers are copied and the
+read re-armed before names are examined. Zero-byte / enumeration-loss completions
+invalidate every scope. Buffers are 1 MiB on confirmed local volumes, and 64 KiB
+on network/UNC or unclassified volumes. Cancellation waits for IOCP completion before closing
+the handle or freeing its buffer; there are no detached retirement waits.
+
+On Windows, an open file handle—including fs-safe's pinned reads, editors, and
+antivirus—blocks renaming that file's ancestor directories, even with delete
+sharing. The watch backend retains only the Root's `ReadDirectoryChangesW` handle,
+which permits renames beneath the Root. Callers renaming directories concurrently
+with reads should use bounded retries, as Windows tools do.
+
+Windows prevents ordinary renames of the Root's own ancestors while its directory
+handle is open, even with DELETE sharing. Use `mode: "poll"` when callers must not
+retain that handle. Renaming or replacing the Root still fails guarded observation;
+the subscription never adopts another location. Subscriptions have independent
+handles and delivery queues, and closing one does not retire another's observation.
+
+## Budgets and lifecycle
+
+| Option | Default / bound |
+| --- | --- |
+| `scopes` | At most 128 literal scopes |
+| `persistent` | `true`; `false` lets Node exit with the subscription still open |
+| `intervalMs` | 30000 with events; 1000 with poll; minimum 20 ms |
+| `pollIntervalMs` | Optional polling override; minimum 20 ms, maximum 2147483647 ms (same as `intervalMs`) |
+| `maxDirectories` | 4096 observed directories, including scope ancestors |
+| `maxEntries` | 100000 examined entries per pass, including excluded entries |
+| `maxPendingPaths` | 256; maximum 4096 |
+| Reconciliation | One active pass and one coalesced pending pass; no convergence/pass budget |
+
+Periodic guarded reconciliation runs without needing an event. It catches
+missed events and works on filesystems where native hints are incomplete.
+When polling is selected, the interval is `pollIntervalMs`, then `intervalMs`,
+then 1000 ms, in that order. This applies to explicit `mode: "poll"`, `auto`
+selecting polling, and `auto` falling back after an unsupported event backend.
+`pollIntervalMs` does not change the events reconciliation interval, which
+remains `intervalMs` or 30000 ms. For example, `mode: "auto", pollIntervalMs: 25`
+uses 25 ms polling when needed and retains the 30-second events reconciliation.
+Scans are metadata comparisons: content changes preserving all compared
+metadata may be missed in polling mode. No mode promises transactional
+snapshots, complete history, or hard real-time delivery.
+
+`ready` resolves after the first complete guarded scan establishes the baseline,
+even while writes continue. Events mode installs each directory registration
+before listing it (FSEvents and recursive RDCW anchors cover the crawl). A changed
+registration/listing identity is retried up to three times per directory; further
+churn invalidates that subtree. Poll mode starts with its first scan and detects
+changes during the crawl on the next comparison. Neither mode waits for two
+agreeing scans.
+`ready` and `reconcile()` do not drain the operating system's event queue.
+For example, FSEvents can deliver coalesced setup creation activity after `ready`,
+even with its stream starting at the current event ID. Consumers must tolerate
+these advisory invalidations; tests measuring a quiet interval should first
+observe a selected sentinel edit and drain its trailing events.
+
+Each later pass compares with the previous snapshot, publishes bounded differences,
+and adopts its result as the next snapshot. Vanishing entries, kind changes, and
+transient descendant scan errors produce structural invalidations, preserving the
+Root identity checks. Events during a pass coalesce into one pending pass and
+retain bounded detail regardless of how long the scan takes. The 25 ms hint
+coalescing window does not impose a scan deadline. A full native callback queue
+retains its bounded pending batch for retry. Genuine backend loss, exhausted
+detail capacity, or an unclassifiable selected hint emits `overflow` without
+detail. Sustained writes cannot exhaust a pass budget or disable observation.
+
+`reconcile()` resolves after a complete pass that **started after the call**. Calls
+waiting for the same future pass coalesce; an earlier in-flight pass cannot satisfy
+a new call. It rejects only when observation becomes unavailable or is closed.
+`setScopes` fences the old generation immediately and resolves after the new
+baseline scan; superseded scope calls reject `AbortError`.
+By default, an open subscription keeps the Node event loop alive, matching
+`fs.watch`. Set `persistent: false` for caches used by one-shot commands:
+the subscription's timers and native delivery handle do not keep Node alive,
+including during startup or reconciliation. Invalidations still arrive while
+other work keeps the process alive. Persistent and non-persistent subscriptions
+have independent lifetimes; closing the last persistent one lets Node exit.
+Native environment cleanup retires any remaining event registrations and joins
+the hub at exit. `signal` triggers close;
+await `close()` or `[Symbol.asyncDispose]()` to join owned work.
+
+`health()` returns `starting`, `ready`, `reconciling`, `unavailable`, or `closed`,
+the actual mode, observed `directories`, and optional `{ operation, code, error }`
+failure. A running reconciliation reports `reconciling`, then returns to `ready`.
+Observation becomes `unavailable` on loss of Root authority (removed, replaced,
+or inaccessible), fatal native backend/registration failures such as `watch-limit`,
+deterministic size limits (`too-large`, operation `scan`), or callback contract
+violations. Invalid scope admission, including symbolic parents, still rejects;
+it never grants authority through a link. Transient descendant churn does not
+make an admitted subscription unavailable. Callbacks may synchronously retire
+the owner. Returning a thenable or a synchronous or asynchronous generator object
+from `onInvalidate`, `onHealth`, or `exclude` rejects observation without advancing
+generators. Application async
+work remains application-owned and is not joined by the subscription.
+
+`close()` is terminal, idempotent, and joined. Observation failures remain in
+health but do not make successful retirement reject. Retirement failures do
+reject, with a `SuppressedError` retaining an earlier observation failure when
+both exist. No new generation or callback can be admitted after close.
+
+The stress harness also provides `node scripts/watch-stress.mjs --scenario soak-short`,
+a two-minute lifecycle and collected-memory smoke. It is separate from the
+full one-hour `soak` scenario and its stronger memory-growth qualification.
+
+## Seeded consumer-cache stress test
+
+After building the package and host binding, run the model against real temporary
+Roots in both modes:
+
+```sh
+node scripts/watch-stress/model-runner.mjs --seeds 2000 --mode both --output watch-model-results.json
+```
+
+Each seed generates file and directory edits, renames, replacements, deep trees,
+symlink retargets, bursts, scope changes, and subscription retirement. A consumer
+queues refreshes only from `onInvalidate`; checkpoints drain those requests after
+quiescence and `reconcile()`, then compare its cache with a guarded Root walk and
+an independent mutation model. Native hints never authorize consumer reads.
+
+`--seed`, `--steps`, `--settle` (milliseconds), and `--concurrency` control a run.
+Failures are shrunk by fast-check and saved beside the report as `.<mode>-<seed>.failure.json`;
+replay one with `--replay <failure.json>`. Event mode requires a working native
+binding and never silently falls back to polling. The small
+`test/watch-model.test.ts` corpus runs in ordinary CI; native-event cases also run
+when `FS_SAFE_TEST_WATCH_EVENTS=1`. Keep fixtures on normal `os.tmpdir()` storage.

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.
@@ -45,8 +45,14 @@ 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.
 
@@ -113,6 +119,14 @@ 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
 the published file. The requested mode is not relaxed for verification.
@@ -146,19 +160,71 @@ 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.
+The JavaScript fallback checks the destination again immediately before attempting
+publication. A collision observed there leaves publication unattempted and cleans
+the owned stage. A later collision or other error from the link call remains
+indeterminate, including `EEXIST`; the error code alone does not prove that the
+filesystem left both names unchanged.
+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 consumes each chunk completely before requesting the next one; it
+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
@@ -202,6 +268,12 @@ 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
@@ -234,6 +306,12 @@ type RootWriteJsonOptions = RootWriteOptions & {
 
 Open in append mode, write, sync the file handle, and close. Honors `mkdir` for the parent directory and syncs the parent directory when the append creates the file. `durable: false` skips both syncs. Pass `prependNewlineIfNeeded: true` to insert a `\n` if the file does not already end in one.
 
+`mode` selects the creation mode, defaulting to `0o600` when neither the call nor
+the Root supplies it. On POSIX, the process umask can further restrict that mode;
+for example, `mode: 0o640` with umask `0o077` creates a `0o600` file. Existing
+files are not chmodded, even when an explicit `mode` is supplied. Empty appends
+use the same creation rules.
+
 ```ts
 await fs.append("logs/today.log", `[${ts}] ${line}\n`);
 await fs.append("notes/scratch.md", "* new bullet", { prependNewlineIfNeeded: true });
@@ -268,6 +346,10 @@ 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
@@ -277,6 +359,11 @@ 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`.
 
+Linux without `openat2` uses the [guarded native parent walk](native.md#linux-without-openat2).
+The move still uses `renameat2(RENAME_NOREPLACE)` and preserves collisions;
+parent resolution reports the documented `best-effort` containment class.
+Disabling the addon still makes no-clobber moves unavailable.
+
 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
@@ -407,6 +494,19 @@ an atomic check-and-delete syscall. Use OS isolation for that threat model.
 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.
@@ -438,6 +538,11 @@ 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.
 
+For all three write modes, `mode` only selects new-file creation permissions,
+defaulting to `0o600` when neither the call nor the Root supplies it. POSIX
+permissions remain subject to the process umask; existing files are not chmodded.
+The returned numeric `stat` records the admitted descriptor before caller writes.
+
 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
 ordinary regular-file write semantics. `replace` and `update` remain write-only
@@ -501,7 +606,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
 
@@ -533,10 +642,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, placeholders, or 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.
+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