@openclaw/fs-safe 0.4.6 → 0.4.7

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.4.7 - 2026-07-24
+
+### Features
+
+- Add `@openclaw/fs-safe/durability` with identity-pinned directory handles,
+  explicit strict sync outcomes, synchronous and best-effort variants, and
+  durable nested-directory creation through every new parent edge.
+
+### Security and Correctness
+
+- Reject final symlinks, FIFOs, non-directories, canonical-path drift, and
+  descriptor/path identity replacement before or after directory sync.
+- Propagate POSIX directory synchronization failures while classifying known
+  unsupported Windows directory flushing only after revalidating the target;
+  directory-open access failures remain strict.
+- Route sibling-temp, root, and pinned-write best-effort parent synchronization
+  through the shared guarded primitive instead of maintaining divergent implementations.
+
+### Docs and Tooling
+
+- Document directory receipts, pin lifecycle, platform outcomes, custom
+  creation callbacks, and the boundary between filesystem durability and
+  application commit protocols.
+
 ## 0.4.6 - 2026-07-24
 
 ### Highlights

package/README.md

@@ -26,7 +26,7 @@ Full docs and reference at **[fs-safe.io](https://fs-safe.io)**.
 
 ## Contents
 
-[Why this exists](#why-this-exists) · [Not a sandbox](#not-a-sandbox) · [Install](#install) · [Quick start](#quick-start) · [Reading](#reading) · [Subpaths](#subpaths) · [Failure semantics](#failure-semantics-in-the-name) · [Atomic writes](#atomic-writes) · [External outputs](#external-outputs) · [Stores](#stores) · [Secure absolute reads](#secure-absolute-file-reads) · [Walking](#directory-walking) · [Archive extraction](#archive-extraction) · [Path scopes](#advanced-path-scopes) · [Errors](#errors) · [Safety model](#safety-model) · [Limitations](#limitations)
+[Why this exists](#why-this-exists) · [Not a sandbox](#not-a-sandbox) · [Install](#install) · [Quick start](#quick-start) · [Reading](#reading) · [Subpaths](#subpaths) · [Failure semantics](#failure-semantics-in-the-name) · [Directory durability](#directory-durability) · [Atomic writes](#atomic-writes) · [External outputs](#external-outputs) · [Stores](#stores) · [Secure absolute reads](#secure-absolute-file-reads) · [Walking](#directory-walking) · [Archive extraction](#archive-extraction) · [Path scopes](#advanced-path-scopes) · [Errors](#errors) · [Safety model](#safety-model) · [Limitations](#limitations)
 
 ## Why this exists
 
@@ -189,6 +189,7 @@ that OpenClaw needs to compose higher-level APIs are grouped under
 | `@openclaw/fs-safe/store` | `fileStore`, `fileStoreSync`, and `jsonStore` |
 | `@openclaw/fs-safe/secret` | strict and try-style secret file read/write helpers |
 | `@openclaw/fs-safe/atomic` | `replaceFileAtomic`, `replaceFileAtomicSync`, `replaceDirectoryAtomic`, `movePathWithCopyFallback` |
+| `@openclaw/fs-safe/durability` | pinned directory identities, strict and best-effort directory sync, durable nested-directory creation |
 | `@openclaw/fs-safe/temp` | `tempWorkspace`, `tempWorkspaceSync`, `withTempWorkspace`, `resolveSecureTempRoot` |
 | `@openclaw/fs-safe/secure-file` | fd-pinned absolute file reads with owner, mode, ACL, trusted-dir, size, and timeout checks |
 | `@openclaw/fs-safe/file-lock` | `acquireFileLock`, `withFileLock`, `createFileLockManager`, and related lock types |
@@ -216,6 +217,35 @@ performs the root-bounded open and JSON object validation in one step. Use
 `readRootStructuredFileSync()` when the parser lives outside fs-safe, such as
 JSON5-backed plugin manifests.
 
+## Directory durability
+
+```ts
+import { ensureDurableDirectory, pinDirectory } from "@openclaw/fs-safe/durability";
+
+const receipt = await ensureDurableDirectory({
+  directoryPath: "/srv/backups/sqlite",
+  mode: 0o700,
+});
+const pinned = await pinDirectory(receipt);
+try {
+  await publishSnapshot();
+  const outcome = await pinned.sync();
+  // `unsupported` is explicit on platforms without directory flushing.
+  console.log(outcome.status);
+} finally {
+  await pinned.close();
+}
+```
+
+The durability subpath pins a directory descriptor to its pathname identity,
+detects symlink/FIFO/replacement races, and synchronizes every new parent edge
+when creating a nested directory. Strict sync propagates real I/O failures and
+reports known Windows directory-flush limitations explicitly. Separate
+best-effort helpers preserve operations that do not promise crash durability.
+
+See [Directory durability](docs/durability.md) for the receipt, pin lifecycle,
+creation callback, and platform contract.
+
 ## Atomic writes
 
 `replaceFileAtomic()` writes a sibling temp file, optionally fsyncs it, and renames it over the destination. Mode preservation, rename retry / copy fallback on `EPERM`, parent-directory fsync, and a `beforeRename` hook for backup or observer flows are all opt-in. `movePathWithCopyFallback()` stages cross-device moves before commit and removes only the copied source entries, so concurrent source additions or replacements are preserved.

package/dist/directory-durability.d.ts

@@ -0,0 +1,44 @@
+import { type Stats } from "node:fs";
+import { type FileIdentityStat } from "./file-identity.js";
+export type DirectorySyncOutcome = {
+    status: "synced";
+} | {
+    status: "unsupported";
+    code?: string;
+};
+export type DirectoryReceipt = {
+    path: string;
+    realPath: string;
+    identity: Stats;
+};
+export type DurableDirectoryReceipt = DirectoryReceipt & {
+    parentSync: DirectorySyncOutcome | {
+        status: "not-needed";
+    };
+};
+export type PinnedDirectory = {
+    readonly receipt: DirectoryReceipt;
+    assertCurrent(): Promise<void>;
+    sync(): Promise<DirectorySyncOutcome>;
+    close(): Promise<void>;
+};
+export type EnsureDurableDirectoryOptions = {
+    directoryPath: string;
+    label?: string;
+    mode?: number;
+    expectedExistingIdentity?: FileIdentityStat;
+    create?: (directoryPath: string) => Promise<void>;
+};
+export declare function pinDirectory(directory: string | DirectoryReceipt, options?: {
+    label?: string;
+}): Promise<PinnedDirectory>;
+export declare function syncDirectory(directory: string | DirectoryReceipt, options?: {
+    label?: string;
+}): Promise<DirectorySyncOutcome>;
+export declare function syncDirectorySync(directory: string | DirectoryReceipt, options?: {
+    label?: string;
+}): DirectorySyncOutcome;
+export declare function syncDirectoryBestEffort(directoryPath: string): Promise<void>;
+export declare function syncDirectoryBestEffortSync(directoryPath: string): void;
+export declare function ensureDurableDirectory(options: EnsureDurableDirectoryOptions): Promise<DurableDirectoryReceipt>;
+//# sourceMappingURL=directory-durability.d.ts.map

package/dist/directory-durability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-durability.d.ts","sourceRoot":"","sources":["../src/directory-durability.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAM7C,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE7E,MAAM,MAAM,oBAAoB,GAC5B;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GACpB;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,KAAK,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,GAAG;IACvD,UAAU,EAAE,oBAAoB,GAAG;QAAE,MAAM,EAAE,YAAY,CAAA;KAAE,CAAC;CAC7D,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wBAAwB,CAAC,EAAE,gBAAgB,CAAC;IAC5C,MAAM,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD,CAAC;AAgKF,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EACpC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,eAAe,CAAC,CAa1B;AAED,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EACpC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,oBAAoB,CAAC,CAmB/B;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,GAAG,gBAAgB,EACpC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,oBAAoB,CAuCtB;AAED,wBAAsB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAElF;AAED,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAMvE;AAuBD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,uBAAuB,CAAC,CA8ElC"}

package/dist/directory-durability.js

@@ -0,0 +1,299 @@
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ensureAbsoluteDirectory } from "./absolute-path.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
+function directoryOpenFlags() {
+    if (process.platform === "win32") {
+        return "r";
+    }
+    return (fsSync.constants.O_RDONLY |
+        fsSync.constants.O_DIRECTORY |
+        fsSync.constants.O_NOFOLLOW |
+        fsSync.constants.O_NONBLOCK);
+}
+function isWindowsDirectorySyncUnsupported(error) {
+    if (process.platform !== "win32") {
+        return false;
+    }
+    const code = error.code;
+    return (code === "EACCES" ||
+        code === "EINVAL" ||
+        code === "EISDIR" ||
+        code === "ENOSYS" ||
+        code === "ENOTSUP" ||
+        code === "EPERM");
+}
+function isWindowsDirectoryOpenUnsupported(error) {
+    if (process.platform !== "win32") {
+        return false;
+    }
+    const code = error.code;
+    return code === "EINVAL" || code === "EISDIR" || code === "ENOSYS" || code === "ENOTSUP";
+}
+function unsupportedOutcome(error) {
+    const code = error.code;
+    return code ? { status: "unsupported", code } : { status: "unsupported" };
+}
+function assertDirectory(identity, pathname, label) {
+    if (identity.isSymbolicLink() || !identity.isDirectory()) {
+        throw new FsSafeError("not-file", `${label} must be a real directory: ${pathname}`);
+    }
+}
+async function createDirectoryReceipt(directoryPath, label) {
+    const resolvedPath = path.resolve(directoryPath);
+    const identity = await fs.lstat(resolvedPath);
+    assertDirectory(identity, resolvedPath, label);
+    return {
+        path: resolvedPath,
+        realPath: await fs.realpath(resolvedPath),
+        identity,
+    };
+}
+function createDirectoryReceiptSync(directoryPath, label) {
+    const resolvedPath = path.resolve(directoryPath);
+    const identity = fsSync.lstatSync(resolvedPath);
+    assertDirectory(identity, resolvedPath, label);
+    return {
+        path: resolvedPath,
+        realPath: fsSync.realpathSync(resolvedPath),
+        identity,
+    };
+}
+async function assertDirectoryReceiptCurrent(receipt, label) {
+    const currentIdentity = await fs.lstat(receipt.path);
+    assertDirectory(currentIdentity, receipt.path, label);
+    if (!sameFileIdentity(receipt.identity, currentIdentity) ||
+        (await fs.realpath(receipt.path)) !== receipt.realPath) {
+        throw new FsSafeError("path-mismatch", `${label} changed during durable directory operation: ${receipt.path}`);
+    }
+}
+function assertDirectoryReceiptCurrentSync(receipt, label) {
+    const currentIdentity = fsSync.lstatSync(receipt.path);
+    assertDirectory(currentIdentity, receipt.path, label);
+    if (!sameFileIdentity(receipt.identity, currentIdentity) ||
+        fsSync.realpathSync(receipt.path) !== receipt.realPath) {
+        throw new FsSafeError("path-mismatch", `${label} changed during durable directory operation: ${receipt.path}`);
+    }
+}
+async function assertOpenDirectoryCurrent(handle, receipt, label) {
+    const openedIdentity = await handle.stat();
+    assertDirectory(openedIdentity, receipt.path, label);
+    if (!sameFileIdentity(receipt.identity, openedIdentity)) {
+        throw new FsSafeError("path-mismatch", `${label} handle changed during directory sync: ${receipt.path}`);
+    }
+    await assertDirectoryReceiptCurrent(receipt, label);
+}
+class PinnedDirectoryImpl {
+    receipt;
+    #handle;
+    #label;
+    #closed = false;
+    constructor(handle, receipt, label) {
+        this.#handle = handle;
+        this.receipt = receipt;
+        this.#label = label;
+    }
+    async assertCurrent() {
+        if (this.#closed) {
+            throw new FsSafeError("helper-failed", `${this.#label} pin is already closed`);
+        }
+        await assertOpenDirectoryCurrent(this.#handle, this.receipt, this.#label);
+    }
+    async sync() {
+        await this.assertCurrent();
+        try {
+            await this.#handle.sync();
+        }
+        catch (error) {
+            if (!isWindowsDirectorySyncUnsupported(error)) {
+                throw error;
+            }
+            await this.assertCurrent();
+            return unsupportedOutcome(error);
+        }
+        await this.assertCurrent();
+        return { status: "synced" };
+    }
+    async close() {
+        if (this.#closed) {
+            return;
+        }
+        this.#closed = true;
+        await this.#handle.close();
+    }
+}
+export async function pinDirectory(directory, options = {}) {
+    const label = options.label ?? "directory";
+    const receipt = typeof directory === "string" ? await createDirectoryReceipt(directory, label) : directory;
+    await assertDirectoryReceiptCurrent(receipt, label);
+    const handle = await fs.open(receipt.path, directoryOpenFlags());
+    try {
+        await assertOpenDirectoryCurrent(handle, receipt, label);
+        return new PinnedDirectoryImpl(handle, receipt, label);
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        throw error;
+    }
+}
+export async function syncDirectory(directory, options = {}) {
+    const label = options.label ?? "directory";
+    const receipt = typeof directory === "string" ? await createDirectoryReceipt(directory, label) : directory;
+    let pinned;
+    try {
+        pinned = await pinDirectory(receipt, { label });
+    }
+    catch (error) {
+        if (!isWindowsDirectoryOpenUnsupported(error)) {
+            throw error;
+        }
+        await assertDirectoryReceiptCurrent(receipt, label);
+        return unsupportedOutcome(error);
+    }
+    try {
+        return await pinned.sync();
+    }
+    finally {
+        await pinned.close();
+    }
+}
+export function syncDirectorySync(directory, options = {}) {
+    const label = options.label ?? "directory";
+    const receipt = typeof directory === "string" ? createDirectoryReceiptSync(directory, label) : directory;
+    assertDirectoryReceiptCurrentSync(receipt, label);
+    let descriptor;
+    try {
+        descriptor = fsSync.openSync(receipt.path, directoryOpenFlags());
+    }
+    catch (error) {
+        if (!isWindowsDirectoryOpenUnsupported(error)) {
+            throw error;
+        }
+        assertDirectoryReceiptCurrentSync(receipt, label);
+        return unsupportedOutcome(error);
+    }
+    try {
+        const openedIdentity = fsSync.fstatSync(descriptor);
+        assertDirectory(openedIdentity, receipt.path, label);
+        if (!sameFileIdentity(receipt.identity, openedIdentity)) {
+            throw new FsSafeError("path-mismatch", `${label} handle changed during directory sync: ${receipt.path}`);
+        }
+        assertDirectoryReceiptCurrentSync(receipt, label);
+        try {
+            fsSync.fsyncSync(descriptor);
+        }
+        catch (error) {
+            if (!isWindowsDirectorySyncUnsupported(error)) {
+                throw error;
+            }
+            assertDirectoryReceiptCurrentSync(receipt, label);
+            return unsupportedOutcome(error);
+        }
+        assertDirectoryReceiptCurrentSync(receipt, label);
+        return { status: "synced" };
+    }
+    finally {
+        fsSync.closeSync(descriptor);
+    }
+}
+export async function syncDirectoryBestEffort(directoryPath) {
+    await syncDirectory(directoryPath).catch(() => undefined);
+}
+export function syncDirectoryBestEffortSync(directoryPath) {
+    try {
+        syncDirectorySync(directoryPath);
+    }
+    catch {
+        // Compatibility helper for operations whose primary write may remain usable.
+    }
+}
+async function findExistingAncestorReceipt(targetPath, label) {
+    let currentPath = path.resolve(targetPath);
+    while (true) {
+        try {
+            return await createDirectoryReceipt(currentPath, label);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+        const parentPath = path.dirname(currentPath);
+        if (parentPath === currentPath) {
+            throw new FsSafeError("not-found", `${label} has no existing directory ancestor`);
+        }
+        currentPath = parentPath;
+    }
+}
+export async function ensureDurableDirectory(options) {
+    const directoryPath = path.resolve(options.directoryPath);
+    const label = options.label ?? "directory";
+    const ancestorReceipt = await findExistingAncestorReceipt(directoryPath, label);
+    const targetExists = ancestorReceipt.path === directoryPath;
+    if (options.expectedExistingIdentity &&
+        (!targetExists || !sameFileIdentity(options.expectedExistingIdentity, ancestorReceipt.identity))) {
+        throw new FsSafeError("path-mismatch", `${label} changed before durable directory pinning: ${directoryPath}`);
+    }
+    const ancestor = await pinDirectory(ancestorReceipt, { label });
+    const pinnedDirectories = [ancestor];
+    try {
+        await ancestor.assertCurrent();
+        if (!targetExists) {
+            if (options.create) {
+                await options.create(directoryPath);
+            }
+            else {
+                const created = await ensureAbsoluteDirectory(directoryPath, {
+                    mode: options.mode,
+                    scopeLabel: label,
+                });
+                if (!created.ok) {
+                    throw created.error;
+                }
+            }
+        }
+        await ancestor.assertCurrent();
+        let currentPath = ancestor.receipt.path;
+        for (const segment of path
+            .relative(ancestor.receipt.path, directoryPath)
+            .split(path.sep)
+            .filter(Boolean)) {
+            currentPath = path.join(currentPath, segment);
+            pinnedDirectories.push(await pinDirectory(currentPath, { label }));
+        }
+        let parentSync = { status: "not-needed" };
+        for (let index = pinnedDirectories.length - 1; index > 0; index -= 1) {
+            const parent = pinnedDirectories[index - 1];
+            const child = pinnedDirectories[index];
+            if (!parent || !child) {
+                throw new FsSafeError("helper-failed", `${label} directory pin chain is incomplete`);
+            }
+            await child.assertCurrent();
+            try {
+                const outcome = await parent.sync();
+                if (outcome.status === "unsupported") {
+                    parentSync = outcome;
+                }
+                else if (parentSync.status === "not-needed") {
+                    parentSync = outcome;
+                }
+            }
+            catch (error) {
+                throw new FsSafeError("helper-failed", `${label} could not sync created directory edge ${child.receipt.path} through ${parent.receipt.path}`, { cause: error });
+            }
+            await child.assertCurrent();
+        }
+        const finalReceipt = pinnedDirectories.at(-1)?.receipt;
+        if (!finalReceipt) {
+            throw new FsSafeError("helper-failed", `${label} directory receipt is missing`);
+        }
+        await ancestor.assertCurrent();
+        await assertDirectoryReceiptCurrent(finalReceipt, label);
+        return { ...finalReceipt, parentSync };
+    }
+    finally {
+        await Promise.all(pinnedDirectories.toReversed().map(async (directory) => directory.close()));
+    }
+}

package/dist/durability.d.ts

@@ -0,0 +1,2 @@
+export { ensureDurableDirectory, pinDirectory, syncDirectory, syncDirectoryBestEffort, syncDirectoryBestEffortSync, syncDirectorySync, type DirectoryReceipt, type DirectorySyncOutcome, type DurableDirectoryReceipt, type EnsureDurableDirectoryOptions, type PinnedDirectory, } from "./directory-durability.js";
+//# sourceMappingURL=durability.d.ts.map

package/dist/durability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durability.d.ts","sourceRoot":"","sources":["../src/durability.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,aAAa,EACb,uBAAuB,EACvB,2BAA2B,EAC3B,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,eAAe,GACrB,MAAM,2BAA2B,CAAC"}

package/dist/durability.js

@@ -0,0 +1 @@
+export { ensureDurableDirectory, pinDirectory, syncDirectory, syncDirectoryBestEffort, syncDirectoryBestEffortSync, syncDirectorySync, } from "./directory-durability.js";

package/dist/fsync.d.ts

@@ -1,2 +1,2 @@
-export declare function syncDirectoryBestEffort(dirPath: string): Promise<void>;
+export { syncDirectoryBestEffort } from "./directory-durability.js";
 //# sourceMappingURL=fsync.d.ts.map

package/dist/fsync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fsync.d.ts","sourceRoot":"","sources":["../src/fsync.ts"],"names":[],"mappings":"AAIA,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB5E"}
+{"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,21 +1 @@
-import fsSync from "node:fs";
-import fs from "node:fs/promises";
-export async function syncDirectoryBestEffort(dirPath) {
-    if (process.platform === "win32") {
-        return;
-    }
-    let handle;
-    try {
-        const flags = fsSync.constants.O_RDONLY |
-            ("O_DIRECTORY" in fsSync.constants ? fsSync.constants.O_DIRECTORY : 0) |
-            ("O_NOFOLLOW" in fsSync.constants ? fsSync.constants.O_NOFOLLOW : 0);
-        handle = await fs.open(dirPath, flags);
-        await handle.sync();
-    }
-    catch {
-        // Some filesystems reject directory handles; keep the write usable there.
-    }
-    finally {
-        await handle?.close().catch(() => undefined);
-    }
-}
+export { syncDirectoryBestEffort } from "./directory-durability.js";

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

@@ -1 +1 @@
-{"version":3,"file":"sibling-temp.d.ts","sourceRoot":"","sources":["../src/sibling-temp.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5C,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AA0CF,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAyCxC;AAkBD,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8ChB"}
+{"version":3,"file":"sibling-temp.d.ts","sourceRoot":"","sources":["../src/sibling-temp.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5C,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AA8BF,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAyCxC;AAkBD,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8ChB"}

package/dist/sibling-temp.js

@@ -2,6 +2,7 @@ import crypto, { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
+import { syncDirectoryBestEffort } from "./directory-durability.js";
 import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { sanitizeUntrustedFileName } from "./filename.js";
 import { root } from "./root.js";
@@ -30,19 +31,6 @@ async function syncFileBestEffort(filePath) {
         await handle.close();
     }
 }
-async function syncDirectoryBestEffort(dirPath) {
-    let handle;
-    try {
-        handle = await fs.open(dirPath, "r");
-        await handle.sync();
-    }
-    catch {
-        // Best-effort on platforms/filesystems that do not support directory fsync.
-    }
-    finally {
-        await handle?.close().catch(() => undefined);
-    }
-}
 function assertFinalPathIsSibling(dir, filePath) {
     const resolvedDir = path.resolve(dir);
     const resolvedFile = path.resolve(filePath);

package/docs/advanced.md

@@ -5,7 +5,7 @@ description: "Lower-level composition helpers under @openclaw/fs-safe/advanced.
 
 # `@openclaw/fs-safe/advanced`
 
-Composition primitives that OpenClaw uses to build higher-level APIs. They are public — semver applies — but treated as a less stable surface than the focused subpaths (`root`, `json`, `store`, `temp`, `archive`, `errors`). Reach for them only when you are building a primitive of your own and the focused subpaths do not cover it.
+Composition primitives that OpenClaw uses to build higher-level APIs. They are public — semver applies — but treated as a less stable surface than the focused subpaths (`root`, `json`, `store`, `temp`, `archive`, `durability`, `errors`). Reach for them only when you are building a primitive of your own and the focused subpaths do not cover it.
 
 ```ts
 import {

package/docs/durability.md

@@ -0,0 +1,89 @@
+---
+title: Directory durability
+description: "Pin directory identities, fsync publication metadata, and durably create nested directory paths."
+---
+
+# Directory durability
+
+`@openclaw/fs-safe/durability` provides the directory side of crash-safe file
+publication. Flushing a file does not guarantee that its containing directory
+entry reached storage; callers that promise durable create, link, rename, or
+unlink operations must also synchronize the affected directory.
+
+```ts
+import {
+  ensureDurableDirectory,
+  pinDirectory,
+} from "@openclaw/fs-safe/durability";
+
+const repository = await ensureDurableDirectory({
+  directoryPath: "/srv/backups/sqlite",
+  mode: 0o700,
+});
+
+const pinned = await pinDirectory(repository, { label: "backup repository" });
+try {
+  await publishSnapshot();
+  const outcome = await pinned.sync();
+  if (outcome.status === "unsupported") {
+    // Decide at the product boundary whether this platform can weaken the promise.
+  }
+} finally {
+  await pinned.close();
+}
+```
+
+## Outcomes and failure semantics
+
+`syncDirectory()` and `PinnedDirectory.sync()` return:
+
+```ts
+type DirectorySyncOutcome =
+  | { status: "synced" }
+  | { status: "unsupported"; code?: string };
+```
+
+POSIX synchronization failures propagate. Windows directory handles do not
+portably support `FlushFileBuffers`; the known unsupported error family is
+reported as `unsupported` after the pathname and pinned identity are checked
+again. Directory-open access failures and other Windows I/O failures still
+propagate.
+
+`syncDirectoryBestEffort()` and `syncDirectoryBestEffortSync()` intentionally
+discard both unsupported outcomes and failures. Use them only when the primary
+write remains useful without a crash-durability promise.
+
+## Pinned directories
+
+`pinDirectory()` rejects final symlinks and non-directories. On POSIX it opens
+with `O_DIRECTORY`, `O_NOFOLLOW`, and `O_NONBLOCK`, then compares the open
+descriptor, pathname identity, and canonical path. `assertCurrent()` repeats
+those checks. This prevents a pathname replacement from turning a later sync
+into proof for a different directory.
+
+Call `close()` in `finally`. Closing is idempotent; using a closed pin fails.
+
+## Durable directory creation
+
+`ensureDurableDirectory()` finds and pins the nearest existing ancestor,
+creates the requested path, opens every new directory segment, and synchronizes
+each new parent-to-child edge from the leaf upward. It returns the final
+directory receipt plus the aggregate parent-sync outcome.
+
+By default it uses fs-safe's guarded one-segment-at-a-time absolute-directory
+creator. Advanced callers can pass `create` when directory creation needs
+platform-specific ACLs or another product-owned policy. The callback owns the
+safety of its mutations and must create exactly `directoryPath`; fs-safe
+validates and pins every resulting segment before any synchronization is
+accepted.
+
+`expectedExistingIdentity` binds an existing target to an identity observed by
+the caller before a separate permission or policy check. A missing or replaced
+target fails with `FsSafeError("path-mismatch")`.
+
+## Scope
+
+These primitives establish path identity and filesystem synchronization. They
+do not decide application commit protocols, marker formats, permission policy,
+or whether an unsupported platform is acceptable. Keep those decisions at the
+owning product boundary.

package/docs/index.md

@@ -52,6 +52,7 @@ await fs.remove("notes/archive/today.txt");
 | [`@openclaw/fs-safe/config`](config.md) | Process-global Python helper and lock-option defaults. |
 | [Python helper policy](python-helper.md) | Choose `auto`, `off`, or `require` for POSIX fd-relative hardening. |
 | [`replaceFileAtomic`](atomic.md) | Sibling-temp + rename, fsync hooks, mode preservation, copy fallback. |
+| [Directory durability](durability.md) | Pinned directory identities, explicit sync outcomes, and durable nested-directory creation. |
 | [`writeExternalFileWithinRoot`](output.md) | Stage external-library file output in private temp storage, then finalize under a root. |
 | [`writeJson` / `readJson*`](json.md) | JSON state files with strict and lenient read variants. |
 | [`@openclaw/fs-safe/store`](store.md) | Overview of `fileStore`, `fileStoreSync`, and `jsonStore`. |

package/docs/security-model.md

@@ -61,6 +61,19 @@ When `hardlinks: "reject"` is set, reads stat the target and refuse if `nlink >
 
 Within one process, async writes to the same target are queued so their temp-write/rename phases do not overlap. Cross-process writers still need an external protocol such as the sidecar lock helpers.
 
+### Directory durability
+
+`pinDirectory()` opens a directory without following its final component on
+POSIX, verifies the descriptor against the pathname identity and canonical
+path, and repeats those checks around synchronization. `ensureDurableDirectory()`
+pins the nearest existing ancestor and each newly created segment before
+synchronizing every new directory edge from the leaf upward.
+
+Known Windows directory-flush limitations are returned as an explicit
+`unsupported` outcome. POSIX and other I/O failures propagate from the strict
+API. The separately named best-effort helpers intentionally provide no crash
+durability guarantee.
+
 ### Archive extraction
 
 `extractArchive` first stages into a private temp directory (mode 0700) outside the destination, validates each entry path against `..` and absolute prefixes, refuses link-type entries by default, enforces entry count and byte budgets, and only then merges the staged tree into the destination through the same boundary checks used by direct writes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -96,6 +96,10 @@
       "types": "./dist/atomic.d.ts",
       "default": "./dist/atomic.js"
     },
+    "./durability": {
+      "types": "./dist/durability.d.ts",
+      "default": "./dist/durability.js"
+    },
     "./archive": {
       "types": "./dist/archive.d.ts",
       "default": "./dist/archive.js"