@openclaw/openshell-sandbox 2026.9.5 → 2026.9.7

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

@@ -42,7 +42,7 @@ POSIX remediation strings shell-quote paths with whitespace or metacharacters
 and protect option-like paths with `--`, so they can be presented as commands
 without letting the inspected pathname add shell syntax.
 
-`inspectPathPermissions()` follows symlink targets for the effective mode but tells you whether the original path was a symlink. On POSIX it reports owner/group/world bits. On Windows it delegates to the ACL helpers below and also reports `ownerSid` plus `ownerTrusted` when ownership can be verified. `ownerTrusted` is true only for a local volume owned by the current user, LocalSystem, or built-in Administrators; remote filesystems fail closed. This remains a pathname reporting API with the fallbacks described below. `readSecureFile()` does not use those pathname fallbacks on Windows: it requires descriptor-bound native owner/DACL facts for the exact handle it reads.
+`inspectPathPermissions()` follows symlink targets for the effective mode but tells you whether the original path was a symlink. On POSIX it reports owner/group/world bits. On Windows it delegates to the ACL helpers below and also reports `ownerSid` plus `ownerTrusted` when ownership can be verified. `ownerTrusted` is true only for a local volume owned by the current user, LocalSystem, or built-in Administrators; remote filesystems fail closed. This remains a pathname reporting API with the fallbacks described below. `readSecureFile()` obtains descriptor-bound owner/DACL facts for the exact handle it reads, using native support or the packaged PowerShell/C# bridge in `auto` and `off` modes.
 
 ## Advanced Windows ACL helpers
 
@@ -69,9 +69,10 @@ resolveWindowsUserPrincipal(env);
 ```
 
 The fallback Windows inspector reads the owner and DACL together through one
-built-in Windows PowerShell/.NET query. It returns canonical SIDs and numeric
-access masks, so Unicode paths and account names do not pass through lossy
-console display text. `inspectWindowsAcl()` uses native descriptor facts for
+built-in Windows PowerShell/.NET query. The query addresses its JSON command by
+module name and limits module discovery to PowerShell's bundled system modules.
+It returns canonical SIDs and numeric access masks, so Unicode paths and account
+names do not pass through lossy console display text. `inspectWindowsAcl()` uses native descriptor facts for
 complete local ACLs with nonzero inherited ACEs (or empty/null DACLs) when the
 optional Windows binding is available. It applies
 the same classifier to native facts and the fallback query, returning canonical
@@ -86,6 +87,12 @@ The advanced options retain `currentUserSid` as an explicit classification
 override and `principalTranslationFailed: true` as an immediate unverified
 result. The optional `principalSids` translation cache is still accepted but
 is no longer needed because the query returns SIDs directly.
+Injected executors must return the same structured success JSON as the built-in
+query: valid `ownerSid` and `currentUserSid` strings, an explicit boolean
+`remote`, and complete DACL facts (`complete`, `daclPresent`, and `aces`).
+Missing or nonboolean locality leaves both inspectors unverified; only
+`remote: false` establishes locality for owner trust. An explicit `remote: true`
+retains the ACL report but never grants trusted ownership.
 The existing classifier assigns principals to trusted, world, or group;
 trusted defaults include the current user, SYSTEM, and Administrators.
 The built-in query has a fixed 30-second process deadline. A command failure or timeout returns an
@@ -102,6 +109,19 @@ characters, including a trailing `…` when truncated. Diagnostics do not copy
 stdout or read target file contents. The separate `errorCause` retains the
 original exception for restricted local diagnosis; do not serialize or expose
 it as display text.
+Custom executors may reject with any JavaScript value. The fallback display
+formatter handles primitives directly and reads only string-valued `name` and
+`message` data descriptors through a small, fixed prototype budget. It does not
+coerce objects, invoke accessors, or inspect proxy targets; unavailable display
+facts use a bounded generic reason. Command fields follow the same best-effort
+data-descriptor rule. Raw string, `Buffer`, or genuine `Uint8Array` stderr
+retains the sanitization above. Byte stderr is copied through captured
+typed-array intrinsics into a private bounded snapshot before replacement-based
+UTF-8 decoding; receiver properties, iterators, constructors, and altered
+prototypes are not consulted. Detached or out-of-bounds byte views contribute
+no stderr detail. These diagnostic limits do not relax permission policy:
+incomplete owner or ACL inspection remains unverified, and `errorCause` remains
+the exact rejected value even when no display metadata is safe to obtain.
 The parser and remediation command builders remain on the advanced surface for
 CLIs processing captured `icacls` output or presenting an explicit repair.
 Runtime inspection does not parse that display text. A null DACL reports
@@ -158,10 +178,78 @@ Object-specific and other ACE layouts are not guessed: they are omitted,
 `complete` becomes false, and their numeric types appear in
 `unsupportedAceTypes`, allowing a security-sensitive caller to fail closed.
 Non-Windows systems return `{ status: "unsupported-platform", platform }`.
-Windows requires the native binding; if it is unavailable or forced
-off, the call throws `FsSafeError("helper-unavailable")`. The existing coarse
-`inspectPathPermissions()` API still owns its compatibility fallback and trust
-classification.
+Windows prefers the native binding. In native `auto` or `off` mode, a missing
+binding or capability uses the packaged PowerShell/C# bridge with
+the same raw ACE projection. Native `require` rejects either absence with
+`FsSafeError("helper-unavailable")` and starts no command. An available native
+query's failure is terminal. The existing coarse `inspectPathPermissions()` API
+still owns its compatibility fallback and trust classification.
+
+### Asynchronous batches
+
+Use `readOwnerAndDaclBatch()` when several paths, such as a directory and its
+ancestors, need inspection without blocking the caller's event loop:
+
+```ts
+import { readOwnerAndDaclBatch } from "@openclaw/fs-safe/permissions";
+
+const facts = await readOwnerAndDaclBatch(stagingDirectories, { timeoutMs: 60_000 });
+```
+
+```ts
+function readOwnerAndDaclBatch(
+  paths: readonly string[],
+  options?: { timeoutMs?: number },
+): Promise<OwnerAndDaclResult[]>;
+```
+
+Results use the same raw fact shape and SID spelling as `readOwnerAndDacl()`.
+They correspond one-for-one to input order, including duplicate paths. An empty
+array returns `[]` without dispatch. Other platforms return an
+`unsupported-platform` result for each path. Query failures, malformed facts,
+or missing/reordered response rows reject the entire batch; no partial facts
+are returned. Null DACLs, incomplete ACE lists and nonlocal observations remain
+raw facts for the caller's policy to evaluate.
+
+The call captures paths, options and native mode before awaiting. Windows
+relative paths are anchored to the current directory or selected drive at
+entry, without normalizing their remaining `.` or `..` components. Empty,
+nonstring, sparse or NUL-containing path entries and Windows namespace aliases
+reject before dispatch. The UTF-8 JSON input is limited to 16 MiB.
+
+An available native capability runs all queries in one isolated process using
+the current runtime executable. Its resolved native mode is forwarded explicitly;
+Node preload and module-search environment overrides are not inherited. An
+available native query's failure is terminal. In `auto` when the binding or
+capability is absent, or in `off`, one packaged PowerShell process reads the
+path array from stdin and compiles the existing C# bridge once. Native `require`
+rejects missing support before launching a process. No route launches one
+process per path or wraps synchronous parent-process queries in promises.
+
+`timeoutMs` defaults to 60,000 and applies to the whole process, including
+startup and fallback compilation. It must be an integer from 1 through
+2,147,483,647. Combined stdout and stderr are limited to 16 MiB. Success waits
+for process exit and both output pipes to close. Timeout and transport failure
+request termination, then retain the existing one-second settlement grace.
+The error's `processExitConfirmed` field, also retained in its cause receipt,
+distinguishes observed exit from an unconfirmed termination attempt. An
+unconfirmed child can still be reading after rejection; the operation returns
+no facts and owns no output files or artifact cleanup. Neither timing out nor
+receiving a successful kill request is reported as confirmed exit.
+
+The PowerShell fallback encodes and budgets each result while collecting it,
+instead of retaining every descriptor graph until the entire batch finishes.
+An encoded response that would exceed 16 MiB rejects with `too-large` before
+inspecting later paths. A query failure observed earlier retains its original
+error, and no partial facts are returned. Duplicate paths remain independent
+observations. This bounds accumulated encoded results, not total process memory:
+the current descriptor and row, decoded input, and runtime overhead still exist.
+
+Batch observations are point-in-time pathname facts, not a snapshot or a
+retained filesystem capability. The caller still owns ancestry trust, principal
+policy and authorization for subsequent operations. Existing singular queries
+and other command operations retain their 30-second deadline, 1 MiB output
+budget and documented failure behavior.
 
 ## Private directories
 
@@ -175,10 +263,11 @@ await createPrivateDirectory(sqliteDirectory);
 await openSqlite(path.join(sqliteDirectory, "sessions.sqlite"));
 ```
 
-On Windows with native support, this creates the directory and applies a
+On Windows, this creates the directory and applies a
 protected owner + LocalSystem + Administrators full-control DACL directly with
-an atomic security descriptor; no PowerShell or `icacls` process is launched.
-The native operation retains the parent and exact created-directory handles
+an atomic security descriptor. The native route launches no command. When its
+binding or capability is unavailable, native `auto` and `off` modes use the
+packaged PowerShell/C# bridge. Both routes retain the parent and exact created-directory handles
 through ACL and final pathname validation. If validation fails, it attempts only
 nonrecursive deletion through the created handle, preserving any pathname
 replacement. If cleanup also fails, the error retains the original failure and
@@ -203,13 +292,32 @@ also rejects explicit `.` and `..` components, including spellings such as
 `.\private` and `parent\..\private`, as a compatibility restriction. Simple
 relative names without these components remain supported.
 
-This API is Windows-only and native-only; it fails closed with
-`FsSafeError("helper-unavailable")` on other platforms, when native mode is off,
-or when the binding is unavailable. POSIX callers should create private
+This API is Windows-only; it fails closed with `FsSafeError("helper-unavailable")`
+on other platforms. Native `require` also fails if the binding or capability is
+missing and never starts a command. An available native operation's failure is
+terminal. POSIX callers should create private
 directories through their existing trusted-root creation policy rather than a
 pathname-only compatibility shim. Existing Windows permission inspection still
 retains its structured .NET compatibility fallback.
 
+The raw owner/DACL and private-directory fallbacks each emit one path-free
+`FS_SAFE_NATIVE_FALLBACK` warning per process. PowerShell startup and C#
+compilation add overhead to each call; install the native package for frequent
+operations. These routes run the package's readable, fixed scripts under normal
+system PowerShell policy; see the [Windows security fallback prerequisites](install.md#windows-security-fallback).
+If command support is unavailable, disallowed, or fails, the operation rejects.
+Private-directory creation never falls back to inherited permissions.
+The asynchronous creation command has a 30-second deadline. After a timeout or
+transport failure, fs-safe requests termination and waits at most one further
+second before rejecting and closing its output pipes. The error distinguishes
+observed process exit from an unconfirmed termination attempt. If the OS refuses
+termination, the command can still create the directory after rejection. An
+already-created object retains its protected DACL, but pathname validation and
+owned-handle cleanup may not finish. An error therefore does not prove the
+pathname is absent; a retry can report `EEXIST`. Before retrying or using the
+pathname, establish that the earlier operation stopped and verify any existing
+directory's security. The library does not attempt pathname-based cleanup.
+
 Use `createIcaclsResetCommand()` when you need a structured command and argv pair. Use `formatIcaclsResetCommand()` when you only need a remediation string for a user-facing message.
 
 ## Types

package/node_modules/@openclaw/fs-safe/docs/public-api.md

@@ -20,6 +20,9 @@ The root subpath also exports `openLocalFileSafely`, `readLocalFileSafely`, and
 `resolveOpenedFileRealPathForHandle` for trusted absolute-file composition.
 They do not create a root boundary around arbitrary caller input; prefer
 `root()` for untrusted paths.
+The handle resolver verifies exact descriptor and pathname identities, with one
+bounded retry for unknown Windows observations. It borrows the handle without
+reading, reopening, closing it, or changing its cursor.
 
 The error helpers are `categorizeFsSafeError` and `FsSafeErrorDetails`. The
 deprecated native-configuration bridge retains the `FsSafePythonConfig` type.
@@ -38,13 +41,19 @@ The lexical path surface additionally exports `isNodeError`,
 `UnsafeDeviceReadPathMatch`, `UnsafeDeviceReadPathOptions`, and
 `UnsafeDeviceReadPathReason`.
 
+`isPathRelativeEscape()` rejects absolute paths and relative paths that step
+above their starting directory at any point. Contained paths such as
+`dir/../file` remain relative. It accepts both separators on Windows; on POSIX,
+a backslash remains a literal filename character.
+
 The advanced root-file primitive exports `OpenRootFileParams`,
 `OpenRootFileSyncParams`, `RootFileOpenResult`, and
 `RootFileOpenFailureReason`. These are composition types for callers building
 their own pinned-open flow, not substitutes for the higher-level `Root` verbs.
 
-`copyFileHandle` and `CopyFileHandleOptions` transfer bytes between already-open
-regular files without taking over their cursors, lifetime, or publication.
+`copyFileHandle` and `copyFileDescriptorSync` share `CopyFileHandleOptions` to
+transfer bytes between already-open regular files without taking over their
+cursors, lifetime, or publication.
 See [borrowed-handle transfers](copy.md#borrowed-filehandle-transfers).
 
 `readDirectoryIdentity`, `assertDirectoryIdentitySync`, and `DirectoryIdentity`
@@ -70,6 +79,16 @@ missing relative suffixes beneath an existing directory using bounded temporary
 directory probes. The caller owns Unicode-pair policy, caching, and the fallback
 for `undefined`. See [path suffix alias probing](path-suffix-aliases.md).
 
+`retainSymlinkInDirectory` holds an explicitly identified POSIX symlink through
+exact-slot no-replace publication; its receipts use the `StagedSymlink*` and
+`PublishedSymlinkReceipt` types. See [staged symlinks](staged-symlink.md).
+
+`retainFileInDirectory` retains an existing Windows NTFS file through a native
+handle for explicit identity-bound retirement. It is described by
+`RetainFileInDirectoryOptions`, `RetainedFile`, `RetainedFileAdmission`,
+`RetainedFileExpected`, `RetainedFileIssue`, `RetainedFileReceipt`, and
+`RetainedFileResult`. See [retained Windows files](retained-file.md).
+
 ## Guest source
 
 `@openclaw/fs-safe/guest` exports `GUEST_FILESYSTEM_PYTHON`,
@@ -96,7 +115,8 @@ best-effort cleanup helper used by those queue flows.
 Permission inspection exposes `PermissionCheckOptions` and `SafeStatResult`.
 Private-directory creation uses `CreatePrivateDirectoryOptions`. Raw Windows
 descriptor facts use `OwnerAndDaclResult`, `WindowsAccessControlEntry`, and
-`WindowsAceFlags`.
+`WindowsAceFlags`. `readOwnerAndDaclBatch()` returns those same facts in input
+order through an isolated asynchronous batch with a whole-process timeout.
 
 Secure reads split their option and result shapes into
 `SecureFileTrustOptions`, `SecureFilePermissionOptions`,
@@ -122,8 +142,11 @@ parent/workspace descriptors; see the
 Atomic helper option and receipt types include
 `MovePathWithCopyFallbackOptions`, `ReplaceDirectoryAtomicOptions`,
 `ReplaceFileAtomicSyncOptions`, `ReplaceFileAtomicResult`,
-`ReplaceFileAtomicRestoreCleanup`, `ReplaceFileCopyFallbackRestorePolicy`, and
-`ReplaceFileDestinationHardlinkPolicy`.
+`ReplaceFileAtomicRestoreCleanup`, `ReplaceFileCopyFallbackRestorePolicy`,
+`ReplaceFileDestinationHardlinkPolicy`, and `ReplaceFileAtomicDestinationState`.
+The `assertBeforeMutation` option rechecks caller authority before new effects,
+and `onDestinationState` reports retained destination identities as
+`ReplaceFileAtomicDestinationState` values; see [atomic writes](atomic.md).
 
 The durability surface also exports the synchronous strict
 `syncDirectorySync`, plus `DirectoryReceipt`, `DurableDirectoryReceipt`,
@@ -134,6 +157,8 @@ The durability surface also exports the synchronous strict
 `Sha256FileSyncInput`, `Sha256FileOptions`, and `Sha256FileResult`.
 `sha256FileSync()` provides synchronous pathname or borrowed-descriptor hashing
 with the same byte-budget and digest-result contracts as `sha256File()`.
+`DirectoryReceipt<T>` accepts `Stats` or `BigIntStats` input metadata; its default
+type argument and returned durability receipts remain numeric `Stats`.
 
 ## Archives
 
@@ -148,6 +173,14 @@ Archive option and policy types are `ExtractArchiveOptions`,
 used by extractors. `resolvePackedRootDir` finds the single packed root when an
 archive layout permits it; neither helper weakens entry validation.
 
+## `watch`
+
+`@openclaw/fs-safe/watch` exports `watch()` plus `WatchScope`, `WatchEntry`,
+`WatchChange`, `WatchInvalidation`, `WatchFailure`, `WatchHealth`,
+`WatchOptions`, and `WatchSubscription`. Invalidations are advisory; guarded
+scans stay authoritative. See [filesystem observation](watch.md) for modes,
+budgets, `persistent`, and lifecycle.
+
 ## Keeping this list honest
 
 Every runtime and type name in `test/public-api.json` must appear somewhere in

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

@@ -60,7 +60,7 @@ await fs.move("notes/today.txt", "notes/archive/today.txt", { overwrite: true })
 await fs.remove("notes/archive/today.txt");
 ```
 
-`move()` defaults to no clobber. That mode requires the native helper so a concurrent target cannot be replaced between an absence check and the rename; without it, the call fails with `helper-unavailable`. Pass `{ overwrite: true }` when replacing the target is intentional. `remove()` works on files and empty directories. For non-empty directories, list and remove children first or use [`replaceDirectoryAtomic`](atomic.md#replacedirectoryatomic).
+`move()` defaults to no clobber. That mode requires the native helper so a concurrent target cannot be replaced between an absence check and the rename; without it, the call fails with `helper-unavailable`. Pass `{ overwrite: true }` when replacing the target is intentional. `remove()` removes files and empty directories by default. To remove a non-empty directory, pass `{ recursive: true }`; use `maxEntries`, `maxDepth`, and `signal` to bound the work. See [`root()`](root.md) for removal ordering, limits, and partial-removal semantics.
 
 ## 5. Inspect
 

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

@@ -28,7 +28,7 @@ Regardless of shape, every read goes through the same boundary checks:
 4. Reject `..` traversal and absolute spellings when they resolve outside the root. In-root absolute spellings remain accepted; `readAbsolute` makes that intent explicit.
 5. Open with `O_NOFOLLOW` where available. Any remaining symlink in the path triggers `symlink` unless the call's `symlinks` policy is `follow-within-root`.
 6. Compare the pre-open bigint path identity with the open fd, then perform one best-effort final admission: check the captured root identity, compare the policy-aware pathname with the fd, freshly canonicalize and re-admit that target inside the captured root, compare its exact bigint identity without following a final symlink with the fd, and check the root again. Both final pathname observations run even when their spellings match. An observed swap triggers `path-mismatch` or `outside-workspace`; a missing final path triggers `not-found`.
-7. If `hardlinks: "reject"`, refuse files with `nlink > 1` (`hardlink`).
+7. If `hardlinks: "reject"`, refuse files with `nlink > 1` (`hardlink`), including links introduced before either fresh final pathname observation. Root-file helpers apply the same final check when `rejectHardlinks` is enabled; directory admission is unaffected.
 8. If `maxBytes` is set, refuse reads larger than the cap (`too-large`).
 
 The final fence closes a rejected descriptor before any Root read consumes bytes or
@@ -100,7 +100,7 @@ type RootReadOptions = {
   hardlinks?: "reject" | "allow";   // override defaults.hardlinks
   maxBytes?: number;                // refuse reads larger than this many bytes
   nonBlockingRead?: boolean;        // compatibility hint; safe opens are already nonblocking where supported
-  symlinks?: "reject" | "follow-within-root"; // override defaults.symlinks
+  symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root"; // override defaults.symlinks
 };
 ```
 

package/node_modules/@openclaw/fs-safe/docs/regular-file.md

@@ -110,6 +110,9 @@ descriptor, and current pathname identities remain exact bigints through the
 append boundary; rounded-equal replacements and persistent unknown Windows
 identities reject before chmod or writing bytes. With
 `rejectSymlinkParents: true`, it also rejects symlinked ancestor directories.
+Supported option values are captured once before filesystem work, so replacing
+the content, encoding, mode or cap cannot change an in-flight append. Byte-array
+contents remain caller-owned; leave them unchanged until the append completes.
 
 On POSIX, `O_NONBLOCK` prevents a no-reader FIFO substituted before open from
 stalling admission. A confirmed non-regular target is refused before chmod or

package/node_modules/@openclaw/fs-safe/docs/retained-file.md

@@ -0,0 +1,115 @@
+---
+title: Retained Windows files
+description: "Explicit identity-bound retirement of an existing file; resource settlement is not persistence."
+---
+
+# Retain an existing Windows file
+
+`retainFileInDirectory` from `@openclaw/fs-safe/advanced` retains **one existing
+regular direct child**, without creating or deleting anything at admission.
+It requires the matching native package. There is no pathname-unlink fallback.
+The initial implementation supports fixed local NTFS drives only; other systems
+return `unsupported`.
+
+```ts
+import { retainFileInDirectory } from "@openclaw/fs-safe/advanced";
+
+const admission = retainFileInDirectory({
+  directory: producer.directory, // canonical C:\... spelling
+  parent: producer.parentIdentity, // exact bigint dev/ino
+  basename: producer.basename,
+  expected: producer.expected, // bigint dev/ino/size/mtimeNs/ctimeNs and SHA-256
+  assertBeforeMutation: () => producer.assertCurrentExclusiveAuthority(),
+});
+if (admission.status === "retained") {
+  using file = admission.file;
+  const outcome = file.remove(); // explicit; using alone does NOT delete
+  // outcome.persistence is always "not-proven".
+  producer.recordRetirementObservation(outcome);
+}
+```
+
+The producer must capture its expected identity, generation and bytes during its
+own creation/ownership protocol. Reading an arbitrary current pathname immediately
+before admission does **not** authenticate the producer. `Number` identities,
+zero/unknown identities, negative/overflowing identities, and malformed digests
+are rejected. A full opaque native volume/file ID is included in the receipt;
+no native handle or numeric descriptor is exposed. Receipts are immutable facts,
+not transferable authority.
+
+## Public types
+
+- `RetainFileInDirectoryOptions`: immutable admission inputs and synchronous authority.
+- `RetainedFileExpected`: exact producer identity, write generation and expected digest.
+- `RetainedFileAdmission`: a retained `RetainedFile` or a refusal/settlement result.
+- `RetainedFileReceipt`: immutable admitted facts, never reusable authority.
+- `RetainedFileResult`: separate disposition, namespace, resources and persistence facts.
+- `RetainedFileIssue`: phase, native code/message and optional original authority cause.
+
+## Admission and mutation custody
+
+The directory's ancestry is opened component by component without following
+reparse points, with delete sharing denied. Its exact expected parent identity
+and canonical path are checked. The file is opened relative to that retained
+parent, with write/delete sharing denied. Existing writer handles refuse
+admission; a read-oplock grant also excludes preexisting writable mapped
+sections. That oplock request is cancelled and joined before admission returns,
+while the no-write-sharing file handle remains open. No detached request remains.
+
+The opened file must match the expected exact NTFS identity, single-link regular
+type, write/change generation, size and SHA-256. Names with stream/device syntax,
+trailing-dot/space aliases and observed named data streams are unsupported.
+Readonly attributes and ACL denials are not repaired or overridden. Verification
+is synchronous and bounded by `maxBytes` (default 16 MiB, maximum 64 MiB).
+
+The original producer must retain **exclusive mutation custody for the entire
+file**, including alternate streams, attributes, security and hardlink creation.
+Windows read/write sharing is per-stream; it is not an application lock over
+all possible aliases. The helper rejects observed alternate streams and changed
+generations, but does not turn a point-in-time check into exclusion of concurrent
+alias/attribute operations. The synchronous `assertBeforeMutation` must check
+that this original authority is still current. Callers unable to establish that
+custody must not call `remove`. Privileged/raw-volume/kernel modifications are
+outside this capability's threat model.
+
+`remove()` admits authority once, revalidates the retained object, sets native
+handle disposition, closes the file, observes the name under the still-retained
+parent, then closes ancestry. No pathname is passed to unlink. Ordinary
+`dispose()` and `[Symbol.dispose]()` only close resources. Authority callbacks
+returning Promises, thenables, or synchronous or asynchronous generator objects
+are refused without deletion; generators are never advanced. Reentrancy is also
+refused, and even caught reentrancy poisons that attempt.
+Repeated settlement returns the original receipt without another mutation or
+another authority call. A copied receipt cannot be used to remove a replacement.
+`[Symbol.dispose]()` throws `FsSafeError` with the complete result in
+`error.details.result` if resource settlement is uncertain; `dispose()` returns
+that result directly. GC closes only and produces no settlement receipt; use
+explicit disposal.
+
+## Read the facts separately
+
+| Field | Meaning |
+| --- | --- |
+| `status` | `unsupported`, `not-attempted`, `preserved-mismatch`, `disposition-accepted`, `name-absent-after-settlement`, `failed`, or `indeterminate`. |
+| `disposition` | Whether native deletion was unattempted, accepted, rejected, or indeterminate. |
+| `namespace` | A post-file-close observation: absent, original, foreign, unknown, or not observed. Absence alone never authenticates prior deletion. |
+| `resources` | `closed` or `close-failed`; operation and close errors are retained together. An uncertain close is never retried against a possibly recycled handle. |
+| `persistence` | Always `not-proven`; no namespace persistence barrier was performed. |
+
+An accepted disposition can still have an unknown/foreign/original namespace
+observation or failed close. A later replacement may exist even after observed
+absence. Existing read handles can retain access to old bytes after the name is
+absent. Namespace observation does not certify all foreign handles are closed.
+An unexpected native binding failure is indeterminate, not success.
+
+## No persistence or service-transaction guarantee
+
+This API does not flush a volume, implement a journal, certify power-loss-safe
+unlink, or issue an application dependency release. Process-termination tests
+establish process-owned handle lifetime only, not crash/storage durability.
+
+An update transaction must independently qualify either a real namespace
+persistence barrier or original-owned durable recovery with correct ordering,
+generation binding and restart consumption. Until then it must retain its
+uncertain recovery/dependency state. Successful removal of one payload does not
+establish a committed multi-file transaction or justify deleting its receipt.