@openclaw/fs-safe 0.14.0 → 0.16.0

package/docs/creation.md

@@ -0,0 +1,128 @@
+# 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.
+
+Native private file creation checks the retained descriptor's actual owner and
+permissions before writing payload bytes, after producer and authority callbacks,
+and at publication. 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 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. 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`.

package/docs/durability.md

@@ -69,6 +69,26 @@ descriptor, pathname identity, and canonical path. `assertCurrent()` repeats
 those checks. This prevents a pathname replacement from turning a later sync
 into proof for a different directory.
 
+Pathname and descriptor checks compare exact bigint device and inode values.
+Each inspection allows one retry for unknown Windows identity components,
+retaining known components and rejecting definite mismatches immediately.
+Persistent unknown identity fails closed with `path-mismatch`, including on an
+otherwise usable directory. A failed preflight identity check never syncs the
+descriptor; a replacement discovered after sync still rejects the operation.
+
+`DirectoryReceipt.identity` remains a numeric Node `Stats` object for metadata
+compatibility, projected from the same exact observation as the private
+identity. Library-created receipts and their identity objects retain a
+private exact snapshot; mutating their public fields cannot change the
+directory authorized by that snapshot. Each returned receipt owns a mutable
+numeric metadata copy. Later admissions retain the original metadata snapshot
+even if advisory fields such as mode or timestamps were edited; changed paths
+or identity components reject. Pass the receipt or its original
+identity object through to later operations to retain this evidence. A copied
+or reconstructed numeric identity is accepted only when both components are
+safe integers and, on Windows, nonzero. Rounded or unknown caller identities
+fail with `path-mismatch` rather than authorizing a different directory.
+
 Call `close()` in `finally`. Closing is idempotent; using a closed pin fails.
 
 These checks intentionally reject a moved or replaced pathname. For one file's
@@ -94,6 +114,10 @@ accepted.
 `expectedExistingIdentity` binds an existing target to an identity observed by
 the caller before a separate permission or policy check. A missing or replaced
 target fails with `FsSafeError("path-mismatch")`.
+Use bigint `dev` and `ino` from `lstat(path, { bigint: true })` or
+[`readDirectoryIdentity()`](directory-identity.md) for caller-owned observations
+that may exceed the numeric safe-integer range. An original library receipt's
+`identity` object also retains its private exact identity for this option.
 
 ## Exclusive file publication
 

package/docs/file-store.md

@@ -133,6 +133,13 @@ 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 a synchronous write operation and its final temp-descriptor close both fail,
+the store reports them in operation-then-close order in an `AggregateError`.
+This ordering and the original JavaScript thrown value are preserved even when
+that value is `undefined` or otherwise falsy. An unsuccessful best-effort temp
+unlink remains registered for identity-checked process-exit cleanup; it does not
+prevent the close attempt or replace either reportable failure.
+
 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
@@ -219,6 +226,14 @@ with the same precedence as `write`.
 
 Per-call overrides for the store-level defaults:
 
+Writes capture byte limits, modes, and durability before asynchronous work or
+stream consumption. JSON writes capture those fields and the trailing-newline
+setting before serialization. Later mutation cannot change those captured values.
+Accessors run on the original options object. Ordinary writes retain content
+conversion and byte-limit validation before reading modes and durability.
+The legacy non-private stream `tempPrefix` accessor still runs after staging;
+it does not control the publication policy.
+
 ```ts
 type FileStoreWriteOptions = {
   durable?: boolean;   // store default, otherwise true
@@ -283,6 +298,10 @@ refreshes are preserved; replacements that are themselves expired remain
 eligible. This does not require read permission. The existing best-effort
 external-process race window after dispatch still applies.
 
+Empty-directory pruning likewise rechecks that the selected entry is still a
+directory immediately before guarded removal. File and symlink replacements
+are preserved, and a directory that becomes nonempty is left in place.
+
 ## Difference from `Root`
 
 | `FileStore` | `Root` |

package/docs/install.md

@@ -119,22 +119,46 @@ Use the main entry for the common surface, or the focused subpaths when you want
 
 ## Runtime dependencies
 
-`@openclaw/fs-safe` bundles an import-free WASM build of its Rust TAR parser for guarded JavaScript TAR/gzip [archive extraction](archive.md), including installs with optional dependencies omitted. ZIP fallback uses lazily loaded optional `jszip` and reports a missing-dependency error without it. Public subpaths remain safe to import with all optional dependencies omitted, but imports do not prove native availability.
+`@openclaw/fs-safe` bundles an import-free WASM build of its Rust TAR parser and zstd/bzip2 codecs for guarded [archive extraction and bounded entry reads](archive.md). Plain TAR, gzip, zstd, and bzip2 work in `off` and missing-native `auto`, including installs with all optional dependencies omitted; gzip uses Node's built-in decoder. These archive fallbacks need no runtime interpreter, download, or consumer compiler. ZIP fallback uses lazily loaded optional `jszip` and reports a missing-dependency error without it. Public subpaths remain safe to import with all optional dependencies omitted, but imports do not prove native availability. Native `require` remains strict, and an available native operation's failure never triggers a WASM retry.
 
 There are no peer dependencies. Exact-version optional packages carry the seven
 native targets and npm-compatible OS, CPU, and Linux libc filters install only
-the matching binary. Consumers do not run a native build, download code at
+the matching binary. Consumers do not run a Rust build, download code at
 runtime, or execute a postinstall step. Omitting optional dependencies keeps
-non-archive fallback-capable operations working in `auto` or `off`. Native-only
+fallback-capable operations working in `auto` or `off`. Native-only
 features, including strict owned-tree temp cleanup, retained-directory staging,
-atomic `rename-noreplace` (including the default no-clobber `Root.move()`),
-zstd/bzip2 TAR handling, and Windows private-directory creation, remain
-unavailable. Operations without a safe fallback fail with `helper-unavailable`
+and atomic `rename-noreplace` (including the default no-clobber `Root.move()`),
+remain unavailable. Operations without a safe fallback fail with `helper-unavailable`
 when the matching package is absent, incompatible, or disabled.
 
 Upgrading an existing 0.5 consumer? Follow [Migrating to 0.6](migrating-to-0.6.md)
 before deploying with native mode `require` or native-only features.
 
+### Windows security fallback
+
+Windows raw owner/DACL inspection, private-directory creation, and secure-file
+reads work without the addon in `auto` or `off` mode when system Windows
+PowerShell and its .NET `Add-Type` compilation support are available. The package
+ships a readable, fixed `.ps1` driver and adjacent `.cs` source and invokes the
+driver with Windows PowerShell `-File`. Paths are passed as data. The fallback
+does not generate helper scripts at runtime or use an encoded launcher.
+The driver addresses built-in commands by module name and limits module
+discovery to PowerShell's bundled system modules, avoiding broad command
+discovery scans during each helper startup.
+
+Normal PowerShell execution policy and Microsoft Defender policy must permit
+the packaged scripts, including their use of `Add-Type`. The package does not
+bypass restrictions, change policies, or add exclusions. Unsupported or
+disallowed command execution fails closed.
+
+The fallback preserves private DACLs at creation and inspects the same open
+handle that supplies secure-file bytes. Each capability emits a path-free
+`FS_SAFE_NATIVE_FALLBACK` warning once per process; each call adds PowerShell
+startup and compilation overhead. Execution or compilation failure also fails
+closed. Native `require` still rejects a missing binding or capability, and an
+available native operation's error never triggers a command retry. See
+[Permissions](permissions.md) and [Secure file reads](secure-file.md).
+
 ## Native helper policy
 
 The platform native binaries provide fd-relative open/link/mkdir primitives,
@@ -147,7 +171,7 @@ where a safe fallback exists. Native-only operations fail with
 import { configureFsSafeNative } from "@openclaw/fs-safe/config";
 
 configureFsSafeNative({ mode: "auto" });    // default
-configureFsSafeNative({ mode: "off" });     // guarded JavaScript; reject native-only operations
+configureFsSafeNative({ mode: "off" });     // disable the addon; reject native-only operations
 configureFsSafeNative({ mode: "require" }); // fail closed if unavailable
 ```
 

package/docs/json-store.md

@@ -85,6 +85,11 @@ For `fileStore(...).json(rel, options)`, `options.durable` overrides the parent
 file store's durability, while omission or `undefined` inherits it. Modes,
 identity checks, mutation serialization, and sidecar locking are unchanged.
 
+Each `write`, `update`, or `updateOr` invocation captures the retained options'
+`durable` and `trailingNewline` values before queueing, locking, reading, or
+calling the updater. Changes to those options affect later invocations only,
+including when a mutation is waiting behind another operation.
+
 The store does **not** validate the parsed value against `T` at runtime — the cast is unchecked. Wrap with a schema (zod/valibot) if the file might be hand-edited or written by another process you don't control.
 
 ## `read()`

package/docs/migrating-to-0.5.md

@@ -88,8 +88,10 @@ await extractArchive({
 ```
 
 Returning `"skip"` rejects the archive unless `onFiltered: "skip-entry"` is
-explicit. Zstd and bzip2 TAR are native-only; ZIP, TAR, and gzip retain guarded
-JavaScript implementations. Catch `ArchiveLimitError` by its code, including
+explicit. Zstd and bzip2 TAR required native support in version 0.5; current
+versions also use bundled WASM codecs in `off` or missing-native `auto`, through
+the same guarded TAR pipeline. ZIP fallback still requires optional JSZip.
+Catch `ArchiveLimitError` by its code, including
 `archive-entry-path-components-exceeds-limit` for deep implicit-directory
 attacks. See [Archive extraction](archive.md).
 
@@ -167,10 +169,17 @@ See [File locks](sidecar-lock.md), [Secret files](secret-file.md), and
 
 ## 7. Gate native-only features
 
-`createPrivateDirectory()` is Windows-only and native-only because a pathname
-fallback cannot promise the same creation-time DACL. Zstd/bzip2 extraction and
-`strategy: "rename-noreplace"` are also native-only. Test the unavailable path
-instead of assuming installation always succeeds.
+Version 0.5 required native support for `createPrivateDirectory()`. Current
+releases also support a packaged PowerShell script in native `auto` and `off`
+modes, retaining its creation-time protected DACL. Check the
+[Windows security fallback prerequisites](install.md#windows-security-fallback)
+before relying on this route. The API remains Windows-only, explicit native
+`require` rejects a missing binding or capability, and native operation failures
+remain terminal.
+`strategy: "rename-noreplace"` remains native-only. Current zstd/bzip2 extraction
+and bounded reads have bundled WASM fallbacks, while explicit native `require`
+remains strict. Test unavailable native-only operations instead of assuming
+installation always succeeds.
 
 ## 8. Run both behavior families in CI
 

package/docs/migrating-to-0.6.md

@@ -24,10 +24,15 @@ uses native mode `require` or any native-only feature. Version 0.5 kept its
 binding in the root tarball; version 0.6 intentionally does not.
 
 Omitting optional dependencies remains supported for fallback-capable APIs in
-`auto` mode. It disables native-only features such as zstd/bzip2 TAR handling,
-retained-directory staging, atomic `rename-noreplace`, and Windows private
-directory creation. Native mode `require` reports `helper-unavailable` when the
-matching package is absent or incompatible.
+`auto` mode. It disables native-only features such as retained-directory staging
+and atomic `rename-noreplace`. Native mode `require`
+reports `helper-unavailable` when the matching package is absent or incompatible.
+Zstd/bzip2 TAR extraction and bounded reads required the binding in version 0.6;
+current versions also support bundled WASM codecs in `auto` and `off` through the
+same guarded TAR pipeline. ZIP fallback still requires optional JSZip.
+Windows private-directory creation required the binding in version 0.6; current
+releases also support [packaged Windows security scripts](install.md#windows-security-fallback)
+in `auto` and `off` mode while preserving the creation-time protected DACL.
 
 ## Deployment checklist
 

package/docs/native-helper.md

@@ -15,7 +15,7 @@ consumer Rust build.
 import { configureFsSafeNative } from "@openclaw/fs-safe/config";
 
 configureFsSafeNative({ mode: "auto" });    // default
-configureFsSafeNative({ mode: "off" });     // guarded JavaScript; reject native-only operations
+configureFsSafeNative({ mode: "off" });     // disable the addon; reject native-only operations
 configureFsSafeNative({ mode: "require" }); // fail closed when the binding is unavailable
 ```
 
@@ -25,14 +25,22 @@ The equivalent environment variables are `FS_SAFE_NATIVE_MODE` and `OPENCLAW_FS_
 
 | Mode | Behavior |
 |---|---|
-| `auto` | Prefer native primitives when the current platform package loads; otherwise use guarded JavaScript where a safe fallback exists and reject native-only operations. |
-| `off` | Do not load a native package. Use guarded JavaScript where safe and reject native-only operations deterministically. |
+| `auto` | Prefer native primitives when the current platform package loads; otherwise use supported fallbacks and reject native-only operations. |
+| `off` | Do not load a native package. Use supported fallbacks and reject native-only operations deterministically. |
 | `require` | Throw `FsSafeError("helper-unavailable")` instead of falling back when an operation needs the native binding and it cannot load. |
 
-TAR/gzip in the guarded JavaScript path uses a bundled, import-free WASM build
-of the same Rust parser used by native. `off` still disables the optional native
-filesystem helper; it does not disable this portable parser. ZIP fallback still requires
-optional `jszip`, and zstd/bzip2 remain native-only.
+Plain TAR, gzip, zstd, and bzip2 extraction and bounded entry reads use a bundled,
+import-free WASM build of the same Rust TAR parser when native support is absent
+or disabled. Zstd/bzip2 codecs are bundled alongside the parser; gzip uses Node's
+built-in decoder. These archive fallbacks require no runtime interpreter or
+download. `off` disables the optional native filesystem helper, not the bundled
+WASM. `auto` prefers native and does not retry a native operation failure through
+WASM; `require` still rejects an unavailable native binding. ZIP fallback still
+requires optional `jszip`. `inspectTarArchive()` remains limited to plain TAR
+and gzip.
+
+Windows security operations can use the package's readable PowerShell/C# scripts
+in `auto` and `off`, subject to the [Windows security fallback prerequisites](install.md#windows-security-fallback).
 
 On Bun macOS/Linux, the [runtime path adapter](install.md#bun-runtime) uses the
 same Rust addon for system canonicalization in `auto` and `require`. No JIT is
@@ -95,15 +103,27 @@ clone/copy/hash workers, POSIX canonicalization, and Windows security descriptor
 layer owns policy, retries, filters, budgets, modes, cleanup, error
 normalization, and the decision to fall back.
 
-- Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS`, `renameat`, and `renameat2(RENAME_NOREPLACE)`. Owned-tree cleanup enumerates and unlinks through retained directory descriptors and rejects device crossings.
-- macOS 15.4 and newer prefer `O_RESOLVE_BENEATH`; older kernels resolve components with `O_NOFOLLOW` and restart in-root symlinks from the pinned root descriptor. Both routes use an `F_GETPATH` post-open escape detector and report `best-effort` because directory rename races are not atomic with that check. Publication uses `renameat` for replacement and `renameatx_np(RENAME_EXCL)` for no-replace; owned-tree cleanup uses descriptor-relative `openat`/`unlinkat`.
-- Windows uses handle-relative `NtCreateFile`, rejects reparse points during root-bounded traversal, uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer, and deletes owned trees through exact opened handles with `FileDispositionInfoEx`; symlink/reparse entries in owned trees are removed as leaves and never traversed. Descriptors crossing N-API are converted only by the host executable's paired `uv_get_osfhandle` and `uv_open_osfhandle` exports. A runtime without both exports is unsupported for these native operations; the binding never guesses a raw HANDLE or uses a foreign CRT descriptor table. Descriptor-producing operations also require that same host's synchronous libuv close and request-management APIs before exporting an owned descriptor.
+- Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS`, `renameat`, and `renameat2(RENAME_NOREPLACE)`. Direct-child no-replace renames borrow already-retained parent descriptors; deeper relative paths retain the guarded reopen. Owned-tree cleanup enumerates and unlinks through retained directory descriptors and rejects device crossings.
+- macOS 15.4 and newer prefer `O_RESOLVE_BENEATH`; older kernels resolve components with `O_NOFOLLOW` and restart in-root symlinks from the pinned root descriptor. Both routes use an `F_GETPATH` post-open escape detector and report `best-effort` because directory rename races are not atomic with that check. Direct-child no-replace renames borrow already-retained parents without another `F_GETPATH`; deeper paths retain the guarded reopen. Publication uses `renameat` for replacement and `renameatx_np(RENAME_EXCL)` for no-replace; owned-tree cleanup uses descriptor-relative `openat`/`unlinkat`.
+- Windows uses handle-relative `NtCreateFile`, rejects reparse points during root-bounded traversal, and uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer. The dedicated retained-directory `renameNoReplaceWithIdentity` primitive compares its required exact source receipt with the handle opened for rename before mutation. Its internal mismatch status is normalized to public `path-mismatch`; the legacy four-argument `renameNoReplace` export and its other callers are unchanged. Owned trees are deleted through exact opened handles with `FileDispositionInfoEx`; symlink/reparse entries in owned trees are removed as leaves and never traversed. Descriptors crossing N-API are converted only by the host executable's paired `uv_get_osfhandle` and `uv_open_osfhandle` exports. A runtime without both exports is unsupported for these native operations; the binding never guesses a raw HANDLE or uses a foreign CRT descriptor table. Descriptor-producing operations also require that same host's synchronous libuv close and request-management APIs before exporting an owned descriptor.
+
+`replaceDirectoryAtomic()` requires `renameNoReplaceWithIdentity` before it
+creates a missing target parent. On POSIX the dedicated entry point keeps the
+existing pre-dispatch exact receipt fence but dispatches direct-child names
+through the retained parents without another receipt, duplicate, reopen, or
+macOS `F_GETPATH`; the documented final source-name substitution window remains
+there. Deeper names retain guarded parent traversal.
 
 Native primitives back create-only and replacing pinned writes, no-clobber
 `Root.move()`, async sidecar creation, guarded publication, archive acceleration,
 and direct Windows ACL operations. Windows secure-file reads require
-descriptor-bound owner/DACL facts from the current helper; they do not use the
-standalone pathname inspector's command fallback. No-clobber moves fail with
+descriptor-bound owner/DACL facts. In native `auto` or `off` mode, a missing
+binding or capability can use a packaged PowerShell script that inspects the
+borrowed handle. Raw owner/DACL inspection and private-directory creation also support
+this fallback, subject to the [Windows security fallback prerequisites](install.md#windows-security-fallback).
+Each capability emits a path-free warning once per process and adds PowerShell
+startup and compilation overhead per call. Native `require` rejects missing
+capabilities, and native operation failures remain terminal. No-clobber moves fail with
 `helper-unavailable` when descriptor-relative parent admission or the atomic
 no-replace rename is unavailable; they never use a check followed by a replacing
 rename. Equivalent JavaScript paths remain available for documented

package/docs/native.md

@@ -17,7 +17,7 @@ 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 and creation-time Windows DACL guarantees fail explicitly
+Native-only formats fail explicitly
 instead of substituting a weaker implementation.
 
 ## The beneath model
@@ -115,6 +115,17 @@ 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
@@ -172,12 +183,26 @@ not bypass the byte limit.
 does not load the binding. Use asynchronous `sha256File()` for native hashing
 and cancellation that can respond while JavaScript callbacks run.
 
-Features without a safe JavaScript implementation, including no-clobber
-`Root.move()`, zstd/bzip2 TAR, Windows private-directory creation, and
+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.
@@ -219,15 +244,21 @@ 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 |
 |---|---|---|
-| Root-relative opens/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. Linux reports `kernel-atomic`; macOS and Windows report `best-effort`. 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. |
+| 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 | Supported. | Unsupported; typed `helper-unavailable`. |
+| 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. | Structured .NET owner/DACL inspection remains available to standalone pathname reporting. Secure-file reads fail closed without the descriptor capability. |
-| Windows private directory | Creation-time protected DACL. | Unsupported; no weaker pathname-only substitute. |
+| 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

package/docs/output.md

@@ -49,6 +49,12 @@ 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,

package/docs/path-prefix.md

@@ -56,6 +56,16 @@ 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

package/docs/path-suffix-aliases.md

@@ -36,6 +36,7 @@ type ProbePathSuffixAliasesOptions = {
   directory: string;
   left: string;
   right: string;
+  maxDepth?: number;
   shouldProbeCaseVariants?: (leftNfc: string, rightNfc: string) => boolean;
 };
 
@@ -44,9 +45,11 @@ function probePathSuffixAliasesSync(
 ): boolean | undefined;
 ```
 
-The helper reads and validates `directory`, then resolves it to an absolute path
-before reading the suffixes or predicate. Later option getters or the predicate
-cannot retarget a relative directory by changing the working directory. When
+The helper reads `directory`, rejects non-string values and supplied paths longer
+than 32,768 code units, then rejects NUL-containing inputs. It resolves the path
+to an absolute path and applies the same limit to that result before reading
+`maxDepth`. Each option is read once. Later option getters or the predicate cannot retarget a
+relative directory by changing the working directory. When
 filesystem observations are needed, the directory is canonicalized and its
 identity is checked; an initial directory alias can be followed.
 
@@ -56,26 +59,68 @@ inputs are rejected with `TypeError`. Windows additionally rejects drive-relativ
 components, colons, and reserved device names, including device aliases with
 extensions or trailing ignored characters. On POSIX, backslashes and colons are
 ordinary filename characters. The optional predicate must be a function.
+`maxDepth` defaults to `32` and must be a non-negative safe integer; invalid
+values, including `Infinity`, throw `RangeError` before mutation or an
+identical-suffix return. A value of `0` admits no ordinary nonempty suffix.
 
 Both suffixes and the predicate are validated before the identical-suffix fast
 path. Identical, valid, within-budget suffixes return `true` without filesystem
 access or a predicate call. This does not prove that the directory exists or that
 the suffix can be created.
 
-## Fixed resource limits
+The forward-observation allowance never exceeds 32,768, even with a large
+`maxDepth`. A deeper or repeatedly colliding probe can return `undefined` when
+that ceiling is reached. Reverse cleanup still runs outside this allowance.
 
-These limits apply to one call and cannot be raised through options:
+## Resource budgets
+
+The default limits for one call are:
 
 | Resource | Limit | On exceeding the limit |
 |---|---|---|
 | Each supplied suffix | 8,192 UTF-16 code units | `RangeError` before mutation |
 | Supplied and resolved directory paths | 32,768 UTF-16 code units each | `RangeError` before mutation |
-| Each suffix's component count | 32 | `RangeError` before mutation |
+| Each suffix's component count | `maxDepth`, default 32 | `RangeError` before mutation |
 | Directory-creation attempts | 128 | `undefined` after cleanup |
 | Successfully created probe directories | 64 | `undefined` after cleanup |
 | Forward filesystem observations | 4,096 | `undefined` after cleanup |
 | Each generated actual path | 32,768 UTF-16 code units | `undefined` after cleanup |
 
+### Deeper observations
+
+Applications comparing deeper prospective paths can explicitly raise `maxDepth`:
+
+```ts
+const prefix = "future/".repeat(32);
+const aliases = probePathSuffixAliasesSync({
+  directory: "/trusted/existing-directory",
+  left: `${prefix}Report.sqlite`,
+  right: `${prefix}report.sqlite`,
+  maxDepth: 33,
+});
+```
+
+The 8,192-code-unit suffix limit and 32,768-code-unit path limits remain fixed.
+Ordinary-component validation, Windows path controls, identity checks, and
+cleanup rules also remain unchanged.
+
+Operation budgets grow proportionally from the actual admitted suffix depth,
+not the requested `maxDepth`. For actual depth `D`, let `B = max(32, D)`.
+Directory-creation attempts are limited to `4 × B`, successfully created
+directories to `2 × B`, and forward filesystem observations to `min(32,768, 4 × B²)`.
+The quadratic observation allowance accommodates rechecks of owned ancestors.
+
+For example, 33 components allow 132 creation attempts, 66 created directories,
+and 4,356 forward observations; 65 components allow 260, 130, and 16,900.
+Specifying a large `maxDepth` for a short suffix keeps the original budgets.
+The suffix-length limit bounds actual depth to at most 4,096, so every budget
+remains a finite safe integer.
+
+Admission does not guarantee a boolean result. Repeated collisions, many
+normalization probes, filesystem limits, or identity failures can exhaust the
+budget or prevent an observation. The helper then returns `undefined` after
+cleanup attempts; callers must preserve their explicit ambiguity policy.
+
 Input limits are checked even for identical suffixes. Dynamic budgets count work
 across the whole call, including collision retries; removing a probe does not
 restore its creation budget. Cleanup is still attempted when a forward budget is