@openclaw/fs-safe 0.9.0 → 0.11.0

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

@@ -199,7 +199,7 @@ import { sha256File } from "@openclaw/fs-safe/durability";
 const snapshot = await open(stagedArchive, "r");
 try {
   const before = await snapshot.stat();
-  const hash = await sha256File(snapshot);
+  const hash = await sha256File(snapshot, { maxBytes: before.size });
   if (hash.bytes !== before.size || hash.digest !== manifest.sha256) {
     throw new Error("staged backup does not match its manifest");
   }
@@ -209,6 +209,21 @@ try {
 ```
 
 The result is `{ bytes, digest }`, where `digest` is lowercase hexadecimal.
+The optional `Sha256FileOptions` argument supports `maxBytes` and `signal`.
+`maxBytes` accepts a non-negative safe integer (including zero), or
+`Infinity` for no limit, which is also the default. Oversized files reject with
+`FsSafeError("too-large")`; reads stay bounded to at most `maxBytes + 1` bytes,
+even if the file grows after its initial size check. Hashing never silently
+truncates to the limit.
+
+Pass `signal` to cancel. A pre-aborted signal rejects before file I/O or native
+loading. In-flight cancellation is cooperative between reads and rejects with
+the signal's original reason only after the pending read or native task stops.
+Callers may close their handle after awaiting rejection; do not close it while
+the operation is pending. A signal can be shared by successive or concurrent
+hashes. Neither mode provides a snapshot of concurrently modified contents;
+callers requiring stable content must also fence identity and metadata.
+
 The handle overload never closes the caller's descriptor and uses positioned
 reads, so it does not alter the descriptor's current offset. The path overload
 rejects symbolic links and non-regular files, compares lossless bigint identities
@@ -226,11 +241,46 @@ descriptor inspection rather than waiting for a writer.
 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 64 KiB chunks but updates Node's `Hash` on the JavaScript
+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.
 
-If publication fails after this call created the target, it throws an
+### 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.
+
+```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,8 +131,8 @@ 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. |
-| `unsupported-platform` | Reserved compatibility code for a platform-specific operation. | No current public helper emits this `FsSafeError` code. Platform-specific APIs currently return a typed unsupported result or use `helper-unavailable`; keep the union member when exhaustively switching across supported package versions. |
+| `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. |

package/docs/guest.md

@@ -0,0 +1,141 @@
+# 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 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.

package/docs/in-place-write.md

@@ -0,0 +1,81 @@
+---
+title: In-place writes
+description: "Replace bytes through a borrowed file handle while preserving its inode and attempting rollback on failure."
+---
+
+# In-place writes
+
+`overwriteFileHandle()` replaces a regular file's contents through a handle the
+caller already owns. Use it when replacing the inode would break hardlinked
+aliases, or when an existing writable file lives in a directory where the caller
+cannot create a sibling temporary file.
+
+```ts
+import { open } from "node:fs/promises";
+import { overwriteFileHandle } from "@openclaw/fs-safe/advanced";
+
+const handle = await open(filePath, "r+");
+try {
+  await overwriteFileHandle(handle, Buffer.from(nextContents, "utf8"), {
+    beforeWrite: () => assertCurrentOwner(),
+  });
+} finally {
+  await handle.close();
+}
+```
+
+## Contract
+
+```ts
+overwriteFileHandle(
+  handle: FileHandle,
+  data: Uint8Array,
+  options?: { beforeWrite?: () => void },
+): Promise<void>;
+```
+
+The handle must be readable and writable, refer to a regular file, and have been
+opened **without append mode**. Node cannot portably inspect a handle's append
+flag, and some operating systems ignore positioned-write offsets for append
+handles. Opening, path admission, symlink and hardlink policy, and closing remain
+the caller's responsibility. The helper never reopens or replaces the inode,
+changes the handle's current position, or closes it. Every hardlinked alias sees
+the in-place changes.
+
+The payload is borrowed, including its byte offset and length. Keep it unchanged,
+attached, and accessible until the returned promise settles. Do not close the
+handle or run concurrent I/O against the file, including through other aliases,
+during preparation, writing, or rollback. This helper does not acquire a lock.
+
+## Preparation, ordering, and failure
+
+The helper checks the file type and original size, then saves only the prefix
+that will be overwritten: `min(data.byteLength, originalSize)` bytes. A short
+prefix read fails with `FsSafeError("read-failed")` before writing. Memory for the
+backup is bounded by that prefix length; a short replacement of a large file does
+not read or buffer the untouched tail.
+
+After preparation, `beforeWrite` runs synchronously once. A thrown value is
+propagated unchanged without any file mutation. A Promise or thenable return is
+rejected with `TypeError`; asynchronous callbacks cannot admit a write. Once
+admitted, the operation finishes the write or its failure recovery without
+calling `beforeWrite` again. This callback is a whole-operation admission point,
+not the per-mutation `assertBeforeMutation` callback used by Root operations.
+It must not change the file, handle, or payload. There is no cancellation option.
+
+For growth, additional tail bytes are written before the existing prefix is
+touched. The prefix is then overwritten, completing partial writes. For shrinkage,
+truncation is last. If a write or truncation fails, the helper attempts to restore
+the saved prefix, if touched, and the original length. It waits for both recovery
+attempts and then rethrows the original error, even when recovery also fails.
+Zero-progress writes fail with `FsSafeError("helper-failed")`.
+
+Recovery is best effort, not atomic publication or a crash-recovery guarantee.
+Other observers can see intermediate contents; failed recovery can leave partial
+bytes. The helper does not chmod or synchronize the file or its directory.
+Normal filesystem effects such as timestamp updates or clearing special mode
+bits can still occur. Callers own any durability or broader transaction policy.
+
+The implementation uses Node positional reads and writes in every native mode;
+it does not load a native binding. Prefer [`Root.write`](writing.md) when atomic
+replacement and root-based path admission are the intended contract.

package/docs/index.md

@@ -52,6 +52,7 @@ await fs.remove("notes/archive/today.txt");
 |---|---|
 | [`root()`](root.md) | One boundary for read/write/move/remove and bounded recursive walking inside a trusted directory. |
 | [`@openclaw/fs-safe/config`](config.md) | Process-global native helper and lock-option defaults. |
+| [`@openclaw/fs-safe/guest`](guest.md) | Python filesystem source for caller-owned guest transports, with admitted roots and descriptor-relative operations. |
 | [Native helper policy](native-helper.md) | Choose `auto`, `off`, or `require` for platform-native primitives. |
 | [Native architecture](native.md) | Understand the thin syscall layer, beneath model, platform mechanisms, and fallback boundary. |
 | [`replaceFileAtomic`](atomic.md) | Sibling-temp + rename, fsync hooks, mode preservation, copy fallback. |
@@ -65,6 +66,7 @@ await fs.remove("notes/archive/today.txt");
 | [`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. |
 | [`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. |
 | [Secret files](secret-file.md) | Mode-0600 credentials with size and TOCTOU defense. |
 | [Permissions](permissions.md) | POSIX mode helpers plus Windows ACL inspection, raw owner/ACE facts, remediation, and private-directory creation. |

package/docs/install.md

@@ -31,6 +31,37 @@ node --version
 # v22.0.0 or newer
 ```
 
+## Bun runtime
+
+Bun 1.4.2 can run the same public APIs and load the matching native package.
+On macOS and Linux, fs-safe uses its Rust N-API addon to call the system
+`realpath` implementation for native resolution. Ordinary resolution follows
+Node's component walk, including lexical normalization of expanded symlink
+targets, in Rust, with a 1,024-link expansion limit that returns `ELOOP` for
+excessive or cyclic expansion. This works around Bun path-resolution defects that
+otherwise reject restrictive permissions and confuse literal POSIX backslashes
+with directory separators. The OS still resolves symlinks and canonical file
+names; fs-safe retains its confinement and file-identity checks.
+
+This works with `bun --jitless` and needs no runtime FFI or JIT. Use native mode
+`auto` or `require` with the matching addon installed. `FS_SAFE_NATIVE_MODE=off`
+still disables all addon loading; `auto` without the addon falls back to Bun's
+resolver. Those configurations retain Bun 1.4.2's limitations with restrictive
+permissions, sockets, literal backslashes, and symlink/parent traversal. Use
+Node if you need full compatibility without the addon. On Bun POSIX, `require`
+also rejects canonicalization when the addon or its canonicalizer is unavailable.
+
+Node and Windows use their existing runtime canonicalizers. On Windows, Bun's
+recursive directory creation receives an absolute spelling that preserves raw
+path components, working around its rejection of existing relative `.` and `..`
+directories. Public paths and caller-supplied filesystem adapters remain unchanged.
+
+The upstream fix is tracked in [Bun #42374](https://github.com/oven-sh/bun/pull/42374).
+The adapter can be removed when the supported Bun baseline includes that fix.
+Run native compatibility checks with `pnpm test:bun:native` after building the
+package and addon. See [contributing](contributing.md) for the Node/pnpm toolchain
+and the broader diagnostic suite.
+
 ## TypeScript
 
 Types ship with the package — no `@types/openclaw__fs-safe` needed. The `exports` map in `package.json` provides typed entries for every subpath:

package/docs/local-roots.md

@@ -71,6 +71,13 @@ component that does not exist: dangling symlinks, descendants of dangling
 symlinks, and candidates whose existing ancestors cannot be canonicalized are
 rejected rather than treated as safe missing paths.
 
+Filesystem path inputs retain symlinks and parent components until boundary
+resolution, including after home expansion. A followed `link/../file` resolves
+the parent of the link's target; default reads reject the link instead of
+normalizing it away. File URLs retain the URL parser's normal path semantics.
+An existing non-directory component cannot be traversed further, including by
+`..`; the helpers reject that input instead of selecting a different file.
+
 ## `readLocalFileFromRoots(options)`
 
 The asynchronous helper opens the candidate through the matched [`Root`](root.md),
@@ -82,7 +89,7 @@ type ReadLocalFileFromRootsOptions = LocalRootsInputOptions & {
   hardlinks?: "reject" | "allow";
   maxBytes?: number;
   nonBlockingRead?: boolean;
-  symlinks?: "reject" | "follow-within-root";
+  symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root";
 };
 
 type LocalRootsReadResult = ReadResult & {