@openclaw/signal 2026.9.5 → 2026.9.7

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

@@ -0,0 +1,445 @@
+---
+title: Directory durability
+description: "Pin directory identities, fsync publication metadata, and durably create nested directory paths."
+---
+
+# Directory durability
+
+`@openclaw/fs-safe/durability` provides the directory side of crash-safe file
+publication. Flushing a file does not guarantee that its containing directory
+entry reached storage; callers that promise durable create, link, rename, or
+unlink operations must also synchronize the affected directory.
+
+```ts
+import {
+  ensureDurableDirectory,
+  pinDirectory,
+} from "@openclaw/fs-safe/durability";
+
+const repository = await ensureDurableDirectory({
+  directoryPath: "/srv/backups/sqlite",
+  mode: 0o700,
+});
+
+const pinned = await pinDirectory(repository, { label: "backup repository" });
+try {
+  await publishSnapshot();
+  const outcome = await pinned.sync();
+  if (outcome.status === "unsupported") {
+    // Decide at the product boundary whether this platform can weaken the promise.
+  }
+} finally {
+  await pinned.close();
+}
+```
+
+## Outcomes and failure semantics
+
+`syncDirectory()` and `PinnedDirectory.sync()` return:
+
+```ts
+type DirectorySyncOutcome =
+  | { status: "synced" }
+  | { status: "unsupported"; code?: string };
+```
+
+POSIX synchronization failures propagate. Windows directory handles do not
+portably support `FlushFileBuffers`; the known unsupported error family is
+reported as `unsupported` after the pathname and pinned identity are checked
+again. Directory-open access failures and other Windows I/O failures still
+propagate.
+
+`syncDirectoryBestEffort()` and `syncDirectoryBestEffortSync()` intentionally
+discard both unsupported outcomes and failures. Use them only when the primary
+write remains useful without a crash-durability promise.
+
+On Windows, pathname inputs and supplied directory receipts reject NTFS
+alternate-stream and directory-index namespace spellings before opening,
+creating, hashing, or publishing anything. This applies to directory
+durability, `publishFileExclusive()`, and the pathname overloads of
+`sha256File()` and `sha256FileSync()`; the already-open `FileHandle` and
+borrowed numeric file-descriptor overloads are unchanged. Ordinary colon-bearing
+POSIX paths remain valid.
+
+## Pinned directories
+
+`pinDirectory()` rejects final symlinks and non-directories. On POSIX it opens
+with `O_DIRECTORY`, `O_NOFOLLOW`, and `O_NONBLOCK`, then compares the open
+descriptor, pathname identity, and canonical path. `assertCurrent()` repeats
+those checks. This prevents a pathname replacement from turning a later sync
+into proof for a different directory.
+
+Pathname and descriptor checks compare exact bigint device and inode values.
+Each inspection allows one retry for unknown Windows identity components,
+retaining known components and rejecting definite mismatches immediately.
+Persistent unknown identity fails closed with `path-mismatch`, including on an
+otherwise usable directory. A failed preflight identity check never syncs the
+descriptor; a replacement discovered after sync still rejects the operation.
+
+`DirectoryReceipt.identity` remains a numeric Node `Stats` object for metadata
+compatibility, projected from the same exact observation as the private
+identity. Library-created receipts and their identity objects retain a
+private exact snapshot; mutating their public fields cannot change the
+directory authorized by that snapshot. Each returned receipt owns a mutable
+numeric metadata copy. Later admissions retain the original metadata snapshot
+even if advisory fields such as mode or timestamps were edited; changed paths
+or identity components reject. Pass the receipt or its original
+identity object through to later operations to retain this evidence. A copied
+or reconstructed numeric identity is accepted only when both components are
+safe integers and, on Windows, nonzero. Rounded or unknown caller identities
+fail with `path-mismatch` rather than authorizing a different directory.
+
+Caller-supplied receipts may use `DirectoryReceipt<BigIntStats>` with the result
+of `lstat(path, { bigint: true })`. `pinDirectory()`, `syncDirectory()`,
+`syncDirectorySync()`, `publishFileExclusive()`'s `parentReceipt`, and
+`stageFileInDirectory()` accept both numeric and bigint receipt inputs.
+`DirectoryReceipt` without a type argument and all returned durability receipts
+still expose numeric `Stats`, including working type predicates and Date
+properties. Bigint metadata is projected from the supplied observation, retaining
+fractional timestamps and the private exact device/inode identity.
+
+```ts
+import { lstatSync, realpathSync, type BigIntStats } from "node:fs";
+import { syncDirectorySync, type DirectoryReceipt } from "@openclaw/fs-safe/durability";
+
+const directoryPath = "/srv/backups/sqlite";
+const receipt: DirectoryReceipt<BigIntStats> = {
+  path: directoryPath,
+  realPath: realpathSync(directoryPath),
+  identity: lstatSync(directoryPath, { bigint: true }),
+};
+// Keep this receipt across the application's publication operation.
+const outcome = syncDirectorySync(receipt);
+```
+
+Call `close()` in `finally`. Closing is idempotent; using a closed pin fails.
+
+These checks intentionally reject a moved or replaced pathname. For one file's
+abort cleanup through its original directory after a move, use the separate
+[retained-directory staging lifecycle](staged-file.md). Its cleanup authority
+does not weaken `pinDirectory().assertCurrent()` or `.sync()`, and namespace
+cleanup is not proof of crash durability.
+
+## Durable directory creation
+
+`ensureDurableDirectory()` finds and pins the nearest existing ancestor,
+creates the requested path, opens every new directory segment, and synchronizes
+each new parent-to-child edge from the leaf upward. It returns the final
+directory receipt plus the aggregate parent-sync outcome.
+
+By default it uses fs-safe's guarded one-segment-at-a-time absolute-directory
+creator. Advanced callers can pass `create` when directory creation needs
+platform-specific ACLs or another product-owned policy. The callback owns the
+safety of its mutations and must create exactly `directoryPath`; fs-safe
+validates and pins every resulting segment before any synchronization is
+accepted.
+
+`expectedExistingIdentity` binds an existing target to an identity observed by
+the caller before a separate permission or policy check. A missing or replaced
+target fails with `FsSafeError("path-mismatch")`.
+Use bigint `dev` and `ino` from `lstat(path, { bigint: true })` or
+[`readDirectoryIdentity()`](directory-identity.md) for caller-owned observations
+that may exceed the numeric safe-integer range. An original library receipt's
+`identity` object also retains its private exact identity for this option.
+
+## Exclusive file publication
+
+`publishFileExclusive()` materializes one file without clobbering an existing
+target. It pins the source with nonblocking `O_NOFOLLOW`, optionally verifies
+`expectedSourceIdentity`, tries a hardlink first, then synchronizes the target
+parent directory.
+
+Trusted relative source and target paths are resolved to absolute paths before
+authority checks. On Windows, ordinary drive-relative operands are anchored at
+entry before namespace-alias admission. A caller-supplied `parentReceipt` must
+still name the resolved target parent and is not relaxed by this compatibility
+rule.
+
+For example, a backup archive is complete before publication. If directory
+sync fails, keeping that complete file is more useful than conditionally
+deleting it by pathname:
+
+```ts
+import { FsSafeError } from "@openclaw/fs-safe/errors";
+import { publishFileExclusive } from "@openclaw/fs-safe/durability";
+
+try {
+  const result = await publishFileExclusive({
+    sourcePath: stagedArchive,
+    targetPath: finalArchive,
+    strategy: "link-or-copy",
+    onSyncFailure: "preserve",
+    parentReceipt: backupDirectory,
+  });
+  recordDurableBackup(result.identity, result.directorySync);
+} catch (error) {
+  if (
+    error instanceof FsSafeError &&
+    error.details?.phase === "directory-sync" &&
+    error.details.cleanup === "preserved"
+  ) {
+    recordCompleteButPossiblyNonDurableBackup(finalArchive, error.details);
+  } else {
+    throw error;
+  }
+}
+```
+
+### Strategies
+
+| Strategy | Behavior | Native requirement |
+|---|---|---|
+| `link-required` | Create a same-filesystem hardlink or propagate the failure. | No; guarded JS `link` fallback remains. |
+| `link-or-copy` | Try hardlink, then clone, Linux `copy_file_range`, then the JS byte loop for classified unsupported errors. | No; acceleration is optional. |
+| `rename-noreplace` | Atomically move the source without replacing an existing target. Success consumes `sourcePath`. | Yes. |
+
+`"link-required"` propagates an unsupported hardlink failure.
+`"link-or-copy"` falls back only for `EPERM`, `EXDEV`, `ENOTSUP`,
+`EOPNOTSUPP`, or `ENOSYS`; `isHardlinkFallbackError()` exposes that exact
+classifier. The fallback copies from the pinned source into a `wx` target,
+fsyncs it, and fences source and target identity and content before reporting
+success. `parentReceipt`, when supplied, must name the target's direct parent.
+
+With a native binding, the copy fallback first attempts a copy-on-write clone
+(`fclonefileat` on macOS, `FICLONE` on Linux), then Linux
+`copy_file_range`, and finally the existing JavaScript byte loop. Every route
+creates the target exclusively, applies mode `0o600` through its owned
+descriptor independently of the process umask, and goes through the same
+post-copy identity and SHA-256 fencing. Hashing uses an async
+native task when available, so large verification reads do not occupy the
+JavaScript event loop.
+
+On a clone-capable filesystem, publication of a large file becomes mostly a
+metadata operation: data blocks are shared copy-on-write until either file is
+modified. Clone support is filesystem- and mount-dependent, so callers must
+not infer durability or physical independence from timing; an unsupported
+clone or `copy_file_range` transparently continues down the fallback chain.
+
+## Recoverable atomic-replace fallback
+
+`replaceFileAtomic()` normally publishes a synchronized sibling temp with an
+atomic rename. Some Windows filesystems and file owners reject that rename with
+`EPERM` or `EEXIST`; `copyFallbackOnPermissionError: true` permits a non-atomic
+copy fallback.
+
+Callers that cannot tolerate a torn in-place fallback can add:
+
+```ts
+await replaceFileAtomic({
+  filePath: statePath,
+  content: nextState,
+  syncTempFile: true,
+  syncParentDir: true,
+  copyFallbackOnPermissionError: true,
+  copyFallbackRestore: "restore-original",
+  maxRestoreBytes: 4 * 1024 * 1024,
+  destinationHardlinks: "reject",
+});
+```
+
+The existing regular-file destination is pinned before its link count is
+accepted. Its original bytes are read within `maxRestoreBytes`, then the new
+bytes are written and synchronized through the same descriptor. If a write or
+sync tears, fs-safe rewrites the snapshot and fsyncs it before throwing. Inspect
+`details.cleanup`: `"restored"` means the original bytes were put back and
+synchronized; `"restore-failed"` means the replacement and recovery both
+failed, so the destination must be treated as indeterminate. This is recovery
+from a live-process I/O failure, not a transaction or a substitute for an
+application backup protocol.
+
+## Streaming SHA-256
+
+`sha256File()` hashes either a pathname string or an already-open Node
+`FileHandle`. A backup verifier can pin the file itself, compare its size, and
+keep ownership of the handle:
+
+```ts
+import { open } from "node:fs/promises";
+import { sha256File } from "@openclaw/fs-safe/durability";
+
+const snapshot = await open(stagedArchive, "r");
+try {
+  const before = await snapshot.stat();
+  const hash = await sha256File(snapshot, { maxBytes: before.size });
+  if (hash.bytes !== before.size || hash.digest !== manifest.sha256) {
+    throw new Error("staged backup does not match its manifest");
+  }
+} finally {
+  await snapshot.close();
+}
+```
+
+The result is `{ bytes, digest }`, where `digest` is lowercase hexadecimal.
+The optional `Sha256FileOptions` argument supports `maxBytes` and `signal`.
+`maxBytes` accepts a non-negative safe integer (including zero), or
+`Infinity` for no limit, which is also the default. Oversized files reject with
+`FsSafeError("too-large")`; reads stay bounded to at most `maxBytes + 1` bytes,
+even if the file grows after its initial size check. Hashing never silently
+truncates to the limit.
+
+Pass `signal` to cancel. A pre-aborted signal rejects before file I/O or native
+loading. In-flight cancellation is cooperative between reads and rejects with
+the signal's original reason only after the pending read or native task stops.
+Callers may close their handle after awaiting rejection; do not close it while
+the operation is pending. A signal can be shared by successive or concurrent
+hashes. Neither mode provides a snapshot of concurrently modified contents;
+callers requiring stable content must also fence identity and metadata.
+
+The handle overload never closes the caller's descriptor and uses positioned
+reads, so it does not alter the descriptor's current offset. The path overload
+rejects symbolic links and non-regular files, compares lossless bigint identities
+from the pre-open pathname inspection to the opened descriptor and from that
+descriptor to the current pathname, and closes its own handle. All identity
+checks complete before any JavaScript or native hashing. Each inspection allows
+one bounded retry for unknown Windows identity components, retaining known
+components and rejecting known differences immediately. Persistent unknown
+identity fails closed with `path-mismatch`, even for benign files: this trades
+availability for verifiable identity. Retries inspect the same descriptor or
+pathname without reopening the file and repeat the symlink and file-type checks.
+POSIX opens are nonblocking, so a raced FIFO or device is rejected after
+descriptor inspection rather than waiting for a writer.
+
+A pathname hash reports failure to close its owned descriptor after successful
+hashing. If hashing, admission, or cancellation already failed, that original
+failure remains primary even when close also fails. This also applies to
+`sha256FileSync()`; borrowed handles and descriptors remain caller-owned.
+
+When the optional binding is active, hashing runs as an async native task and
+does not occupy the JavaScript event loop with digest updates. With native mode
+`off`, or in `auto` when no binding loads, the fallback performs asynchronous
+positioned reads in chunks of up to 256 KiB but updates Node's `Hash` on the JavaScript
+thread. Both paths stream bounded buffers rather than loading the file into memory.
+The fallback sizes its scratch buffer to small files and grows it if a stale
+size hint is exceeded, while still probing for actual EOF and byte-limit overflow.
+Native mode `require` keeps its usual fail-closed loader semantics.
+
+### Synchronous hashing
+
+`sha256FileSync()` accepts a pathname or a borrowed numeric file descriptor and
+returns the same `{ bytes, digest }` result. It shares `Sha256FileOptions`,
+including the default unlimited byte budget and `too-large` errors for growth
+beyond `maxBytes`. It always reads from offset zero with bounded positional
+`readSync` calls and leaves a borrowed descriptor open at its original position.
+Path inputs use the same regular-file, final-symlink, nonblocking-open, and exact
+bigint admission checks described above, then close their owned descriptor.
+These checks do not provide ancestor confinement or a snapshot of concurrent edits.
+
+```ts
+import { closeSync, openSync } from "node:fs";
+import { sha256FileSync } from "@openclaw/fs-safe/durability";
+
+const fd = openSync(stagedArchive, "r");
+try {
+  const hash = sha256FileSync(fd, { maxBytes: manifest.sizeBytes });
+  if (hash.bytes !== manifest.sizeBytes || hash.digest !== manifest.sha256) {
+    throw new Error("staged backup does not match its manifest");
+  }
+} finally {
+  closeSync(fd);
+}
+```
+
+The synchronous API uses Node's crypto implementation in every native mode,
+including `require`; it never loads a native binding. It blocks the calling
+thread until hashing finishes or throws. A pre-aborted signal fails before I/O,
+and synchronous signal changes are checked between operations with the original
+reason preserved. Timers and other JavaScript callbacks cannot run while the
+hash is executing; use `sha256File()` when responsive cancellation is needed.
+
+## Publication failure receipts
+
+If `publishFileExclusive()` fails after creating the target, it throws an
+`FsSafeError` with a `details` receipt:
+
+```ts
+type PublishFileExclusiveFailureDetails = {
+  phase:
+    | "hardlink-create" | "hardlink-verify"
+    | "copy-create" | "copy-verify"
+    | "rename-create" | "rename-verify"
+    | "directory-sync";
+  targetCreated: boolean;
+  targetIdentity?: { dev: number | bigint; ino: number | bigint };
+  cleanup: "removed" | "preserved" | "unknown";
+  directorySync?: { status: "failed"; code?: string };
+};
+```
+
+`"removed"` means the path still matched the identity created by this call and
+was unlinked (or was already absent). `"preserved"` means it was deliberately
+retained—for example after a successful no-replace rename—or the pathname had
+been replaced and therefore was not safe to remove. `"unknown"` means cleanup
+could not verify or remove the created identity. Callers that run a second
+application-level guard, such as SQLite snapshot validation, should branch on
+this receipt instead of inferring ownership from path existence. The original
+failure remains available as `cause`. Failures before target creation retain
+their existing error shape and do not claim a cleanup result.
+
+Source and target identities are checked again after successful or unsupported
+directory synchronization, while their descriptors remain owned. A late
+verification failure retains its strategy's verification phase and is not a
+directory-sync failure. Completed copied targets stay pinned during conditional
+cleanup; substituted entries remain untouched. Returned numeric metadata comes
+from the retained target descriptor and grants no continuing pathname authority.
+
+### Directory-sync failure policy
+
+`onSyncFailure` applies only after target creation and content/identity fencing
+have succeeded but synchronizing the containing directory throws:
+
+```ts
+type PublishFileExclusiveSyncFailurePolicy = "rollback" | "preserve";
+```
+
+A returned `{ status: "unsupported", code? }` is an explicit successful
+publication outcome, not a thrown sync failure, so this option does not rewrite
+or clean up that target.
+
+- `rollback` is the default. fs-safe removes the target only if its current
+  identity still matches the file created by this call. A replacement is never
+  removed. The error reports `cleanup: "removed"`, `"preserved"`, or
+  `"unknown"` and `directorySync: { status: "failed", code? }`.
+- `preserve` never attempts that unlink. The error reports
+  `targetCreated: true`, `cleanup: "preserved"`, the created identity, and the
+  failed directory-sync outcome. The file is complete and fenced, but its
+  directory entry is not proven crash-durable.
+
+Choose `rollback` when the pathname must mean “durably committed” and a failed
+commit should disappear from the live process view. Choose `preserve` when the
+payload itself remains valuable—backup archives are the common case—and the
+caller can record, retry, or independently validate durability. Neither choice
+can make a failed directory sync succeed: rollback deletion is also not proven
+durable, and a preserved name may disappear after a crash. Always use the
+typed receipt rather than inferring ownership from `exists()`.
+
+`rename-noreplace` always preserves its target after a successful rename,
+because removing it would discard the source's only remaining name; its typed
+failure receipt makes that explicit regardless of `onSyncFailure`.
+
+`"rename-noreplace"` requires the native helper and atomically moves the
+source to the target without replacement. A collision is reported as
+`EEXIST`, both files remain unchanged, and a successful call returns
+`method: "rename-noreplace"` after synchronizing the source and target parent
+directories. Unlike the link/copy strategies, success consumes `sourcePath`.
+
+## Scope
+
+These primitives establish path identity and filesystem synchronization. One
+`publishFileExclusive()` call is one no-clobber file materialization, not a
+retention policy, multi-file transaction, or application commit protocol. They
+do not decide application commit protocols, marker formats, permission policy,
+or whether an unsupported platform is acceptable. Keep those decisions at the
+owning product boundary.
+
+## See also
+
+- [Migrating to 0.5](migrating-to-0.5.md) — choosing a publication policy during upgrade.
+- [Native architecture](native.md) — clone/copy/hash mechanisms and fallback guarantees.
+- [Errors](errors.md) — typed operational failure handling.
+
+## Existing Windows file retirement
+
+[`retainFileInDirectory`](retained-file.md) describes identity-bound native
+disposition and resource settlement separately from persistence. Its result is
+always `persistence: "not-proven"`; neither accepted disposition nor observed
+namespace absence is a directory/volume barrier or an application commit.

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

@@ -0,0 +1,109 @@
+# Directory entries
+
+`Root.entries()` observes one directory at a time. Use it when the application
+owns traversal order or must inspect symlinks itself, such as an installer that
+validates selected dependency links or a manifest builder that rejects all links.
+
+```ts
+import { root } from "@openclaw/fs-safe";
+
+const workspace = await root("/srv/workspace");
+for await (const entry of workspace.entries("plugins", {
+  maxEntries: 1_000,
+  signal: AbortSignal.timeout(5_000),
+})) {
+  if (entry.isSymbolicLink) {
+    throw new Error(`unexpected link: ${entry.name}`);
+  }
+  console.log(entry.name, entry.size);
+}
+```
+
+## API
+
+```ts
+interface Root {
+  entries(relativePath: string, options?: RootEntriesOptions): AsyncIterableIterator<DirEntry>;
+}
+
+type RootEntriesOptions = {
+  maxEntries?: number;
+  order?: "filesystem" | "sorted";
+  signal?: AbortSignal;
+  symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root";
+};
+```
+
+Each result is the existing [`DirEntry`](types.md) shape: a basename and advisory
+`lstat` metadata, including `isFile`, `isDirectory`, `isSymbolicLink`, `size`,
+`mode`, `nlink`, `dev`, and `ino`. Entries are immediate children; the iterator
+never descends. An empty path or `"."` selects the root directory.
+
+Child symlinks are always reported without following them, including dangling
+links and links whose targets lie outside the root. Their metadata describes
+the link, not its target. Hardlinked files are also reported regardless of the
+Root's read hardlink policy. Reporting a name grants no read or mutation access.
+Use the Root operation methods when consuming or changing an entry.
+
+The `symlinks` option applies only to the path of the selected directory. It
+inherits the Root's read policy and defaults to `"reject"`. The two follow
+policies allow only contained aliases; `"follow-parents-within-root"` also
+rejects a link as the final directory component. Child-link reporting is
+independent of this path policy.
+
+## Work limits and ordering
+
+`maxEntries` is an optional non-negative safe integer. Every child counts,
+including directories, symlinks, special files, and entries the caller later
+ignores. Omit it to leave the count unbounded. An empty directory satisfies a
+zero limit. Exceeding the limit throws `FsSafeError` with code `"too-large"`;
+there is no silent truncation or success marker for a partial scan.
+
+The default `order: "filesystem"` reads names incrementally in the filesystem's
+nondeterministic order. It observes one child's metadata per iterator step,
+with one name of lookahead to distinguish an exact limit from an overflow.
+Entries already yielded before overflow remain partial observations. A caller
+that stops early has not established that the whole directory fits the limit.
+
+`order: "sorted"` collects names first and orders them with JavaScript's default
+string sort, not locale collation. With `maxEntries`, names are collected from
+a bounded directory stream; overflow rejects before yielding any entries or
+requesting their full metadata. Without a limit, sorted mode enumerates the
+complete name list. Metadata is observed only as each sorted entry is consumed.
+Applications that need locale-specific ordering can collect with an explicit
+limit and apply their own comparator.
+
+The count bounds logical directory reads and fs-safe metadata requests. Node
+may classify a directory entry with `lstat` when the filesystem omits type
+information, including the single lookahead entry. It does not bound elapsed
+time for an individual filesystem operation or the size of one filename.
+
+Cancellation is checked before setup and around awaited work. Directory
+handles close on completion, overflow, cancellation, failure, and early
+`break` or iterator return. In-flight filesystem work settles before rejection;
+an individual syscall cannot be interrupted. If iteration and disposal both
+fail, a `SuppressedError` retains the close failure in `error` and the original
+failure in `suppressed`.
+
+## Identity and caller responsibilities
+
+The iterator reuses Root's guarded directory-listing owner. It validates the
+selected path, pins exact Root and directory identities, and checks them around
+directory observations, including after control returns from the caller. A
+replaced directory rejects instead of continuing under the replacement.
+
+These are pure-Node, best-effort checks. The iterator does not hold descriptors
+for every path component and cannot sandbox a hostile process that repeatedly
+swaps and restores directories. Results are not an atomic snapshot, an exact
+identity receipt, or permission to use the name later. Contents and metadata
+can change between entries; a removed entry may cause iteration to reject.
+Use an admitted descriptor for metadata and hashing that must refer to the same
+opened file, and keep snapshot consistency or cooperative locking with its
+application owner.
+
+Traversal strategy, global budgets, ignored names, and approved external peers
+remain application policy. A per-directory physical-entry limit cannot replace
+a global file-only or unique-directory budget. Full metadata also requires a
+child `lstat`; a caller that previously needed only `Dirent` types should assess
+that cost. `Root.walk()` remains the recursive option for its supported link,
+pruning, and error policies; `Root.list()` returns an eager advisory listing.