@openclaw/matrix 2026.9.5 → 2026.9.7

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

@@ -0,0 +1,154 @@
+# Quickstart
+
+Five minutes. By the end you will have a working `root()` and know how to read, write, atomically replace, and unpack an archive — without your code being able to escape the workspace.
+
+If you have used Go's `os.Root` / `OpenInRoot` or Rust's [`cap-std`](https://github.com/bytecodealliance/cap-std), this is the same shape: a capability-style handle that carries the boundary across every operation. The first thing to internalize is that you stop reasoning about *paths* and start reasoning about *the handle*.
+
+## 1. Build a root
+
+```ts
+import { root } from "@openclaw/fs-safe";
+
+const fs = await root("/srv/jobs/incoming", {
+  hardlinks: "reject",  // refuse files that are hardlinks of out-of-tree inodes
+  symlinks: "reject",   // refuse to traverse a symlink during open
+  mkdir: true,          // create missing parent dirs on write
+});
+```
+
+`root()` resolves the directory through the real filesystem (so symlinked roots become canonical) and verifies it exists. The defaults you pass apply to every call below; per-call options override them.
+
+If the root directory itself does not exist yet, `root()` throws `FsSafeError`
+with code `not-found`; create it before constructing the capability.
+`fs.ensureRoot()` is for generic code that needs to assert or recreate the root
+itself after a handle was successfully constructed. It does not accept a
+subpath and cannot bootstrap a root that prevented `root()` from returning.
+
+## 2. Read and write text
+
+```ts
+await fs.write("notes/today.txt", "hello\n");
+const text = await fs.readText("notes/today.txt");
+```
+
+Writes use a sibling temp file plus `rename`, so a partial write never appears at the destination. Reads open with `O_NOFOLLOW` where available and verify the opened fd matches the path identity before returning the buffer.
+
+`create()` is the don't-clobber variant of `write()` and throws `already-exists` when the target is already there:
+
+```ts
+await fs.create("notes/README.md", "seed\n"); // throws if it already exists
+```
+
+## 3. JSON, with parsing
+
+```ts
+type Config = { tokens: string[]; updatedAt: string };
+
+await fs.writeJson("state/config.json", { tokens: [], updatedAt: new Date().toISOString() }, {
+  space: 2,
+});
+
+const config = await fs.readJson<Config>("state/config.json");
+```
+
+`writeJson` stringifies and writes atomically. `readJson` reads through the same boundary and parses; validate the shape at your application boundary if it came from a less-trusted source.
+
+## 4. Move and remove
+
+```ts
+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()` 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
+
+```ts
+const here = await fs.exists("state/config.json"); // boolean
+const stat = await fs.stat("state/config.json");   // { isFile, isDirectory, size, mtimeMs, ... }
+const names = await fs.list("state");              // string[]
+const entries = await fs.list("state", { withFileTypes: true }); // DirEntry[]
+```
+
+`exists`, `stat`, and `list` are boundary-checked but **do not pin a later operation** to the same filesystem object. For operation-local identity checks, use `read()`, `open()`, `write()`, `create()`, `copyIn()`, `move()`, or `remove()`. Linux native beneath opens are kernel-atomic; other mechanisms remain best-effort as documented in the [security model](security-model.md#containment-guarantees-by-platform).
+
+## 6. Catch escapes
+
+```ts
+import { FsSafeError } from "@openclaw/fs-safe";
+
+try {
+  await fs.write("../escape.txt", "x");
+} catch (err) {
+  if (err instanceof FsSafeError && err.code === "outside-workspace") {
+    // log, count, drop the request
+  } else {
+    throw err;
+  }
+}
+```
+
+Error codes are a closed union — branch on `err.code` instead of matching message text. The full list lives in the [Errors](errors.md) reference.
+
+## 7. Replace a config file atomically
+
+```ts
+import { replaceFileAtomic } from "@openclaw/fs-safe/atomic";
+
+await replaceFileAtomic({
+  filePath: "/srv/jobs/incoming/state/config.json",
+  content: JSON.stringify(state, null, 2),
+  mode: 0o600,
+  syncTempFile: true,
+  syncParentDir: true,
+});
+```
+
+Use `replaceFileAtomic` directly when you have an absolute path you trust and want sibling-temp + rename without going through `root()`. See [Atomic writes](atomic.md).
+
+## 8. Unpack a ZIP
+
+```ts
+import { extractArchive, resolveArchiveKind } from "@openclaw/fs-safe/archive";
+
+const kind = resolveArchiveKind("upload.zip");
+if (!kind) throw new Error("unsupported archive");
+
+await extractArchive({
+  archivePath: "/srv/jobs/incoming/uploads/upload.zip",
+  destDir: "/srv/jobs/incoming/extracted",
+  kind,
+  timeoutMs: 15_000,
+  limits: {
+    maxArchiveBytes: 256 * 1024 * 1024,
+    maxEntries: 50_000,
+    maxExtractedBytes: 512 * 1024 * 1024,
+    maxEntryBytes: 256 * 1024 * 1024,
+    maxMetaEntryBytes: 1024 * 1024,
+    maxEntryPathComponents: 64,
+  },
+  entryModes: "clamp",
+});
+```
+
+Extraction stages into a private dir and merges through the same boundary used by direct writes, so a symlinked entry can't trick the merge into following an out-of-tree path. See [Archive extraction](archive.md).
+
+## 9. Get a private scratch directory
+
+```ts
+import { withTempWorkspace } from "@openclaw/fs-safe/temp";
+
+await withTempWorkspace({ rootDir: "/srv/jobs/tmp", prefix: "build-" }, async (workspace) => {
+  await workspace.copyIn("input.bin", "/tmp/source.bin");
+  // ...do work in workspace.dir; auto-cleaned on exit
+});
+```
+
+The directory is mode `0700` under the caller-provided root, and cleanup runs when the callback returns or throws. Compatible cleanup remains available without native support; pass `cleanupSafety: "require-bounded"` to require native no-replace quarantine and descriptor-bounded tree removal before creating a child. Cleanup preserves raced or ambiguous entries under a private quarantine name. See the [temp workspace compatibility and security contract](temp.md#private-temp-workspaces).
+
+## Where to next
+
+- [Security model](security-model.md) — exactly what the boundary defends against, what it does not.
+- [Root API](root.md) — every method on the `Root` handle, including streaming and reader callbacks.
+- [Errors](errors.md) — the full code union and what each one means.

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

@@ -0,0 +1,196 @@
+# Reading
+
+The `Root` handle exposes five read shapes. Pick the narrowest one that gives you what you need — narrower shapes do less work and surface fewer footguns.
+
+```ts
+const result = await fs.read("notes/today.txt");        // { buffer, containment, realPath, stat }
+const text   = await fs.readText("notes/today.txt");    // string
+const bytes  = await fs.readBytes("image.png");         // Buffer
+const json   = await fs.readJson<Config>("config.json"); // T
+const opened = await fs.open("large.log");               // FileHandle for streaming
+```
+
+## What every read does
+
+Identity and containment checks use brief synchronous metadata calls, like Node's module resolution, while file data is read asynchronously. Canonical paths retain Node's native realpath spelling, including expansion of Windows short paths.
+
+The same observation rule applies to archive extraction, copy, publication, move,
+directory modes, and supporting lock, queue, and secret-file operations. Opens,
+data transfers, durability syncs, filesystem mutations, and closes retain their
+existing asynchronous behavior. Custom filesystem adapters retain their async
+metadata interface.
+
+Regardless of shape, every read goes through the same boundary checks:
+
+1. Resolve the input lexically against the canonical real root.
+2. Reject a lexically explicit unsafe device or process-fd namespace (`device-path`). This check precedes component alias policy because paths such as `/dev/fd` are themselves symlinks on common Linux hosts.
+3. Resolve path components and reject anything that escapes the root (`outside-workspace`).
+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`), 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
+`open()` hands the descriptor to its caller. It is a sequence of filesystem
+observations, not an atomic kernel pathname/open primitive, so a hostile peer can
+still race the namespace after the last observation. Standalone absolute-file
+helpers have no captured `Root` identity and do not claim this replacement-root
+fence; use a `Root` for untrusted paths.
+
+## Read shapes
+
+### `fs.read(rel, options?)`
+
+The full result. Use it when you need both the bytes and the verified `realPath` or `stat`:
+
+```ts
+const { buffer, containment, realPath, stat } = await fs.read("notes/today.txt");
+console.log(`${stat.size} bytes at ${realPath}`);
+```
+
+### `fs.readText(rel, options?)`
+
+`buffer.toString(encoding)`. Defaults to `"utf8"`; encoding is a per-call text
+option, not a `RootDefaults` field:
+
+```ts
+const utf16 = await fs.readText("doc.txt", { encoding: "utf16le" });
+```
+
+### `fs.readBytes(rel, options?)`
+
+The buffer alone. Useful when you don't care about the realPath or stat:
+
+```ts
+const png = await fs.readBytes("image.png");
+```
+
+### `fs.readJson<T>(rel, options?)`
+
+`readText` + `JSON.parse`. The generic is a *cast*, not a validator — validate the parsed value at your application boundary if it came from a less-trusted source.
+
+```ts
+type Config = { tokens: string[] };
+const config = await fs.readJson<Config>("config.json");
+```
+
+For tighter control over malformed-or-missing JSON, use the standalone helpers in [`@openclaw/fs-safe/json`](json.md): `tryReadJson` (returns `null` on missing/invalid) vs `readJson` (throws).
+
+### `fs.open(rel, options?)`
+
+Returns a `FileHandle` plus `containment: "best-effort"`, the verified `realPath`, and `stat`. Use this for streaming or partial reads, and **always close the handle**:
+
+```ts
+const opened = await fs.open("large.log");
+try {
+  const stream = opened.handle.createReadStream();
+  for await (const chunk of stream) {
+    process.stdout.write(chunk);
+  }
+} finally {
+  await opened.handle.close();
+}
+```
+
+## Read options
+
+```ts
+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" | "follow-parents-within-root"; // override defaults.symlinks
+};
+```
+
+`maxBytes` is enforced eagerly: the library reads up to `maxBytes + 1` and throws `too-large` if there is more, so a hostile target cannot silently exhaust memory. Values must be non-negative safe integers or positive `Infinity`; zero is an active cap, while `Infinity` disables it. Explicitly forwarding `undefined` preserves the Root default.
+
+`nonBlockingRead` remains as a compatibility hint. Safe reads always add the platform's nonblocking open flag where available so a raced FIFO cannot pin a worker indefinitely; regular-file descriptor reads retain normal Node behavior.
+
+## `readAbsolute()` and `reader()`
+
+Some APIs hand you an absolute path that the caller has already produced. Going back to a relative form just to call `read()` is awkward, so the library exposes:
+
+```ts
+fs.readAbsolute(absPath, options?)   // ReadResult, abs path must be inside the root
+fs.reader(options?)              // (path) => Promise<Buffer>
+```
+
+`readAbsolute` accepts absolute paths using either the configured root spelling
+or its canonical real path. This includes roots configured through a directory
+symlink or Windows junction. Anything outside the root throws
+`outside-workspace`. It also accepts relative paths for compatibility, but use
+`read()`/`readBytes()` when the input contract is explicitly relative.
+
+`reader()` returns a closure that takes either a relative or an absolute path and returns a Buffer. Useful for plugging `fs-safe` into framework loader hooks:
+
+```ts
+const load = fs.reader({ maxBytes: 4 * 1024 * 1024 });
+await someLibrary.parseTemplate({ load });
+```
+
+## Inspection vs reading
+
+`fs.exists`, `fs.stat`, and `fs.list` are advisory. They are safe to call to drive UI or decisions, but they do **not** pin the file:
+
+```ts
+if (await fs.exists("notes/today.txt")) {
+  // the file existed when stat() ran — it may not now
+  const text = await fs.readText("notes/today.txt"); // this is the call that pins
+}
+```
+
+A symlink swap between `exists` and `readText` is checked again by the read; the boundary and its documented race window are per-call.
+
+## Streaming patterns
+
+### Read into a writable stream
+
+```ts
+import { pipeline } from "node:stream/promises";
+
+const opened = await fs.open("large.log");
+try {
+  await pipeline(opened.handle.createReadStream(), process.stdout);
+} finally {
+  await opened.handle.close();
+}
+```
+
+### Read in chunks
+
+```ts
+const opened = await fs.open("large.bin");
+try {
+  const buf = Buffer.alloc(64 * 1024);
+  let off = 0;
+  while (true) {
+    const { bytesRead } = await opened.handle.read(buf, 0, buf.length, off);
+    if (bytesRead === 0) break;
+    consume(buf.subarray(0, bytesRead));
+    off += bytesRead;
+  }
+} finally {
+  await opened.handle.close();
+}
+```
+
+## Common errors
+
+- **`outside-workspace`** — relative path escaped the root, or `readAbsolute` got an absolute path outside.
+- **`not-found`** — the file is gone.
+- **`not-file`** — you read a directory or a non-regular file (FIFO, socket, …).
+- **`device-path`** — the path targets a known unsafe device or process fd path.
+- **`symlink`** — a path component is a symlink and the policy is `reject`.
+- **`path-mismatch`** — opened fd identity did not match the resolved path. Almost always a TOCTOU swap by something else.
+- **`hardlink`** — `hardlinks: "reject"` saw `nlink > 1`.
+- **`too-large`** — read exceeded `maxBytes`.
+
+See [Errors](errors.md) for the full list.
+
+## See also
+
+- [Writing](writing.md) — companion verbs for produce-side I/O.
+- [JSON files](json.md) — standalone strict/lenient JSON helpers.
+- [Secure file reads](secure-file.md) — pinned absolute file reads with permission checks.

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

@@ -0,0 +1,193 @@
+# Regular file helpers
+
+The advanced `regular-file` helpers provide direct read/append/stat helpers for absolute file paths, with an explicit "regular file or nothing" contract. Useful when you have a trusted absolute path and want a thin layer on top of `fs` that:
+
+- refuses non-regular files (directories, FIFOs, sockets, symlinks)
+- enforces a `maxBytes` read cap
+- separates "missing" from "io-error" in the result type
+
+```ts
+import {
+  readRegularFile,
+  readRegularFileSync,
+  appendRegularFile,
+  appendRegularFileSync,
+  resolveRegularFileAppendFlags,
+  statRegularFile,
+  statRegularFileSync,
+  type AppendRegularFileOptions,
+  type RegularFileStatResult,
+} from "@openclaw/fs-safe/advanced";
+```
+
+## Stat
+
+### `statRegularFile(filePath)`
+
+Async. Returns:
+
+```ts
+type RegularFileStatResult =
+  | { missing: true }
+  | { missing: false; stat: Stats };
+```
+
+A non-regular file (directory, FIFO, symlink, …) throws. Missing paths return
+`{ missing: true }`; existing regular files return `{ missing: false, stat }`.
+
+```ts
+import { statRegularFile } from "@openclaw/fs-safe/advanced";
+
+const r = await statRegularFile("/var/log/app.log");
+if (r.missing) return;
+console.log(`size=${r.stat.size}`);
+```
+
+### `statRegularFileSync(filePath)`
+
+Synchronous variant. Same shape.
+
+## Read
+
+### `readRegularFile(params)`
+
+Async. Reads the entire file into a Buffer if it is a regular file, with `maxBytes` enforcement.
+
+```ts
+import { readRegularFile } from "@openclaw/fs-safe/advanced";
+
+const result = await readRegularFile({
+  filePath: "/var/log/app.log",
+  maxBytes: 4 * 1024 * 1024,
+});
+processLog(result.buffer);
+```
+
+The result is `{ buffer, stat }`. Missing files preserve the normal `ENOENT`
+shape; non-regular targets throw. Reads compare exact bigint identities from the
+preview, opened descriptor, and current path before consuming bytes; the returned
+`stat` remains numeric Node `Stats`. Unknown Windows identities receive one
+re-inspection without reopening; persistent unknowns or replacements throw
+`FsSafeError("path-mismatch")`.
+
+Throws `FsSafeError` with code `too-large` if the file exceeds `maxBytes`. Other I/O errors propagate as `NodeJS.ErrnoException`.
+
+### `readRegularFileSync(params)`
+
+Synchronous variant. Same shape; the only required field is `filePath`. `maxBytes` is optional.
+
+## Append
+
+### `appendRegularFile(options)`
+
+Async. Opens the file in append mode, writes data, closes. Refuses non-regular targets:
+
+```ts
+import { appendRegularFile } from "@openclaw/fs-safe/advanced";
+
+await appendRegularFile({
+  filePath: "/var/log/app.log",
+  content: `[${new Date().toISOString()}] ${line}\n`,
+  encoding: "utf8",
+});
+```
+
+### Options
+
+```ts
+type AppendRegularFileOptions = {
+  filePath: string;
+  content: string | Uint8Array;
+  encoding?: BufferEncoding; // default utf8 when content is string
+  maxFileBytes?: number;     // skip if the resulting file would exceed this
+  mode?: number;             // default 0o600
+  rejectSymlinkParents?: boolean;
+};
+```
+
+The helper refuses symlink and hardlinked final targets. Preview, opened
+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
+append; other open errors propagate unchanged. This safeguard does not change
+ordinary regular-file append semantics or require read permission.
+
+The requested mode is applied through the admitted descriptor **before** any
+content is appended, so an existing file is tightened first. On successful
+completion, explicitly requested POSIX special bits are reapplied after the
+content write, which can otherwise clear set-ID bits. An initial chmod failure
+leaves the content untouched; a write or final chmod failure can leave appended
+content and is not rolled back. Windows does not enforce POSIX mode semantics.
+
+### `appendRegularFileSync(options)`
+
+Synchronous. Same options and mode ordering. Writes the complete input through
+the already-open descriptor, including when an individual write is short.
+
+### `resolveRegularFileAppendFlags()`
+
+Helper that returns the append helpers' `O_WRONLY | O_APPEND | O_CREAT` flags,
+plus `O_NOFOLLOW` where the platform provides it and `O_NONBLOCK` on POSIX
+where available. Windows flags are unchanged:
+
+```ts
+import { resolveRegularFileAppendFlags } from "@openclaw/fs-safe/advanced";
+
+const flags = resolveRegularFileAppendFlags();
+```
+
+## Difference from `Root` methods
+
+| `regular-file` | `Root` |
+|---|---|
+| Absolute paths only. | Relative to the root. |
+| Verifies path and descriptor identity around reads. | Enforces the same checks within a trusted root. |
+| Caller must be confident the path is trusted. | Boundary check is automatic. |
+| Stat reports missing explicitly; reads throw on missing/non-file. | Throws `FsSafeError` with `code`. |
+
+If your call site already trusts the path (it came from your own config, not a caller), `regular-file` is a thinner, faster surface. If the path is caller-influenced, prefer `root()` or wrap in [`pathScope()`](path-scope.md).
+
+## Common patterns
+
+### Read a config file if it's there, else seed
+
+```ts
+const info = await statRegularFile("/etc/app/config.json");
+if (info.missing) {
+  await writeJson("/etc/app/config.json", defaultConfig);
+} else {
+  const r = await readRegularFile({
+    filePath: "/etc/app/config.json",
+    maxBytes: 64 * 1024,
+  });
+  applyConfig(JSON.parse(r.buffer.toString("utf8")));
+}
+```
+
+### Cheap "exists and is a file" check
+
+```ts
+const r = await statRegularFile(p);
+if (r.missing) return false;
+return true;
+```
+
+### Bounded log tail
+
+```ts
+const r = await readRegularFile({ filePath: logPath, maxBytes: 1 * 1024 * 1024 });
+return r.buffer.toString("utf8").split("\n").slice(-100);
+```
+
+## See also
+
+- [Reading](reading.md) — `Root` reads with boundary checks.
+- [Atomic writes](atomic.md) — for atomic write semantics, prefer `replaceFileAtomic`.
+- [`fs.appendFile`](https://nodejs.org/api/fs.html#fsappendfilepath-data-options-callback) — Node's stock append, without regular-file gating.

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.