@openclaw/matrix 2026.9.6 → 2026.9.8

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

@@ -0,0 +1,352 @@
+# Permissions
+
+`@openclaw/fs-safe/permissions` contains the curated mode and permission inspection helpers used by secure file reads and by applications that want to report actionable permission problems.
+
+```ts
+import {
+  formatPermissionDetail,
+  formatPermissionRemediation,
+  inspectPathPermissions,
+} from "@openclaw/fs-safe/permissions";
+
+const perms = await inspectPathPermissions("/var/lib/app/auth.token");
+console.log(formatPermissionDetail("/var/lib/app/auth.token", perms));
+if (perms.ok && (perms.groupReadable || perms.worldReadable)) {
+  console.log(
+    formatPermissionRemediation({
+      targetPath: "/var/lib/app/auth.token",
+      perms,
+      isDir: false,
+      posixMode: 0o600,
+    }),
+  );
+}
+```
+
+## POSIX helpers
+
+```ts
+safeStat(path);
+inspectPathPermissions(path, options?);
+formatPermissionDetail(path, check);
+formatPermissionRemediation({ targetPath, perms, isDir, posixMode });
+modeBits(mode);
+formatOctal(bits);
+isWorldWritable(bits);
+isGroupWritable(bits);
+isWorldReadable(bits);
+isGroupReadable(bits);
+```
+
+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()` 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
+
+The low-level Windows ACL parser and `icacls` command builders live in `@openclaw/fs-safe/advanced`:
+
+```ts
+import {
+  createIcaclsResetCommand,
+  formatIcaclsResetCommand,
+  formatWindowsAclSummary,
+  inspectWindowsAcl,
+  parseIcaclsOutput,
+  resolveWindowsUserPrincipal,
+  summarizeWindowsAcl,
+} from "@openclaw/fs-safe/advanced";
+
+inspectWindowsAcl(path, { env, exec });
+parseIcaclsOutput(output, targetPath);
+summarizeWindowsAcl(entries, env);
+formatWindowsAclSummary(summary);
+formatIcaclsResetCommand(targetPath, { isDir, env });
+createIcaclsResetCommand(targetPath, { isDir, env });
+resolveWindowsUserPrincipal(env);
+```
+
+The fallback Windows inspector reads the owner and DACL together through one
+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
+SIDs in its `principal` fields with normalized rights tokens. Explicit `env` or
+`exec` options retain the query path. Disabled or unavailable native helpers,
+remote or incomplete descriptors, leaf symbolic links, and native query errors
+use the fallback. Explicit ACEs and zero-mask entries also retain the query so
+.NET continues to own its ACE ordering and normalization.
+Structured ACLs containing only canonical SIDs are classified directly from
+the current-user SID without requiring a separate account-name lookup.
+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
+unverified result (`source: "unknown"`) so callers fail closed. Advanced callers
+that inject a custom `exec` implementation own that executor's deadline.
+Failed owner and ACL inspections retain `error` text and an optional
+`errorDetail: PermissionCommandFailure` with `command`, integer `durationMs`,
+`timedOut`, `exitCode`, `signal`, and `stderr`. The type is exported from both
+`@openclaw/fs-safe/permissions` and `@openclaw/fs-safe/advanced`. Built-in
+execution measures elapsed time; injected execFile-shaped failures receive
+best-effort command diagnostics. Plain errors have no `errorDetail`.
+Display reasons and stderr escape control characters and are limited to 400
+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
+unrestricted access; an empty DACL grants nothing. Inherit-only ACEs do not
+apply to the inspected object, and deny ACEs never subtract coarse grants or
+claim effective-access evaluation. Unsupported ACE layouts remain unverified.
+
+When the native binding is available, `inspectPathPermissions()`
+reads the owner and DACL directly with Windows security APIs. It classifies the
+current user, LocalSystem, and built-in Administrators as trusted and reports
+the world/group read/write facts consumed by secure reads. Descriptor forms it
+cannot classify equivalently fall back to the structured .NET query; `mode: "off"` exercises that fallback deterministically.
+
+## Policy-free owner and DACL facts
+
+`readOwnerAndDacl()` exposes the direct Windows descriptor facts needed by a
+consumer that owns a principal allowlist. It deliberately does not decide
+which SID is trusted or calculate effective access. For example, snapshot
+staging can reject an incomplete descriptor and ignore inherit-only ACEs before
+applying its own exact SID policy:
+
+```ts
+import { readOwnerAndDacl } from "@openclaw/fs-safe/permissions";
+
+const facts = readOwnerAndDacl(stagingDirectory);
+if (facts.status === "unsupported-platform") {
+  throw new Error(`Windows ACL facts unavailable on ${facts.platform}`);
+}
+if (!facts.isLocal || !facts.daclPresent || !facts.complete) {
+  throw new Error("staging DACL cannot be evaluated completely");
+}
+
+for (const ace of facts.aces) {
+  if (ace.flags.inheritOnly) continue;
+  if (!trustedSids.has(ace.sid)) {
+    throw new Error(`unexpected staging principal: ${ace.sid}`);
+  }
+  evaluateMaskAndDenyOrder(ace.aceType, ace.mask);
+}
+```
+
+On Windows the supported result contains `ownerSid`, `currentUserSid`,
+`daclPresent`, `isLocal`, `complete`, `unsupportedAceTypes`, and ordered basic
+allow/deny `aces`. `currentUserSid` is the process token's `TokenUser` SID, so
+callers can compare it with the owner or their own allowlist without fs-safe
+applying trust policy. Each ACE has `{ sid, mask, aceType, flags }`; `flags`
+retains the raw byte and decoded
+`objectInherit`, `containerInherit`, `noPropagateInherit`, `inheritOnly`,
+`inherited`, `successfulAccess`, and `failedAccess` facts. SID strings are
+lowercase Windows SID notation. `daclPresent: false` represents a null DACL,
+which grants unrestricted access; it must not be mistaken for an empty DACL.
+
+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 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
+
+```ts
+import path from "node:path";
+import { createPrivateDirectory } from "@openclaw/fs-safe/permissions";
+
+const sqliteDirectory =
+  "C:\\Users\\me\\AppData\\Local\\OpenClaw\\private-databases";
+await createPrivateDirectory(sqliteDirectory);
+await openSqlite(path.join(sqliteDirectory, "sessions.sqlite"));
+```
+
+On Windows, this creates the directory and applies a
+protected owner + LocalSystem + Administrators full-control DACL directly with
+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
+includes the cleanup failure.
+
+Directory association checks compare the complete 64-bit volume serial and
+128-bit `FILE_ID_INFO` identity, including on ReFS. If that identity class is
+unavailable, the operation fails closed without a narrower file-index fallback.
+Validation confirms that the created directory is local, its DACL is protected
+from inheritance, and its final public pathname opens the same local directory.
+
+This is a point-in-time pathname association check. The function closes its
+handles before returning; callers must keep the pathname's ancestry trusted
+during subsequent use, including opening SQLite databases in the example above.
+The immediate parent and final directory must not be reparse points. Earlier
+ancestor reparse points can be followed; this API does not reject every reparse
+point in the full ancestry.
+
+Path components ending in a space or period are rejected before filesystem
+operations to avoid differing Win32 and native pathname interpretations. This
+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; 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
+
+```ts
+type PermissionCheck = {
+  ok: boolean;
+  isSymlink: boolean;
+  isDir: boolean;
+  mode: number | null;
+  bits: number | null;
+  source: "posix" | "windows-acl" | "unknown";
+  worldWritable: boolean;
+  groupWritable: boolean;
+  worldReadable: boolean;
+  groupReadable: boolean;
+  ownerSid?: string;
+  ownerTrusted?: boolean;
+  ownerError?: string;
+  aclSummary?: string;
+  error?: string;
+};
+```
+
+`ok: false` means the path itself could not be inspected. `ok: true` with `source: "unknown"` means basic stat information was available, but the platform-specific permission source could not be verified.
+
+## See also
+
+- [Secure file reads](secure-file.md) — fd-pinned reads that enforce these checks.
+- [Errors](errors.md) — permission-related `FsSafeError` codes.
+- [Native architecture](native.md) — direct Windows security descriptor mechanisms.
+- [Migrating to 0.5](migrating-to-0.5.md) — native-only feature checklist.

package/node_modules/@openclaw/fs-safe/docs/positional-read.md

@@ -0,0 +1,63 @@
+# Positional reads
+
+Use `readFileWindowFully()` and `readFileWindowFullySync()` to read a bounded
+window from an already-open file. They fill a caller-owned `Buffer`, completing
+short reads until the buffer is full or the file reaches EOF, and return the
+number of bytes read. They never allocate a payload buffer, close the descriptor,
+or change its current offset.
+
+```ts
+import { root } from "@openclaw/fs-safe";
+import { readFileWindowFully } from "@openclaw/fs-safe/advanced";
+
+const workspace = await root("/srv/workspace");
+await using opened = await workspace.open("large.log");
+const buffer = Buffer.allocUnsafe(4096);
+const bytesRead = await readFileWindowFully(opened.handle, buffer, 8192);
+const window = buffer.subarray(0, bytesRead);
+```
+
+## Signatures
+
+```ts
+type ReadFileWindowOptions = { signal?: AbortSignal };
+
+function readFileWindowFully(
+  handle: import("node:fs/promises").FileHandle,
+  buffer: Buffer,
+  position: number,
+  options?: ReadFileWindowOptions,
+): Promise<number>;
+
+function readFileWindowFullySync(
+  fd: number,
+  buffer: Buffer,
+  position: number,
+): number;
+```
+
+`position` and the exclusive window end (`position + buffer.length`) must be
+non-negative safe integers. Invalid ranges throw `RangeError` before reading.
+A zero-length buffer returns zero without I/O. Reading at or beyond EOF also
+returns zero. If EOF occurs within the window, only the returned prefix is
+written; the remaining buffer bytes stay unchanged. Always slice by the returned
+count before using an unsafe-allocated buffer.
+
+These helpers use the caller's open descriptor directly. They do not establish
+path containment, file identity, file-type admission, or a snapshot of concurrently
+modified contents. Use [`Root.open()`](root.md#reads) to admit untrusted paths,
+and keep the handle open and the buffer available until the operation settles.
+Underlying I/O errors propagate unchanged.
+
+## Cancellation
+
+The async variant accepts `signal`. A pre-aborted signal rejects before I/O.
+In-flight cancellation is checked after the pending read settles and before
+another read starts, preserving the signal's reason. Bytes already read remain
+in the buffer; cancellation does not roll them back. Once the promise settles,
+the caller can reuse the buffer or close its handle without a hidden read still
+running.
+
+For a whole-file read that rejects files exceeding a byte limit, use the
+[bounded descriptor readers](advanced.md#files-and-identity) instead. Positional
+reads stop successfully at the requested window and do not probe for extra data.

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

@@ -0,0 +1,68 @@
+# Private file-store mode
+
+Private state is not a separate store family. Use `fileStore({ private: true })`
+when a directory holds credentials, tokens, auth profiles, or other private
+JSON/text state.
+
+```ts
+import { fileStore } from "@openclaw/fs-safe/store";
+
+const store = fileStore({ rootDir: "/var/lib/app", private: true });
+
+await store.writeJson("state.json", state);
+const loaded = await store.readJsonIfExists<State>("state.json");
+```
+
+## Behavior
+
+- Writes create parent directories at `0o700` and files at `0o600` unless you
+  pass stricter `dirMode` / `mode` options.
+- Async private-mode writes route through the secret-file atomic path, which refuses
+  symlink parent components and re-asserts mode after rename. Existing directories
+  must already have the requested mode; writes do not repair their permissions.
+  New-directory initialization requires guarded descriptor authority and may
+  fail closed under restrictive platform/umask combinations; see the
+  [secret-directory policy](secret-file.md#parameters).
+- Locked JSON mutations prepare private directories before acquiring their
+  sidecar and bind the lock to the admitted parent identity. Lock normalization
+  is read-only: a deleted or replaced admitted parent is rejected, not recreated.
+  The writer still revalidates directory admission afterward; reads do not create
+  directories.
+- `readText()` and `readJson()` are strict and throw on missing files.
+- `readTextIfExists()` and `readJsonIfExists()` return `null` on missing files.
+- `write()`, `writeText()`, `writeJson()`, `writeStream()`, and `copyIn()` all
+  keep the same root-relative `FileStore` shape.
+
+## Sync writes
+
+Use `fileStoreSync({ private: true })` for boot paths or sync-only integration
+points:
+
+```ts
+import { fileStoreSync } from "@openclaw/fs-safe/store";
+
+fileStoreSync({ rootDir: "/var/lib/app", private: true }).writeJson("config.json", config);
+```
+
+The sync store intentionally exposes a smaller surface: path resolution,
+lenient reads, and atomic text/JSON writes.
+
+Sync directory modes remain repair-compatible on POSIX, but repairs are applied
+only through an exact-identity, no-follow directory descriptor after the store
+root and admitted parent name are revalidated. Root or component swaps fail
+without chmodding the substituted directory. Matching modes take the no-open
+fast path. Windows uses its existing `mkdir` mode request plus exact directory
+identity checks and never falls back to pathname chmod.
+
+On Linux, Node offers no portable search-only descriptor that can also be
+`fchmod`ed. A mismatched directory without effective read access—including one
+created under an owner-read-removing umask—fails closed with
+`permission-unverified`. Supported macOS x64/arm64 hosts additionally try
+`O_SEARCH` when the directory remains searchable; an inaccessible directory
+still fails rather than restoring the pathname race.
+
+## See also
+
+- [`fileStore`](file-store.md) — full store API.
+- [Secret files](secret-file.md) — standalone credential file reads and writes.
+- [JSON files](json.md) — strict/lenient JSON helpers without a bound store.

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

@@ -0,0 +1,188 @@
+# Public API inventory
+
+This page closes the gap between the narrative guides and the complete package
+surface. The generated declarations define the exact signatures; the lists
+below name the lower-frequency exports that are easy to miss when reading only
+the focused guides. `test/public-api.json` guards the same inventory during
+pack checks.
+
+## Main entry and `root`
+
+The main entry and `@openclaw/fs-safe/root` expose the root capability types,
+including `ContainmentGuarantee`, `RootOpenOptions`, `RootCreateOptions`,
+`RootCreateJsonOptions`, and `WritableOpenMode`. The root-bounded iterator uses
+`RootWalkOptions`, `RootWalkEntry`, `RootWalkDataEntry`, `RootWalkEntryKind`,
+`RootWalkDataEntryKind`, `RootWalkSymlinkPolicy`, `RootWalkLimitBehavior`,
+`RootWalkDirectoryErrorBehavior`, `RootWalkEntryFilter`, and
+`RootWalkEntryFilterResult`.
+
+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.
+
+## `path` and `advanced`
+
+`safePathSegmentHashedV2` encodes every trimmed install ID with domain-separated
+SHA-256 into a fixed lowercase segment. The legacy `safePathSegmentHashed` keeps
+its existing output but can alias distinct IDs. See [install paths](install-path.md)
+for the exact encoding and migration contract.
+
+The lexical path surface additionally exports `isNodeError`,
+`isPathRelativeEscape`, `normalizeWindowsPathForComparison`,
+`resolveSafeRelativePath`, `splitSafeRelativePath`, and
+`matchUnsafeDeviceReadPath`. The device matcher is described by
+`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 `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`
+provide exact directory observations without owning a descriptor or a mutation.
+The assertion accepts an observed path and optional expected canonical path;
+see [directory identity](directory-identity.md).
+
+`overwriteFileHandle` and `OverwriteFileHandleOptions` provide in-place byte
+replacement through a borrowed regular-file handle. Its once-only `beforeWrite`
+callback admits the complete write and any required best-effort rollback after
+prefix preparation. See [in-place writes](in-place-write.md).
+
+`probePathCaseInsensitiveSync` and `ProbePathCaseOptions` are advanced exports
+for local ASCII-case observations. An unavailable answer remains `undefined`;
+the caller selects any fallback. See [path case probing](path-case.md).
+
+`resolvePathPrefixSync` and `ResolvedPathPrefix` separate a canonical existing
+path prefix from its raw unresolved suffix after physical symlink traversal.
+See [resolving path prefixes](path-prefix.md).
+
+`probePathSuffixAliasesSync` and `ProbePathSuffixAliasesOptions` compare selected
+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`,
+`GUEST_FILESYSTEM_CREATE_EXISTS_EXIT_CODE`,
+`GUEST_FILESYSTEM_READ_NOT_FOUND_EXIT_CODE`, and
+`GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON`. These are source and protocol
+constants; the caller launches the Python guest and owns authorization and
+transport lifetime. See the [guest protocol](guest.md).
+
+## `json` and `store`
+
+Standalone structured reads use `ReadJsonOptions`, `ReadRootJsonSyncOptions`,
+`ReadRootStructuredFileSyncOptions`, and `RootStructuredFileReadResult`.
+
+The store surface additionally exports `FileStoreReadOptions` and
+`JsonFileStoreOptions`. Durable-queue inspection and recovery use
+`jsonDurableQueueEntryExists`, `loadJsonDurableQueueEntry`,
+`readJsonDurableQueueEntry`, and the `JsonDurableQueueLoadOptions` and
+`JsonDurableQueueReadResult` types. `unlinkBestEffort` is the explicitly
+best-effort cleanup helper used by those queue flows.
+
+## Permissions and secure files
+
+Permission inspection exposes `PermissionCheckOptions` and `SafeStatResult`.
+Private-directory creation uses `CreatePrivateDirectoryOptions`. Raw Windows
+descriptor facts use `OwnerAndDaclResult`, `WindowsAccessControlEntry`, and
+`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`,
+`SecureFileInjectOptions`, `SecureFileIoOptions`, and `SecureFileReadResult`.
+
+## Locks, walking, and temp workspaces
+
+The file-lock diagnostics surface includes `FileLockHeldEntry`,
+`FileLockStaleRecovery`, and `SidecarLockCompromisedInfo`.
+`drainFileLockManagerForTest` and `resetFileLockManagerForTest` are test-only
+manager controls; production code should not use them as lock recovery.
+
+Standalone walkers use the `WalkEntryKind` and `WalkSymlinkPolicy` unions.
+Private workspaces expose `TempPathIdentityReceipt`,
+`TempWorkspaceCleanupResult`, and `TempWorkspaceCleanupSafety` so callers can
+distinguish outcomes and select compatible or required bounded-tree cleanup.
+Strict workspace creation requires native no-replace quarantine plus retained
+parent/workspace descriptors; see the
+[creation and cleanup contract](temp.md#private-temp-workspaces).
+
+## Atomic replacement and durability
+
+Atomic helper option and receipt types include
+`MovePathWithCopyFallbackOptions`, `ReplaceDirectoryAtomicOptions`,
+`ReplaceFileAtomicSyncOptions`, `ReplaceFileAtomicResult`,
+`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`,
+`EnsureDurableDirectoryOptions`, `PublishFileExclusiveResult`,
+`PublishFileExclusiveStrategy`, `PublishFileExclusiveCleanup`,
+`PublishFileExclusiveFailurePhase`,
+`PublishFileExclusiveDirectorySyncFailure`, `Sha256FileInput`,
+`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
+
+Archive option and policy types are `ExtractArchiveOptions`,
+`ArchiveEntryFilter`, `ArchiveEntryModePolicy`, and
+`ArchiveFilteredEntryPolicy`. Typed error-code unions are
+`ArchiveFormatErrorCode`, `ArchiveLimitErrorCode`, and
+`ArchiveSecurityErrorCode`. TAR and ZIP preflight composition uses
+`TarEntryInfo` and `ZipArchiveWithFiles`.
+
+`createArchiveSymlinkTraversalError` constructs the typed traversal failure
+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
+`README.md` or `docs/`. Documentation examples are also checked so a named
+import cannot silently move to another package subpath.