@openclaw/fs-safe 0.4.7 → 0.5.0

package/docs/archive.md

@@ -1,12 +1,11 @@
 # Archive extraction
 
-`@openclaw/fs-safe/archive` extracts ZIP and TAR archives behind one API, with traversal checks, blocked-link-type rejection, and entry-count and byte budgets. Extraction stages into a private directory and merges through the same safe-open boundary used by direct writes — a symlinked entry can't trick the merge into following an out-of-tree path.
+`@openclaw/fs-safe/archive` extracts ZIP and TAR archives behind one API, with traversal checks, blocked-link-type rejection, and entry-count and byte budgets. When the bundled native binding is available for the current platform, Rust streams ZIP, TAR, gzip, zstd, and bzip2 while TypeScript remains the sole policy owner; every accepted output is created fd-relative in a private staging root. Extraction then merges through the same safe-open boundary used by direct writes — a symlinked entry can't trick the merge into following an out-of-tree path.
 
-Archive extraction uses optional runtime dependencies: `jszip` for ZIP and `tar`
-for TAR. Installs that omit optional dependencies can still import this subpath,
-inspect archive kinds, and use pure path/limit helpers, but extraction or ZIP
-loading fails with a clear message until the matching optional dependency is
-installed.
+The guarded JavaScript fallback uses optional runtime dependencies: `jszip` for
+ZIP and `tar` for TAR/gzip. The native path does not use those packages. Installs
+that omit optional dependencies can still import this subpath and use the
+native path or pure path/limit helpers.
 
 Some package managers and CI installs skip optional dependencies
 (`--no-optional`, `--omit=optional`, or equivalent). If an archive helper throws
@@ -26,11 +25,16 @@ await extractArchive({
   kind: "zip",                        // optional; resolveArchiveKind() can infer
   timeoutMs: 15_000,                  // hard ceiling for the whole extraction
   stripComponents: 0,                 // tar-style strip-leading-dirs
+  entryModes: "clamp",                // default; use "preserve" for archive rwx bits
+  entryFilter: ({ path, kind, size }) => "extract",
+  onFiltered: "reject-archive",        // default; opt into "skip-entry" explicitly
   limits: {
     maxArchiveBytes: 256 * 1024 * 1024,
     maxEntries: 50_000,
     maxExtractedBytes: 512 * 1024 * 1024,
     maxEntryBytes: 256 * 1024 * 1024,
+    maxMetaEntryBytes: 1024 * 1024,
+    maxEntryPathComponents: 256,
   },
 });
 ```
@@ -42,14 +46,67 @@ type ExtractArchiveParams = {
   archivePath: string;          // absolute path to the archive
   destDir: string;              // absolute destination directory; must already exist
   timeoutMs: number;            // wall-clock cap; throws on overrun
-  kind?: ArchiveKind;           // "zip" | "tar"; inferred from filename when omitted
+  kind?: ArchiveKind;           // "zip" | "tar" | "tar-zstd" | "tar-bzip2"
   stripComponents?: number;     // strip N leading dirs from entry paths
   tarGzip?: boolean;            // when archive is .tar.gz/.tgz
   limits?: ArchiveExtractLimits;
   logger?: ArchiveLogger;       // { info?, warn? }
+  entryModes?: "clamp" | "preserve";
+  entryFilter?: (entry: { path: string; kind: ArchiveEntryKind; size: number }) =>
+    "extract" | "skip";
+  onFiltered?: "reject-archive" | "skip-entry";
 };
 ```
 
+`entryModes` defaults to `"clamp"`: directories become `0o755`; files become
+`0o644`, or `0o755` when the archived owner-execute bit is set. `"preserve"`
+keeps archived read/write/execute bits. Both policies strip setuid, setgid, and
+sticky bits, and neither applies archived ownership. TAR extraction disables
+`tar`'s ownership and mode restoration and applies the selected modes in the
+private staging tree; ZIP applies the same policy to `unixPermissions`.
+
+Native extraction is deliberately split into two phases. Rust first reports an
+entry manifest without creating paths. TypeScript validates paths, applies
+`stripComponents`, filters, limits, and mode policy, then passes an explicit
+accepted-entry plan back to Rust. Rust only performs decompression and the
+fd-relative `mkdirBeneath`/exclusive-open writes. This keeps policy identical
+between native and JavaScript paths rather than reimplementing it in Rust.
+
+An `entryFilter` sees the validated archive path, entry kind, and declared
+size. Returning `"skip"` rejects the whole archive unless `onFiltered` is
+explicitly `"skip-entry"`. Path traversal and archive-wide entry-count checks
+still apply to skipped entries.
+
+For example, a fleet restore can omit regenerated cache entries while rejecting
+any other policy mismatch by default:
+
+```ts
+await extractArchive({
+  archivePath: snapshotPath,
+  destDir: restoreRoot,
+  timeoutMs: 30_000,
+  entryFilter: ({ path: entryPath, kind }) =>
+    kind === "directory" && entryPath === "state/cache"
+      ? "skip"
+      : entryPath.startsWith("state/cache/")
+        ? "skip"
+        : "extract",
+  onFiltered: "skip-entry",
+  limits: { maxEntries: 50_000, maxEntryPathComponents: 64 },
+});
+```
+
+If skipping was not explicitly part of the restore contract, omit
+`onFiltered`; the first `"skip"` then rejects the complete archive with
+`ArchiveSecurityError("entry-filtered")`.
+
+Policy rejection is prompt on both implementations. The JavaScript TAR path
+owns the file stream and aborts node-tar through a pipeline on filter, path,
+link, limit, validation, or timeout failure, which destroys both ends instead
+of leaving a paused parser to drain indefinitely. The native path finishes its
+bounded manifest read before TypeScript policy evaluation, so a rejected plan
+never starts the extraction worker.
+
 If `kind` is omitted, the helper calls `resolveArchiveKind(archivePath)` and throws if the extension is not recognized. Pass `kind` explicitly when the archive name doesn't carry the type (e.g. content-addressed names).
 
 ### Limits
@@ -60,29 +117,48 @@ type ArchiveExtractLimits = {
   maxEntries?: number;          // refuse before extracting if entry count > this
   maxExtractedBytes?: number;   // refuse mid-stream if total extracted bytes > this
   maxEntryBytes?: number;       // refuse a single entry larger than this
+  maxMetaEntryBytes?: number;   // refuse one PAX/GNU metadata body above this
+  maxEntryPathComponents?: number; // bound output path depth after stripComponents
 };
 ```
 
-Defaults exist for each (`DEFAULT_MAX_ARCHIVE_BYTES_ZIP`, `DEFAULT_MAX_ENTRIES`, `DEFAULT_MAX_EXTRACTED_BYTES`, `DEFAULT_MAX_ENTRY_BYTES`). They are conservative — pass explicit values when you know your domain's actual ceiling.
+Defaults exist for each (`DEFAULT_MAX_ARCHIVE_BYTES_ZIP`, `DEFAULT_MAX_ENTRIES`, `DEFAULT_MAX_EXTRACTED_BYTES`, `DEFAULT_MAX_ENTRY_BYTES`, `DEFAULT_MAX_META_ENTRY_BYTES`, `DEFAULT_MAX_ENTRY_PATH_COMPONENTS`). The path-component default is 256. It is evaluated after `stripComponents` and before TypeScript accepts an entry for either JavaScript or native extraction, so rejected entries cannot cause implicit parent-directory creation. The 1 MiB metadata default matches node-tar's `maxMetaEntrySize`; fs-safe passes the same resolved value to node-tar and the native TAR meter.
 
 A limit violation throws `ArchiveLimitError`. The error's code is one of:
 
 ```ts
 ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT
 ARCHIVE_LIMIT_ERROR_CODE.ENTRY_COUNT_EXCEEDS_LIMIT
-ARCHIVE_LIMIT_ERROR_CODE.EXTRACTED_BYTES_EXCEEDS_LIMIT
-ARCHIVE_LIMIT_ERROR_CODE.ENTRY_BYTES_EXCEEDS_LIMIT
+ARCHIVE_LIMIT_ERROR_CODE.EXTRACTED_SIZE_EXCEEDS_LIMIT
+ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT
+ARCHIVE_LIMIT_ERROR_CODE.META_ENTRY_SIZE_EXCEEDS_LIMIT
+ARCHIVE_LIMIT_ERROR_CODE.ENTRY_PATH_COMPONENTS_EXCEEDS_LIMIT
 ```
 
 Catch and branch on the code to surface a meaningful response to the caller.
 
+Entry policy failures throw `ArchiveSecurityError`. Its entry-related codes
+are `"entry-path"`, `"entry-link"`, and `"entry-filtered"`; destination-race
+codes remain `"destination-not-directory"`, `"destination-symlink"`, and
+`"destination-symlink-traversal"`.
+
 ## What it defends against
 
 - **Path traversal:** entries with `..`, absolute paths, or Windows drive prefixes are rejected (`ArchiveSecurityError`).
 - **Symlink/hardlink entries:** rejected by default. Some archives ship symlink/hardlink entries that point outside the destination once resolved; `extractArchive` does not follow them.
-- **TOCTOU during merge:** extraction first writes to a private temp dir, then merges into `destDir` using the same boundary checks as `root().write()`. A symlink swap in the destination tree mid-merge is caught.
+- **TOCTOU during merge:** extraction first writes to a private temp dir, then merges into `destDir` using the same boundary checks as `root().write()`. Destination symlink swaps are checked with the selected platform mechanism; non-Linux routes retain the best-effort race window documented in the [security model](security-model.md#containment-guarantees-by-platform).
 - **Zip bombs:** `maxExtractedBytes` and `maxEntryBytes` apply to *post-decompression* bytes, so highly-compressed payloads hit the cap before they exhaust disk.
 - **Slow-loris archives:** `timeoutMs` is a hard wall-clock budget. Extraction is aborted on overrun.
+- **Metadata bombs:** a fixed-header pass-through reader rejects oversized PAX, GNU long-name, and GNU long-link bodies before either TAR implementation buffers them. It understands octal and base-256 size fields without interpreting metadata content.
+
+PAX headers can override the next entry's size from inside their content. The
+fixed-header meter deliberately never interprets that content, so PAX and GNU
+sparse entries are rejected with
+`ArchiveFormatError("archive-header-invalid")` rather than guessing. GNU sparse
+extension blocks are still metered in 512-byte units before rejection, ensuring
+malformed or excessive chains cannot bypass the metadata ceiling. GNU long-name
+and long-link entries remain supported because their fixed header size fully
+determines their layout.
 
 ## `resolveArchiveKind`
 
@@ -91,15 +167,56 @@ import { resolveArchiveKind, type ArchiveKind } from "@openclaw/fs-safe/archive"
 
 const kind = resolveArchiveKind("upload.zip"); // "zip"
 const tar = resolveArchiveKind("upload.tar.gz"); // "tar"
+const zstd = resolveArchiveKind("upload.tar.zst"); // "tar-zstd" when native is available
 const unknown = resolveArchiveKind("upload.bin"); // undefined
 ```
 
 Recognizes:
 
 - `*.zip` → `"zip"`
-- `*.tar`, `*.tar.gz`, `*.tgz`, `*.tar.bz2`, `*.tbz`, `*.tbz2` → `"tar"`
+- `*.tar`, `*.tar.gz`, `*.tgz` → `"tar"`
+- `*.tar.zst`, `*.tar.zstd`, `*.tzst` → `"tar-zstd"` (native only)
+- `*.tar.bz2`, `*.tbz2`, `*.tbz` → `"tar-bzip2"` (native only)
 
-Returns `undefined` for unknown extensions; check the result before calling `extractArchive` if the filename is caller-controlled.
+Returns `undefined` for unknown extensions; check the result before calling
+`extractArchive` if the filename is caller-controlled. A recognized zstd or
+bzip2 TAR extension with no native binding throws the typed
+`FsSafeError("helper-unavailable")` with installation guidance. This includes
+`mode: "off"`; those two formats have no JavaScript fallback.
+
+For a service whose input contract requires zstd, configure native mode before
+the first archive call so a packaging mistake fails at the boundary:
+
+```ts
+import { configureFsSafeNative } from "@openclaw/fs-safe/config";
+import { extractArchive } from "@openclaw/fs-safe/archive";
+
+configureFsSafeNative({ mode: "require" });
+await extractArchive({
+  archivePath: "/srv/restore/snapshot.tar.zst",
+  destDir: "/srv/restore/staging",
+  kind: "tar-zstd",
+  timeoutMs: 60_000,
+});
+```
+
+## `readArchiveEntry`
+
+`readArchiveEntry(archivePath, entryPath, { maxBytes, kind? })` reads one
+regular-file entry into a bounded `Buffer` without extracting a tree. It pins
+and privately stages the archive input, rejects link and directory entries,
+and throws `ArchiveLimitError` if decompressed bytes exceed `maxBytes`. ZIP
+inputs retain the archive subpath's 256 MiB compressed-input ceiling.
+With a native binding it uses the same Rust decoders as extraction, including
+zstd and bzip2 TAR. Without native it retains the JS ZIP/TAR/gzip implementation.
+
+```ts
+const rawManifest = await readArchiveEntry(uploadPath, "package/manifest.json", {
+  maxBytes: 64 * 1024,
+});
+const manifest = JSON.parse(rawManifest.toString("utf8")) as PluginManifest;
+validatePluginManifest(manifest);
+```
 
 ## Lower-level building blocks
 
@@ -196,4 +313,5 @@ await withTempWorkspace({ rootDir: "/srv/site/tmp", prefix: "extract-" }, async
 - [Atomic writes](atomic.md) — `replaceDirectoryAtomic` for staged directory replacement.
 - [Temp workspaces](temp.md) — extract into a private workspace and commit as one step.
 - [Errors](errors.md) — `FsSafeError` codes the underlying writes can raise.
+- [Migrating to 0.5](migrating-to-0.5.md) — clamp-default and native-format upgrade checklist.
 - [`extractArchive` source](https://github.com/openclaw/fs-safe/blob/main/src/archive.ts).

package/docs/atomic.md

@@ -43,6 +43,9 @@ type ReplaceFileAtomicOptions = {
   renameMaxRetries?: number;
   renameRetryBaseDelayMs?: number;
   copyFallbackOnPermissionError?: boolean;
+  copyFallbackRestore?: "restore-original" | "none"; // default: "none"
+  maxRestoreBytes?: number;          // required with "restore-original"
+  destinationHardlinks?: "reject";
   syncTempFile?: boolean;           // fsync(temp) before rename
   syncParentDir?: boolean;          // fsync(parent) after rename (POSIX only)
   beforeRename?: (params: { filePath: string; tempPath: string }) => Promise<void>;
@@ -75,6 +78,25 @@ with exclusive/no-follow flags where the platform supports them, and refuses
 known symlink destinations so it does not write through a replaced destination
 link.
 
+Set `destinationHardlinks: "reject"` when an existing regular-file destination
+must not have aliases. The policy reads `nlink` from a pinned destination
+descriptor, not pathname metadata, before rename and rechecks it in the copy
+fallback.
+
+The default `copyFallbackRestore: "none"` preserves the existing fallback
+contract: a failed copy can leave a partial destination. For state files where
+preserving the old bytes is more important, choose `"restore-original"` and set
+an explicit `maxRestoreBytes` memory budget. If the destination exists, fs-safe
+snapshots it through a pinned descriptor, overwrites through that same
+descriptor, and synchronizes the result. Any write or sync failure triggers a
+restore and another sync through the same descriptor.
+
+Restore failures are `FsSafeError("helper-failed")` values with typed
+`details.cleanup` set to `"restored"` or `"restore-failed"`. An original larger
+than `maxRestoreBytes` fails with `too-large` before mutation. A missing
+destination has no original to restore and follows the exclusive-create copy
+fallback.
+
 ### Sync variant
 
 `replaceFileAtomicSync` accepts the same options shape, with the obvious removal of the async-only hooks. Use it inside synchronous boot paths or test setup code.
@@ -148,6 +170,13 @@ await movePathWithCopyFallback({
 ```
 
 Use it when source and destination might live on different filesystems (containers, tmpfs, separate volumes).
+`sourceHardlinks: "reject"` performs a recursive preflight capped at 50,000
+entries before any mutation. Because link count and rename cannot be one atomic
+portable operation, this mode always commits a fresh inode/tree through the
+staged-copy route, even on one filesystem. Each regular file is checked again
+after open and after copying, so a post-scan hardlink cannot become the
+published target. A hardlink fails with `FsSafeError("hardlink")`; exceeding
+the preflight cap fails with `FsSafeError("too-large")`.
 If another writer changes source entries during the fallback, the staged copy
 throws `ESTALE` before commit when possible. If the destination has already
 been committed, cleanup still preserves the changed source entries and throws
@@ -160,7 +189,7 @@ been committed, cleanup still preserves the changed source entries and throws
 | Take relative paths, bound to a `rootDir`. | Take absolute paths, no boundary. |
 | Throw `FsSafeError` with `code`. | Throw `FsSafeError` *or* the underlying `NodeJS.ErrnoException`, depending on failure point. |
 | Atomicity, mode, hooks, fsync are sane defaults. | Caller controls all of the above. |
-| `mkdir`, identity check, hardlink reject built in. | No identity check, no hardlink reject — pair with [path helpers](path.md) if you need them. |
+| `mkdir`, identity check, hardlink reject built in. | No root boundary; `movePathWithCopyFallback` has explicit `sourceHardlinks` policy, while other helpers expose their own narrower checks. |
 
 Use `Root` when the path is caller-controlled. Use `atomic` when the path is fully under your control and you want explicit knobs.
 

package/docs/config.md

@@ -5,47 +5,46 @@ description: "Process-global defaults for optional fs-safe helpers."
 
 # `@openclaw/fs-safe/config`
 
-Process-global configuration knobs for optional fs-safe helpers. The Python helper policy is described in the [Python helper policy](python-helper.md); this page is the API reference.
+Process-global configuration knobs for optional fs-safe helpers. The native helper policy is described in the [native helper policy](native-helper.md); this page is the API reference.
 
 ```ts
 import {
-  configureFsSafePython,
+  configureFsSafeNative,
   configureFsSafeLocks,
-  getFsSafePythonConfig,
+  getFsSafeNativeConfig,
   getFsSafeLockConfig,
   type FsSafeLockConfig,
-  type FsSafePythonConfig,
-  type FsSafePythonMode,
+  type FsSafeNativeConfig,
+  type FsSafeNativeMode,
 } from "@openclaw/fs-safe/config";
 ```
 
 These functions are also re-exported from the main entry point. Prefer the subpath when you only need helper configuration and want the smallest import surface.
 
-## `configureFsSafePython(config)`
+## `configureFsSafeNative(config)`
 
 ```ts
-function configureFsSafePython(config: Partial<FsSafePythonConfig>): void;
+function configureFsSafeNative(config: Partial<FsSafeNativeConfig>): void;
 
-type FsSafePythonConfig = {
-  mode: FsSafePythonMode;
-  pythonPath?: string;
+type FsSafeNativeConfig = {
+  mode: FsSafeNativeMode;
 };
 
-type FsSafePythonMode = "auto" | "off" | "require";
+type FsSafeNativeMode = "auto" | "off" | "require";
 ```
 
-Set the process-global policy. Calls merge into the existing override config, so passing `{ pythonPath: "/usr/bin/python3" }` keeps any previously set `mode`. Configure once at startup, before the first `root()` call — switching modes mid-process is supported but the helper may already be running.
+Set the process-global loading policy. Configure once at startup, before the first filesystem operation. The binding is loaded lazily and the result is cached.
 
 | Mode | Behavior |
 |---|---|
-| `auto` | Default. Use the helper when it starts; fall back to Node-only behavior if Python is missing or fails to start. |
-| `off` | Never spawn the helper. Read/write/move use Node fallbacks plus pre/post identity checks. |
-| `require` | Fail closed if the helper cannot start. Operations that need the helper raise `FsSafeError("helper-unavailable")`. |
+| `auto` | Default. Prefer the platform binding and use guarded JavaScript when it is unavailable. |
+| `off` | Do not load the binding; use guarded JavaScript deterministically. |
+| `require` | Operations that need the binding raise `FsSafeError("helper-unavailable")` when it cannot load. |
 
-## `getFsSafePythonConfig()`
+## `getFsSafeNativeConfig()`
 
 ```ts
-function getFsSafePythonConfig(): FsSafePythonConfig;
+function getFsSafeNativeConfig(): FsSafeNativeConfig;
 ```
 
 Return the effective configuration: programmatic overrides win, then env vars, then the package default (`auto`).
@@ -67,6 +66,22 @@ Set process-wide defaults for sidecar lock options. This does **not** turn locki
 
 `staleRecovery` defaults to `"fail-closed"`. The opt-in `"remove-if-unchanged"` mode requires caller approval and serializes the final snapshot check and unlink with an exclusive `.reclaim` guard. A reclaim guard left by a killed reclaimer fails closed and requires externally coordinated cleanup.
 
+For a daemon that should wait briefly for normal contention but never delete a
+stale owner without per-lock approval:
+
+```ts
+configureFsSafeLocks({
+  staleRecovery: "fail-closed",
+  staleMs: 2 * 60_000,
+  timeoutMs: 15_000,
+  retry: { retries: 30, minTimeout: 50, maxTimeout: 1_000, randomize: true },
+});
+```
+
+Individual lock calls can override any default. Switching the global stale
+recovery mode does not provide the application-owned liveness proof required
+by `shouldRemoveStaleLock`.
+
 ## `getFsSafeLockConfig()`
 
 ```ts
@@ -80,15 +95,30 @@ Return the current sidecar lock defaults.
 The same policy can be set without code:
 
 ```bash
-FS_SAFE_PYTHON_MODE=auto      # auto | off | require | true | false | on | off | 1 | 0 | never | required
-FS_SAFE_PYTHON=/usr/bin/python3
+FS_SAFE_NATIVE_MODE=auto      # auto | off | require | true | false | on | 1 | 0 | never | required
 ```
 
-OpenClaw compatibility aliases are accepted: `OPENCLAW_FS_SAFE_PYTHON_MODE`, `OPENCLAW_FS_SAFE_PYTHON`, `OPENCLAW_PINNED_PYTHON`, and `OPENCLAW_PINNED_WRITE_PYTHON`. Programmatic overrides via `configureFsSafePython` always win.
+`OPENCLAW_FS_SAFE_NATIVE_MODE` is accepted as an alias. Programmatic overrides via `configureFsSafeNative` always win.
+
+### Python-helper migration bridge
+
+Version 0.5 detects the former `FS_SAFE_PYTHON_MODE`, `FS_SAFE_PYTHON`,
+`OPENCLAW_FS_SAFE_PYTHON_MODE`, `OPENCLAW_FS_SAFE_PYTHON`,
+`OPENCLAW_PINNED_PYTHON`, and `OPENCLAW_PINNED_WRITE_PYTHON` names. It emits one
+`FS_SAFE_PYTHON_DEPRECATED` warning and maps `auto`, `off`, or `require` to the
+same native mode; interpreter paths are ignored. The deprecated
+`configureFsSafePython()` export behaves the same way.
+
+Replace these inputs with `configureFsSafeNative()` or
+`FS_SAFE_NATIVE_MODE` during the 0.5 upgrade. The bridge exists only so shipped
+0.4 configuration fails loudly and maps predictably; it is not a supported
+Python execution path. Follow the [0.5 migration checklist](migrating-to-0.5.md)
+for the full upgrade.
 
 ## Related pages
 
-- [Python helper policy](python-helper.md) — when to pick `auto`, `off`, or `require`, and what each mode protects.
+- [Native helper policy](native-helper.md) — when to pick `auto`, `off`, or `require`, and what each mode protects.
 - [File lock](sidecar-lock.md) — the per-resource lock API that consumes lock defaults.
 - [Root API](root.md) — the API whose POSIX hardening the helper backs.
 - [Errors](errors.md) — `helper-unavailable` and `helper-failed`.
+- [Migrating to 0.5](migrating-to-0.5.md) — ordered consumer upgrade checklist.

package/docs/durability.md

@@ -81,9 +81,219 @@ accepted.
 the caller before a separate permission or policy check. A missing or replaced
 target fails with `FsSafeError("path-mismatch")`.
 
+## Exclusive file publication
+
+`publishFileExclusive()` materializes one file without clobbering an existing
+target. It pins the source with `O_NOFOLLOW`, optionally verifies
+`expectedSourceIdentity`, tries a hardlink first, then synchronizes the target
+parent directory.
+
+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, normalizes its mode to `0o600`, 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);
+  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 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, verifies the opened descriptor
+still names the requested path, and closes its own handle. POSIX opens are
+nonblocking, so a raced FIFO or device is rejected after descriptor inspection
+rather than waiting for a writer.
+
+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 64 KiB chunks but updates Node's `Hash` on the JavaScript
+thread. Both paths stream constant-size buffers rather than loading the file
+into memory. Native mode `require` keeps its usual fail-closed loader semantics.
+
+If publication fails after this call created 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.
+
+### 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. They
+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.