@openclaw/fs-safe 0.15.0 → 0.17.0

package/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`.

package/docs/durability.md

@@ -69,6 +69,49 @@ 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.
+
+Caller-supplied receipts may use `DirectoryReceipt<BigIntStats>` with the result
+of `lstat(path, { bigint: true })`. `pinDirectory()`, `syncDirectory()`,
+`syncDirectorySync()`, `publishFileExclusive()`'s `parentReceipt`, and
+`stageFileInDirectory()` accept both numeric and bigint receipt inputs.
+`DirectoryReceipt` without a type argument and all returned durability receipts
+still expose numeric `Stats`, including working type predicates and Date
+properties. Bigint metadata is projected from the supplied observation, retaining
+fractional timestamps and the private exact device/inode identity.
+
+```ts
+import { lstatSync, realpathSync, type BigIntStats } from "node:fs";
+import { syncDirectorySync, type DirectoryReceipt } from "@openclaw/fs-safe/durability";
+
+const directoryPath = "/srv/backups/sqlite";
+const receipt: DirectoryReceipt<BigIntStats> = {
+  path: directoryPath,
+  realPath: realpathSync(directoryPath),
+  identity: lstatSync(directoryPath, { bigint: true }),
+};
+// Keep this receipt across the application's publication operation.
+const outcome = syncDirectorySync(receipt);
+```
+
 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 +137,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
 
@@ -252,6 +299,11 @@ pathname without reopening the file and repeat the symlink and file-type checks.
 POSIX opens are nonblocking, so a raced FIFO or device is rejected after
 descriptor inspection rather than waiting for a writer.
 
+A pathname hash reports failure to close its owned descriptor after successful
+hashing. If hashing, admission, or cancellation already failed, that original
+failure remains primary even when close also fails. This also applies to
+`sha256FileSync()`; borrowed handles and descriptors remain caller-owned.
+
 When the optional binding is active, hashing runs as an async native task and
 does not occupy the JavaScript event loop with digest updates. With native mode
 `off`, or in `auto` when no binding loads, the fallback performs asynchronous
@@ -323,6 +375,13 @@ this receipt instead of inferring ownership from path existence. The original
 failure remains available as `cause`. Failures before target creation retain
 their existing error shape and do not claim a cleanup result.
 
+Source and target identities are checked again after successful or unsupported
+directory synchronization, while their descriptors remain owned. A late
+verification failure retains its strategy's verification phase and is not a
+directory-sync failure. Completed copied targets stay pinned during conditional
+cleanup; substituted entries remain untouched. Returned numeric metadata comes
+from the retained target descriptor and grants no continuing pathname authority.
+
 ### Directory-sync failure policy
 
 `onSyncFailure` applies only after target creation and content/identity fencing

package/docs/file-contents.md

@@ -0,0 +1,68 @@
+# Exact file comparison
+
+`sameFileContentsSync()` compares the bytes of two already-open regular files,
+starting at offset zero. It uses bounded buffers and completes positive short
+reads independently on each descriptor. A `true` result requires matching bytes
+and observed EOF on both inputs; a difference can return `false` immediately.
+
+```ts
+import fs from "node:fs";
+import { sameFileContentsSync } from "@openclaw/fs-safe/advanced";
+
+const source = fs.openSync("/trusted/source.sqlite", "r");
+try {
+  const copy = fs.openSync("/trusted/copy.sqlite", "r");
+  try {
+    console.log(sameFileContentsSync(source, copy, { maxBytes: 256 * 1024 * 1024 }));
+  } finally {
+    fs.closeSync(copy);
+  }
+} finally {
+  fs.closeSync(source);
+}
+```
+
+## Signature
+
+```ts
+type SameFileContentsOptions = { maxBytes?: number };
+
+function sameFileContentsSync(
+  leftFd: number,
+  rightFd: number,
+  options?: SameFileContentsOptions,
+): boolean;
+```
+
+Both descriptors must be open regular files. Nonregular inputs throw
+`FsSafeError("not-file")`; underlying filesystem errors propagate unchanged.
+Passing the same descriptor twice is allowed, but does not bypass validation,
+the byte limit, or reads. File sizes are checked against the limit, but are not
+used as proof that contents match or that EOF has been reached.
+
+## Bounds and ownership
+
+`maxBytes` is a limit for each file, not their combined size. It accepts a
+non-negative safe integer or `Infinity`; omission imposes no caller-selected
+limit. Invalid limits throw `RangeError` before filesystem work. Comparisons
+cannot exceed `Number.MAX_SAFE_INTEGER` bytes because positions must remain
+exactly representable.
+
+A reported file size above the limit throws `FsSafeError("too-large")` before
+reading. At the limit, the comparison reads at most one additional byte from
+each input to prove EOF; any observed overflow throws the same error. A
+matching prefix is never reported as complete equality. An early mismatch
+does not scan the remaining bytes or promise to detect later errors or growth.
+A zero-byte limit admits two empty files. Memory use is at most two 1 MiB
+payload buffers, regardless of file size.
+
+The operation neither changes the descriptors' current offsets nor closes
+them, including on failure. It performs no writes, hashing, pathname lookup,
+or identity comparison. Callers retain path admission, hardlink policy,
+descriptor lifetime, and any before/after mutation-fingerprint checks. A
+comparison is not a snapshot of concurrently modified files; applications
+requiring stable contents must retain their existing coordination and checks.
+
+Use [`readFileWindowFullySync()`](positional-read.md) for a selected byte
+window and [bounded descriptor reads](advanced.md#files-and-identity) when the
+caller needs the file contents in memory.

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.md

@@ -146,10 +146,11 @@ where lower latency matters more than crash-durability.
 
 Synchronous variant. It pretty-prints with two spaces, appends a newline,
 creates parents at `0o700`, writes at `0o600`, and synchronizes the parent
-directory best-effort. File-mode tightening carries the staged bigint identity
-through rename and applies `fchmod` only when the reopened descriptor and current
-pathname still name that same single-link regular file; a swap is preserved and
-skips this best-effort step. It has no options bag. On `EPERM`/`EEXIST`, its legacy
+directory best-effort. A retained staging descriptor carries the exact bigint
+identity through rename and file-mode tightening. Publication and cleanup never
+adopt a substituted temporary file: a changed identity, type or link count rejects
+the write and leaves the replacement untouched. A swap detected after publication
+also rejects without deleting or changing the replacement. It has no options bag. On `EPERM`/`EEXIST`, its legacy
 compatibility path removes the existing destination and retries the staged-file
 rename, so that fallback is temporarily non-atomic while retaining the staged
 file's `0600` mode; use the async `writeJson()`/`replaceFileAtomic()` surfaces

package/docs/local-roots.md

@@ -83,6 +83,8 @@ An existing non-directory component cannot be traversed further, including by
 The asynchronous helper opens the candidate through the matched [`Root`](root.md),
 so no-follow, identity, hardlink, device-path, and byte-limit checks happen at
 the read itself.
+Link policies are captured once before root initialization and reused for every
+candidate, so replacing options while a read is pending cannot weaken admission.
 
 ```ts
 type ReadLocalFileFromRootsOptions = LocalRootsInputOptions & {

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/mutation-policy-proof.md

@@ -44,9 +44,11 @@ new placeholder, and before publishing to an existing symlink-selected destinati
 They verify alias binding, destination preservation, observed placeholder/stage
 states, and cleanup before fixture teardown. The default native-off and explicit
 `verify-content-with-lock` native-require configurations both select the existing
-Windows JS buffer writer. The compatibility route is expected not to load the
-addon; the receipt does not mislabel this as native publication or evidence that
-content-verification fallback or lock contention was exercised.
+Windows JS buffer writer. In native-require mode, the compatibility route loads
+the addon to publish its retained sidecar lock through `Root.create`; the payload
+writer remains JS. The receipt does not mislabel this as native payload
+publication or evidence that content-verification fallback or lock contention
+was exercised.
 
 ## Bounds and interpretation
 

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
@@ -109,8 +117,13 @@ 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
@@ -76,14 +76,14 @@ whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
   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 owns a
-close-on-exec duplicate for inspection, leaves the caller's descriptor and file
-position alone, and never reopens a pathname. Darwin's `acl_get_entry` returns
+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,
-prove volume ownership enforcement, or add ACL enforcement to private writers
-and secure readers outside the clone path.
+reported as absence. These facts do not classify individual ACE permissions or
+prove volume ownership enforcement; each caller applies its own security policy.
 
 ## Archives
 
@@ -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
@@ -236,8 +267,9 @@ infer native loading from timing.
 ## Loader security
 
 Importing fs-safe never executes a child process. Linux libc selection uses
-the Node process report, conventional musl library filenames, and the ELF
-`PT_INTERP` field of `process.execPath`. If all probes are inconclusive, the
+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