@openclaw/signal 2026.9.5 → 2026.9.6

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

@@ -0,0 +1,289 @@
+---
+title: Native architecture
+description: "The platform-specific native bindings, fd-relative beneath model, platform mechanisms, loader security, and JavaScript fallback contract."
+---
+
+# Native architecture
+
+`@openclaw/fs-safe` uses native bindings that supply mechanisms Node does
+not expose directly. The Rust layer is deliberately not a second policy engine.
+TypeScript owns trusted-root selection, path validation, archive filtering,
+budgets, modes, identity fencing, cleanup decisions, and error normalization.
+Rust receives already-decided relative operations and performs the smallest
+platform syscall sequence that can preserve the boundary.
+
+Every operation that has an equivalent safe Node implementation keeps that
+guarded JavaScript path. Native loading is lazy; installs do not compile Rust,
+run postinstall code, or fetch binaries at runtime. Seven exact-version optional
+packages are filtered by OS, CPU, and Linux libc, so an installation receives
+only its matching prebuilt binding.
+Native-only formats fail explicitly
+instead of substituting a weaker implementation.
+
+## The beneath model
+
+A trusted directory descriptor is the capability. Native operations accept
+that descriptor plus a validated relative path and never reconstruct authority
+from a process working directory. Newly created files use exclusive creation,
+and TypeScript compares descriptor, pathname, and expected identities before
+accepting results.
+
+Conceptually, a caller grants authority to an already-open root—not to a path
+string that can be reinterpreted later:
+
+```text
+validated Root handle
+  └─ relative components (untrusted)
+       └─ open/link/mkdir beneath the handle
+            └─ compare descriptor + pathname + expected identity
+```
+
+The TypeScript layer validates and decides. The native layer never decides
+whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
+
+- Linux uses `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)`, fd-relative
+  `mkdirat`/`linkat`/`renameat`/`renameat2`, `FICLONE`, and `copy_file_range`.
+- macOS 15.4 and newer first use `openat(O_RESOLVE_BENEATH)`; older kernels walk
+  components with `openat(O_NOFOLLOW)` and restart in-root symlinks from the
+  pinned root. Both routes apply an `F_GETPATH` post-open containment detector,
+  but directory rename races mean the result remains `best-effort`, not
+  race-atomic. macOS uses `renameatx_np(RENAME_EXCL)` and permits
+  `fclonefileat` in an owned, non-shared parent. The clone is normalized inside
+  a private staging directory: flags, ACLs, extended attributes, and broad mode
+  bits are cleared before no-replace publication. Clone admission obtains mode,
+  owner, exact identity, flags, and ACL state together from the retained descriptor;
+  immutable receipts are compared across the private staging operation and against
+  fresh no-follow pathname identity reads. Any extended entry on the target parent
+  or private staging directory is rejected before cloning bytes. The payload's
+  cleared ACL and normalized descriptor facts are verified before publication and
+  again, with a fresh published-name identity fence, before its descriptor is
+  returned. Unsupported admission before payload
+  creation or an unsupported clone syscall may still select the documented
+  ordinary-copy path. After the clone creates bytes, normalization and security
+  verification failures report terminal `EIO`, retaining the original error
+  detail; successful cleanup does not make them eligible for ordinary-copy retry.
+  Cleanup failures remain secondary diagnostics, and already-terminal publication
+  errors such as `EEXIST` retain their status.
+- Windows uses handle-relative `NtCreateFile` with `OBJ_DONT_REPARSE` and
+  `FILE_OPEN_REPARSE_POINT`, then explicitly rejects reparse points. Rename and
+  hardlink operations stay rooted in already-open handles. Owner/DACL reads
+  use `GetSecurityInfo`; private directories receive their protected DACL in
+  an exclusive, handle-relative `NtCreateFile` call. Their created handles remain
+  open through ACL and pathname-association checks and own any failure cleanup.
+  N-API descriptors cross into and out of
+  this layer only through the host executable's paired libuv descriptor bridge;
+  missing or partial exports fail with `ENOTSUP` instead of trying a raw HANDLE
+  or add-on CRT descriptor namespace.
+
+The internal macOS `inspectDarwinAcl(fd)` capability reports `absent`, `empty`,
+or `present` for the opened object's extended ACL. It synchronously borrows the
+caller's descriptor, preserving its file position and POSIX record locks, and
+never reopens a pathname. Keep the descriptor open until inspection returns.
+Darwin's `acl_get_entry` returns
+zero for an entry; end-of-list is accepted only for the first entry of a valid,
+privately owned empty ACL. Unsupported, malformed, and failed inspection is not
+reported as absence. These facts do not classify individual ACE permissions or
+prove volume ownership enforcement; each caller applies its own security policy.
+
+## Archives
+
+Native ZIP and TAR entry reads retain a private, unpooled input Buffer in
+the async reader. ZIP reuses its parsed directory; TAR retains admitted member
+offsets. TypeScript validates and selects the requested member before reading. The internal binding borrows that allocation: it must never be
+mutated or detached while the reader or a read task exists. The public API only
+accepts a pathname and owns this buffer exclusively. An N-API reference keeps
+the bytes alive; a mutex serializes access to the retained ZIP cursor. Plain
+TAR copies only the selected range after complete admission, while gzip, zstd,
+and bzip2 replay bounded decompression and validate the full physical stream.
+Concurrent TAR reads share immutable input and own separate decoder state.
+Each output owns a new vector, which N-API transfers to Node without a second
+payload copy on runtimes supporting external buffers. No entry-read path
+requires temporary-file staging. Extraction retains its private staged input.
+
+Rust streams ZIP and TAR payloads, including gzip, zstd, and bzip2. It first
+returns a bounded manifest. TypeScript applies the shared path, filter, strip,
+mode, and byte policies and returns an index-bound extraction plan. Rust then
+creates only those planned entries beneath a private staging descriptor.
+
+The `fs-safe-archive-core` Rust workspace crate owns TAR framing, paths, types,
+mode decoding, GNU metadata, and byte-counted local PAX records. The native
+binding and bundled WASM module compile the same source. No `tar::Archive` or
+Node TAR parser reinterprets admitted identities or sizes. Executors replay
+admitted payload ranges after complete bounded admission; native writes retain
+the platform's descriptor-relative primitives, while fallback writes retain
+the guarded Node staging/publication boundary. ZIP behavior is unchanged.
+`maxMetaEntryBytes` bounds bodies before allocation; unsupported global/old
+metadata and sparse forms fail closed. See [bounded local PAX support](archive.md#bounded-local-pax-support).
+
+The bundled module also compiles the same zstd and bzip2 codec implementations
+used by native. In `off` or missing-native `auto`, those decoders feed the shared
+TAR parser through fixed 64 KiB windows in one import-free WASM session with a
+256 MiB linear-memory ceiling. Gzip retains Node's built-in decoder. Complete
+container and TAR admission precedes policy evaluation and guarded publication;
+concatenated compressed members and zstd skippable frames are consumed through
+physical EOF. No runtime command, interpreter, download, or consumer compilation
+is needed for these archive routes. `require` stays strict, and available native
+operation failures do not retry through WASM. Public `inspectTarArchive()` still
+accepts only plain TAR/gzip; ZIP fallback still requires optional JSZip.
+
+Every raw pass receives only TypeScript's resolved `maxEntries`,
+`maxMetaEntryBytes`, and `maxDecodedBytes`. Shared resolution caps metadata and
+decoded byte fields at JavaScript's safe-integer maximum and entry counts at
+`2^32 - 1` before backend selection. Large finite limits remain accepted;
+native conversion mirrors those caps and rejects malformed non-finite or
+negative direct-call values before casting. Logical member headers count
+before filtering/stripping; metadata records do not. `maxEntryBytes` and
+`maxExtractedBytes` remain exclusively in TypeScript's accepted-plan builder,
+after strip/filter policy, and are absent from the raw meter's interface.
+Bounded reads use the default count/metadata/decoded bounds; public `maxBytes`
+bounds only the requested output. TypeScript derives the internal decoded cap
+by safely adding `maxExtractedBytes` and `maxArchiveBytes`, clamped to the safe
+integer maximum. Every native pass receives that same cap and charges headers,
+metadata, bodies, padding, EOF blocks, and trailing zeros. It rejects overflow
+with `archive-decoded-size-exceeds-limit`; no ratio policy is implied.
+Extraction and entry reads drain the metered reader through physical EOF after
+admitted-range replay. Trailing framing or decoded-limit failures propagate before
+directory modes are finalized, staging is published, or selected bytes return.
+Native gzip uses the existing flate2 member decoder with an explicit bounded
+member/padding transition; JavaScript retains Node gunzip and validates its
+unconsumed compressed suffix. Only all-zero physical padding after a complete
+validated trailer is accepted, still within the original archive-byte budget.
+Native reads stop at framing boundaries so a rejected header does not request
+its body from the decoder; codec buffering can still read ahead internally.
+Inspection finishes the complete bounded framing pass before returning its manifest. Directory
+and link bodies, missing two-block EOF, and nonzero trailers reject on both
+backends, as detailed in [raw TAR framing](archive.md#raw-tar-framing). Raw and
+padded sizes above JavaScript's safe-integer maximum reject as invalid framing
+before applying member budgets, including when local PAX overrides the size.
+
+## Publication and hashing
+
+Exclusive publication tries a hardlink, then a copy-on-write clone, Linux
+`copy_file_range`, and finally the existing asynchronous JavaScript byte loop.
+All routes preserve `wx` semantics and the same source/target identity and
+SHA-256 fencing. Native hashing and Linux whole-file copying run on N-API async
+workers rather than the JavaScript event loop.
+
+Linux range copying confirms every zero-byte result with a positioned source
+read at the current transfer offset, including after earlier calls copied data.
+If readable bytes remain, automatic Root copying resumes its byte loop from
+that offset; exclusive publication removes its partial target before retrying
+the guarded byte-copy fallback. EOF checks preserve descriptor cursors and do
+not bypass the byte limit.
+
+## Mode semantics
+
+| Mode | Native loading | Fallback |
+|---|---|---|
+| `auto` | Try once, cache the result | Use guarded JavaScript when safe; reject native-only operations |
+| `require` | Try once, cache the result | Throw `FsSafeError("helper-unavailable")` |
+| `off` | Never attempt a binding load | Use guarded JavaScript when safe; reject native-only operations |
+
+`sha256FileSync()` is a synchronous Node implementation in all three modes and
+does not load the binding. Use asynchronous `sha256File()` for native hashing
+and cancellation that can respond while JavaScript callbacks run.
+
+Features without a safe fallback, including no-clobber
+`Root.move()` and
+[retained-directory staging](staged-file.md), fail with `helper-unavailable`
+when native support is absent or off. Staging is currently Linux/macOS only and
+rejects Windows with `unsupported-platform`.
+
+Windows raw owner/DACL inspection, private-directory creation, and secure-file
+descriptor inspection can use a package-shipped, readable `.ps1` driver and
+adjacent `.cs` source in `auto` or `off` mode when their binding or capability is
+unavailable. System Windows PowerShell runs the fixed driver with `-File`;
+paths remain data, with no runtime-generated helper script or encoded launcher.
+The [Windows security fallback prerequisites](install.md#windows-security-fallback)
+apply, and unsupported or disallowed command execution fails closed. This route
+preserves raw ACL facts, private DACLs at creation, and descriptor-bound secure
+reads, and emits a path-free `FS_SAFE_NATIVE_FALLBACK` warning once per capability
+per process. Each call adds PowerShell startup and compilation overhead.
+`require` rejects missing capabilities without a command, and an available native operation's
+failure never triggers this fallback. See [Permissions](permissions.md) and
+[Secure file reads](secure-file.md) for error and platform contracts.
+
+The staged-file owner also serves POSIX native pinned writes, including streaming.
+Unpublished files remain at `0600`; requested modes are applied through the
+owned file descriptor only after rename and published-entry identity validation.
+Post-rename chmod or sync failures retain the publication receipt and final name.
+Its direct-child exclusive `openat` hands off the descriptor before any fallible
+post-open checks; non-following `statat` compares against that descriptor with
+exact native identities, and cleanup uses `unlinkat` in the retained parent.
+The separate checks and unlink are not atomic conditional deletion. Windows
+pinned writes and other fallback-capable APIs retain their existing mechanisms.
+Native writers share root and parent admission, but keep their platform identity
+checks and leaf ownership. POSIX coordinator disposal uses `SuppressedError` to
+retain both an operation failure and a disposal failure, including their receipts;
+stage preparation and cleanup keep their documented error mappings.
+Root replacement verification borrows the published descriptor after final mode
+application, while a private coordinator retains the staged owner until the
+asynchronous check finishes. The owner never escapes that coordinator; public
+staging methods and receipts expose no descriptor or verification callback.
+Verification failures preserve the published name, and disposal still retains
+both verification and cleanup errors when both fail.
+The private verification channel carries exact bigint identity from the original
+owned descriptor (or the content-accepted FUSE descriptor). Root compares it
+against exact fd and pathname metadata; legacy helper return facts and public
+read metadata behavior are unchanged. Missing Windows pathname identity still
+requires a guarded path reopen and comparison with the original retained file;
+that fallback does not apply to POSIX no-read modes.
+
+## JavaScript fallback guarantees and delta
+
+Policy-bound parent creation can refresh exact directory facts through the
+retained POSIX descriptor. The optional native observer compares descriptor and
+no-follow pathname metadata and verifies the descriptor's canonical path before
+and after the observation. Ordinary paths can share that observation within one
+synchronous admission phase; callbacks, mutations, and later phases require fresh
+evidence. Unsupported helpers retain the guarded pathname checks. Policy and
+denied-path decisions remain in TypeScript.
+
+Public policy does not change with the selected mechanism: traversal and link
+rejection, archive filters/limits/modes, exclusive target creation, source and
+target identity fencing, publication cleanup receipts, and secret/lock policy
+remain TypeScript-owned. What changes is the syscall strength or availability:
+
+The table compares underlying mechanisms. On Node, public `Root.open()`,
+`Root.read()`, and `Root.openWritable()` use guarded Node file opens and report
+`containment: "best-effort"` in every native mode. `require` checks availability
+when an operation requests native support; it does not upgrade those results.
+See [Root containment guarantees](security-model.md#containment-guarantees-by-platform).
+
+| Capability | Native path | Guarded JavaScript path |
+|---|---|---|
+| Native beneath opens and Root mutations | Descriptor-relative beneath operations. Pinned writes create parents and publish both replacement and no-replace targets relative to open directory descriptors. No-clobber `Root.move()` admits both parents and uses the native no-replace rename. Native `openBeneath()` reports `kernel-atomic` on Linux and `best-effort` on macOS and Windows. macOS uses `O_RESOLVE_BENEATH` when available plus an `F_GETPATH` detector, while Windows rejects reparse traversal in the object-manager call. | Reports `best-effort`: component-wise alias checks, no-follow opens where Node exposes them, private temp/rename, and post-operation identity verification. No-clobber `Root.move()` is unsupported because a check followed by a replacing rename is unsafe. A same-privilege peer can replace a writable parent after a guard assertion but before Node resolves another pathname mutation; the mutation may land outside the intended root before the post-check detects it. |
+| ZIP/TAR/gzip | Rust streaming decode and fd-relative output creation. | Optional JSZip or bundled WASM TAR into guarded private staging, then the same guarded merge policy. |
+| Zstd/bzip2 TAR | Rust streaming decode and fd-relative output creation. | Bundled WASM codecs feed the shared Rust TAR parser, then guarded private staging and the same merge policy; no optional codec dependency. |
+| Publication copy | Clone, Linux `copy_file_range`, async native SHA-256. | Exclusive `wx` byte loop and Node SHA-256 with the same content/identity fences. |
+| `rename-noreplace` | Atomic platform no-replace rename. | Unsupported; no emulation by check-then-rename. |
+| Windows DACL read | Direct `GetSecurityInfo`; the public facts API exposes ordered basic allow/deny ACE SIDs, masks, and decoded flags without trust policy. Secure-file reads query the borrowed open descriptor and compare its 32-bit volume serial and 64-bit file-index projection with Node's bigint receipt. | The packaged PowerShell/C# bridge preserves raw facts and inspects the borrowed descriptor for secure reads, with the same Node identity comparison; its command failures reject. Structured .NET pathname reporting retains its separate compatibility query. |
+| Windows private directory | Creation-time protected DACL. | The packaged PowerShell/C# bridge applies the protected DACL at creation and retains exact handles through identity validation and failure cleanup. Command failures reject. |
+
+Use `off` in CI to keep the fallback contract exercised. Use `require` when a
+deployment depends on the stronger mechanism or a native-only feature; do not
+infer native loading from timing.
+
+## Loader security
+
+Importing fs-safe never executes a child process. Linux libc selection uses
+the Node process report, then the ELF `PT_INTERP` field of `process.execPath`,
+then conventional musl library filenames. An installed compatibility loader
+does not override the running executable's interpreter. If all probes are inconclusive, the
+loader conservatively attempts the glibc package and lets normal module loading
+fail into `auto` fallback. The loader requires only the package selected from
+the detected target; it never probes unrelated packages, downloads code, or
+runs a postinstall step. A missing or incompatible binary
+silently selects the JavaScript fallback in `auto`, throws typed
+`helper-unavailable` in `require`, and is never inspected in `off`. Tests reject
+`child_process`, `exec`, or `spawn` usage in the loader.
+
+## Related pages
+
+- [Native helper policy](native-helper.md)
+- [Security model](security-model.md)
+- [Archive extraction](archive.md)
+- [Durability](durability.md)
+- [Permissions](permissions.md)
+- [Migrating to 0.5](migrating-to-0.5.md)
+- [Migrating to 0.6](migrating-to-0.6.md)

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

@@ -0,0 +1,193 @@
+# External outputs
+
+`@openclaw/fs-safe/output` covers the case where another library insists on
+writing to an absolute path you give it. Browser downloads, renderers, media
+tools, and native libraries often have this shape:
+
+```ts
+import { writeExternalFileWithinRoot } from "@openclaw/fs-safe/output";
+
+await writeExternalFileWithinRoot({
+  rootDir: "/srv/workspace/downloads",
+  path: "reports/today.pdf",
+  write: async (filePath) => {
+    await download.saveAs(filePath);
+  },
+});
+```
+
+The external writer receives a staged path instead of the final destination.
+The default private-workspace mode finalizes through `Root.copyIn()`. An
+opt-in sibling mode stages in the destination directory and atomically renames
+the completed file over the target.
+
+## Signature
+
+```ts
+function writeExternalFileWithinRoot<T = void>(
+  options: ExternalFileWriteOptions<T>,
+): Promise<ExternalFileWriteResult<T>>;
+
+type ExternalFileWriteOptions<T = void> = {
+  rootDir: string;
+  path: string; // relative or absolute, but must stay under rootDir
+  write: (filePath: string) => Promise<T>;
+  maxBytes?: number;
+  mode?: number;
+  staging?: "workspace" | "sibling"; // default: "workspace"
+  producerIsolation?: "private-directory"; // opt-in for sibling staging
+  fallbackFileName?: string;          // safe staged-name fallback
+};
+
+type ExternalFileWriteResult<T = void> = {
+  path: string; // final absolute path under the canonical root
+  result: T;    // value returned by write()
+};
+```
+
+The requested `path` must name a file. Missing destination parents are created
+by the helper because the operation is "produce this output file under the
+root"; callers should choose the filename before calling this API.
+
+The helper reads each option once before its first asynchronous operation.
+Changing the options object after invocation does not change the selected
+writer, staging mode, isolation, filename fallback, byte limit, or final mode
+for that write. Workspace writers retain the original options object as their
+callback receiver; sibling writers retain the internal staging receiver.
+
+`maxBytes` must be a non-negative safe integer or positive `Infinity`; zero is an active cap and `Infinity` disables it. Invalid values reject before the producer or filesystem staging runs.
+
+Use `maxBytes` when the external producer can create arbitrarily large files,
+and `mode` when the finalized file needs a specific POSIX mode. Both staging
+modes enforce them after the producer returns and before committing the target.
+Requested basenames containing C0/C1 controls or Windows-invalid characters go
+through the package's filename sanitizer; `fallbackFileName` supplies the name
+when nothing remains. This removes traversal, device-name, and invalid-character
+hazards but does not trim Windows-normalized trailing dots or spaces; reject or
+rewrite those when cross-platform filename uniqueness matters.
+`staging: "workspace"` passes the sanitized basename to the producer.
+`staging: "sibling"` embeds that basename in its randomized temporary name.
+When the complete temporary component would exceed 255 bytes as written or under NFC or NFD,
+only the embedded tail is shortened, preserving its extension when possible;
+short callback paths remain unchanged. The final target and returned `path` use
+the destination basename, sanitized
+when needed as described above. Guarded temporary files used only inside
+fs-safe have independent names so their length does not grow with the
+destination basename.
+
+On Windows, `rootDir` and every target parent reject NTFS alternate-stream and
+directory-index namespace spellings such as `file:stream` and
+`dir::$INDEX_ALLOCATION`. A colon in only the requested basename still follows
+the documented portable filename sanitization above instead of being treated
+as a raw stream path. Ordinary colon-bearing POSIX roots and parents remain
+valid.
+
+## Choosing a staging mode
+
+`staging: "workspace"` is the default. The producer writes in private temp
+storage, then fs-safe copies through the guarded root boundary. Choose it when
+the temp and destination filesystems may differ, or when an externally produced
+partial file must never appear in the destination directory. The final target
+still appears only after guarded finalization. Its internal `tempFile()` does
+not expose `cleanupSafety` through this API and uses compatible cleanup, with
+the final check-to-pathname-recursive-removal gap documented in
+[`tempFile`](temp.md#tempfile).
+
+By default, `staging: "sibling"` gives the producer a randomized temp path in
+the target directory. Choose it only when that directory itself is the approved writable
+boundary and same-filesystem atomic replacement is required. After the callback
+returns, fs-safe pins and validates the staged regular file, rejects hardlinks
+and size-limit violations, applies `mode`, fsyncs it, and atomically renames it
+over the target. Existing files and symlink entries are replaced without
+following their contents or referents. The parent identity is guarded across
+the operation and the parent directory is synchronized best-effort after
+rename. If an error leaves the sibling temp in place and immediate cleanup
+fails, its verified identity remains registered for a best-effort process-exit
+cleanup retry.
+
+Sibling staging shares the [callback sibling owner](temp.md#sibling-temp-writes):
+it checks exact pre-open, descriptor, and current-path identities, retains the
+descriptor through publication, and never chmods or reads a replacement by path.
+Without producer isolation, cleanup preserves unverified paths, including partial
+output when the callback throws before admission. Native-off and Windows
+operation remain supported with the platform limits and non-atomic
+rename/unlink identity checks described there.
+When `mode` is omitted, output-sibling staging preserves the producer's mode.
+
+Add `producerIsolation: "private-directory"` to sibling staging when the
+producer can leave partial output before throwing. It receives an initially
+absent file path inside a private child workspace under the target parent, on
+the target filesystem. Directory cleanup ownership is captured before the
+callback. A callback exception triggers owned workspace cleanup, including
+partial output, subject to directory identity checks and I/O failures.
+After success, an available native helper uses guarded no-replace `Root.move`.
+With native mode off, the helper opens and identity-fences the completed regular
+file, creates the randomized sibling through an atomic no-clobber hard link,
+verifies its temporary two-link state, then removes the private name. Windows
+first transfers the pin to an independently verified sibling descriptor so the
+source name can disappear before workspace cleanup, including on runtimes with
+legacy deletion behavior. If that unlink clears the producer's read-only
+attribute, the retained descriptor restores it and the helper verifies mode and
+identity before continuing. This keeps the handoff zero-copy while preserving the
+ordinary retained-descriptor, mode,
+file-sync, and final-rename lifecycle. Escaping symlinks still fail with
+`path-alias`; filesystems without hard-link support fail with
+`helper-unavailable`.
+
+Exact bigint parent and workspace identities are rechecked before moving
+output to the sibling path to reject observed replacements. Cleanup uses the
+compatible [`withTempFile` ownership contract](temp.md#withtempfile); this
+output option does not expose `cleanupSafety: "require-bounded"`. A moved or
+replaced parent or workspace can leave artifacts, and a workspace substituted
+in the final check-to-pathname-recursive-removal gap can redirect traversal.
+The option does not promise cleanup through a retained directory after a
+rename. The existing Windows and JavaScript pathname-guard limitations remain,
+with no additional permissions or durability guarantee. Native-off publication
+is supported only where hard links are available. See the
+[producer-isolation contract](temp.md#sibling-temp-writes)
+for cleanup and pathname-race details. The option affects only `staging: "sibling"`;
+with `staging: "workspace"`, it is redundant and harmless because the producer
+already uses a private workspace. Omitting it leaves both staging defaults
+unchanged.
+
+## Why not pass the final path to the library?
+
+If a target parent can be swapped after validation, handing an external library
+the final path can make the library write outside the intended root before
+fs-safe has a chance to finalize or reject the operation. Workspace staging
+keeps the trust-boundary write inside fs-safe's root-aware copy/atomic-write
+path. Sibling staging intentionally shifts the writable boundary to the
+destination directory, while keeping pathname validation, staged-file identity
+checks, and the final rename under fs-safe's control.
+
+## Browser download example
+
+```ts
+const outputPath = requestedOutputPath || sanitizeBrowserSuggestedName(suggestedFilename);
+
+await writeExternalFileWithinRoot({
+  rootDir: downloadsRoot,
+  path: outputPath,
+  maxBytes: 512 * 1024 * 1024,
+  write: async (filePath) => {
+    await download.saveAs(filePath);
+  },
+});
+```
+
+The chosen path may be absolute if it is already inside `downloadsRoot`, or
+relative to `downloadsRoot`. Traversal, symlink parent escapes, hardlinked final
+targets, over-large staged files, and missing temp files surface as
+`FsSafeError`s.
+
+This helper is not the right fit when the final filename depends on inspecting
+the produced bytes. In that case, write to a private temp workspace, sniff or
+validate the file, choose the final name, then copy or write into the root with
+the normal root APIs.
+
+## See also
+
+- [Root writes](writing.md) — `write`, `copyIn`, `move`, and `mkdir`.
+- [Temp workspaces](temp.md) — private scratch directories for longer workflows.
+- [`pathScope()`](path-scope.md) — validation-only helper when you must pass an
+  absolute path directly to another library.

package/node_modules/@openclaw/fs-safe/docs/path-case.md

@@ -0,0 +1,64 @@
+# Path case probing
+
+`probePathCaseInsensitiveSync()` observes whether a path's lookup location
+folds ASCII case. It returns `true`, `false`, or `undefined` when the observation
+cannot establish an answer. It does not infer a filesystem property from the
+operating system or cache its result.
+
+```ts
+import { probePathCaseInsensitiveSync } from "@openclaw/fs-safe/advanced";
+
+const insensitive = probePathCaseInsensitiveSync("/srv/data/future.json", {
+  allowTemporaryProbe: false,
+});
+if (insensitive === undefined) {
+  // The application decides how to handle an unavailable observation.
+}
+```
+
+## Lookup location
+
+The input is resolved with Node's `path.resolve()`. Existing targets, including
+directories and final symlinks, are first compared by basename in their parent.
+The probe does not follow a final symlink to decide the target's case behavior.
+Parent aliases are followed. For a missing path, it walks to the nearest existing
+directory whose metadata can be read, without creating the missing directories.
+An unreadable directory listing returns `undefined`.
+
+The probe checks existing directory entries before considering a temporary
+file. Separately listed case variants count as distinct entries even when they
+are hardlinks to the same inode. Identity comparisons retain bigint precision;
+unknown Windows identities do not count as matches. The original entry is
+rechecked after looking up its case variant, so its disappearance or replacement
+invalidates the observation. A detected directory replacement also returns
+`undefined`.
+
+## Temporary probes and cleanup
+
+`allowTemporaryProbe` defaults to `true`. When existing entries give no answer,
+the helper exclusively creates one empty `.fs-safe-case-probe-*` file in the
+selected directory at mode `0o600`. It uses the existing temporary-file owner
+to retain the descriptor and exact cleanup identity. Successful ordinary
+completion removes the probe and closes the descriptor.
+
+Set `allowTemporaryProbe: false` for strictly read-only observation. In that
+mode an empty directory, or one with no useful ASCII-case names, returns
+`undefined` without creating a temporary file. Temporary probing can change
+directory timestamps and trigger filesystem watchers even when cleanup succeeds.
+
+Operational failures, unverified identities, changed entries, and cleanup
+failures return `undefined`. A substituted or hardlinked temporary entry is
+preserved. When cleanup fails operationally, the existing owner retains its
+identity-bound process-exit retry. A creation whose identity cannot be obtained
+may leave an empty file; the helper never guesses cleanup ownership. Therefore
+`undefined` does not promise that no temporary artifact remains.
+
+## Limits
+
+This is a local ASCII-case observation, not a Unicode-normalization test,
+filesystem-wide guarantee, lock, or authorization receipt. Directory enumeration
+and metadata lookups are separate operations. Concurrent changes can invalidate
+or immediately stale a result, and the final identity check and unlink are not
+an atomic conditional deletion. Use temporary probing only where creating a
+temporary file is permitted. The caller retains any admission, serialization,
+fallback, or later mutation policy.

package/node_modules/@openclaw/fs-safe/docs/path-prefix.md

@@ -0,0 +1,74 @@
+# Resolving an existing path prefix
+
+`resolvePathPrefixSync()` follows filesystem path components until the first
+missing entry. It returns a canonical existing prefix and the unprocessed
+suffix separately, including dangling symlink targets.
+
+```ts
+import { resolvePathPrefixSync, type ResolvedPathPrefix } from "@openclaw/fs-safe/advanced";
+
+const observed: ResolvedPathPrefix = resolvePathPrefixSync("/srv/data/future/file.json");
+// When /srv/data exists but future does not:
+// observed.existingPath is the canonical spelling of /srv/data.
+// observed.unresolvedSegments is ["future", "file.json"].
+```
+
+The result has three readonly fields:
+
+| Field | Meaning |
+| --- | --- |
+| `absolutePath` | Input anchored to the current directory or Windows drive, with raw path components retained and Windows separators converted to backslashes. |
+| `existingPath` | Existing prefix canonicalized by fs-safe's native-realpath owner. This may be a file when the entire path exists. |
+| `unresolvedSegments` | Components from the first missing entry onward, after expanding any earlier symlinks. Empty when the entire path exists. |
+
+## Physical traversal and missing paths
+
+The helper resolves `link/..` from the link's physical target. It does not use
+`path.resolve()` on the full input or a symlink target, because lexical
+normalization would erase that traversal. Relative inputs use the current
+directory; Windows drive-relative inputs use Node's current directory for that
+drive. A root-relative Windows symlink target retains its containing link's
+drive or share root. Windows junctions and full UNC share roots are supported.
+
+At the first `ENOENT`, traversal stops. A suffix such as
+`missing/../live.sqlite` remains `["missing", "..", "live.sqlite"]`, even if
+`live.sqlite` exists beside the missing component. Dot components, repeated
+separators, and a trailing separator in the unresolved suffix are retained.
+Normalizing that suffix would invent an alias to a file the filesystem cannot
+reach through the missing directory. The caller owns any application-specific
+comparison or prospective-path policy.
+
+## Failures and limits
+
+Only `ENOENT` from component inspection produces a missing suffix. Permission,
+I/O, non-directory traversal, symlink-reading, and final canonicalization
+failures propagate. A vanished symlink that was already observed is an error,
+not an unprocessed missing component. NUL bytes reject with `invalid-path`.
+
+Resolution rejects with `ELOOP` after 64 symlink expansions or a repeated
+resolution state. The state retains exact bigint device/inode identity and
+the remaining suffix, so revisiting a link with a shorter suffix is permitted.
+Traversing through a non-directory, including `file/..`, `file/.`, or `file/`,
+rejects with `ENOTDIR`.
+
+Dot and parent components require the directory's search permission before
+they are collapsed. Native realpath alone does not establish this permission
+on every platform. Empty components from repeated or trailing separators do
+not introduce a `.` lookup.
+
+Raw component queues of at most 32 entries retain the legacy small-array
+consumption path. After both the initial parse and every symlink expansion, a
+longer queue uses forward cursor bookkeeping instead of moving the unprocessed
+suffix for every component. The fixed small-queue bound limits repeated front
+removal while retaining legacy shift-based consumption for shallow paths. This
+asymptotic bound is not a platform performance result; performance acceptance
+requires separate benchmark evidence. Callers should still apply their own
+input-size limits: the helper is synchronous, retains the raw suffix, and
+performs filesystem work for each non-empty existing component.
+
+This is a read-only path observation. It neither pins files nor creates a root
+boundary, authorizes access, or guarantees a consistent snapshot during
+concurrent changes. Results can become stale immediately. Use a guarded Root
+operation for subsequent access to untrusted paths; keep any database ownership,
+cache invalidation, and mutation policy with the caller. Native configuration
+and Bun realpath limitations follow the existing [runtime contract](install.md#bun-runtime).