@openclaw/signal 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/docs/contributing.md

@@ -0,0 +1,262 @@
+# Contributing
+
+The `fs-safe` repo lives at [github.com/openclaw/fs-safe](https://github.com/openclaw/fs-safe). Contributions welcome — issues, bug reports, focused PRs.
+
+## Local setup
+
+```bash
+git clone https://github.com/openclaw/fs-safe.git
+cd fs-safe
+pnpm install
+```
+
+Node 22 or newer. The dev toolchain and lockfile use pnpm; use the package
+manager version declared in `package.json`.
+
+## Build
+
+```bash
+pnpm build
+```
+
+Runs TypeScript compilation and builds the portable Rust TAR parser and its
+bzip2/zstd codecs for `wasm32-unknown-unknown`. Contributors need Rust (the
+native crate's declared minimum or newer), `rustup target add
+wasm32-unknown-unknown`, and LLVM's WebAssembly-capable `clang` and `llvm-ar`.
+The system's native `ar` is not sufficient. `pnpm archive:wasm` rebuilds just
+the portable module.
+
+Linux, macOS, and Windows CI use the same pinned WASI SDK 34 LLVM toolchain;
+Alpine uses its versioned LLVM 22 packages alongside `rust-wasm`. For local
+builds, install LLVM through your package manager or use the official
+[WASI SDK](https://github.com/WebAssembly/wasi-sdk/releases/tag/wasi-sdk-34).
+On macOS, `brew install llvm` supplies the archiver missing from Apple's
+Command Line Tools. On Windows, install the LLVM distribution with both
+`clang.exe` and `llvm-ar.exe`. On Linux, install the matching `clang` and
+`llvm` packages; a GCC-only build toolchain cannot compile these WASM codecs.
+
+The build discovers tools on `PATH`, in `LLVM_PATH/bin`, in Homebrew's LLVM
+prefixes, and in Windows' standard LLVM installation. It also checks the
+versioned `clang-18` through `clang-21` and `llvm-ar-18` through `llvm-ar-21`
+executables. To select another installation explicitly, set
+`CC_wasm32_unknown_unknown` and `AR_wasm32_unknown_unknown` to its compiler
+and archiver. The corresponding hyphenated target variables and cc-rs's
+`TARGET_CC`/`TARGET_AR` or `CC`/`AR` overrides are also respected; an unusable
+explicit override fails with a builder diagnostic instead of being ignored.
+Windows build environment names are case-insensitive, including when worker
+processes uppercase them. The build normalizes only its copied child environment.
+Clang's implicit configuration is disabled for this target so the WASI SDK's
+default libc/sysroot cannot leak into the import-free module. These settings
+affect compilation only and do not become runtime dependencies.
+
+The build disables release LTO only in the WASM Cargo subprocess. An observed
+Rust 1.98.1 optimized-WASM-LTO allocation/free failure makes that necessary;
+the native release profile stays unchanged. The WASM linker strips debug
+sections to keep the bundled module small without stripping native binaries.
+The build verifies zero host
+imports and one unshared 32-bit memory with the existing 256 MiB maximum
+before copying the artifact. Allocator regression tests build a separate
+instrumented module with `pnpm archive:wasm:allocator-tests` under the Cargo
+target directory. That module is never copied to `dist/` or packaged. `pnpm
+check` and coverage collection build it explicitly before testing. After a
+fresh checkout, run that command before `pnpm test`, `pnpm test:coverage`, or
+focused `test/archive-codec-wasm-allocator.test.ts` runs; the tests fail if
+their prerequisite artifact is missing.
+
+The import-free asset lands at `dist/archive-parser.wasm`; source tests and
+compiled consumers both resolve that generated artifact. Run `pnpm build`
+before source tests in a fresh checkout. Do not commit `dist/` or built WASM.
+Consumers receive the asset in the npm package and need no compiler.
+
+Output lands in `dist/`. The package's `prepack` hook re-runs the build before publishing — manual `pnpm build` is only required when you want to inspect the output or run a freshly-built copy locally.
+
+## Test
+
+```bash
+pnpm test
+```
+
+Vitest. Tests live in `test/` and follow `*.test.ts`. Run a single file with:
+
+```bash
+pnpm test test/archive.test.ts
+```
+
+Guest filesystem tests and package smoke also need `python3` on Linux and
+macOS. They execute the exported source on synthetic files; Windows checks
+the import surface and leaves POSIX execution to the Linux/macOS lanes.
+After building on Linux, `node scripts/check-pack.mjs --guest-cross-device`
+also proves an installed-package directory move from temporary storage to
+`/dev/shm`; the command requires those locations to be different filesystems.
+
+With Bun 1.4.2 installed, build the host addon and run the native compatibility
+lane in real Bun workers, then exercise the built package with JIT disabled:
+
+```bash
+pnpm native:build
+pnpm test:bun:native
+bun --jitless scripts/bun-native-proof.mjs
+```
+
+Keep the Node/pnpm build toolchain above. CI runs the native compatibility lane
+on Linux, macOS, and Windows. The built-package proof checks `auto`/`require`,
+native-off loading policy, and a separate installation without the addon.
+
+`pnpm test:bun` runs the entire Node-oriented suite as a diagnostic. On released
+Bun, its explicit native-off and missing-helper cases include unsupported
+permission/path behavior described in [install](install.md#bun-runtime); this
+command is not a passing compatibility gate. Node CI retains every fallback
+assertion. Neither lane rewrites `off` to `auto` or marks defects as expected passes.
+
+Use `vi.mock` sparingly. Most tests should drive real disk operations in a `mkdtemp`-created scratch directory, asserting on observable behavior. The library has [test hooks](testing.md) for the rare cases where you need to inject a TOCTOU race deterministically.
+
+Vitest timeouts do not cancel filesystem promises. Shared fixtures with expensive
+setup use `useSuiteFixture` from `test/helpers/suite-fixture.ts`: setup has a separate
+30-second hook budget, and teardown waits for tracked setup and test work before
+removing directories. Run shared-state corpora sequentially with a deadline per
+payload. Keep child-process liveness limits separate from fixture preparation.
+The Windows CI slow-copy proof runs the real package-copy process-exit test with a
+16-second copy delay, a 10-second child deadline, a 15-second test deadline, and
+60-second setup and teardown hook budgets. Other hosts retain the ordinary
+six-second delay, four-second child deadline, five-second test deadline, and
+30-second hook budgets:
+
+```bash
+pnpm build
+pnpm test --config scripts/slow-package-copy.config.ts
+```
+
+## Checks
+
+Run the complete repository gate before handoff:
+
+```bash
+pnpm check
+```
+
+This runs the filesystem boundary checks, build, tests, and package
+tarball/import validation.
+
+### Method benchmarks
+
+`pnpm benchmark:methods` measures the callable library surface against synthetic
+fixtures and fails on uncovered exports or returned methods. See the
+[benchmark guide](https://github.com/openclaw/fs-safe/tree/main/benchmarks) for native/fallback runs, per-call
+timings, exclusions, and comparison methodology. Run `pnpm build` first.
+
+### Real TAR producers
+
+After installing the freshly packed root (and optionally its freshly built host
+binding) in a disposable consumer, run:
+
+```bash
+pnpm archive:producer-smoke ./consumer off
+pnpm archive:producer-smoke ./consumer require
+```
+
+This uses a child bound to canonical cwd/device/inode running `/usr/bin/tar -czf - .`
+with unchanged stdout, and npm tar, on synthetic Unicode/newline/long-name files,
+then the installed package API for exact payload hashes and bounded reads.
+The consumer must be separate from the source checkout; package resolution must
+stay within its own `node_modules`, including pnpm's local `.pnpm` layout.
+Workspace self-resolution, upward resolution, and external package links reject
+before package imports or archive fixture creation.
+It also rejects a valid PAX override attached to an invalid raw UTF-8 field.
+The `require` command must resolve the freshly packed native binding; the
+`off` command uses the installed WASM asset. No live user files are read.
+
+### Native consumer installs
+
+The CI Node 24 and native jobs also run `node scripts/device-path-proof.mjs off`
+and `node scripts/device-path-proof.mjs require` against the built package.
+This extracts real ZIP files and checks bounded member reads, preserving reserved
+device-like names on POSIX while rejecting them and ignored-space aliases on
+Windows. It also verifies ordinary secret reads and typed device-path rejection
+without replacing filesystem functions. Run after `pnpm build`, and build the
+host binding with `pnpm native:build` before the `require` case.
+
+After `pnpm build` and a fresh `pnpm native:build`, run `pnpm package:smoke`.
+It packs the real root and host binding, then runs root-only npm and the
+declared pnpm version against a disposable loopback registry. The root's exact
+optional dependencies stay unchanged. Each consumer lives outside the workspace
+with isolated configuration, caches, and stores; the registry never proxies to
+the Internet. The smoke verifies root integrity, consumer-local resolution,
+OS/CPU/libc selection, a native-required SHA-256 operation, and fresh-process
+`auto`/`off` fallbacks and `require` failures for missing bindings and omitted
+optionals. Omitted-optionals installs also verify that all public subpaths can
+be imported, without implying every operation remains available.
+
+Host-only smoke supplies the six foreign packages using their unchanged real
+manifests and clearly marked synthetic, non-executable payloads. Every foreign
+metadata/tarball endpoint is checked before installation, so a missing fixture
+cannot masquerade as successful platform filtering. These temporary fixtures
+never enter `packages/`, release artifacts, or the publish manifest. They prove
+installer filtering, not foreign native compilation or execution. Full release
+collection uses the actual seven collected native tarballs instead. Run it with
+`pnpm package:collect` after assembling all seven real bindings; missing targets
+fail collection. `pnpm package:collect --allow-host-only` exercises the same
+lifecycle boundary locally but proves only the host. Both collection commands
+require the pnpm lifecycle CLI path; JavaScript CLIs run through Node and standalone
+`@pnpm/exe` binaries run directly. Shell/cmd shims and PATH fallback are not used;
+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,
+cases, and synthetic-fixture scope to `release-artifacts/consumer-proof.json`.
+
+## Docs
+
+The docs site is rendered recursively from Markdown files under `docs/` by `scripts/build-docs-site.mjs`. Build locally to preview:
+
+```bash
+pnpm docs:site
+open dist/docs-site/index.html
+```
+
+The build validates internal links and embedded anchors. Broken links fail the build — fix them before pushing. Navigation must list every non-excluded Markdown page exactly once: missing, nonexistent, and duplicate entries fail before the build replaces existing site output. The builder and navigation tests share discovery and validation in `scripts/docs-site-navigation.mjs`.
+
+Adding a new doc page:
+
+1. Create `docs/<page>.md`. Use a leading `# Title` heading.
+2. Add the page to the appropriate section in `scripts/docs-site-navigation.mjs` (`sections` array near the top). Nested pages use slash-separated paths relative to `docs/`, such as `guides/example.md`.
+3. Cross-link from `docs/index.md` if it's a major surface.
+4. Run `pnpm test test/docs-site-navigation.test.ts` and re-run the local build.
+
+Internal links use relative `*.md` paths — the builder rewrites them to the rendered HTML. Code fences support GitHub-flavored markdown.
+
+## PRs
+
+Small, focused PRs land faster. The general shape:
+
+- One concern per PR. Bug fixes separate from new APIs.
+- A regression test for every bug fix where the test framework can express it.
+- A changelog entry under `## Unreleased` when behavior visibly changes.
+- For new public APIs: a docs page in `docs/` plus a sidebar entry.
+
+## Releases
+
+Maintainers publish from a protected `vX.Y.Z` tag on `main` through
+`.github/workflows/release.yml`. The workflow requires the package version and a
+dated `CHANGELOG.md` section to match the tag. It builds and publishes all seven
+platform packages before publishing `@openclaw/fs-safe`, verifies every registry
+artifact and provenance statement, and then creates the GitHub release.
+
+Each package needs its own npm trusted-publisher configuration for
+`openclaw/fs-safe` and `release.yml`. A new platform package must be created and
+configured on npm before the first tag that references it; npm trust is
+package-specific and cannot be bootstrapped by the tag workflow itself.
+
+External contributors do not need to do anything beyond getting the pull
+request merged. Maintainers must not publish locally or add npm automation
+tokens.
+
+## Reporting security issues
+
+Suspected security issues belong in private disclosure first. See [`SECURITY.md`](https://github.com/openclaw/fs-safe/blob/main/SECURITY.md) in the repo for the current contact path. Don't open a public issue for a credential-stealing or sandbox-escape bug — coordinate the disclosure first.
+
+## License
+
+By contributing you agree that your contributions are licensed under the project's [MIT license](https://github.com/openclaw/fs-safe/blob/main/LICENSE).

package/node_modules/@openclaw/fs-safe/docs/copy.md

@@ -0,0 +1,197 @@
+# Directory copying and cloning
+
+`@openclaw/fs-safe/copy` materializes independent, caller-owned directory trees. `copyTree` prefers native copy-on-write operations by default, can require cloning, or can copy regular file bytes without cloning or copy offload.
+
+```ts
+import { copyTree, createCloneSource, probeTreeClone } from "@openclaw/fs-safe/copy";
+
+const parent = "/srv/worktrees";
+const backend = probeTreeClone(parent);
+if (backend) {
+  const template = `${parent}/template`;
+  await createCloneSource(template);
+  // Populate this caller-owned template, then keep its contents unchanged.
+  await copyTree(template, `${parent}/checkout`, {
+    clone: "always",
+    signal: AbortSignal.timeout(60_000),
+  });
+}
+```
+
+## Filesystems
+
+| Backend | Operation                                                  | Source preparation                                                                                                          |
+| ------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `apfs`  | Native bulk clone, then directory timestamp repair         | `createCloneSource` creates an empty directory.                                                                             |
+| `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, 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.
+
+### APFS permissions
+
+APFS directory cloning does not guarantee descendant ACL preservation. With the `CLONE_ACL` flag used here, live macOS testing preserved the source root's ACL but dropped an explicit ACL on a source descendant. Destination ACL inheritance was also omitted below the cloned root. `probeTreeClone` checks filesystem support only; neither it nor `copyTree` checks whether these ACL semantics meet the caller's permission policy. A successful clone is not proof of source ACL preservation or normal file-creation inheritance throughout the tree.
+
+Callers that require source ACL preservation or destination ACL inheritance must use a creation path that preserves their permission policy. For example, a private Git template cache can prohibit custom descendant ACLs and decline cloning when the destination parent has inheritable ACL entries, the template root carries ACLs, or ACL inspection fails; it must also account for policy changes during cloning. Checking only the source root cannot establish that an arbitrary tree has no descendant ACLs. This library does not inspect or repair ACLs after a clone.
+
+Apple [strongly discourages general directory cloning](https://github.com/apple-oss-distributions/xnu/blob/f6217f891ac0bb64f3d375211650a4c1ff8ca1ea/bsd/man/man2/clonefile.2). The [XNU directory-clone authorizer notes unfinished descendant ACL inheritance](https://github.com/apple-oss-distributions/xnu/blob/f6217f891ac0bb64f3d375211650a4c1ff8ca1ea/bsd/vfs/vfs_subr.c#L8879); this is one verified limitation, not Apple's stated complete rationale. The bulk operation remains useful for controlled, immutable templates whose callers accept its metadata semantics.
+
+## API
+
+`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.
+
+`createCloneSource(destination, { signal? })` creates an empty cloneable source. Its parent must already exist and the destination must be absent.
+
+`copyTree(source, destination, { clone?, signal?, concurrency? })` copies a directory into an absent destination. Existing destinations are never merged or overwritten. The destination must be outside the source tree.
+
+| `clone` policy     | Behavior                                                                                                                                     |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"auto"` (default) | Prefer native cloning; copy bytes when the binding or filesystem capability is unavailable, or cloning cannot cross the filesystem boundary. |
+| `"always"`         | Require native cloning. Unsupported operations fail without a byte-copy fallback.                                                            |
+| `"never"`          | Copy regular file bytes using reads and writes. No native cloning or copy-offload calls. Works without a native binding.                     |
+
+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, 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 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.
+
+Tree-copy cleanup attempts every acquired close once, even when another close fails. Portable file handles close output before input; completed directories close their pinned source before target; the public wrapper then closes its source before the destination parent. A copy, identity, metadata, native-clone, or cancellation failure already observed at one of those scopes remains the reported value instead of being replaced by cleanup. If that scope otherwise succeeded, its first close failure is reported unchanged. Concurrent siblings have no global structural close order: the first observed sibling failure stops new work while admitted work settles. Portable copying records caller cancellation when it occurs, so a later abort during cleanup cannot replace an earlier copy failure.
+
+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 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.
+
+All input paths must be absolute and valid before native availability is checked. On platforms other than macOS, `auto` and `off` can return one `undefined` per path without the addon, matching native's unsupported result. On macOS, `off` or an unavailable addon still rejects with `helper-unavailable`; JavaScript cannot supply APFS clone IDs. Explicit `require` mode rejects an unavailable addon on every platform, including for an empty batch. Errors from a loaded native helper remain terminal.
+
+## 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 four options are selected once before descriptor inspection; later mutation
+of the options object cannot replace the active budget, signal, observer, or
+mutation-authority callback.
+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.
+
+### Synchronous descriptor transfers
+
+`copyFileDescriptorSync(sourceFd, targetFd, options?)` provides the same
+zero-origin byte transfer for borrowed numeric descriptors. It shares
+`CopyFileHandleOptions` and returns the copied byte count synchronously:
+
+```ts
+import { copyFileDescriptorSync } from "@openclaw/fs-safe/advanced";
+
+const bytes = copyFileDescriptorSync(sourceFd, targetFd, {
+  maxBytes: expectedSize,
+  assertBeforeMutation: assertSnapshotOwnerCurrent,
+});
+```
+
+The same regular-file and exact-identity admission, byte limits, short-I/O
+handling, cursor preservation, and caller-owned cleanup apply. The target must
+be opened without append mode, and both descriptors must remain open and free
+of concurrent I/O, including inside callbacks. Neither helper makes a mutable
+source into a consistent snapshot or truncates an existing destination suffix.
+
+The synchronous helper snapshots the four options once and invokes both
+callbacks with no receiver (`this` is `undefined` in strict callbacks).
+`onChunk` receives a borrowed view that must be consumed immediately without
+retaining or mutating it. Both callbacks must finish synchronously; thenables
+throw `TypeError` before the current write. Cancellation is cooperative: a
+pre-aborted signal or an abort triggered by a callback stops the transfer before
+the next write. Timers cannot interrupt synchronous filesystem calls while the
+event loop is blocked. Authority runs before every partial write; an abort
+triggered by that assertion prevents the same write.
+
+## 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.
+
+An already aborted signal prevents dispatch. In-flight cancellation stops cancellable traversal and waits for admitted native writes to finish before rejecting. APFS and Btrfs bulk operations cannot be interrupted once dispatched. An aborted or failed call can therefore leave a destination, including a complete bulk clone. It remains caller-owned; after settlement, the caller decides whether to retain or remove it. Do not start cleanup by racing the cloning promise against an abort promise.
+
+Tree copying preserves caller abort handlers and receives cancellation even when a caller handler stops event propagation, including native cloning and byte-copy fallbacks.
+
+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.
+
+A close-only rejection reports descriptor settlement, not whether bytes reached stable storage. The destination can already be complete when a close fails, just as other failed or cancelled calls can leave caller-owned output. Inspect or remove that output only after the copying promise settles and under the same source and destination authority assumptions.
+
+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, 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/node_modules/@openclaw/fs-safe/docs/creation.md

@@ -0,0 +1,132 @@
+# Exclusive leaf creation
+
+The creation-policy work is tracked in [#482](https://github.com/openclaw/fs-safe/issues/482).
+
+Use `createDirectory()`, `createDirectorySync()`, and `createFileSync()` from
+`@openclaw/fs-safe/advanced` when an existing, trusted parent should receive
+one new entry. These operations are exclusive and nonrecursive: an existing
+entry throws `FsSafeError("already-exists")`, and missing parents are not
+created. They do not repair or adopt an existing destination. `Root.mkdir()`
+continues to own recursive, idempotent directory creation within a Root.
+
+```ts
+import {
+  createDirectorySync,
+  createFileSync,
+} from "@openclaw/fs-safe/advanced";
+import fs from "node:fs";
+
+createDirectorySync("/trusted/application/new-state", { private: true });
+using file = createFileSync("/trusted/application/new-state/initial.db", {
+  private: true,
+});
+fs.fsyncSync(file.fd);
+```
+
+Both directory variants return `void`; `createFileSync()` returns an empty,
+read/write descriptor owned by `OwnedFileDescriptorSync`, with
+`{ fd, close(), [Symbol.dispose]() }`. Use the
+owner to close it, rather than calling `fs.closeSync()` yourself. Closing and
+disposal are idempotent; a failed close is not retried through a descriptor
+number that might already have been reused. File creation does not write
+payload data or request file or parent-directory synchronization.
+
+## Permission options
+
+`CreateDirectoryOptions` and `CreateFileOptions` both support `private?: boolean`
+for private creation. `mode?: number` selects permission
+bits; invalid values and private requests with group/world or special bits
+reject before mutation. Restrictive owner-only modes remain restrictive.
+Without `private`, ordinary Node defaults and the process umask apply. Private
+POSIX creation requests `0700` for directories and `0600` for files by default;
+the umask may restrict those permissions further. Existing directory privacy
+checks never broaden permissions.
+
+Private POSIX `Root.create()` and `createJson()` writes check the retained descriptor's actual owner and
+permissions before writing payload bytes, after producer and authority callbacks,
+and at publication, including JavaScript fallback writes. Payload writes require
+the temporary `0600` mode even when the requested final mode differs.
+Private ownership, permissions and ACLs are checked before preparing that mode,
+including after authority callbacks; valid restrictive initial modes remain supported.
+A successful `chmod` is insufficient: filesystems that do not
+enforce owner-only permissions reject before payload writes. The requested final
+mode is verified too; a failure after publication preserves the completed file
+and staged creation reports its published outcome.
+
+On macOS (Darwin), private creation also requires an ACL-free result. The native
+helper must provide `inspectDarwinAcl`; native `off`, a missing helper, or an
+older helper without that capability rejects with `helper-unavailable` before
+creating parents or staging entries. There is no system-command fallback for
+Darwin private creation. Operations without `private: true` keep their existing
+native-mode behavior.
+
+Private Darwin directories must retain owner-read or owner-search permission
+after applying the umask so their ACL can be inspected. Modes `0000` and `0200`
+reject with `helper-unavailable` before directory creation. Existing private
+directories with neither permission also reject with `helper-unavailable`;
+permissions are never broadened to inspect them. Modes `0100`, `0300`, and `0400`
+remain supported, as does the default `0700`. Private files with mode `0000`
+remain supported because inspection uses the owned creation descriptor.
+
+Before creation, the parent ACL is inspected for entries that could be inherited
+by the new directory or file, as applicable. Relevant inheritable entries reject
+creation. Noninheriting parent ACLs, such as the usual macOS home-directory
+deny-delete entry, do not reject child creation. Created directories and files
+are checked for owner-only permissions and no ACL before admitting the directory
+or allowing payload writes. An existing directory requested with `private: true`
+must also be owned by the current user, have owner-only permissions, and have no
+ACL. These checks never clear an ACL after creation or repair an existing entry.
+
+On Windows, mode bits alone do not establish privacy. Private creation uses a
+protected current-user, LocalSystem and Administrators DACL. A private staging
+directory supplies trusted-only inheritable permissions before Node creates
+the file. The original Node descriptor stays pinned while its full Windows
+identity is compared with a security handle before the file DACL is protected.
+An already broadly accessible file is rejected, not repaired. Keep the trusted
+parent ancestry and staging directory ACL protected from untrusted changes;
+post-operation checks do not make pathname-based fallback operations atomic
+against an adversary who can change that namespace.
+
+The internal async writer awaits system commands, file opens and closes, and
+security verification. It does not wrap the synchronous creator in a promise.
+Short identity checks and the existing guarded link/unlink critical sections
+remain synchronous.
+
+Private Windows file publication retains the same inode and never overwrites
+an existing destination. The current implementation requires hardlinks on the same
+local filesystem. Unsupported filesystems reject with `helper-unavailable`;
+there is no copy-to-destination fallback. On Windows the owner overlaps a
+verified destination descriptor with the creation descriptor before removing
+the temporary name. Requested read-only attributes are finalized through the
+retained destination descriptor after that handoff.
+
+On Windows, native `auto` uses available capabilities; native `off` and
+missing-capability `auto` use the packaged system-command security bridge. Native `require`
+rejects unavailable required capabilities instead of starting a command. The
+private-file capability check runs before creating parents or staging entries;
+directory-only operations require only their directory capabilities. The
+[Windows security fallback prerequisites](install.md#windows-security-fallback)
+apply. All command mutations report unconfirmed outcomes when their reply or
+termination cannot establish completion.
+
+## Authority and failure outcomes
+
+`assertBeforeMutation?: () => void` is a synchronous current-authority check.
+It runs after preparation and immediately before creation or publication;
+thenables reject before mutation. Parent and file identity checks are repeated
+after the callback. Final permission checks, descriptor settlement and cleanup
+retain the operation's cleanup ownership after publication.
+
+Failure does not always mean the final path is absent. Staged private-file errors
+after publication or ambiguous publication preserve the destination and carry
+`details.publication.status` (`published` or `indeterminate`), the target path and
+staging cleanup outcome. Cleanup and close failures retain the original error
+in the cause chain. When `stageDirectory` is present, `cleanup` describes that
+stage's settlement; it does not mean the published destination was removed.
+If a directory is created but its subsequent admission fails, the error records
+its published path and preserves it. A private file whose staging directory
+cannot be admitted reports `not-published` and identifies the preserved stage.
+Observed replacement paths are preserved. Existing
+`createPrivateDirectory()` retains its Windows-only compatibility contract;
+new portable callers should use the ordinary creation operations with
+`private: true`.