@openclaw/fs-safe 0.10.0 → 0.12.0

package/docs/copy.md

@@ -26,8 +26,11 @@ if (backend) {
 | `btrfs` | One native writable subvolume snapshot                     | `createCloneSource` creates a subvolume; an ordinary directory is not a snapshot source. No `btrfs` executable is required. |
 | `refs`  | Native directory traversal with parallel file block clones | `createCloneSource` creates an empty directory on ReFS, including Dev Drive volumes.                                        |
 | `xfs`   | Native directory traversal with parallel file reflinks     | `createCloneSource` creates an empty directory. The XFS volume must support reflinks.                                       |
+| `zfs`   | Native directory traversal with parallel file reflinks     | `createCloneSource` creates an empty directory. Requires Linux OpenZFS file reflinks and the pool block-cloning feature. |
 
-Native cloning requires source and destination filesystems that support cloning between them. Automatic and ordinary copying can cross filesystems. The source repository used to populate a template can live elsewhere. ReFS and XFS share file data rather than the whole directory metadata tree, so creating many small files still has a cost.
+Native cloning requires source and destination filesystems that support cloning between them. Automatic and ordinary copying can cross filesystems. The source repository used to populate a template can live elsewhere. ReFS, XFS, and ZFS share file data rather than the whole directory metadata tree, so creating many small files still has a cost.
+
+ZFS uses strict file reflinks within one dataset, not dataset snapshots. The installed Linux OpenZFS version must implement `FICLONE`, and the pool must enable `feature@block_cloning`. The probe identifies ZFS even when that feature is unavailable; `clone: "always"` then fails and `"auto"` can copy bytes. Native cloning was verified on OpenZFS 2.4.1 with POSIX ACLs. See the [OpenZFS block-cloning contract](https://openzfs.github.io/openzfs-docs/Basic%20Concepts/Data%20Storage/Block%20Cloning.html) for filesystem limits and pool sharing counters.
 
 Btrfs preserves native subvolume snapshot semantics: nested subvolume contents are not included. Prepare source-only templates without nested subvolumes. This API does not recursively snapshot a hierarchy of subvolumes.
 
@@ -41,7 +44,7 @@ Apple [strongly discourages general directory cloning](https://github.com/apple-
 
 ## API
 
-`TreeCloneBackend` is the `"apfs" | "btrfs" | "refs" | "xfs"` union returned by the probe. `CopyTreeOptions` contains the optional `clone`, `signal`, and `concurrency` arguments. `CopyCloneMode` is the `"auto" | "always" | "never"` strategy shared with [`Root.copyIn`](root.md#writes); tree copies default to `"auto"`, while guarded file copies default to `"never"`.
+`TreeCloneBackend` is the `"apfs" | "btrfs" | "refs" | "xfs" | "zfs"` union returned by the probe. `CopyTreeOptions` contains the optional `clone`, `signal`, and `concurrency` arguments. `CopyCloneMode` is the `"auto" | "always" | "never"` strategy shared with [`Root.copyIn`](root.md#writes); tree copies default to `"auto"`, while guarded file copies default to `"never"`.
 
 `probeTreeClone(parentPath)` synchronously inspects an existing directory and returns its supported backend name or `undefined`. It creates no probe artifacts. A filesystem name identifies a candidate backend; for example, an older XFS volume may have reflinks disabled. The actual operation determines availability. An unavailable native binding produces `undefined` in automatic mode; the package's explicit native `require` mode still reports a missing binding as an error.
 
@@ -57,18 +60,80 @@ Apple [strongly discourages general directory cloning](https://github.com/apple-
 
 Automatic copying does not recover from permission errors, I/O errors, cancellation, or rejected source contents such as ReFS named streams. A failed clone must leave the destination absent before fallback can create it; otherwise copying fails rather than merging into a partial tree.
 
-`concurrency` accepts integers from 1 through 32 and bounds active file copies. ReFS and XFS cloning default to 16 workers. Byte copying defaults to four concurrent files on Windows and one elsewhere. Btrfs uses its bulk operation. APFS uses a bulk clone followed by native directory-entry enumeration to restore directory timestamps; known regular files and symbolic links need no additional stat or open.
+`concurrency` accepts integers from 1 through 32 and bounds active file copies. ReFS, XFS, and ZFS cloning default to 16 workers. Byte copying defaults to four concurrent files on Windows and one elsewhere. Btrfs uses its bulk operation. APFS uses a bulk clone followed by native directory-entry enumeration to restore directory timestamps; known regular files and symbolic links need no additional stat or open.
+
+On Windows, automatic byte copying uses the native binding when available to transfer data between the already-checked file handles in chunks of at most 1 MiB, with smaller buffers for small files. This accelerates NTFS and cross-volume copies without reopening source or destination pathnames. The native worker finishes before its descriptors are closed or cancellation is reported. `clone: "never"` and native-disabled copies use JavaScript read/write loops with reusable buffers: at most 1 MiB per active file on Windows, or 128 KiB elsewhere. Both paths share the file-worker budget across sibling directories, wait for all admitted writes after cancellation or failure, and restore directory timestamps after their descendants finish. Completed directory traversals awaiting writes or metadata are bounded by concurrency; ancestors remain pinned while traversing their children.
 
-On Windows, automatic byte copying uses the native binding when available to transfer data between the already-checked file handles in 1 MiB chunks. This accelerates NTFS and cross-volume copies without reopening source or destination pathnames. The native worker finishes before its descriptors are closed or cancellation is reported. `clone: "never"` and native-disabled copies use JavaScript read/write loops with reusable buffers: at most 1 MiB per active file on Windows, or 128 KiB elsewhere. Both paths wait for all admitted writes after cancellation or failure and restore directory timestamps only after their file copies finish.
+On Linux, automatic byte copying also uses the native binding when available. It reads in chunks up to 1 MiB, using smaller buffers for smaller source-size hints, and leaves leading and trailing zero-filled portions of each chunk unwritten in the new file, avoiding their allocation on filesystems that support sparse files. A final size update preserves trailing holes and all-zero files. This path uses reads and writes, without cloning or copy offload; it still reads the full logical contents and does not promise identical sparse extent layout. `clone: "never"` retains the JavaScript byte-copy path.
 
 Clones preserve file contents, empty directories, timestamps, executable modes where supported, and literal symbolic links. Editing a clone does not modify its source. Unsupported filesystem operations fail; callers may choose their own copy or checkout fallback after the failed operation has settled.
 
+Native Windows byte copies can store large zero-filled chunks as sparse ranges when the destination is initially empty and its filesystem supports sparse files. This still reads every source byte and creates an independent copy.
+
 The ReFS backend rejects files with alternate data streams and unsupported reparse-point types instead of silently losing their contents. Symbolic links and junctions are preserved.
 
-XFS preserves regular-file and directory modes, timestamps, extended attributes, and ACLs. It rejects special files, symlink extended attributes, non-UTF-8 names, and directory nesting deeper than 128 levels. Hardlinked source files become independent reflinked files. Portable byte copying preserves file contents, empty directories, modes where supported, file and directory timestamps, and literal symbolic links; it does not promise ownership, ACL, extended-attribute, alternate-stream, or sparse-layout preservation. On Windows, byte copying rejects unresolved symbolic links because Node does not expose their file/directory link type; resolved links keep their literal target and source type. POSIX dangling links are preserved. Choose a copying policy that meets the caller's metadata requirements; automatic copying can select either path.
+XFS and ZFS preserve regular-file and directory modes, timestamps, extended attributes, and ACLs. They reject special files, symlink extended attributes, non-UTF-8 names, and directory nesting deeper than 128 levels. Hardlinked source files become independent reflinked files. Portable byte copying preserves file contents, empty directories, modes where supported, file and directory timestamps, and literal symbolic links; it does not promise ownership, ACL, extended-attribute, alternate-stream, or sparse-layout preservation. On Windows, byte copying rejects unresolved symbolic links because Node does not expose their file/directory link type; resolved links keep their literal target and source type. POSIX dangling links are preserved. Choose a copying policy that meets the caller's metadata requirements; automatic copying can select either path.
 
 `readCloneFileMetadata(files)` asynchronously reads APFS data-stream identities and file metadata in one native batch. Results correspond to input order; missing or unsupported entries return `undefined`. The returned `CloneFileMetadata` includes clone ID, device/inode, size, mode, ownership, and timestamps. These are point-in-time observations, not authorization or proof that later reads remain unchanged. Consumers such as Git index adapters must validate their own content and timestamp invariants. The reader does not follow leaf symbolic links.
 
+## Borrowed FileHandle transfers
+
+`copyFileHandle` from `@openclaw/fs-safe/advanced` copies bytes between two
+already-open regular files. Use it when a snapshot or materialization owner
+has admitted the source and opened its own destination:
+
+```ts
+import { createHash } from "node:crypto";
+import { copyFileHandle } from "@openclaw/fs-safe/advanced";
+
+const digest = createHash("sha256");
+const bytes = await copyFileHandle(sourceHandle, targetHandle, {
+  maxBytes: expectedSize,
+  signal: AbortSignal.timeout(30_000),
+  onChunk: (chunk) => { digest.update(chunk); },
+  assertBeforeMutation: assertSnapshotOwnerCurrent,
+});
+```
+
+`CopyFileHandleOptions` contains optional `maxBytes`, `signal`, `onChunk`, and
+`assertBeforeMutation`. The result is the actual byte count copied through EOF.
+The byte limit is not a prefix length: excess data rejects with `too-large`,
+including data added after admission. Omitted limits are unlimited; Root's
+default read cap does not apply. Zero accepts only an empty source. Invalid
+limits reject before descriptor inspection.
+
+The source and target must be distinct regular files; exact device/inode
+aliases, including two handles to hardlinked names, reject before writing.
+Both reads and writes start at position zero and preserve the handles' current
+cursors. Existing destination bytes beyond the copied prefix remain intact.
+The target must have been opened **without append mode**: some platforms ignore
+positional writes on append handles, and Node exposes no portable open-flags
+query. Keep both handles open and free of concurrent I/O through settlement.
+
+The synchronous `onChunk` observer sees each source chunk before any target
+write for that chunk. It receives a borrowed view reused by later reads; consume
+it immediately without retaining or mutating it. This supports source hashing;
+it does not verify bytes persisted by the destination. Callers that require a
+destination digest must still hash the destination handle afterward. Observer
+and authority callbacks may throw; thenable returns reject with `TypeError`
+before the affected write. `assertBeforeMutation` runs immediately before every
+partial-write submission and must inspect current authority each time.
+
+The helper reuses Root copying's bounded read buffer and completes positive
+short reads and writes. JavaScript file transfers use at most 512 KiB of scratch
+space, reduced for smaller source-size hints and capped by a finite byte budget
+plus its one-byte overflow probe. A zero-progress write rejects with `helper-failed`.
+Cancellation is checked before I/O, after source reads, and before each write;
+admitted reads and writes settle before rejection. A rejected operation can
+leave a copied prefix. There is no rollback or pathname cleanup.
+
+This helper never opens or closes a file, truncates, chmods, syncs, renames, or
+publishes it. Source admission, immutability checks, destination preparation,
+durability, publication, and failure recovery stay with the caller. Initial
+descriptor inspection does not prove that the source remained unchanged while
+copying. Keep existing source-fingerprint and publication checks around the
+transfer when building snapshot operations.
+
 ## Ownership and cancellation
 
 These are low-level operations on caller-owned absolute paths, not Root-relative methods. The source and destination parent must be real directories. The library pins their descriptors and verifies their identities; it does not establish the caller's authorization to use them. Keep the source immutable for the operation, including writes through other aliases, and keep the destination namespace under the caller's control. Literal symlinks in the cloned contents are preserved rather than followed or sanitized.
@@ -77,10 +142,14 @@ An already aborted signal prevents dispatch. In-flight cancellation stops cancel
 
 Completion is not a crash-durability guarantee. The API is suitable for reconstructible templates and checkouts; it does not sync every file or replace application-level publication and recovery rules.
 
+Byte copying retains fractional file and directory access/modification timestamps to the precision supported by Node's timestamp APIs and the destination filesystem. This includes dates before 1970 on Unix. On Windows, [Node's unsigned stat seconds](https://github.com/nodejs/node/blob/v26.8.2/src/node_file-inl.h#L93-L104) can report pre-1970 timestamps as dates about 136 years later; byte copying inherits that upstream limitation.
+
 ## Platform tests and benchmarks
 
-After building the host native binding, run `pnpm test test/clone.test.ts test/copy-tree.test.ts`. APFS tests can use the normal macOS temporary directory. For Btrfs, ReFS, or XFS, set `FS_SAFE_CLONE_TEST_ROOT` to an existing writable directory on that filesystem. The test creates and cleans only its own temporary children. An explicitly configured unsupported directory fails the test rather than silently skipping platform proof. XFS metadata tests require the `attr` and `acl` utilities.
+After building the host native binding, run `pnpm test test/clone.test.ts test/copy-tree.test.ts`. APFS tests can use the normal macOS temporary directory. For Btrfs, ReFS, XFS, or ZFS, set `FS_SAFE_CLONE_TEST_ROOT` to an existing writable directory on that filesystem. The test creates and cleans only its own temporary children. An explicitly configured unsupported directory fails the test rather than silently skipping platform proof. XFS and ZFS metadata tests require the `attr` and `acl` utilities.
 
 Run `node scripts/clone-xfs-proof.mjs MOUNT` on a real XFS volume to verify the public API, hashes, independent writes, and shared physical extents. It requires `filefrag` from `e2fsprogs`. Add `no-reflink` for an XFS fixture formatted with reflinks disabled; strict copying must fail and automatic copying must succeed through byte copying.
 
+Run `node scripts/clone-zfs-proof.mjs MOUNT POOL` on a dedicated, otherwise idle Linux ZFS pool with compression and deduplication disabled. It verifies both `copyTree` and `Root.copyIn` through hashes and changes in the documented `bclonesaved` pool counter. It requires `zfs`, `zpool`, and `findmnt`, including permission to run `zpool sync`. Add `no-reflink` for a pool without block cloning to verify strict refusal and automatic byte fallback. The script creates and removes only its temporary directory; it does not create pools or change their properties.
+
 Run `node benchmarks/clone.mjs SOURCE DESTINATION_PARENT` after `pnpm build` to compare one, four, and 16 workers on the same immutable source. Add `3 auto` or `3 never` to measure three samples of ordinary copying, including NTFS destinations. It records copying time separately from fixture preparation and full file-hash verification, and retains its uniquely named output directory for inspection. Prepare Btrfs sources with `createCloneSource` first.

package/docs/directory-identity.md

@@ -0,0 +1,85 @@
+---
+title: Directory identity
+description: "Exact directory observations and synchronous identity assertions for application-owned workflows."
+---
+
+# Directory identity
+
+Use `readDirectoryIdentity()` and `assertDirectoryIdentitySync()` from
+`@openclaw/fs-safe/advanced` when an application owns a staging or recovery flow
+and needs to verify that a pathname still identifies an observed directory.
+
+```ts
+import {
+  readDirectoryIdentity,
+  assertDirectoryIdentitySync,
+} from "@openclaw/fs-safe/advanced";
+
+const expected = await readDirectoryIdentity(directoryPath);
+await prepareOutput();
+assertDirectoryIdentitySync(directoryPath, expected);
+```
+
+`readDirectoryIdentity(path)` returns a frozen `DirectoryIdentity`:
+
+```ts
+type DirectoryIdentity = Readonly<{
+  dev: bigint;
+  ino: bigint;
+  realPath: string;
+}>;
+```
+
+Both operations reject a final symlink or a non-directory, including paths with
+one or more trailing separators. Filesystem, drive, and UNC roots remain valid.
+Parent aliases and `..` retain their filesystem traversal meaning; POSIX
+backslashes and whitespace remain literal filename characters. These helpers do
+not confine a path to a root or reject every symlink ancestor. Keep the
+application's path policy, or use the [Root API](root.md) for paths that must
+remain beneath a root.
+
+## Checking the selected path
+
+`assertDirectoryIdentitySync(observedPath, expected)` reads the supplied path
+and compares its exact `dev` and `ino` against the expected bigint values. It
+returns `undefined` on success and throws synchronously on failure.
+
+If `expected.realPath` is present, the current canonical path must also match
+that string exactly. Pass the complete observation to keep both checks:
+
+```ts
+assertDirectoryIdentitySync(newlyOpenedRootPath, expected);
+```
+
+For a directory intentionally moved to another name, omit `realPath` while
+retaining the expected identity:
+
+```ts
+assertDirectoryIdentitySync(movedPath, { dev: expected.dev, ino: expected.ino });
+```
+
+Only `dev`, `ino`, and optional `realPath` participate in the assertion. A
+`MovePathPublicationReceipt` can supply the identity after a move; its `path`
+does not implicitly require the previous pathname to remain current.
+
+## Errors and ownership
+
+| Condition | Result |
+|---|---|
+| Final symlink or non-directory | `FsSafeError("not-file")` |
+| Different expected identity or supplied canonical path | `FsSafeError("path-mismatch")` |
+| Numeric expected identity or persistently unknown Windows identity | `FsSafeError("path-mismatch")` |
+| Filesystem failure such as `ENOENT` or `EACCES` | The original error, unchanged |
+
+Windows can temporarily report a zero device or inode. The shared identity
+owner permits one re-inspection, retaining every known component so a later
+observation cannot erase a definite mismatch. It rejects identities that remain
+unknown and does not retry operational filesystem errors.
+
+These helpers observe directory identity. They do not open a retained handle,
+hold a lock, create or remove directories, change permissions, or authorize
+application work. A pathname can change after an assertion; continue to use
+guarded mutation APIs and recheck application authority at the operation's
+existing submission point. Keep publication, rollback, and cleanup decisions
+with the caller. Use [pinned directories](durability.md#pinned-directories) when
+the operation specifically needs the directory synchronization lifecycle.

package/docs/durability.md

@@ -242,10 +242,47 @@ When the optional binding is active, hashing runs as an async native task and
 does not occupy the JavaScript event loop with digest updates. With native mode
 `off`, or in `auto` when no binding loads, the fallback performs asynchronous
 positioned reads in chunks of up to 256 KiB but updates Node's `Hash` on the JavaScript
-thread. Both paths stream constant-size buffers rather than loading the file
-into memory. Native mode `require` keeps its usual fail-closed loader semantics.
+thread. Both paths stream bounded buffers rather than loading the file into memory.
+The fallback sizes its scratch buffer to small files and grows it if a stale
+size hint is exceeded, while still probing for actual EOF and byte-limit overflow.
+Native mode `require` keeps its usual fail-closed loader semantics.
+
+### Synchronous hashing
+
+`sha256FileSync()` accepts a pathname or a borrowed numeric file descriptor and
+returns the same `{ bytes, digest }` result. It shares `Sha256FileOptions`,
+including the default unlimited byte budget and `too-large` errors for growth
+beyond `maxBytes`. It always reads from offset zero with bounded positional
+`readSync` calls and leaves a borrowed descriptor open at its original position.
+Path inputs use the same regular-file, final-symlink, nonblocking-open, and exact
+bigint admission checks described above, then close their owned descriptor.
+These checks do not provide ancestor confinement or a snapshot of concurrent edits.
 
-If publication fails after this call created the target, it throws an
+```ts
+import { closeSync, openSync } from "node:fs";
+import { sha256FileSync } from "@openclaw/fs-safe/durability";
+
+const fd = openSync(stagedArchive, "r");
+try {
+  const hash = sha256FileSync(fd, { maxBytes: manifest.sizeBytes });
+  if (hash.bytes !== manifest.sizeBytes || hash.digest !== manifest.sha256) {
+    throw new Error("staged backup does not match its manifest");
+  }
+} finally {
+  closeSync(fd);
+}
+```
+
+The synchronous API uses Node's crypto implementation in every native mode,
+including `require`; it never loads a native binding. It blocks the calling
+thread until hashing finishes or throws. A pre-aborted signal fails before I/O,
+and synchronous signal changes are checked between operations with the original
+reason preserved. Timers and other JavaScript callbacks cannot run while the
+hash is executing; use `sha256File()` when responsive cancellation is needed.
+
+## Publication failure receipts
+
+If `publishFileExclusive()` fails after creating the target, it throws an
 `FsSafeError` with a `details` receipt:
 
 ```ts

package/docs/entries.md

@@ -0,0 +1,109 @@
+# Directory entries
+
+`Root.entries()` observes one directory at a time. Use it when the application
+owns traversal order or must inspect symlinks itself, such as an installer that
+validates selected dependency links or a manifest builder that rejects all links.
+
+```ts
+import { root } from "@openclaw/fs-safe";
+
+const workspace = await root("/srv/workspace");
+for await (const entry of workspace.entries("plugins", {
+  maxEntries: 1_000,
+  signal: AbortSignal.timeout(5_000),
+})) {
+  if (entry.isSymbolicLink) {
+    throw new Error(`unexpected link: ${entry.name}`);
+  }
+  console.log(entry.name, entry.size);
+}
+```
+
+## API
+
+```ts
+interface Root {
+  entries(relativePath: string, options?: RootEntriesOptions): AsyncIterableIterator<DirEntry>;
+}
+
+type RootEntriesOptions = {
+  maxEntries?: number;
+  order?: "filesystem" | "sorted";
+  signal?: AbortSignal;
+  symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root";
+};
+```
+
+Each result is the existing [`DirEntry`](types.md) shape: a basename and advisory
+`lstat` metadata, including `isFile`, `isDirectory`, `isSymbolicLink`, `size`,
+`mode`, `nlink`, `dev`, and `ino`. Entries are immediate children; the iterator
+never descends. An empty path or `"."` selects the root directory.
+
+Child symlinks are always reported without following them, including dangling
+links and links whose targets lie outside the root. Their metadata describes
+the link, not its target. Hardlinked files are also reported regardless of the
+Root's read hardlink policy. Reporting a name grants no read or mutation access.
+Use the Root operation methods when consuming or changing an entry.
+
+The `symlinks` option applies only to the path of the selected directory. It
+inherits the Root's read policy and defaults to `"reject"`. The two follow
+policies allow only contained aliases; `"follow-parents-within-root"` also
+rejects a link as the final directory component. Child-link reporting is
+independent of this path policy.
+
+## Work limits and ordering
+
+`maxEntries` is an optional non-negative safe integer. Every child counts,
+including directories, symlinks, special files, and entries the caller later
+ignores. Omit it to leave the count unbounded. An empty directory satisfies a
+zero limit. Exceeding the limit throws `FsSafeError` with code `"too-large"`;
+there is no silent truncation or success marker for a partial scan.
+
+The default `order: "filesystem"` reads names incrementally in the filesystem's
+nondeterministic order. It observes one child's metadata per iterator step,
+with one name of lookahead to distinguish an exact limit from an overflow.
+Entries already yielded before overflow remain partial observations. A caller
+that stops early has not established that the whole directory fits the limit.
+
+`order: "sorted"` collects names first and orders them with JavaScript's default
+string sort, not locale collation. With `maxEntries`, names are collected from
+a bounded directory stream; overflow rejects before yielding any entries or
+requesting their full metadata. Without a limit, sorted mode enumerates the
+complete name list. Metadata is observed only as each sorted entry is consumed.
+Applications that need locale-specific ordering can collect with an explicit
+limit and apply their own comparator.
+
+The count bounds logical directory reads and fs-safe metadata requests. Node
+may classify a directory entry with `lstat` when the filesystem omits type
+information, including the single lookahead entry. It does not bound elapsed
+time for an individual filesystem operation or the size of one filename.
+
+Cancellation is checked before setup and around awaited work. Directory
+handles close on completion, overflow, cancellation, failure, and early
+`break` or iterator return. In-flight filesystem work settles before rejection;
+an individual syscall cannot be interrupted. If iteration and disposal both
+fail, a `SuppressedError` retains the close failure in `error` and the original
+failure in `suppressed`.
+
+## Identity and caller responsibilities
+
+The iterator reuses Root's guarded directory-listing owner. It validates the
+selected path, pins exact Root and directory identities, and checks them around
+directory observations, including after control returns from the caller. A
+replaced directory rejects instead of continuing under the replacement.
+
+These are pure-Node, best-effort checks. The iterator does not hold descriptors
+for every path component and cannot sandbox a hostile process that repeatedly
+swaps and restores directories. Results are not an atomic snapshot, an exact
+identity receipt, or permission to use the name later. Contents and metadata
+can change between entries; a removed entry may cause iteration to reject.
+Use an admitted descriptor for metadata and hashing that must refer to the same
+opened file, and keep snapshot consistency or cooperative locking with its
+application owner.
+
+Traversal strategy, global budgets, ignored names, and approved external peers
+remain application policy. A per-directory physical-entry limit cannot replace
+a global file-only or unique-directory budget. Full metadata also requires a
+child `lstat`; a caller that previously needed only `Dirent` types should assess
+that cost. `Root.walk()` remains the recursive option for its supported link,
+pruning, and error policies; `Root.list()` returns an eager advisory listing.

package/docs/errors.md

@@ -117,11 +117,11 @@ type FsSafeErrorCode =
 | `helper-unavailable` | Required native binding could not be loaded. | Unsupported platform, omitted/missing/incompatible platform package, or `FS_SAFE_NATIVE_MODE=require`. `auto` falls back where possible; `require` fails closed. |
 | `insecure-permissions` | A secure file or path permission check found a mode/ACL that allows broader access than requested. | File or directory is group/world writable/readable; Windows ACL grants broad read. |
 | `invalid-path` | Input was empty, contained NUL, was an unparseable URL, or otherwise unusable; a FileStore key used a noncanonical spelling. | Noncanonical FileStore aliases, backslashes, or complete parent segments; a network path on Windows; a drive-relative segment in a portable relative path or store key; or a leading drive-relative spelling such as `C:name` used as a Root destination. Existing-object Root lookups retain broader confined path compatibility, including legal POSIX drive-like names. |
-| `not-empty` | `remove()` on a non-empty directory. | Use `replaceDirectoryAtomic` or remove children first. |
+| `not-empty` | Nonrecursive `remove()` on a non-empty directory, or new children appeared during recursive removal. | Use bounded `recursive: true` removal or coordinate concurrent writers. |
 | `not-file` | Read or copy targeted a non-regular file, or a path walk found a non-directory ancestor. | Target was a directory, FIFO, socket, device, or an existing file was followed by another segment. |
 | `not-found` | The target does not exist (or its parent does not, with `mkdir: false`). | Typical missing-file case. |
 | `not-owned` | A secure file owner check failed. | File is owned by another UID. |
-| `not-removable` | `remove()` couldn't `unlink`/`rmdir` for a reason other than non-empty. | Permissions, device busy, immutable bit. |
+| `not-removable` | `remove()` couldn't inspect a directory stream or `unlink`/`rmdir` for a reason other than non-empty. | Permissions, device busy, immutable bit; the original filesystem error remains in `cause`. |
 | `outside-workspace` | Path resolves outside the configured root. | `..` traversal; absolute path outside the root; symlink resolved out. |
 | `path-alias` | A path alias check failed (e.g. canonical-real-path moved out of the root). | Symlink resolution lands outside the root. |
 | `path-mismatch` | Post-open identity check failed: the opened fd does not match the resolved path. | TOCTOU — something else swapped the path between resolve and open. |
@@ -131,7 +131,7 @@ type FsSafeErrorCode =
 | `store-reentrant-update` | A `JsonStore.update()` callback called `update()` or `updateOr()` for the same canonical store before returning. | Reentrant mutation would deadlock or lose an update; return the complete next value from the outer callback. |
 | `symlink` | Path component is a symlink, policy is `reject`. | Caller followed a symlink they shouldn't have, or `symlinks: "reject"` is set. |
 | `timeout` | An operation with a wall-clock budget overran. | Secure file read or timed operation exceeded `timeoutMs`. |
-| `too-large` | A read or bounded walk exceeded its configured budget. | Caller gave a too-permissive file or traversal limit. |
+| `too-large` | A read, bounded walk, or recursive removal exceeded its configured budget. | Review the expected file or tree size before increasing the limit; recursive removal may have completed earlier entries. |
 | `unsupported-platform` | The platform or filesystem cannot perform the requested operation. | `createCloneSource` and `copyTree({ clone: "always" })` require native cloning support. The default `copyTree({ clone: "auto" })` selects portable byte copying when cloning is unavailable; unsupported source contents or metadata still fail. See [directory copying](copy.md) for backend limits and fallback behavior. |
 
 Secret writes reject invalid `mode` / `dirMode` values with `invalid-path` before directory creation. Existing secret directories with a mode different from the requested `dirMode` report `insecure-permissions` without chmod; a created directory whose descriptor ownership no longer matches its initializing effective user reports `not-owned`.

package/docs/file-store.md

@@ -121,6 +121,21 @@ metadata where lower latency matters more than crash-durability. Per-call
 `undefined` override preserves the store default. Modes, path confinement,
 and publication identity checks are unchanged.
 
+Synchronous writes retain their original write-only descriptor through rename
+and publication checks, using exact bigint file identities. When Windows cannot
+report a pathname's identity, verification reopens the name only to compare its
+descriptor with the retained writer; it never reads file contents. A substituted
+file is rejected even if its bytes match, and a post-publication failure leaves
+the published entry intact for caller-owned recovery. Ordinary write-only and
+mode-000 outputs do not require a readable descriptor when pathname metadata is
+available.
+
+If an opaque pathname cannot be reopened because of an ACL denial or sharing
+restriction, the synchronous writer intentionally rejects with `path-mismatch`:
+its exact publication identity cannot be verified. There is no equal-content
+fallback. The published entry remains present, so callers must inspect or
+recover that outcome instead of assuming the write did not occur.
+
 | Method | Durability support |
 |---|---|
 | `write`, `writeText`, `writeJson` (async and sync) | Per-call option overrides store default. |
@@ -241,6 +256,12 @@ type FileStorePruneOptions = {
 
 Symlinks are skipped. The walk is best-effort — failures on individual entries don't abort the whole prune. Compares against `mtimeMs`.
 
+Pruning rechecks that a selected entry is still a regular file and still expired
+immediately before guarded removal. Fresh replacements and in-place timestamp
+refreshes are preserved; replacements that are themselves expired remain
+eligible. This does not require read permission. The existing best-effort
+external-process race window after dispatch still applies.
+
 ## Difference from `Root`
 
 | `FileStore` | `Root` |

package/docs/filename.md

@@ -1,6 +1,6 @@
 # Filenames
 
-`sanitizeUntrustedFileName(name, fallback)` reduces a filename string from an untrusted source to one traversal-free path segment. Use it as a thin first pass before storing user-supplied names; pair with [`safeDirName`](install-path.md#safedirname) when you need stricter directory-name handling.
+`sanitizeUntrustedFileName(name, fallback)` reduces a filename string from an untrusted source to one traversal-free path segment. Use it as a thin first pass before storing user-supplied names; use [`safePathSegmentHashedV2`](install-path.md#safepathsegmenthashedv2) when mapping untrusted install IDs to separate directory names.
 
 ```ts
 import { sanitizeUntrustedFileName } from "@openclaw/fs-safe/advanced";
@@ -27,6 +27,13 @@ In order:
 6. **Suffix Windows reserved basenames.** Compare the part before the first `.` case-insensitively with the Windows device-name set, including `CON`, `PRN`, `AUX`, `NUL`, `CLOCK$`, `CONIN$`, `CONOUT$`, `COM1..9`, `LPT1..9`, and their superscript `¹`, `²`, and `³` variants. Windows-ignored spaces and dots at the end of that basename do not disguise a device name. A match gains `_` before its extension, preserving the original case and extension on every platform.
 7. **Truncate.** If the cleaned segment is longer than 200 UTF-16 code units, take up to the first 200 without splitting a valid Unicode surrogate pair.
 
+If truncation itself exposes a reserved-device basename after Windows ignores
+trailing spaces or dots, the result is shortened once more and receives the
+same underscore suffix. A name that reaches the sanitization branch therefore
+remains at most 200 UTF-16 code units and is never a Windows reserved-device
+alias. `fallbackName` is returned verbatim for empty or path-alias input, so
+callers must supply a fallback that already satisfies their filename policy.
+
 That's it. The function stays intentionally small: it removes traversal and
 the most obvious cross-platform device and character hazards, but it is not a
 complete portable-filename or uniqueness policy.
@@ -92,5 +99,5 @@ await fs.write(`uploads/${safe}`, body); // fs is a Root() handle; rejects trave
 
 ## See also
 
-- [Install path helpers](install-path.md) — `safeDirName`, `safePathSegmentHashed` for directory-segment sanitization.
+- [Install path helpers](install-path.md) — legacy directory-segment sanitizers and `safePathSegmentHashedV2` for untrusted install IDs.
 - [`root()`](root.md) — the boundary you'll write into after sanitizing.

package/docs/guest.md

@@ -0,0 +1,146 @@
+# Guest filesystem source
+
+`@openclaw/fs-safe/guest` exports Python 3 source for filesystem operations in
+Linux and macOS guests that do not have Node installed. The host imports a
+string and passes it to its existing container, SSH, or process transport.
+Importing this subpath performs no I/O and launches no process.
+
+This is the filesystem engine extracted from OpenClaw's sandbox bridge. The
+caller still owns root admission, mount selection, read-only policy, canonical
+path authorization, live authority, argument framing, and process lifetime.
+Use [Root](root.md) for ordinary filesystem operations in the Node process.
+This source artifact is separate from the retired host-side Python worker
+described in [Migrating to 0.5](migrating-to-0.5.md).
+
+## Exports and requirements
+
+```ts
+import {
+  GUEST_FILESYSTEM_PYTHON,
+  GUEST_FILESYSTEM_CREATE_EXISTS_EXIT_CODE,
+  GUEST_FILESYSTEM_READ_NOT_FOUND_EXIT_CODE,
+  GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON,
+} from "@openclaw/fs-safe/guest";
+```
+
+`GUEST_FILESYSTEM_PYTHON` is the complete single-invocation program. The two
+exit constants are `17` for an exclusive-create collision and `2` for a
+missing read parent or leaf after the root opens. Other nonzero statuses are
+errors; stderr is diagnostic text, not a structured error protocol.
+
+The guest needs Python 3 with `ctypes`, descriptor-relative POSIX operations,
+`O_DIRECTORY`, and `O_NOFOLLOW`. Linux and macOS are the supported guest
+platforms. The guest does not need fs-safe's Node package, native addon, Rust,
+or WASM. Native mode configuration in the host does not configure this program.
+
+`GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON` contains just the
+`rename_no_replace(src_parent_fd, src_basename, dst_parent_fd, dst_basename)`
+definition. OpenClaw's workspace bootstrap consumes this same fragment when
+publishing a prepared workspace; exporting it avoids a second source owner.
+Its embedding program must import `ctypes`, `errno`, `os`, and `sys`, admit
+the descriptors and single-component names, and own cleanup and syncing.
+The fragment has no argument preflight of its own.
+
+On Linux it uses `renameat2(RENAME_NOREPLACE)`; on macOS it uses
+`renameatx_np(RENAME_EXCL)`. If Linux lacks that function or reports it as
+unsupported, it falls back to `link(..., follow_symlinks=False)`, leaving the
+source entry for caller cleanup. That fallback supports files, not directory
+publication. Existing destinations are never replaced by this fragment.
+
+## Invocation protocol
+
+Pass the source through `python3 -c` and arguments as literal argv elements.
+Do not concatenate untrusted values into a shell command. Transport adapters
+that require a shell must apply their existing quoting rules to every element.
+The following example uses an already admitted guest root and parent path:
+
+```ts
+import { spawnSync } from "node:child_process";
+import { GUEST_FILESYSTEM_PYTHON } from "@openclaw/fs-safe/guest";
+
+const result = spawnSync("python3", [
+  "-c", GUEST_FILESYSTEM_PYTHON,
+  "write", "/srv/admitted-workspace", "notes", "today.txt", "1",
+], { input: Buffer.from("hello\n"), timeout: 10_000 });
+if (result.error) throw result.error;
+if (result.status !== 0) throw new Error(result.stderr.toString());
+```
+
+All frames below start at `sys.argv[1]`. `root` is an admitted guest directory;
+`parent` and `directory` are paths relative to that root. An empty relative
+path selects the root itself. Flags are strings: `"1"` enables and `"0"`
+disables. Do not omit required fields.
+
+| Operation | Positional frame | Input / output |
+|---|---|---|
+| Read | `read root parent basename [maxBytes]` | Raw bytes on stdout; optional nonnegative integer byte limit. |
+| Write | `write root parent basename mkdir` | Raw stdin; atomically replaces a file entry. |
+| Create | `create root parent basename mkdir` | Raw stdin; exclusively publishes a completed file. |
+| Copy | `copy srcRoot srcParent srcBasename dstRoot dstParent dstBasename mkdir` | Regular-file copy, atomically replaces destination. |
+| Rename | `rename srcRoot srcParent srcBasename dstRoot dstParent dstBasename mkdir` | Rename with cross-device copy/delete fallback. |
+| Remove | `remove root parent basename recursive force` | Removes the leaf, or recursively removes its tree. |
+| Make directories | `mkdirp root directory` | Creates missing relative directory components. |
+| List directory | `readdir root directory` | JSON array of `{ name, isDirectory }`; no sorting guarantee. |
+
+The complete program rejects empty, `.`, `..`, slash-containing, and NUL
+basenames before opening roots or creating parents. Both leaf operands of copy
+and rename are checked. Backslashes, colons, quotes, and newlines remain legal
+POSIX basename characters. Relative directory traversal rejects `..`; empty
+and `.` components are skipped. Supply admitted relative paths, not arbitrary
+absolute paths whose spelling happens to pass that component walk.
+
+## Boundary and operation behavior
+
+The supplied root spelling is trusted. Opening it does not prove the root is
+the mount or inode previously authorized by the caller. Basename syntax checks
+are not authorization. Callers must admit their roots and paths, preserve
+read-only shadows and live authority, and run the program inside the intended
+OS isolation boundary.
+
+Parent traversal and operation bodies use directory descriptors. Reads and
+copies refuse final symlinks, hardlinked files, and nonregular files. Bounded
+reads check both admitted size and consumed bytes; a growing file can produce
+partial stdout before rejection. Consumers must discard read output when the
+exit status indicates failure. Removal unlinks a final symlink without
+following it; rename moves symlink entries. Write and copy replace destination
+entries, including symlinks, without following them. A force removal tolerates
+a missing leaf but does not suppress failure to open its parent.
+
+Write preserves an existing regular file's mode and otherwise creates private
+files. Copy preserves the source mode. Exclusive create publishes a mode-0600
+file from a private staging directory. Staging names retain the `.openclaw-*`
+prefixes and use short random suffixes independent of the destination basename,
+so legal names near the filesystem's component limit also work for writes and
+cross-device moves.
+
+Cross-device symlink moves create the new link in a private destination-side
+staging directory before atomically replacing the destination. Link creation or
+publication failure preserves the existing destination and source link; ordinary
+failure cleanup removes the staging directory.
+
+Cross-device directory moves build a copy manifest and check it during source
+cleanup. Source changes can leave the published destination and some or all
+of the source. Regular-file and symlink move fallbacks unlink the source
+pathname after publication; they do not perform the directory manifest's
+identity checks. Directory cleanup also has check-to-unlink race windows.
+These mechanics do not promise content integrity against same-UID peers.
+
+## Failure, cancellation, and budgets
+
+Nonzero exit is not proof that nothing was published. A post-publication
+identity or sync failure, or cross-device source-cleanup failure, can leave a
+destination. The caller owns reconciliation and retry policy; do not assume
+it is safe to remove that destination or replay a mutation blindly.
+
+Ordinary Python failures run `finally` cleanup. There is no cancellation frame
+or signal handler. Process death closes descriptors, but forced termination
+can leave staging names. The transport owns termination, waiting for children
+to settle, and any application-specific recovery.
+
+Read byte limits are optional. Copy, write, recursive removal, directory
+listing, and cross-device tree moves have no byte, entry, or depth budget in
+this protocol. Recursive traversal and listing collect entries eagerly.
+Use caller-owned isolation and resource limits appropriate to the operation.
+The existing fsync sequence is preserved; this is not a recursive transaction,
+rollback facility, or a stronger durability guarantee than the underlying
+filesystem provides.