@openclaw/fs-safe 0.8.1 → 0.8.3

package/dist/secret-read-async.js

@@ -1,20 +1,13 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import { readFileHandleBounded } from "./bounded-read.js";
-import { normalizeMaxBytes } from "./byte-budget.js";
+import { assertNoUnsafeDeviceReadPath } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
-import { resolveHomeRelativePath } from "./home-dir.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
-import { assertSecretFilePreview, DEFAULT_SECRET_FILE_MAX_BYTES, secretPathErrorCode, secretReadError, trimSecretFileContent, } from "./secret-read-policy.js";
+import { assertSecretFilePreview, resolveSecretReadPolicy, secretPathErrorCode, secretReadError, trimSecretFileContent, } from "./secret-read-policy.js";
 export async function readSecretFile(filePath, label, options = {}) {
-    const resolvedPath = resolveHomeRelativePath(filePath.trim());
-    if (!resolvedPath) {
-        throw new FsSafeError("invalid-path", `${label} file path is empty.`, { cause: undefined });
-    }
-    const maxBytes = normalizeMaxBytes(options.maxBytes, {
-        defaultValue: DEFAULT_SECRET_FILE_MAX_BYTES,
-    });
+    const { resolvedPath, maxBytes } = resolveSecretReadPolicy(filePath, label, options);
     async function inspectInput(symlinkMessage) {
         const stat = options.rejectSymlink
             ? await fs.lstat(resolvedPath, { bigint: true })
@@ -26,6 +19,7 @@ export async function readSecretFile(filePath, label, options = {}) {
     }
     let previewStat;
     try {
+        assertNoUnsafeDeviceReadPath(resolvedPath);
         previewStat = await inspectFileIdentity(() => inspectInput(`${label} file at ${resolvedPath} must not be a symlink.`));
     }
     catch (error) {
@@ -36,6 +30,7 @@ export async function readSecretFile(filePath, label, options = {}) {
     let raw;
     try {
         const realPath = await fs.realpath(resolvedPath);
+        assertNoUnsafeDeviceReadPath(realPath);
         handle = await fs.open(realPath, resolveReadOpenFlags());
         const openedHandle = handle;
         const openedStat = await inspectFileIdentity(async () => {

package/dist/secret-read-policy.d.ts

@@ -10,4 +10,8 @@ export declare function secretPathErrorCode(error: unknown): FsSafeErrorCode;
 export declare function secretReadError(code: FsSafeErrorCode, action: "inspect" | "read", label: string, resolvedPath: string, error: unknown): FsSafeError;
 export declare function assertSecretFilePreview(stat: BigIntStats, label: string, resolvedPath: string, maxBytes: number, rejectHardlinks: boolean): void;
 export declare function trimSecretFileContent(raw: string, label: string, resolvedPath: string): string;
+export declare function resolveSecretReadPolicy(filePath: string, label: string, options: SecretFileReadOptions): {
+    resolvedPath: string;
+    maxBytes: number;
+};
 //# sourceMappingURL=secret-read-policy.d.ts.map

package/dist/secret-read-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secret-read-policy.d.ts","sourceRoot":"","sources":["../src/secret-read-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAEhE,eAAO,MAAM,6BAA6B,QAAY,CAAC;AAEvD,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAGnE;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,SAAS,GAAG,MAAM,EAC1B,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,OAAO,GACb,WAAW,CAGb;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,OAAO,GACvB,IAAI,CAUN;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAM9F"}
+{"version":3,"file":"secret-read-policy.d.ts","sourceRoot":"","sources":["../src/secret-read-policy.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAEhE,eAAO,MAAM,6BAA6B,QAAY,CAAC;AAEvD,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAGnE;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,SAAS,GAAG,MAAM,EAC1B,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,OAAO,GACb,WAAW,CAGb;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,OAAO,GACvB,IAAI,CAUN;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAM9F;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,GAAG;IACxG,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB,CASA"}

package/dist/secret-read-policy.js

@@ -1,3 +1,5 @@
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { resolveHomeRelativePath } from "./home-dir.js";
 import { FsSafeError } from "./errors.js";
 export const DEFAULT_SECRET_FILE_MAX_BYTES = 16 * 1024;
 export function secretPathErrorCode(error) {
@@ -26,3 +28,13 @@ export function trimSecretFileContent(raw, label, resolvedPath) {
     }
     return secret;
 }
+export function resolveSecretReadPolicy(filePath, label, options) {
+    const resolvedPath = resolveHomeRelativePath(filePath.trim());
+    if (!resolvedPath) {
+        throw new FsSafeError("invalid-path", `${label} file path is empty.`, { cause: undefined });
+    }
+    const maxBytes = normalizeMaxBytes(options.maxBytes, {
+        defaultValue: DEFAULT_SECRET_FILE_MAX_BYTES,
+    });
+    return { resolvedPath, maxBytes };
+}

package/dist/sibling-staged-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sibling-staged-file.d.ts","sourceRoot":"","sources":["../src/sibling-staged-file.ts"],"names":[],"mappings":"AAkCA,wBAAsB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACxC,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;CACxB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,CA6G3C"}
+{"version":3,"file":"sibling-staged-file.d.ts","sourceRoot":"","sources":["../src/sibling-staged-file.ts"],"names":[],"mappings":"AAmCA,wBAAsB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACxC,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;CACxB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,CAyG3C"}

package/dist/sibling-staged-file.js

@@ -1,3 +1,4 @@
+import { syncFileBestEffort } from "./file-sync.js";
 import fsSync, {} from "node:fs";
 import fs, {} from "node:fs/promises";
 import path from "node:path";
@@ -92,13 +93,7 @@ export async function writeCallbackSibling(params) {
             }
             if (params.syncTempFile) {
                 await assertCurrent(params.tempPath);
-                try {
-                    await handle.sync();
-                }
-                catch (error) {
-                    if (error?.code !== "EPERM")
-                        throw error;
-                }
+                await syncFileBestEffort(handle);
             }
             await assertCurrent(params.tempPath);
             await fs.rename(params.tempPath, filePath);

package/dist/sidecar-lock-policy.d.ts

@@ -4,7 +4,6 @@ export declare function validateSidecarLockTimeoutMs(timeoutMs: number | undefin
 export declare function computeSidecarLockDelayMs(retry: SidecarLockRetryOptions, attempt: number): number;
 export declare const maxTransientLockDenials = 8;
 export declare function isTransientLockFileDenial(error: unknown, lockPath: string): boolean;
-export declare function sidecarLockPayloadIsStale(payload: unknown, staleMs: number, nowMs: number): boolean;
 export declare function sidecarLockPayloadCreatedAtMs(payload: unknown): number | null;
 export declare function defaultSidecarLockShouldReclaim(params: {
     lockPath: string;

package/dist/sidecar-lock-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock-policy.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAQvE,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI,CAkBpF;AAED,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAGhF;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAQjG;AASD,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGnF;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,OAAO,CAGT;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAU7E;AAED,wBAAsB,+BAA+B,CAAC,MAAM,EAAE;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,OAAO,CAAC,CAQnB"}
+{"version":3,"file":"sidecar-lock-policy.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAQvE,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI,CAkBpF;AAED,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAGhF;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAQjG;AASD,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGnF;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAU7E;AAED,wBAAsB,+BAA+B,CAAC,MAAM,EAAE;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,OAAO,CAAC,CAQnB"}

package/dist/sidecar-lock-policy.js

@@ -48,10 +48,6 @@ export function isTransientLockFileDenial(error, lockPath) {
     const denial = error;
     return process.platform === "win32" && denial?.code === "EPERM" && denial.path === lockPath;
 }
-export function sidecarLockPayloadIsStale(payload, staleMs, nowMs) {
-    const createdAtMs = sidecarLockPayloadCreatedAtMs(payload);
-    return createdAtMs !== null && nowMs - createdAtMs > staleMs;
-}
 export function sidecarLockPayloadCreatedAtMs(payload) {
     const createdAt = payload &&
         typeof payload === "object" &&

package/dist/string-coerce.d.ts

@@ -1,14 +1,5 @@
-export declare function readStringValue(value: unknown): string | undefined;
 export declare function normalizeNullableString(value: unknown): string | null;
 export declare function normalizeOptionalString(value: unknown): string | undefined;
-export declare function normalizeStringifiedOptionalString(value: unknown): string | undefined;
 export declare function normalizeOptionalLowercaseString(value: unknown): string | undefined;
 export declare function normalizeLowercaseStringOrEmpty(value: unknown): string;
-export declare function normalizeFastMode(raw?: string | boolean | null): boolean | undefined;
-export declare function lowercasePreservingWhitespace(value: string): string;
-export declare function localeLowercasePreservingWhitespace(value: string): string;
-export declare function resolvePrimaryStringValue(value: unknown): string | undefined;
-export declare function normalizeOptionalThreadValue(value: unknown): string | number | undefined;
-export declare function normalizeOptionalStringifiedId(value: unknown): string | undefined;
-export declare function hasNonEmptyString(value: unknown): value is string;
 //# sourceMappingURL=string-coerce.d.ts.map

package/dist/string-coerce.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"string-coerce.d.ts","sourceRoot":"","sources":["../src/string-coerce.ts"],"names":[],"mappings":"AAAA,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAElE;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAMrE;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAE1E;AAED,wBAAgB,kCAAkC,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQrF;AAED,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAEnF;AAED,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtE;AAED,wBAAgB,iBAAiB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,OAAO,GAAG,SAAS,CAepF;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,wBAAgB,mCAAmC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQ5E;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAKxF;AAED,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAGjF;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEjE"}
+{"version":3,"file":"string-coerce.d.ts","sourceRoot":"","sources":["../src/string-coerce.ts"],"names":[],"mappings":"AAAA,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAMrE;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAE1E;AAED,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAEnF;AAED,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtE"}

package/dist/string-coerce.js

@@ -1,6 +1,3 @@
-export function readStringValue(value) {
-    return typeof value === "string" ? value : undefined;
-}
 export function normalizeNullableString(value) {
     if (typeof value !== "string") {
         return null;
@@ -11,62 +8,9 @@ export function normalizeNullableString(value) {
 export function normalizeOptionalString(value) {
     return normalizeNullableString(value) ?? undefined;
 }
-export function normalizeStringifiedOptionalString(value) {
-    if (typeof value === "string") {
-        return normalizeOptionalString(value);
-    }
-    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
-        return normalizeOptionalString(String(value));
-    }
-    return undefined;
-}
 export function normalizeOptionalLowercaseString(value) {
     return normalizeOptionalString(value)?.toLowerCase();
 }
 export function normalizeLowercaseStringOrEmpty(value) {
     return normalizeOptionalLowercaseString(value) ?? "";
 }
-export function normalizeFastMode(raw) {
-    if (typeof raw === "boolean") {
-        return raw;
-    }
-    if (!raw) {
-        return undefined;
-    }
-    const key = normalizeLowercaseStringOrEmpty(raw);
-    if (["off", "false", "no", "0", "disable", "disabled", "normal"].includes(key)) {
-        return false;
-    }
-    if (["on", "true", "yes", "1", "enable", "enabled", "fast"].includes(key)) {
-        return true;
-    }
-    return undefined;
-}
-export function lowercasePreservingWhitespace(value) {
-    return value.toLowerCase();
-}
-export function localeLowercasePreservingWhitespace(value) {
-    return value.toLocaleLowerCase();
-}
-export function resolvePrimaryStringValue(value) {
-    if (typeof value === "string") {
-        return normalizeOptionalString(value);
-    }
-    if (!value || typeof value !== "object") {
-        return undefined;
-    }
-    return normalizeOptionalString(value.primary);
-}
-export function normalizeOptionalThreadValue(value) {
-    if (typeof value === "number") {
-        return Number.isFinite(value) ? Math.trunc(value) : undefined;
-    }
-    return normalizeOptionalString(value);
-}
-export function normalizeOptionalStringifiedId(value) {
-    const normalized = normalizeOptionalThreadValue(value);
-    return normalized == null ? undefined : String(normalized);
-}
-export function hasNonEmptyString(value) {
-    return normalizeOptionalString(value) !== undefined;
-}

package/dist/temp-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AA0EF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAaT;AAsCD,wBAAsB,QAAQ,CAAC,MAAM,EAAE;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,GAAG,OAAO,CAAC,QAAQ,CAAC,CAwBpB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE;IACN,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,EACD,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}
+{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AA8DF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAaT;AAsCD,wBAAsB,QAAQ,CAAC,MAAM,EAAE;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,GAAG,OAAO,CAAC,QAAQ,CAAC,CAwBpB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE;IACN,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,EACD,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/temp-target.js

@@ -2,7 +2,7 @@ import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { sameFileIdentityForCleanup } from "./file-identity.js";
-import { assertSafePathSegment, sanitizeSafePathSegment } from "./safe-path-segment.js";
+import { assertSafePathSegment, sanitizeSafePathSegment, trimHyphenEdges } from "./safe-path-segment.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
 const HYPHEN_CHAR_CODE = 0x2d;
@@ -14,17 +14,6 @@ const UPPERCASE_Z_CHAR_CODE = 0x5a;
 const UNDERSCORE_CHAR_CODE = 0x5f;
 const LOWERCASE_A_CHAR_CODE = 0x61;
 const LOWERCASE_Z_CHAR_CODE = 0x7a;
-function trimHyphenEdges(value) {
-    let start = 0;
-    let end = value.length;
-    while (start < end && value.charCodeAt(start) === HYPHEN_CHAR_CODE) {
-        start += 1;
-    }
-    while (end > start && value.charCodeAt(end - 1) === HYPHEN_CHAR_CODE) {
-        end -= 1;
-    }
-    return start === 0 && end === value.length ? value : value.slice(start, end);
-}
 function isExtensionCharCode(charCode) {
     return ((charCode >= NUMBER_ZERO_CHAR_CODE && charCode <= NUMBER_NINE_CHAR_CODE) ||
         (charCode >= UPPERCASE_A_CHAR_CODE && charCode <= UPPERCASE_Z_CHAR_CODE) ||

package/docs/archive.md

@@ -2,15 +2,12 @@
 
 `@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 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.
 
-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
-that an optional archive dependency is not installed, install `jszip` and/or
-`tar` explicitly in the consuming package.
+TAR admission uses one Rust core compiled into both the native binding and a
+bundled, import-free WebAssembly module. The guarded JavaScript fallback uses
+that module for TAR/gzip and optional `jszip` for ZIP. TAR needs no optional
+parser dependency, runtime download, install script, or consumer Rust toolchain.
+Installs omitting optional dependencies can import every public subpath and use
+TAR/gzip in `auto` or `off`; ZIP fallback still requires `jszip`.
 
 ```ts
 import { extractArchive, resolveArchiveKind } from "@openclaw/fs-safe/archive";
@@ -68,12 +65,12 @@ directories; ZIP UNIX creator records with zero attributes are explicit zero,
 while non-UNIX ZIP records use the absent-metadata defaults.
 
 TAR mode fields containing only NUL/ASCII-space padding use absent defaults.
-Native extraction also recognizes GNU binary modes, including signed values,
-within node-tar's JavaScript safe-integer range before masking permission bits.
-Malformed or unsupported mode representations retain existing decoder behavior:
-native falls back to zero, while JavaScript may default, parse an octal prefix,
-or reject. These representations are not newly admitted or standardized by the
-mode repair; raw framing and other numeric-field checks remain unchanged.
+Both backends recognize GNU binary modes, including signed values,
+within JavaScript's safe-integer range before masking permission bits.
+Malformed or unsupported mode fields consistently fall back to zero, matching
+the former native behavior. This replaces JavaScript's decoder-dependent octal
+prefix parsing, defaulting, or rejection for malformed fields. Ordinary octal,
+absent, explicit zero, and supported GNU binary fields retain their behavior.
 
 Final modes remain separate from private working staging permissions: files
 stay `0o600` and directories `0o700` until publication. Files receive their final
@@ -112,8 +109,8 @@ normalizing separators. For example, `./pkg/hello.txt` with
 `stripComponents: 1` extracts to `hello.txt` on both backends. Entries with no
 remaining components are skipped before the filter callback, but still count
 toward `maxEntries` and undergo traversal validation. JavaScript TAR extraction
-passes node-tar this accepted output path with its own stripping disabled, so
-depth checks, collision checks, writes, and mode application agree.
+copies the admitted payload range to this accepted output path, so depth checks,
+collision checks, writes, and mode application agree.
 
 An `entryFilter` sees the validated **canonical effective archive path before
 stripping**, entry kind, and declared size. On every JavaScript and native
@@ -127,6 +124,12 @@ Unicode Path names use the same canonicalization.
 Raw paths undergo traversal, absolute/drive-path, and NUL validation **before**
 canonicalization; normalization cannot turn an unsafe path into an accepted
 one. Stripping and output collision checks use this same canonical identity.
+On Windows, archive admission also rejects reserved device segments such as
+`NUL`, `CON.txt`, and `nul .txt` with `ArchiveSecurityError("entry-path")`,
+before extraction or bounded member reads. Ignored trailing spaces in the stem
+before an extension do not bypass this check. Ordinary members with these names
+remain valid on POSIX; this is a host-specific device guard, not a portable-name
+restriction.
 Filters that compare exact strings should use canonical pre-strip paths,
 including directory names without a trailing `/`.
 Returning `"skip"` rejects the whole archive unless `onFiltered` is
@@ -162,11 +165,10 @@ If skipping was not explicitly part of the restore contract, omit
 `onFiltered`; the first `"skip"` then rejects the complete archive with
 `ArchiveSecurityError("entry-filtered")`.
 
-Both TAR implementations finish bounded admission before TypeScript policy
-evaluation, so a rejected plan never starts extraction. The JavaScript path
-owns the extraction file stream and aborts node-tar through a pipeline on
-parser disagreement, validation, or timeout failure, destroying both ends
-instead of leaving a paused parser to drain indefinitely.
+Both TAR routes finish bounded admission before TypeScript policy evaluation,
+so a rejected plan never starts extraction. The JavaScript path owns its input,
+decoder, and WASM parser streams, joining their teardown on validation, write,
+or timeout failure.
 
 TAR character devices, block devices, and FIFOs are presented to the filter as
 `kind: "other"`. Accepted entries of these types reject with
@@ -183,8 +185,7 @@ and output collision checks in physical order. Each remaining record reaches
 `entryFilter` once with its canonical pre-strip path, `kind: "other"`, and
 declared effective size. A filter skip rejects with `"entry-filtered"` unless
 `onFiltered: "skip-entry"` is explicit. Accepted unsupported records are safely
-omitted and do not consume output payload budgets. This applies even when the
-underlying TAR parser suppresses the record. GNU long names describe one such
+omitted and do not consume output payload budgets. The shared core admits these records explicitly. GNU long names describe one such
 record and are then cleared; local PAX on unsupported types and GNU sparse
 `S` records retain their existing fail-closed format policy.
 
@@ -219,7 +220,7 @@ type ArchiveExtractLimits = {
 };
 ```
 
-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`). An explicit zero remains zero rather than selecting the default. `maxEntries` counts every archive entry, including entries removed by `stripComponents` or an explicit filter. 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.
+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`). An explicit zero remains zero rather than selecting the default. `maxEntries` counts every archive entry, including entries removed by `stripComponents` or an explicit filter. 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 same resolved 1 MiB metadata default applies to the native and WASM core.
 
 A limit violation throws `ArchiveLimitError`. Its constant and string code are:
 
@@ -262,17 +263,17 @@ codes remain `"destination-not-directory"`, `"destination-symlink"`, and
 - **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.
 - **Corrupt ZIP payloads:** streamed output must match both the central-directory CRC and declared uncompressed size before it can leave private staging.
-- **Corrupt gzip streams:** truncated compressed bodies, missing trailers, and checksum failures reject before extraction publishes files or an entry read returns bytes, on both JavaScript and native backends.
+- **Gzip container integrity:** every concatenated gzip member must have a complete valid header, body, CRC32, and ISIZE trailer. A completed member may be followed by all-zero compressed-container padding (including system-tar stdout padding), bounded by the original archive-byte limit. The padding must remain zero through physical EOF; nonzero bytes or another member after padding reject. Truncation and corruption reject before publication or selected bytes return on both backends. Compressed padding is separate from decoded TAR EOF and does not bypass its checks.
 - **Slow-loris archives:** `timeoutMs` is a hard wall-clock budget for non-mutating work. Extraction is aborted on overrun; if a destination mutation is already in flight, that mutation and rollback are joined before rejection so archive-controlled publication cannot continue afterward.
-- **Metadata bombs:** a streaming 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 fixed sizes and validates bounded local PAX bodies before using their size overrides for member framing. Original archive bytes remain unchanged.
+- **Metadata bombs:** a streaming pass-through reader rejects oversized PAX, GNU long-name, and GNU long-link bodies before buffering their bodies. It understands octal and base-256 fixed sizes and validates bounded local PAX bodies before using their size overrides for member framing. Original archive bytes remain unchanged.
 
 ### Raw TAR framing
 
 Extraction and bounded reads admit the complete decoded TAR stream through the
-raw meter before either backend's TAR parser runs. This applies to plain TAR,
+shared Rust core. This applies to plain TAR,
 gzip, and native-supported zstd/bzip2, without changing native-mode availability
-or fallback policy. The existing TypeScript and Rust meters enforce the same
-framing rules before parser normalization:
+or fallback policy. The native and WASM builds enforce the same
+framing rules:
 
 - Every nonzero header must have a valid unsigned octal checksum, delimited
   within its field. Checksum validation precedes metadata allocation and member
@@ -301,22 +302,28 @@ Missing linknames on links and nonempty linknames on non-links still use the
 format error. PAX `x` and GNU long-name/long-link `L`/`K` payloads retain their
 existing support and metadata limits; the zero-body rule is not applied to all
 non-regular types.
-PAX effective sizes still determine regular-member framing. Admission preserves
-the input bytes, and all entry/path/byte limits and extraction deadlines remain
-in force. Native inspection now completes this admission pass before parsing,
-requiring one additional streaming read/decompression pass.
-JavaScript admission reports an ordered logical-member manifest from the raw
-meter, bounded by entry-count, manifest, and decoded limits. Policy runs once
-over that manifest; extraction checks parser-visible members against the
-accepted decisions before writing. Original member names and USTAR prefixes
-are validated even when overridden, and non-padding bytes after a fixed path
-field's NUL terminator reject rather than hiding an unsafe suffix.
-Both meters enforce the 255-byte component ceiling under NFC and NFD before
-metadata replaces a raw path, including Hangul decomposition expansion.
-Native extraction and entry reads also drain their metered readers through
-physical EOF after parser traversal, before completing directory modes,
-publishing staged files, or returning the requested bytes. Finding the requested
-member or reaching the parser's logical EOF cannot bypass trailing validation.
+PAX effective sizes determine regular-member framing. Admission preserves input
+bytes and emits an ordered manifest with exact effective names, types, modes,
+sizes, and decoded payload offsets. TypeScript owns filtering, stripping,
+collisions, permissions, and accepted-output limits. Executors replay admitted
+ranges from the immutable staged input; no second TAR parser interprets PAX,
+GNU names, or payload lengths. Native writes remain descriptor-relative;
+JavaScript writes use the shared guarded private staging and pinned-write helpers.
+
+Original member names and USTAR prefixes are validated even when overridden.
+Non-padding bytes after a fixed path field's NUL terminator reject. The core
+enforces the 255-byte component ceiling under NFC and NFD, including Hangul
+expansion. Every replay drains and validates physical EOF before publication or
+returning selected bytes. Unrequested, filtered, and stripped members cannot
+bypass validation. Decompression remains streaming; no complete decoded archive
+is retained in memory or written to a decoded spool.
+
+The WASM transport has a fixed 64 KiB input buffer, one pending member event,
+and a 256 MiB maximum linear memory per isolated parser instance. Metadata is
+bounded before allocation; allocation failure rejects. Stream backpressure
+bounds queued chunks, and completion/error destroys the instance's parser
+state. The manifest retains the existing charged budget below; linear memory
+is an additional execution resource bound, not a new public limit option.
 
 The raw meter enforces `maxEntries` before consuming each logical member's body,
 including members later skipped by filtering or stripping. PAX/GNU metadata
@@ -343,9 +350,7 @@ archive overhead with safe addition. Ordinary limits, including
 zero and the existing defaulting/rounding rules, retain their behavior.
 There is no new public option. This is an absolute decoded admission
 cap, not a decompression-ratio policy; bounded stream/codec read-ahead remains.
-After this complete preflight, the JavaScript backend disables node-tar's
-independent ratio threshold so it cannot reject data that the native backend
-accepts within the same absolute limits.
+There is no independent TAR parser decompression-ratio threshold.
 
 ### Bounded local PAX support
 
@@ -359,13 +364,14 @@ permits link creation. Effective sizes drive framing, filters, and the existing
 budgets; `maxEntries` still counts members, not their metadata headers.
 
 Records must have exact byte lengths, ASCII keys, a final newline, and no
-duplicate keys, embedded newlines, or unconsumed bytes. Structural `path` and
-`linkpath` values and ownership names must be nonempty printable ASCII. A PAX
-member's raw name, USTAR prefix, and raw link target must also be printable
-ASCII; raw link targets must be present only on links, even when overridden.
-Unicode
-PAX structural text is deliberately unsupported because the underlying parsers
-do not agree when UTF-8 is split across input chunks. `size`, `uid`, and `gid`
+duplicate keys or unconsumed bytes. `path` and `linkpath` must be nonempty strict
+UTF-8 without NUL. Unicode, a leading BOM, numeric-looking names, and embedded
+newlines preserve their exact spelling; newlines inside a byte-counted value
+are data. Windows filesystem filename restrictions still apply during creation.
+Ownership names retain the existing nonempty printable-ASCII contract. Raw name,
+USTAR prefix, and link fields still require strict UTF-8 and NUL padding even
+when metadata overrides them. Raw link targets must be present only on links.
+`size`, `uid`, and `gid`
 must be canonical unsigned decimal safe integers (zero is valid; signs, leading
 zeros, fractions, and exponents are not). Padded member sizes must also fit the
 safe integer range. Raw and effective directory/link sizes must both be zero;
@@ -378,8 +384,7 @@ with optional fractional digits, within JavaScript's Date range), `uid`, `gid`,
 destination. `LIBARCHIVE.xattr.*` and `SCHILY.xattr.*` with nonempty ASCII
 alphanumeric/dot/underscore/hyphen suffixes are also accepted as inert metadata,
 never restored as extended attributes. Their values are byte-counted and may
-contain NUL or non-UTF8 bytes, including macOS provenance metadata; embedded
-newlines are rejected because they can disrupt downstream record parsing.
+contain NUL, non-UTF8 bytes, or newlines, including macOS provenance metadata.
 
 Global `g`, old `X`, old GNU `N`, empty/dangling/repeated local headers, mixed
 PAX/GNU extension chains, unknown keys, charset declarations, ACL extensions,
@@ -393,11 +398,11 @@ chains without introducing a new limit or changing defaults.
 
 ### Bounded GNU long names and links
 
-Both raw meters buffer GNU long-name `L` and long-link `K` bodies within
-`maxMetaEntryBytes` before either TAR parser runs. A body must contain a nonempty
+The shared core buffers GNU long-name `L` and long-link `K` bodies within
+`maxMetaEntryBytes`. A body must contain a nonempty
 UTF-8 name, with either no NUL or exactly one terminal NUL. Embedded NULs,
 additional terminal NULs, bytes after a NUL, and invalid UTF-8 reject with
-`ArchiveFormatError("archive-header-invalid")`. The meters preserve original
+`ArchiveFormatError("archive-header-invalid")`. The core preserves original
 archive bytes, including the optional terminator and block padding.
 
 One logical member may have at most one `L` and one `K`, in either order.

package/docs/atomic.md

@@ -173,7 +173,8 @@ metadata where lower latency matters more than crash-durability.
 
 ## `movePathWithCopyFallback`
 
-Rename a path. If the rename fails with `EXDEV` (cross-device), fall back to
+Rename a path. If the rename fails with `EXDEV` (cross-device), or `EPERM` on
+Windows, fall back to
 copying into a staged sibling path, renaming that staged path into place, and
 then removing only the source entries that were copied. The fallback avoids
 buffering regular files into memory and does not tighten the destination parent
@@ -215,39 +216,72 @@ identity becomes the next cleanup receipt. This accounts for the operation's
 own link-count and ctime changes without suppressing unexpected external
 mutations.
 
-### Final rename authorization
+### Mutation authority and publication receipts
 
-Pass `assertBeforeRename` when a move depends on a revocable lease or another
-caller-owned authorization. The helper captures this callback when called and
-runs it synchronously after asynchronous preparation and directory checks,
-immediately before each rename is dispatched:
+Pass `assertBeforeMutation` when a move depends on a revocable lease or another
+caller-owned authorization. The helper captures the callback when called and
+runs it synchronously after asynchronous preparation and identity checks,
+immediately before each rename, source-file or source-symlink unlink, and
+source-directory removal. `assertBeforeRename` remains available for callers
+that only guard publication. When both are set, the rename check runs first,
+then the mutation check, without yielding before dispatch.
 
 ```ts
+type MovePathPublicationReceipt = Readonly<{
+  path: string;
+  dev: bigint;
+  ino: bigint;
+}>;
+
 type MovePathWithCopyFallbackOptions = {
   from: string;
   sourceHardlinks?: "allow" | "reject";
   to: string;
   assertBeforeRename?: () => void;
+  assertBeforeMutation?: () => void;
+  onDestinationPublished?: (receipt: MovePathPublicationReceipt) => void;
 };
 ```
 
-Throw to refuse publication. The original error is propagated, including errors
-with `EXDEV` or `EPERM` codes; an authorization failure never starts a copy
-fallback. A genuine rename failure may still require a second authorization
+Throw to refuse the next mutation. The original error is propagated, including
+errors with `EXDEV` or `EPERM` codes; an authorization failure never starts a
+copy fallback. A genuine rename failure may still require a second authority
 check before publishing the staged copy.
 
-The callback must return `undefined` synchronously. Returning a Promise, thenable,
-or any other value refuses the rename with a `TypeError`; rejected asynchronous
-results are consumed without authorizing the operation. Perform asynchronous
-policy checks before calling the helper and use this callback to recheck the
-current owner at the mutation boundary.
+All three callbacks must return `undefined` synchronously. Returning a Promise,
+thenable, or any other value fails with a `TypeError`; rejected asynchronous
+results are consumed. Perform asynchronous policy checks before calling the
+helper and use the authority callback to recheck the current owner at each
+mutation boundary. All callbacks are captured before the first await.
+
+`onDestinationPublished` runs exactly once after a successful rename resolves,
+before awaited post-rename directory checks or source cleanup. It receives a
+frozen receipt with the resolved absolute destination path and the exact bigint
+device/inode identity observed on the rename source before dispatch: the
+original source for a direct rename, or the staged copy for fallback. Failed
+rename attempts never emit receipts. The return contract remains `Promise<void>`.
+
+The receipt records an observed identity, not authorization, durable storage,
+or an atomic guarantee against concurrent pathname replacement. Before recovery,
+recheck caller authority and compare the retained identity with a fresh bigint
+stat of the destination. In particular, unknown Windows device/inode values
+must not be treated as proof of ownership. Do not derive ownership from a new
+post-failure snapshot alone.
 
 A refused rename leaves the source and destination unchanged; any private
-staged copy follows the helper's normal cleanup. The check does not cancel an
-already-dispatched rename or make an external lease store atomic with the
-filesystem. Cleanup after a successful move retains the existing source-identity
-checks. Omitting the
-callback preserves the usual move behavior.
+staged copy follows normal cleanup. If publication has already happened, a
+callback error or later verification failure preserves the published destination
+and stops further source cleanup. Revocation during cleanup leaves all
+as-yet-unremoved source entries intact; entries already removed remain removed.
+The caller retains the receipt even if the move later rejects and owns recovery
+from this partial-move state. An observer that throws must retain its receipt
+before throwing if recovery needs it.
+
+These callbacks do not cancel already-dispatched operations or make an external
+lease store atomic with the filesystem. `assertBeforeMutation` guards renames
+and removal of copied source entries; private staging creation, writes, and
+failed-staging cleanup remain owned by the helper. Omitting the new callbacks
+preserves the existing move and source-identity behavior.
 
 ## Difference from `root()`