@openclaw/fs-safe 0.8.2 → 0.8.3

package/dist/secret-read-async.js

@@ -1,21 +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 })

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/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()`
 

package/docs/staged-file.md

@@ -66,8 +66,12 @@ Strings are UTF-8. `mode` is the requested **published** mode and defaults to
 `0600`; exact final modes, including `000`, are supported. The unpublished file
 stays at `0600` throughout preparation and any awaited application checks.
 After rename succeeds and the published entry passes identity validation, the
-owner applies the requested mode through its retained file descriptor and
-synchronizes the file. No parent is created or chmodded.
+owner applies the requested mode through its retained file descriptor. Content
+was synchronized during preparation; publication always synchronizes the parent.
+Modes retaining owner read/write skip the extra mode-only file sync, so a crash
+may leave the tighter staged `0600` instead of the wider requested mode. Modes
+removing owner read or write, and corrections of an observed wider staged mode,
+retain the post-chmod file sync. No parent is created or chmodded.
 Creation uses an exclusive, no-follow, close-on-exec open of a generated direct
 child name. Writes use that descriptor. Inspection uses non-following metadata
 operations, never a potentially blocking reopen of the leaf.

package/docs/writing.md

@@ -84,6 +84,11 @@ final verification uses a descriptor retained by the writer rather than reopenin
 the published file. The requested mode is not relaxed for verification.
 Publication verification compares exact bigint descriptor and pathname identities,
 including large file indexes that cannot be represented by a JavaScript number.
+Native publication syncs content before rename and always syncs the parent directory.
+Modes that retain owner read/write skip the extra mode-only file sync: after a
+crash, the file may retain staged mode `0o600` instead of the wider requested mode.
+Modes that remove owner read or write, and corrections of observed wider staging
+permissions, keep the post-chmod file sync.
 Later reads still obey OS permissions, and access checks on a pre-existing
 destination are unchanged. The explicit FUSE compatibility policy still requires
 a readable destination to prove matching content when rename changes its identity.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -156,13 +156,13 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.8.2",
-    "@openclaw/fs-safe-darwin-x64": "0.8.2",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.8.2",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.8.2",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.8.2",
-    "@openclaw/fs-safe-linux-x64-musl": "0.8.2",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.8.2",
+    "@openclaw/fs-safe-darwin-arm64": "0.8.3",
+    "@openclaw/fs-safe-darwin-x64": "0.8.3",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.8.3",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.8.3",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.8.3",
+    "@openclaw/fs-safe-linux-x64-musl": "0.8.3",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.8.3",
     "jszip": "^3.10.1"
   },
   "devDependencies": {

package/dist/archive-tar-extract.d.ts

@@ -1,11 +0,0 @@
-import { type ExtractionDeadline } from "./archive-deadline.js";
-import type { ResolvedArchiveExtractLimits, TarMeterLimits } from "./archive-limits.js";
-import type { ExtractArchiveOptions } from "./archive-options.js";
-export declare function extractWasmTar(params: {
-    archivePath: string;
-    options: ExtractArchiveOptions;
-    limits: ResolvedArchiveExtractLimits;
-    tarLimits: TarMeterLimits;
-    deadline: ExtractionDeadline;
-}): Promise<void>;
-//# sourceMappingURL=archive-tar-extract.d.ts.map

package/dist/archive-tar-extract.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"archive-tar-extract.d.ts","sourceRoot":"","sources":["../src/archive-tar-extract.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,4BAA4B,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAExF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAQlE,wBAAsB,cAAc,CAAC,MAAM,EAAE;IAC3C,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,qBAAqB,CAAC;IAAC,MAAM,EAAE,4BAA4B,CAAC;IAC1F,SAAS,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,kBAAkB,CAAC;CACzD,GAAG,OAAO,CAAC,IAAI,CAAC,CAqChB"}

package/dist/archive-tar-extract.js

@@ -1,49 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { Readable } from "node:stream";
-import { stripArchivePath } from "./archive-entry.js";
-import {} from "./archive-deadline.js";
-import { mergePlannedArchiveIntoDestination } from "./archive-merge.js";
-import { resolveArchiveEntryMode } from "./archive-policy.js";
-import { prepareArchiveDestinationDir, preparePrivateArchiveOutputPath, withStagedArchiveDestination } from "./archive-staging.js";
-import { createTarEntryPreflightChecker } from "./archive-tar.js";
-import { inspectTar, replayTar } from "./archive-tar-stream.js";
-import { runPinnedWriteHelper } from "./pinned-write.js";
-export async function extractWasmTar(params) {
-    const { options, deadline, tarLimits } = params;
-    const manifest = [];
-    await inspectTar({ archivePath: params.archivePath, limits: tarLimits, signal: deadline.signal,
-        onMember: (entry) => { manifest.push(entry); } });
-    deadline.check();
-    const destinationRealDir = await prepareArchiveDestinationDir(options.destDir);
-    await withStagedArchiveDestination({ destinationRealDir, run: async (stagingPath) => {
-            const stagingDir = await fs.realpath(stagingPath);
-            const check = createTarEntryPreflightChecker({ rootDir: destinationRealDir,
-                stripComponents: options.stripComponents, limits: params.limits,
-                entryFilter: options.entryFilter, onFiltered: options.onFiltered });
-            const strip = Math.max(0, Math.floor(options.stripComponents ?? 0));
-            const accepted = manifest.filter((entry) => { deadline.check(); return check(entry); }).map((entry) => {
-                const kind = entry.type === "Directory" || entry.type === "GNUDumpDir" ? "directory" : "file";
-                return { ...entry, path: stripArchivePath(entry.path, strip), kind,
-                    mode: resolveArchiveEntryMode({ kind, archivedMode: entry.mode, policy: options.entryModes }) };
-            });
-            await replayTar({ archivePath: params.archivePath, limits: tarLimits, signal: deadline.signal, members: accepted,
-                async consume(member, payload) {
-                    deadline.check();
-                    await preparePrivateArchiveOutputPath({ destinationDir: stagingDir, destinationRealDir: stagingDir,
-                        relPath: member.path, outPath: path.join(stagingDir, member.path), originalPath: member.path,
-                        isDirectory: member.kind === "directory", deadline });
-                    if (member.kind === "file") {
-                        await runPinnedWriteHelper({ rootPath: stagingDir, relativeParentPath: path.posix.dirname(member.path),
-                            basename: path.posix.basename(member.path), mkdir: false, mode: 0o600, overwrite: false,
-                            maxBytes: member.size, input: { kind: "stream", stream: Readable.from(payload) } });
-                    }
-                    deadline.check();
-                },
-            });
-            deadline.check();
-            await mergePlannedArchiveIntoDestination({ entries: accepted, sourceDir: stagingDir,
-                destinationDir: options.destDir, destinationRealDir, deadline });
-            deadline.check();
-        } });
-}

package/dist/fsync.d.ts

@@ -1,2 +0,0 @@
-export { syncDirectoryBestEffort } from "./directory-durability.js";
-//# sourceMappingURL=fsync.d.ts.map

package/dist/fsync.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"fsync.d.ts","sourceRoot":"","sources":["../src/fsync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/fsync.js

@@ -1 +0,0 @@
-export { syncDirectoryBestEffort } from "./directory-durability.js";

package/dist/json-durable-queue-retirement.d.ts

@@ -1,9 +0,0 @@
-export declare function recoverDurableQueueRetirement(params: {
-    jsonPath: string;
-    processingPath: string;
-}): Promise<void>;
-export declare function retireDurableQueueSource(params: {
-    jsonPath: string;
-    processingPath: string;
-}): Promise<void>;
-//# sourceMappingURL=json-durable-queue-retirement.d.ts.map

package/dist/json-durable-queue-retirement.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"json-durable-queue-retirement.d.ts","sourceRoot":"","sources":["../src/json-durable-queue-retirement.ts"],"names":[],"mappings":"AAgFA,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmChB;AAED,wBAAsB,wBAAwB,CAAC,MAAM,EAAE;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBhB"}

package/dist/json-durable-queue-retirement.js

@@ -1,126 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { syncDirectory } from "./directory-durability.js";
-import { FsSafeError } from "./errors.js";
-import { sameFileIdentityForCleanup } from "./file-identity.js";
-const RETIREMENT_ROOT_NAME = ".fs-safe-retirements";
-const RETIREMENT_ENTRY_NAME = "entry";
-function getErrorCode(error) {
-    return error && typeof error === "object" && "code" in error
-        ? String(error.code)
-        : null;
-}
-async function lstatOrNull(filePath) {
-    try {
-        return await fs.lstat(filePath, { bigint: true });
-    }
-    catch (error) {
-        if (getErrorCode(error) === "ENOENT")
-            return null;
-        throw error;
-    }
-}
-function assertDirectory(identity, label) {
-    if (identity.isSymbolicLink() || !identity.isDirectory()) {
-        throw new FsSafeError("path-mismatch", `${label} is not an owned directory`);
-    }
-}
-async function regularFileIdentity(filePath) {
-    const identity = await lstatOrNull(filePath);
-    if (!identity)
-        return null;
-    if (identity.isSymbolicLink() || !identity.isFile()) {
-        throw new FsSafeError("path-mismatch", "queue retirement path is not a regular file");
-    }
-    return identity;
-}
-function retirementPaths(jsonPath) {
-    const rootPath = path.join(path.dirname(jsonPath), RETIREMENT_ROOT_NAME);
-    const dirPath = path.join(rootPath, path.basename(jsonPath));
-    return { dirPath, entryPath: path.join(dirPath, RETIREMENT_ENTRY_NAME), rootPath };
-}
-async function inspectRetirementRoot(jsonPath) {
-    const rootPath = retirementPaths(jsonPath).rootPath;
-    const root = await lstatOrNull(rootPath);
-    if (!root)
-        return null;
-    assertDirectory(root, "queue retirement root");
-    return rootPath;
-}
-async function ensureRetirementRoot(jsonPath) {
-    const parentPath = path.dirname(jsonPath);
-    const rootPath = retirementPaths(jsonPath).rootPath;
-    await fs.mkdir(rootPath, { mode: 0o700 }).catch((error) => {
-        if (getErrorCode(error) !== "EEXIST")
-            throw error;
-    });
-    const root = await fs.lstat(rootPath, { bigint: true });
-    assertDirectory(root, "queue retirement root");
-    await syncDirectory(parentPath);
-    return rootPath;
-}
-async function removeRetirementRecord(params) {
-    await fs.rmdir(params.dirPath).catch((error) => {
-        if (getErrorCode(error) !== "ENOENT")
-            throw error;
-    });
-    await syncDirectory(params.rootPath);
-}
-export async function recoverDurableQueueRetirement(params) {
-    const rootPath = await inspectRetirementRoot(params.jsonPath);
-    if (!rootPath)
-        return;
-    const { dirPath, entryPath } = retirementPaths(params.jsonPath);
-    const dir = await lstatOrNull(dirPath);
-    if (!dir)
-        return;
-    assertDirectory(dir, "queue retirement record");
-    const names = await fs.readdir(dirPath);
-    if (names.length === 0) {
-        await removeRetirementRecord({ dirPath, rootPath });
-        return;
-    }
-    if (names.length !== 1 || names[0] !== RETIREMENT_ENTRY_NAME) {
-        throw new FsSafeError("path-mismatch", "queue retirement record is ambiguous");
-    }
-    const entry = await regularFileIdentity(entryPath);
-    const processing = await regularFileIdentity(params.processingPath);
-    if (!entry || !processing) {
-        throw new FsSafeError("path-mismatch", "queue retirement ownership is incomplete");
-    }
-    if (!sameFileIdentityForCleanup(entry, processing)) {
-        const pending = await regularFileIdentity(params.jsonPath);
-        if (!pending) {
-            await fs.link(entryPath, params.jsonPath);
-            await syncDirectory(path.dirname(params.jsonPath));
-        }
-        else if (sameFileIdentityForCleanup(pending, entry)) {
-            await syncDirectory(path.dirname(params.jsonPath));
-        }
-        else if (pending.nlink > 1n) {
-            throw new FsSafeError("path-mismatch", "queue replacement identity is ambiguous");
-        }
-    }
-    await fs.unlink(entryPath);
-    await syncDirectory(dirPath);
-    await removeRetirementRecord({ dirPath, rootPath });
-}
-export async function retireDurableQueueSource(params) {
-    await recoverDurableQueueRetirement(params);
-    const rootPath = await ensureRetirementRoot(params.jsonPath);
-    const { dirPath, entryPath } = retirementPaths(params.jsonPath);
-    await fs.mkdir(dirPath, { mode: 0o700 });
-    await syncDirectory(rootPath);
-    try {
-        await fs.rename(params.jsonPath, entryPath);
-    }
-    catch (error) {
-        if (getErrorCode(error) !== "ENOENT")
-            throw error;
-        await removeRetirementRecord({ dirPath, rootPath });
-        return;
-    }
-    await syncDirectory(dirPath);
-    await syncDirectory(path.dirname(params.jsonPath));
-    await recoverDurableQueueRetirement(params);
-}

package/dist/json-durable-queue-transfer-lock.d.ts

@@ -1,2 +0,0 @@
-export declare function withQueueTransferLock<T>(filePath: string, run: () => Promise<T>): Promise<T>;
-//# sourceMappingURL=json-durable-queue-transfer-lock.d.ts.map

package/dist/json-durable-queue-transfer-lock.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"json-durable-queue-transfer-lock.d.ts","sourceRoot":"","sources":["../src/json-durable-queue-transfer-lock.ts"],"names":[],"mappings":"AAKA,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,CAAC,CAqBZ"}