@openclaw/fs-safe 0.20.0 → 0.21.1

package/docs/contributing.md

@@ -94,11 +94,11 @@ GLIBC versions. To inspect an existing binding, use
 `pnpm native:build` remains a host-toolchain development build; it does not
 establish the GNU release ABI floor.
 
-On Linux x64 with Docker, run `pnpm build`, copy the GNU x64 artifact from
+On Linux x64 or arm64 with Docker, run `pnpm build`, copy the matching GNU artifact from
 `artifacts/` to `native/`, run `node scripts/stage-host-native.mjs`, then run
 `bash scripts/test-linux-glibc-floor.sh`. CI uses this command to load the actual
 artifact and run native security and no-replace move tests in Rocky Linux 8
-(glibc 2.28). GNU arm64 is cross-built and symbol-checked in the same CI matrix.
+(glibc 2.28). Both GNU architectures execute this load test on matching runners.
 
 ## Test
 
@@ -167,6 +167,52 @@ pnpm check
 This runs the filesystem boundary checks, build, tests, and package
 tarball/import validation.
 
+The native watch lane requires events on Linux, macOS, and Windows and reports
+actual edit latency. Run `FS_SAFE_TEST_SERIAL=1 pnpm check` to isolate local timing
+checks from the other filesystem stress suites. Watch fixtures use normal OS
+temporary storage; session scratch trees may suppress macOS filesystem events.
+
+### Optional Linux Testbox
+
+The manual `testbox-validation.yml` workflow prepares a 16-vCPU Ubuntu 24.04
+Blacksmith Testbox with Node 24.21.0, pnpm 12.4.2, dependencies, the Rust WASM
+target, and the pinned portable archive compiler. It leaves library builds and
+validation commands to the caller and does not replace required CI checks.
+
+Use an authenticated Blacksmith CLI with access to the repository and its
+Blacksmith organization. From a full repository checkout, warm one session
+through Crabbox:
+
+```sh
+CRABBOX_BLACKSMITH_IDLE_TIMEOUT=240m crabbox warmup --provider blacksmith-testbox \
+  --blacksmith-org openclaw \
+  --blacksmith-workflow .github/workflows/testbox-validation.yml \
+  --blacksmith-job validate --blacksmith-ref main \
+  --idle-timeout 240m --timing-json
+```
+
+Use a branch or tag containing the workflow for `--blacksmith-ref`; GitHub must
+first have registered the workflow on the default branch. The job has a fixed
+240-minute limit. Keep the idle timeout at that limit (240 minutes in the native
+Blacksmith CLI) because the pinned Testbox action can miss active SSH sessions
+behind a forwarded port. Bound commands by the remaining job time and leave time
+to collect results and stop before the deadline.
+
+Use the returned `tbx_...` ID for subsequent commands. The `fs-safe-testbox`
+wrapper restores the prepared tool paths and WASM compiler settings in the SSH
+shell. For example:
+
+```sh
+crabbox run --provider blacksmith-testbox --id <tbx_id> --timing-json -- \
+  fs-safe-testbox pnpm check
+crabbox stop --provider blacksmith-testbox <tbx_id>
+```
+
+Stop the session when finished and verify its terminal status. Blacksmith owns
+checkout synchronization; record the tested source revision or diff, Testbox ID,
+and Actions run. This backend is Linux-only and does not accept Crabbox's direct
+SSH `--script` or `--download` flags. The workflow provides no application secrets.
+
 ### Method benchmarks
 
 `pnpm benchmark:methods` measures the callable library surface against synthetic
@@ -231,10 +277,32 @@ require the pnpm lifecycle CLI path; JavaScript CLIs run through Node and standa
 direct `node` invocation without lifecycle metadata is unsupported. Archive
 codecs and their dependencies are packed from the installed dependency graph.
 
-PR CI builds and executes four host targets: Linux x64 glibc, Linux x64 musl
-(Alpine), macOS arm64, and Windows x64. The root-only smoke runs on each. The
-seven-target source build matrix runs on release tags; packaging all seven is
-not execution proof for every architecture. The smoke writes manager versions,
+PR CI builds and executes all seven shipped bindings. The existing check names
+stay stable; extra runner/runtime combinations add checks without changing the
+repository ruleset. Native lanes run Node 24; the GNU host lanes also exercise
+Bun 1.4.2 (as do macOS and Windows).
+
+| Lane | Runner | Architecture / libc | Runtime |
+| --- | --- | --- | --- |
+| JavaScript check | `ubuntu-latest` | x64 / glibc | Node 22, 24, 26 |
+| JavaScript check | `macos-15` | arm64 | Node 22, 24, 26 |
+| JavaScript check | `fs-safe-windows-16core` (`windows-latest`) | x64 | Node 22, 24, 26 |
+| Native check | `ubuntu-latest` | x64 / glibc | Node 24, Bun 1.4.2 |
+| Native check (forced no-openat2) | `ubuntu-latest` | x64 / glibc | Node 24 |
+| Native check | `ubuntu-24.04-arm` | arm64 / glibc | Node 24, Bun 1.4.2 |
+| Native check | `macos-15` | arm64 | Node 24, Bun 1.4.2 |
+| Native check | `macos-15-intel` | x64 | Node 24, Bun 1.4.2 |
+| Native check | `fs-safe-windows-16core` (`windows-latest`) | x64 | Node 24, Bun 1.4.2 |
+| Native check | `windows-2022` (standard hosted) | x64 | Node 24, Bun 1.4.2 |
+| Native check (Alpine 3.24) | `ubuntu-latest` | x64 / musl | Node 24 |
+| Native check (Alpine 3.24) | `ubuntu-24.04-arm` | arm64 / musl | Node 24 |
+| GNU glibc 2.28 build + Rocky Linux 8 load | `ubuntu-latest` | x64 / glibc | Node 24 |
+| GNU glibc 2.28 build + Rocky Linux 8 load | `ubuntu-24.04-arm` | arm64 / glibc | Node 24 |
+| Bundled package smoke | `ubuntu-latest`, `macos-15`, `fs-safe-windows-16core` | host | Node 22, 24 |
+| Coverage | `ubuntu-latest`, `macos-15`, `fs-safe-windows-16core` | host | Node 22 |
+
+Both musl lanes also run root-only package smoke with the real host binding.
+The seven-target source build matrix still runs on release tags. The smoke writes manager versions,
 cases, and synthetic-fixture scope to `release-artifacts/consumer-proof.json`.
 
 ## Docs

package/docs/durability.md

@@ -436,3 +436,10 @@ owning product boundary.
 - [Migrating to 0.5](migrating-to-0.5.md) — choosing a publication policy during upgrade.
 - [Native architecture](native.md) — clone/copy/hash mechanisms and fallback guarantees.
 - [Errors](errors.md) — typed operational failure handling.
+
+## Existing Windows file retirement
+
+[`retainFileInDirectory`](retained-file.md) describes identity-bound native
+disposition and resource settlement separately from persistence. Its result is
+always `persistence: "not-proven"`; neither accepted disposition nor observed
+namespace absence is a directory/volume barrier or an application commit.

package/docs/index.md

@@ -65,6 +65,7 @@ await fs.remove("notes/archive/today.txt");
 | [Private file-store mode](private-file-store.md) | `fileStore({ private: true })` for private JSON/text state at 0600 under 0700 dirs. |
 | [`tempWorkspace`](temp.md) | 0700 scratch dir with auto-cleanup. |
 | [`readSecureFile`](secure-file.md) | Absolute file reads with fd pinning, permissions, owner, size, and timeout checks. |
+| [`watch`](watch.md) | Guarded filesystem observation with advisory native hints and polling. |
 | [`walkDirectory` / `Root.walk`](walk.md) | Standalone inventories plus root-bounded pruning, budgets, and partial-error reporting. |
 | [`Root.entries`](entries.md) | Guarded nonrecursive entries, bounded name collection, and caller-owned symlink validation. |
 | [`extractArchive`](archive.md) | Policy-driven ZIP/TAR extraction with clamp/filter, metadata/path-depth, link, count, and byte limits. |

package/docs/install.md

@@ -130,6 +130,8 @@ features, including strict owned-tree temp cleanup, retained-directory staging,
 and atomic `rename-noreplace` (including the default no-clobber `Root.move()`),
 remain unavailable. Operations without a safe fallback fail with `helper-unavailable`
 when the matching package is absent, incompatible, or disabled.
+No-clobber `Root.move()` preserves a native loader failure in the error's
+`cause`, including the original missing-library or incompatible-glibc diagnostic.
 
 Upgrading an existing 0.5 consumer? Follow [Migrating to 0.6](migrating-to-0.6.md)
 before deploying with native mode `require` or native-only features.

package/docs/native-helper.md

@@ -182,3 +182,12 @@ consumer performs its 0.5 upgrade.
 - [Durability](durability.md)
 - [Migrating to 0.5](migrating-to-0.5.md)
 - [Migrating to 0.6](migrating-to-0.6.md)
+
+### Retained existing Windows file
+
+The maintained Windows helper supports the public
+[`retainFileInDirectory`](retained-file.md) lifecycle on fixed local NTFS.
+Private native handles, exact identity/generation checks, writable-section
+admission and explicit close results stay behind that public API. Older helpers
+without this capability are unsupported; there is no pathname deletion fallback.
+No Windows namespace persistence barrier is provided.

package/docs/native.md

@@ -96,12 +96,30 @@ operation is still a permission error and never triggers a retry. Install
 syscall filters before the first native operation; a later `ENOSYS` fails with
 `ENOTSUP`, rather than changing the cached mechanism during a call.
 
-The fallback opens each directory relative to a retained descriptor with
-`O_PATH | O_DIRECTORY | O_NOFOLLOW`, compares exact device/inode/type identities,
-and rechecks the retained parent chain before and after the final no-follow
-open. It rejects all symlink components, including procfs magic links, even
-when the low-level caller requests symlink following. Public Root policy and
-canonical-path admission, hardlink rejection, pinned-file checks, and mutation
+The fallback inspects components with `O_PATH | O_NOFOLLOW`, follows relative
+symlink targets using a stack of retained directory descriptors, and rejects
+absolute targets or `..` past the retained root with `EXDEV`. It permits at most
+40 link expansions (`ELOOP` beyond that limit). Final `O_NOFOLLOW` and exclusive
+creation retain their syscall semantics, including opening the link itself with
+`O_PATH | O_NOFOLLOW` and creating through a dangling in-root relative link.
+Exact device/inode/type identities are checked before and after the final
+no-follow open; followed links also retain their descriptors and have their
+named identities and target strings rechecked. Detected replacements fail with
+`EXDEV`, including changes to directories left behind by a link's `..` target.
+
+The fallback also honors `nosymfollow` mount restrictions on retained links.
+Two conservative restrictions remain: the fallback refuses to follow **any
+procfs symlink** with `ELOOP`, including ordinary links such as `/proc/mounts`.
+Userspace metadata cannot distinguish these from procfs magic links, which
+`RESOLVE_NO_MAGICLINKS` must never follow. Opening a final link itself with
+`O_PATH | O_NOFOLLOW` remains allowed. In a sticky, world-writable directory,
+the fallback refuses all symlink following with `EACCES`, even when the calling
+thread or directory owner owns the link, or `fs.protected_symlinks=0`. This
+preserves Linux's protected-symlink restriction without assuming the thread's
+filesystem UID or treating equal mapped `stat` UIDs as proof of equal kernel
+owners (distinct unmapped owners can both appear as the overflow UID).
+
+Public Root policy and canonical-path admission, hardlink rejection, pinned-file checks, and mutation
 identity fences remain in place. `openBeneath()` reports `best-effort`: these
 identity samples detect replacements but cannot make a multi-component walk
 atomic against a hostile process renaming directories between samples. This

package/docs/public-api.md

@@ -79,6 +79,16 @@ missing relative suffixes beneath an existing directory using bounded temporary
 directory probes. The caller owns Unicode-pair policy, caching, and the fallback
 for `undefined`. See [path suffix alias probing](path-suffix-aliases.md).
 
+`retainSymlinkInDirectory` holds an explicitly identified POSIX symlink through
+exact-slot no-replace publication; its receipts use the `StagedSymlink*` and
+`PublishedSymlinkReceipt` types. See [staged symlinks](staged-symlink.md).
+
+`retainFileInDirectory` retains an existing Windows NTFS file through a native
+handle for explicit identity-bound retirement. It is described by
+`RetainFileInDirectoryOptions`, `RetainedFile`, `RetainedFileAdmission`,
+`RetainedFileExpected`, `RetainedFileIssue`, `RetainedFileReceipt`, and
+`RetainedFileResult`. See [retained Windows files](retained-file.md).
+
 ## Guest source
 
 `@openclaw/fs-safe/guest` exports `GUEST_FILESYSTEM_PYTHON`,
@@ -132,8 +142,11 @@ parent/workspace descriptors; see the
 Atomic helper option and receipt types include
 `MovePathWithCopyFallbackOptions`, `ReplaceDirectoryAtomicOptions`,
 `ReplaceFileAtomicSyncOptions`, `ReplaceFileAtomicResult`,
-`ReplaceFileAtomicRestoreCleanup`, `ReplaceFileCopyFallbackRestorePolicy`, and
-`ReplaceFileDestinationHardlinkPolicy`.
+`ReplaceFileAtomicRestoreCleanup`, `ReplaceFileCopyFallbackRestorePolicy`,
+`ReplaceFileDestinationHardlinkPolicy`, and `ReplaceFileAtomicDestinationState`.
+The `assertBeforeMutation` option rechecks caller authority before new effects,
+and `onDestinationState` reports retained destination identities as
+`ReplaceFileAtomicDestinationState` values; see [atomic writes](atomic.md).
 
 The durability surface also exports the synchronous strict
 `syncDirectorySync`, plus `DirectoryReceipt`, `DurableDirectoryReceipt`,
@@ -160,6 +173,14 @@ Archive option and policy types are `ExtractArchiveOptions`,
 used by extractors. `resolvePackedRootDir` finds the single packed root when an
 archive layout permits it; neither helper weakens entry validation.
 
+## `watch`
+
+`@openclaw/fs-safe/watch` exports `watch()` plus `WatchScope`, `WatchEntry`,
+`WatchChange`, `WatchInvalidation`, `WatchFailure`, `WatchHealth`,
+`WatchOptions`, and `WatchSubscription`. Invalidations are advisory; guarded
+scans stay authoritative. See [filesystem observation](watch.md) for modes,
+budgets, `persistent`, and lifecycle.
+
 ## Keeping this list honest
 
 Every runtime and type name in `test/public-api.json` must appear somewhere in

package/docs/retained-file.md

@@ -0,0 +1,115 @@
+---
+title: Retained Windows files
+description: "Explicit identity-bound retirement of an existing file; resource settlement is not persistence."
+---
+
+# Retain an existing Windows file
+
+`retainFileInDirectory` from `@openclaw/fs-safe/advanced` retains **one existing
+regular direct child**, without creating or deleting anything at admission.
+It requires the matching native package. There is no pathname-unlink fallback.
+The initial implementation supports fixed local NTFS drives only; other systems
+return `unsupported`.
+
+```ts
+import { retainFileInDirectory } from "@openclaw/fs-safe/advanced";
+
+const admission = retainFileInDirectory({
+  directory: producer.directory, // canonical C:\... spelling
+  parent: producer.parentIdentity, // exact bigint dev/ino
+  basename: producer.basename,
+  expected: producer.expected, // bigint dev/ino/size/mtimeNs/ctimeNs and SHA-256
+  assertBeforeMutation: () => producer.assertCurrentExclusiveAuthority(),
+});
+if (admission.status === "retained") {
+  using file = admission.file;
+  const outcome = file.remove(); // explicit; using alone does NOT delete
+  // outcome.persistence is always "not-proven".
+  producer.recordRetirementObservation(outcome);
+}
+```
+
+The producer must capture its expected identity, generation and bytes during its
+own creation/ownership protocol. Reading an arbitrary current pathname immediately
+before admission does **not** authenticate the producer. `Number` identities,
+zero/unknown identities, negative/overflowing identities, and malformed digests
+are rejected. A full opaque native volume/file ID is included in the receipt;
+no native handle or numeric descriptor is exposed. Receipts are immutable facts,
+not transferable authority.
+
+## Public types
+
+- `RetainFileInDirectoryOptions`: immutable admission inputs and synchronous authority.
+- `RetainedFileExpected`: exact producer identity, write generation and expected digest.
+- `RetainedFileAdmission`: a retained `RetainedFile` or a refusal/settlement result.
+- `RetainedFileReceipt`: immutable admitted facts, never reusable authority.
+- `RetainedFileResult`: separate disposition, namespace, resources and persistence facts.
+- `RetainedFileIssue`: phase, native code/message and optional original authority cause.
+
+## Admission and mutation custody
+
+The directory's ancestry is opened component by component without following
+reparse points, with delete sharing denied. Its exact expected parent identity
+and canonical path are checked. The file is opened relative to that retained
+parent, with write/delete sharing denied. Existing writer handles refuse
+admission; a read-oplock grant also excludes preexisting writable mapped
+sections. That oplock request is cancelled and joined before admission returns,
+while the no-write-sharing file handle remains open. No detached request remains.
+
+The opened file must match the expected exact NTFS identity, single-link regular
+type, write/change generation, size and SHA-256. Names with stream/device syntax,
+trailing-dot/space aliases and observed named data streams are unsupported.
+Readonly attributes and ACL denials are not repaired or overridden. Verification
+is synchronous and bounded by `maxBytes` (default 16 MiB, maximum 64 MiB).
+
+The original producer must retain **exclusive mutation custody for the entire
+file**, including alternate streams, attributes, security and hardlink creation.
+Windows read/write sharing is per-stream; it is not an application lock over
+all possible aliases. The helper rejects observed alternate streams and changed
+generations, but does not turn a point-in-time check into exclusion of concurrent
+alias/attribute operations. The synchronous `assertBeforeMutation` must check
+that this original authority is still current. Callers unable to establish that
+custody must not call `remove`. Privileged/raw-volume/kernel modifications are
+outside this capability's threat model.
+
+`remove()` admits authority once, revalidates the retained object, sets native
+handle disposition, closes the file, observes the name under the still-retained
+parent, then closes ancestry. No pathname is passed to unlink. Ordinary
+`dispose()` and `[Symbol.dispose]()` only close resources. Authority callbacks
+returning Promises, thenables, or synchronous or asynchronous generator objects
+are refused without deletion; generators are never advanced. Reentrancy is also
+refused, and even caught reentrancy poisons that attempt.
+Repeated settlement returns the original receipt without another mutation or
+another authority call. A copied receipt cannot be used to remove a replacement.
+`[Symbol.dispose]()` throws `FsSafeError` with the complete result in
+`error.details.result` if resource settlement is uncertain; `dispose()` returns
+that result directly. GC closes only and produces no settlement receipt; use
+explicit disposal.
+
+## Read the facts separately
+
+| Field | Meaning |
+| --- | --- |
+| `status` | `unsupported`, `not-attempted`, `preserved-mismatch`, `disposition-accepted`, `name-absent-after-settlement`, `failed`, or `indeterminate`. |
+| `disposition` | Whether native deletion was unattempted, accepted, rejected, or indeterminate. |
+| `namespace` | A post-file-close observation: absent, original, foreign, unknown, or not observed. Absence alone never authenticates prior deletion. |
+| `resources` | `closed` or `close-failed`; operation and close errors are retained together. An uncertain close is never retried against a possibly recycled handle. |
+| `persistence` | Always `not-proven`; no namespace persistence barrier was performed. |
+
+An accepted disposition can still have an unknown/foreign/original namespace
+observation or failed close. A later replacement may exist even after observed
+absence. Existing read handles can retain access to old bytes after the name is
+absent. Namespace observation does not certify all foreign handles are closed.
+An unexpected native binding failure is indeterminate, not success.
+
+## No persistence or service-transaction guarantee
+
+This API does not flush a volume, implement a journal, certify power-loss-safe
+unlink, or issue an application dependency release. Process-termination tests
+establish process-owned handle lifetime only, not crash/storage durability.
+
+An update transaction must independently qualify either a real namespace
+persistence barrier or original-owned durable recovery with correct ordering,
+generation binding and restart consumption. Until then it must retain its
+uncertain recovery/dependency state. Successful removal of one payload does not
+establish a committed multi-file transaction or justify deleting its receipt.

package/docs/root.md

@@ -68,7 +68,10 @@ fs.walk(rel, options)          // root-bounded AsyncIterable<{ relativePath, kin
 
 `walk()` is the incremental, root-bounded recursive scan. It supports entry and
 depth budgets, cancellation, and `symlinkPolicy: "skip" |
-"follow-within-root"`. With an entry budget, sorted walks prepare small metadata
+"follow-within-root" | "include"`. Include mode returns links as
+`{ relativePath, kind: "symlink", size }` without resolving or entering their
+targets, including dangling and outside-root links. `size` describes the link,
+not its target. With an entry budget, sorted walks prepare small metadata
 batches within the remaining budget; unbounded sorted walks reuse the full
 directory snapshot.
 The default `order: "sorted"` enumerates and sorts each directory's names;
@@ -92,6 +95,8 @@ Directory reads remain fail-fast by default. With
 `{ relativePath, kind: "directory-error", size: 0, error }` and continues with
 the remaining tree. That policy also covers identity-check failures after an
 awaited filter, while callback failures always reject.
+In include mode, a directory that becomes a symlink before descent is a
+`path-mismatch` directory error; it is never silently omitted or followed.
 See [Directory walking](walk.md) for the pure-Node guarantees and the contrast
 with the standalone best-effort walkers.
 
@@ -258,8 +263,10 @@ occurred, later cancellation or verification failure preserves the destination.
 The synchronous optional `onDestinationPublished` callback receives a frozen
 `RootCopyPublicationReceipt` containing `{ path, dev, ino }`, with exact bigint identity immediately after
 publication, before later checks can fail. Callback errors also preserve the
-published file. This receipt records an outcome; it does not authorize removing
-a file that another actor may have edited. Application recovery and cooperative
+published file. Promise, thenable, and synchronous or asynchronous generator
+results reject with `TypeError`; returned generators are never advanced. Other
+synchronous return values are ignored. This receipt records an outcome; it does
+not authorize removing a file that another actor may have edited. Application recovery and cooperative
 locking remain caller-owned.
 
 Existing `copyIn` callers must account for completed destinations retained after
@@ -319,10 +326,12 @@ truncation, append, move, and removal. Buffered writes use bounded chunks and
 recheck before every partial-write submission; file removal submits a direct
 unlink request. Native calls that perform multiple filesystem steps are one
 dispatch. No asynchronous wait separates the check
-from that dispatch. A thrown value rejects the operation unchanged; an async
-or thenable-returning callback rejects with `TypeError` before that mutation.
-Synchronous return values are ignored. Callbacks can run multiple times and
-must inspect current authority each time.
+from that dispatch. A thrown value rejects the operation unchanged; a Promise,
+thenable, or synchronous or asynchronous generator result rejects with `TypeError`
+before that mutation. Returned generators are never advanced. Other synchronous
+return values are ignored. Generator detection applies to generator objects
+themselves, not proxy wrappers. Callbacks can run multiple times and must inspect
+current authority during each call; return-value validation does not establish it.
 Directory creation rechecks the retained parent after the callback and before
 submitting mkdir, so a replacement is rejected before creating that component.
 Overwrite moves recheck the retained root, parents, source identity and both
@@ -349,7 +358,9 @@ For `openWritable()`, the callback covers the library's parent creation,
 exclusive creation, and truncation. The returned raw `FileHandle` belongs to
 the caller, which must check authority before its own later writes.
 
-All mutation methods accept `denyMutations?: { paths?: string[]; prefixes?: string[] }`. Entries must be absolute paths. `paths` blocks those exact paths; `prefixes` blocks those paths and their descendants. fs-safe preserves path strings exactly and canonicalizes through existing ancestors before comparing, so a symlinked ancestor to a denied location is still denied. Denied mutations throw `FsSafeError` with code `denied-path`. Use this for caller-specific sensitive paths, not as a replacement for the root boundary, symlink, or hardlink checks.
+All mutation methods accept `denyMutations?: { paths?: string[]; prefixes?: string[] }`. Entries must be absolute paths. `paths` blocks those exact paths; `prefixes` blocks those paths and their descendants. fs-safe preserves path strings exactly and canonicalizes through existing ancestors before comparing, so a symlinked ancestor to a denied location is still denied. Missing suffixes also match prospective case and canonical Unicode normalization aliases: case-folding and Unicode NFC/NFD-equivalent spellings cannot bypass a denied path or prefix. A read-only observation of the existing parent can establish that ASCII case variants are distinct. Admission never creates temporary probe files or directories. If sensitivity cannot be established (including empty or unreadable parents, future directories, and Unicode normalization), equivalent suffixes are denied conservatively, even on a filesystem that would allow distinct names. Distinct existing canonical ancestors and unrelated names remain distinct. Observations are local to each synchronous policy check and are refreshed after callbacks or mutations. This conservative fallback does not model other filesystem-specific equivalences, such as HFS+ ignorable formatting characters.
+
+Denied mutations throw `FsSafeError` with code `denied-path`. Use this for caller-specific sensitive paths, not as a replacement for the root boundary, symlink, or hardlink checks.
 
 `move()` snapshots its merged default and per-call mutation policy before
 asynchronous preparation. Later changes to the original policy objects or arrays
@@ -384,6 +395,12 @@ fs.entries(rel, options?)        // nonrecursive AsyncIterable<DirEntry>, includ
 fs.resolve(rel)                  // absolute path inside the root, after canonicalization
 ```
 
+Directory enumeration (`list`, `entries`, and `walk`) requires UTF-8 filenames.
+A discovered name that cannot be represented losslessly as a JavaScript string
+rejects with `invalid-path`, before looking up metadata through that name.
+Streaming traversal may already have yielded earlier entries. Literal Unicode
+replacement characters (`U+FFFD`) remain valid names.
+
 These do not pin a later operation. During `stat()`, the exact selected target and
 parent are checked around metadata collection; `list()` checks one exact selected
 directory around the complete name/metadata batch instead of repeating containment

package/docs/sidecar-lock.md

@@ -61,7 +61,7 @@ Always release locks in a `finally` block. Application-managed graceful shutdown
 
 Exit cleanup tolerates shared managers created by older package copies that lack reclaim-guard state, and continues through later manager domains. Handler ownership remains first-registration-wins: loading an updated copy does not replace an older copy's registered handler. First registration is committed only after Node accepts the listener; synchronous `newListener` reentry fails closed and a thrown registration rolls back so a later acquisition can retry. Restart with the updated copy registering first to obtain the fix. After building, `node scripts/legacy-lock-exit-proof.mjs` checks clean exit, removal of legacy and modern raw locks, and preservation of a retained lock using synthetic temporary files.
 
-Each new sidecar also carries an internal random ownership token encoded as JSON trailing whitespace. `JSON.parse()` and every payload callback still see exactly the caller-provided object. Only the process that successfully created the sidecar keeps that token as release authority; merely reading token-shaped bytes from disk does not enable this mode. Release compares the in-memory token and exact serialized bytes, and requires the pathname to remain a regular file, instead of requiring an opened descriptor and pathname lookup to report the same inode identity. This preserves ownership checks on filesystems such as Docker Desktop VirtioFS where those two views can legitimately differ. Sidecars created by older releases have no token and retain the legacy identity-plus-content check. If Windows reports a zero device or inode for either identity observation, that check is inconclusive and removal is skipped.
+Each new sidecar also carries an internal random ownership token encoded as JSON trailing whitespace. `JSON.parse()` and every payload callback still see exactly the caller-provided object. Only the process that successfully created the sidecar keeps that token as release authority; merely reading token-shaped bytes from disk does not enable this mode. Release compares the in-memory token and exact serialized bytes, and requires the pathname to remain a regular file, instead of requiring an opened descriptor and pathname lookup to report the same inode identity. This preserves ownership checks on filesystems such as Docker Desktop VirtioFS where those two views can legitimately differ. Sidecars created by older releases have no token and retain the legacy identity-plus-content check. Raw acquisition, snapshot, and exit cleanup capture bigint device/inode values; unsafe numeric identities from older in-process receipts cannot authorize cleanup. If Windows reports a zero device or inode for either identity observation, that check is inconclusive and removal is skipped.
 
 Last-chance raw-lock exit cleanup requires known Windows device and inode values from both pathname observations and the opened descriptor. A zero value leaves the sidecar in place, including for token-owned locks. Known descriptor/path identity differences remain supported; a pathname identity change during the read still prevents cleanup.
 

package/docs/staged-symlink.md

@@ -86,7 +86,8 @@ the original receipt is never replaced by a post-publication identity.
   touching descriptor numbers.
 - `await using` invokes cleanup and raises on a `preserved` outcome. Invocation
   order serializes descriptor work; reentrant calls from the authority callback
-  reject. Callbacks must be synchronous; returned thenables are refused.
+  reject. Callbacks must be synchronous; returned thenables and synchronous or
+  asynchronous generator objects are refused. Generators are never advanced.
 
 Errors carry `StagedSymlinkFailureDetails` in `FsSafeError.details`: the phase,
 recorded `publication`, and a cleanup receipt when applicable. Publication is

package/docs/temp.md

@@ -22,10 +22,11 @@ substitutions; the compatible JavaScript fallback has the narrower race
 contract documented below.
 
 On POSIX, workspace creation verifies the supplied root and its canonical
-ancestors before creating a child. Each existing directory must be owned by the
-effective user or root. Group/world-writable directories must also have the
-sticky bit, so ordinary system temp directories remain usable without changing
-their modes. Foreign-owned directories and non-sticky writable ancestors reject
+ancestors before creating a child. The supplied root must be owned by the
+effective user and must not be group/world writable, even with the sticky bit.
+Use a private per-user directory rather than supplying a shared `/tmp` directly.
+Ancestors must be owned by the effective user or root; group/world-writable
+ancestors must have the sticky bit. Foreign-owned directories and non-sticky writable ancestors reject
 with `not-owned` or `insecure-permissions`; unavailable effective-user identity
 rejects with `permission-unverified`. Existing supplied directories keep their
 permissions. Missing root components are created at `0o700` and initialized
@@ -34,6 +35,25 @@ mode, correction uses a verified directory descriptor.
 An initial mode-descriptor admission error is preserved if closing that rejected
 descriptor also fails; close failures after successful admission remain reportable.
 
+On Linux, non-identity `/proc/self/uid_map` and `/proc/self/gid_map` evidence
+permits ancestors whose UID and GID equal unmapped kernel overflow IDs,
+provided the same ancestor mode checks pass.
+These owners are classified as **unmapped**, not verified root owners:
+[Linux maps all unmapped owners to overflow IDs](https://man7.org/linux/man-pages/man7/user_namespaces.7.html).
+Supporting systemd user services with `PrivateUsers=true` therefore trusts the
+host directory hierarchy against unmapped host peers who own an ancestor and
+can rename it. Sticky world-writable ancestors remain admitted because host
+`/tmp` and `PrivateTmp` appear unmapped under `PrivateUsers`; refusing them would
+disable the default system-temp layout even with a private per-user leaf root.
+An unmapped host owner of such a sticky ancestor could rename its children,
+but a normal host's `/tmp` is root-owned by construction. Mapped foreign owners
+still reject, and this exception never applies to the supplied root or newly
+created workspace. Both maps and mapped-owner exclusions are checked afresh
+whenever admission relies on unmapped ownership, including identity replay;
+unavailable namespace evidence leaves admission unchanged.
+The first admitted unmapped ancestor emits `FS_SAFE_UNMAPPED_TEMP_ANCESTOR`
+through Node's warning event. The warning contains no caller paths.
+
 For an already existing canonical root, discovery retains only its immutable
 exact identity. Cleanup-parent retention is provisional: after any native
 capability probe, creation captures and validates the complete ancestry,