@openclaw/fs-safe 0.8.2 → 0.8.4

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/strict-file-identity.d.ts

@@ -1,6 +1,6 @@
 import type { BigIntStats } from "node:fs";
 type ExactFileIdentity = Pick<BigIntStats, "dev" | "ino">;
-export declare function inspectFileIdentity<T extends ExactFileIdentity>(inspect: () => Promise<T>, expected?: ExactFileIdentity, platform?: NodeJS.Platform): Promise<T>;
+export declare function inspectFileIdentity<T extends ExactFileIdentity>(inspect: () => T | Promise<T>, expected?: ExactFileIdentity, platform?: NodeJS.Platform): Promise<T>;
 export declare function inspectFileIdentitySync<T extends ExactFileIdentity>(inspect: () => T, expected?: ExactFileIdentity, platform?: NodeJS.Platform): T;
 export {};
 //# sourceMappingURL=strict-file-identity.d.ts.map

package/dist/strict-file-identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strict-file-identity.d.ts","sourceRoot":"","sources":["../src/strict-file-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAI3C,KAAK,iBAAiB,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;AA+B1D,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,iBAAiB,EACnE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,iBAAiB,EACjE,OAAO,EAAE,MAAM,CAAC,EAChB,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,CAAC,CAOH"}
+{"version":3,"file":"strict-file-identity.d.ts","sourceRoot":"","sources":["../src/strict-file-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAI3C,KAAK,iBAAiB,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;AA+B1D,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,iBAAiB,EACnE,OAAO,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC7B,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,iBAAiB,EACjE,OAAO,EAAE,MAAM,CAAC,EAChB,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,CAAC,CAOH"}

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/symlink-parents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symlink-parents.d.ts","sourceRoot":"","sources":["../src/symlink-parents.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAyBF,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,6BAA6B,GACpC,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,6BAA6B,GACpC,IAAI,CA6BN"}
+{"version":3,"file":"symlink-parents.d.ts","sourceRoot":"","sources":["../src/symlink-parents.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAyBF,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,6BAA6B,GACpC,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,6BAA6B,GACpC,IAAI,CA6BN"}

package/dist/symlink-parents.js

@@ -1,5 +1,4 @@
 import fsSync from "node:fs";
-import fs from "node:fs/promises";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { hasNodeErrorCode, isPathRelativeEscape } from "./path.js";
@@ -30,7 +29,7 @@ export async function assertNoSymlinkParents(params) {
     for (const [index, segment] of walk.segments.entries()) {
         current = path.join(current, segment);
         try {
-            const stat = await fs.lstat(current);
+            const stat = fsSync.lstatSync(current);
             if (stat.isSymbolicLink()) {
                 if (params.allowRootChildSymlink && path.dirname(current) === walk.root) {
                     continue;

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

@@ -422,6 +422,63 @@ Normal link/filter policy still governs the described member. Canonical
 pre-strip filter paths, decoded-stream ceilings, and physical EOF checks apply
 to plain/gzip TAR and native zstd/bzip2 alike.
 
+## `inspectTarArchive`
+
+Inspect accepted TAR members without creating an extracted tree. This operation
+uses the same complete Rust/WASM admission and TypeScript extraction planner as
+`extractArchive`, with zero stripping. It detects plain TAR or gzip from the
+input bytes; ZIP, zstd, and bzip2 are not part of this inspection API.
+
+```ts
+import { inspectTarArchive } from "@openclaw/fs-safe/archive";
+
+const entries = await inspectTarArchive({
+  archivePath: "/srv/uploads/tree.tar.gz",
+  timeoutMs: 30_000,
+  limits: {
+    maxArchiveBytes: 16 * 1024 * 1024,
+    maxEntries: 5_000,
+    maxEntryBytes: 16 * 1024 * 1024,
+    maxExtractedBytes: 64 * 1024 * 1024,
+  },
+  entryFilter: ({ kind }) => kind === "file" || kind === "directory" ? "extract" : "skip",
+  onFiltered: "reject-archive",
+});
+```
+
+`InspectTarArchiveOptions` accepts `archivePath`, `timeoutMs`, `limits`,
+`entryFilter`, and `onFiltered`, with the same defaults and error classes as
+extraction. The result is a frozen array of frozen `InspectedTarEntry` records:
+`{ path: string; kind: "file" | "directory"; size: number }`, in archive order.
+`size` is the effective declared payload length. `path` is extraction's
+canonical pre-strip identity: case, Unicode spelling, BOM, and embedded LF are
+preserved, while separators and dot components follow the existing archive path
+contract. No human-readable tar listing or escape decoding is involved.
+
+Full framing, gzip integrity, EOF, metadata, decoded-byte, and manifest-budget
+validation finishes before the caller's filter runs. The shared planner then
+applies traversal, collision, depth, blocked-type, and accepted-payload limits.
+A failure returns no partial result. Filter callbacks are decisions, not admission
+receipts: later policy, collision, or budget checks can still reject the archive.
+Only the resolved Promise/result is authorization-worthy; do not perform
+irreversible actions from a filter callback.
+
+Root-only records count toward entry limits but produce no result; PAX/GNU metadata headers are not members. Only accepted
+file/directory members appear, not implicit parent directories. Unsupported
+records follow extraction's omission policy unless the filter rejects them, as
+in the example. AppleDouble records encoded as ordinary files are ordinary
+members, not hidden metadata.
+
+Inspection pins and privately stages its input, then cleans up that copy. It
+neither creates destination paths nor tests destination permissions or platform
+filename restrictions. Its result is evidence about those inspected bytes, not
+an extraction capability or a promise that a later file at `archivePath` is
+unchanged. Callers making authorization decisions must retain the same private
+immutable archive or verify byte identity before extracting with matching
+filter/limit settings. Extraction always performs its own admission and guarded
+publication. Native `off`, `auto`, and `require` retain their existing selection
+and availability semantics; inspection does not fall back after native failure.
+
 ## `resolveArchiveKind`
 
 ```ts

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/reading.md

@@ -12,6 +12,8 @@ const opened = await fs.open("large.log");               // FileHandle for strea
 
 ## What every read does
 
+Identity and containment checks use brief synchronous metadata calls, like Node's module resolution, while file data is read asynchronously. Canonical paths retain Node's native realpath spelling, including expansion of Windows short paths.
+
 Regardless of shape, every read goes through the same boundary checks:
 
 1. Resolve the input lexically against the canonical real root.

package/docs/root.md

@@ -18,6 +18,7 @@ const fs = await root("/srv/workspace", {
 function root(rootDir: string, defaults?: RootDefaults): Promise<Root>;
 
 type RootDefaults = {
+  durable?: boolean;               // fsync write/create/writeJson/createJson/append; default true
   hardlinks?: "reject" | "allow";  // refuse files with nlink > 1 on read; defaults to "reject"
   denyMutations?: DenyMutationPolicy; // absolute paths/prefixes mutation methods may not change
   maxBytes?: number;               // refuse reads larger than this many bytes; defaults to 16 MiB
@@ -99,7 +100,7 @@ fs.write(rel, data, options?)            // overwrite-ok atomic write
 fs.create(rel, data, options?)           // throws "already-exists" if target exists
 fs.writeJson(rel, value, options?)       // JSON.stringify + atomic write
 fs.createJson(rel, value, options?)      // create() variant of writeJson
-fs.append(rel, data, options?)           // append text/buffer; syncs before close
+fs.append(rel, data, options?)           // append text/buffer; syncs before close by default
 fs.copyIn(rel, sourceAbsPath, options?)  // copy from outside the root, atomically, with size cap
 fs.openWritable(rel, options?)           // FileHandle for streaming writes; supports await using
 fs.move(from, to, options?)              // rename within the root; defaults to no clobber
@@ -110,6 +111,14 @@ fs.ensureRoot(options?)                  // accepts "" / "." as the root itself
 
 `write`, `create`, `append`, `writeJson`, and `createJson` accept `mode?: number`; use `0o600` for credentials and other private state. `writeJson` also accepts the same options as `JSON.stringify` plus `trailingNewline?: boolean` (defaults `true` so the file ends in `\n`).
 
+These five methods also accept `durable?: boolean`: the per-call value overrides
+`Root.defaults.durable`, which defaults to `true` when omitted. An explicitly
+`undefined` per-call value preserves the root default. `durable: false` keeps
+the existing publication behavior, modes, and identity checks but skips file
+and parent-directory fsync calls. Use it only for reconstructible data: a crash
+may lose the write or leave the previous file. See [Writing](writing.md#write-options)
+for platform details.
+
 `copyIn` is a one-shot ingest from a trusted absolute source path: it streams the source through the boundary, atomically renames into the root, and respects `maxBytes`.
 
 Root operations that choose a new destination reject a leading Windows

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/types.md

@@ -100,6 +100,7 @@ type RenameIdentityPolicy = "strict" | "verify-content-with-lock";
 
 type RootDefaults = {
   denyMutations?: DenyMutationPolicy;
+  durable?: boolean; // default true for write/create/writeJson/createJson/append
   hardlinks?: "reject" | "allow";
   maxBytes?: number;
   mkdir?: boolean; // default true for mutation methods
@@ -126,7 +127,7 @@ type RootOptions = {
 
 ```ts
 type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "nonBlockingRead" | "symlinks">;
-type RootWriteOptions = Pick<RootDefaults, "denyMutations" | "mkdir" | "mode" | "renameIdentity"> & {
+type RootWriteOptions = Pick<RootDefaults, "denyMutations" | "durable" | "mkdir" | "mode" | "renameIdentity"> & {
   encoding?: BufferEncoding;
   overwrite?: boolean;
 };

package/docs/writing.md

@@ -77,13 +77,41 @@ await fs.write("state/last-run.json", JSON.stringify(run));
 await fs.write("notes/today.txt", "hello\n", { encoding: "utf8" });
 ```
 
-`data` accepts `string | Buffer`. `options` are `{ denyMutations?: DenyMutationPolicy; encoding?: BufferEncoding; mkdir?: boolean; mode?: number; overwrite?: boolean; renameIdentity?: RenameIdentityPolicy }`. `mode` sets the file's POSIX mode. If neither the call nor `RootDefaults` supplies it, a replacement preserves the existing file mode and a new file uses `0o600`. `mkdir` and `overwrite` both default to `true`; set `overwrite: false` for the same no-clobber behavior as `create()`.
+`data` accepts `string | Buffer`. `mode` sets the file's POSIX mode. If neither the call nor `RootDefaults` supplies it, a replacement preserves the existing file mode and a new file uses `0o600`. `mkdir` and `overwrite` both default to `true`; set `overwrite: false` for the same no-clobber behavior as `create()`.
+
+#### Write options
+
+| Option | Type | Default / behavior |
+|---|---|---|
+| `denyMutations` | `DenyMutationPolicy` | Merged with root-level denies. |
+| `durable` | `boolean` | `true`; use `false` to skip file and parent fsync. |
+| `encoding` | `BufferEncoding` | `"utf8"` for strings. |
+| `mkdir` | `boolean` | `true`; creates missing parents. |
+| `mode` | `number` | Inherited on replacement, otherwise `0o600`. |
+| `overwrite` | `boolean` | `true`; `false` is create-only. |
+| `renameIdentity` | `RenameIdentityPolicy` | `"strict"`. |
+
+`write`, `create`, `writeJson`, `createJson`, and `append` accept `durable`.
+Precedence is per-call option, then `Root.defaults.durable`, then `true`;
+an explicitly `undefined` call option preserves the root default.
+`durable: false` keeps the sibling-temp replace/rename behavior of replacement
+writes but skips file and parent-directory fsync calls. Create-only and append
+publication behavior, permissions, identity checks, and error codes are unchanged.
+Use it only for reconstructible data: a crash may lose the write or leave the
+previous file. `copyIn`, `move`, and streaming `openWritable` do not use this option.
+The existing pure-JavaScript Windows writer performs no fsync calls in either
+setting; native Windows writes honor the option. Directory sync remains best-effort.
 
 POSIX modes without read permission, including `0o000` and `0o200`, succeed:
 final verification uses a descriptor retained by the writer rather than reopening
 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.
+With durability enabled (the default), native publication syncs content before rename and 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.
@@ -138,7 +166,7 @@ type RootWriteJsonOptions = RootWriteOptions & {
 
 ### `fs.append(rel, data, options?)`
 
-Open in append mode, write, sync the file handle, and close. Honors `mkdir` for the parent directory and syncs the parent directory when the append creates the file. Pass `prependNewlineIfNeeded: true` to insert a `\n` if the file does not already end in one.
+Open in append mode, write, sync the file handle, and close. Honors `mkdir` for the parent directory and syncs the parent directory when the append creates the file. `durable: false` skips both syncs. Pass `prependNewlineIfNeeded: true` to insert a `\n` if the file does not already end in one.
 
 ```ts
 await fs.append("logs/today.log", `[${ts}] ${line}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "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.4",
+    "@openclaw/fs-safe-darwin-x64": "0.8.4",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.8.4",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.8.4",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.8.4",
+    "@openclaw/fs-safe-linux-x64-musl": "0.8.4",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.8.4",
     "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