@adobe/data-persistence 0.9.90

package/dist/node/create-node-fs-provider.js

@@ -0,0 +1,48 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { promises as fs } from "node:fs";
+import { createInprocessTransport } from "../transport/inprocess-transport.js";
+import { createIncrementalPersistenceService } from "../service/create-incremental-persistence-service.js";
+import { createNodeFsBackend } from "./node-fs-backend.js";
+import { createNodeWorkerTransport } from "./node-worker-transport.js";
+/**
+ * Creates a Node.js persistence provider backed by `node:fs`.
+ *
+ * ```ts
+ * import { mount } from "@adobe/data-persistence";
+ * import { createNodeFsProvider } from "@adobe/data-persistence/node";
+ *
+ * const m = await mount(createNodeFsProvider("/tmp/my-db"), database);
+ * await m.service.load();
+ * // ...run app...
+ * await m.dispose();
+ * ```
+ *
+ * Pass `{ worker: true }` to move I/O off the calling thread into a
+ * dedicated `node:worker_threads` worker.
+ */
+export const createNodeFsProvider = (root, options) => ({
+    providerName: "NodeFsProvider",
+    async mount(database, mountOptions) {
+        await fs.mkdir(root, { recursive: true });
+        const backend = await createNodeFsBackend(root);
+        const useWorker = options?.worker ?? false;
+        const transport = useWorker
+            ? createNodeWorkerTransport({ root, workerScript: options?.workerScript })
+            : createInprocessTransport(backend);
+        const service = await createIncrementalPersistenceService({
+            database,
+            backend,
+            transport,
+            autoPersist: mountOptions?.autoPersist,
+            checkpoint: mountOptions?.checkpoint,
+        });
+        return {
+            service,
+            async dispose() {
+                await service.dispose();
+                await transport.close();
+            },
+        };
+    },
+});
+//# sourceMappingURL=create-node-fs-provider.js.map

package/dist/node/create-node-fs-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-node-fs-provider.js","sourceRoot":"","sources":["../../src/node/create-node-fs-provider.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AAEzC,OAAO,EAAE,wBAAwB,EAAE,MAAM,qCAAqC,CAAC;AAC/E,OAAO,EAAE,mCAAmC,EAAE,MAAM,sDAAsD,CAAC;AAE3G,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAmBvE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAChC,IAAY,EACZ,OAA+B,EACZ,EAAE,CAAC,CAAC;IACvB,YAAY,EAAE,gBAAgB;IAE9B,KAAK,CAAC,KAAK,CACP,QAA0D,EAC1D,YAAmC;QAEnC,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1C,MAAM,OAAO,GAAG,MAAM,mBAAmB,CAAC,IAAI,CAAC,CAAC;QAEhD,MAAM,SAAS,GAAG,OAAO,EAAE,MAAM,IAAI,KAAK,CAAC;QAC3C,MAAM,SAAS,GAAG,SAAS;YACvB,CAAC,CAAC,yBAAyB,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;YAC1E,CAAC,CAAC,wBAAwB,CAAC,OAAO,CAAC,CAAC;QAExC,MAAM,OAAO,GAAG,MAAM,mCAAmC,CAAC;YACtD,QAAQ;YACR,OAAO;YACP,SAAS;YACT,WAAW,EAAE,YAAY,EAAE,WAAW;YACtC,UAAU,EAAE,YAAY,EAAE,UAAU;SACvC,CAAC,CAAC;QAEH,OAAO;YACH,OAAO;YACP,KAAK,CAAC,OAAO;gBACT,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;gBACxB,MAAM,SAAS,CAAC,KAAK,EAAE,CAAC;YAC5B,CAAC;SACJ,CAAC;IACN,CAAC;CACJ,CAAC,CAAC"}

package/dist/node/index.d.ts

@@ -0,0 +1,6 @@
+export { createNodeFsFile } from "./node-fs-file.js";
+export { createNodeFsBackend, type NodeFsBackendOptions } from "./node-fs-backend.js";
+export { createNodeWorkerTransport, type NodeWorkerTransportOptions } from "./node-worker-transport.js";
+export { createNodeFsProvider, type NodeFsProviderOptions } from "./create-node-fs-provider.js";
+/** @deprecated Use `mount(createNodeFsProvider(root), db, opts)` instead. */
+export { mountNodeFs } from "./mount-node-fs.js";

package/dist/node/index.js

@@ -0,0 +1,10 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// Node-only entry point. Re-exports node:fs-based factories and the
+// node:worker_threads transport.
+export { createNodeFsFile } from "./node-fs-file.js";
+export { createNodeFsBackend } from "./node-fs-backend.js";
+export { createNodeWorkerTransport } from "./node-worker-transport.js";
+export { createNodeFsProvider } from "./create-node-fs-provider.js";
+/** @deprecated Use `mount(createNodeFsProvider(root), db, opts)` instead. */
+export { mountNodeFs } from "./mount-node-fs.js";
+//# sourceMappingURL=index.js.map

package/dist/node/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,oEAAoE;AACpE,iCAAiC;AAEjC,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAA6B,MAAM,sBAAsB,CAAC;AACtF,OAAO,EAAE,yBAAyB,EAAmC,MAAM,4BAA4B,CAAC;AACxG,OAAO,EAAE,oBAAoB,EAA8B,MAAM,8BAA8B,CAAC;AAEhG,6EAA6E;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/node/mount-node-fs.d.ts

@@ -0,0 +1,12 @@
+import type { MountOptions, PersistenceMount } from "../service/worker-persistence-service.js";
+/**
+ * @deprecated Use `mount(createNodeFsProvider(root), database, opts)` instead.
+ *
+ * ```ts
+ * import { mount } from "@adobe/data-persistence";
+ * import { createNodeFsProvider } from "@adobe/data-persistence/node";
+ *
+ * const m = await mount(createNodeFsProvider("/tmp/my-db"), database);
+ * ```
+ */
+export declare const mountNodeFs: (options: MountOptions<string>) => Promise<PersistenceMount>;

package/dist/node/mount-node-fs.js

@@ -0,0 +1,15 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { mount } from "../provider/mount.js";
+import { createNodeFsProvider } from "./create-node-fs-provider.js";
+/**
+ * @deprecated Use `mount(createNodeFsProvider(root), database, opts)` instead.
+ *
+ * ```ts
+ * import { mount } from "@adobe/data-persistence";
+ * import { createNodeFsProvider } from "@adobe/data-persistence/node";
+ *
+ * const m = await mount(createNodeFsProvider("/tmp/my-db"), database);
+ * ```
+ */
+export const mountNodeFs = async (options) => mount(createNodeFsProvider(options.root, { worker: true }), options.database, { autoPersist: options.autoPersist, checkpoint: options.checkpoint });
+//# sourceMappingURL=mount-node-fs.js.map

package/dist/node/mount-node-fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-node-fs.js","sourceRoot":"","sources":["../../src/node/mount-node-fs.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAGvD,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAC7C,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEpE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAC5B,OAA6B,EACJ,EAAE,CAC3B,KAAK,CACD,oBAAoB,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EACpD,OAAO,CAAC,QAAQ,EAChB,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CACvE,CAAC"}

package/dist/node/node-fs-backend-lock.node.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/node/node-fs-backend-lock.node.test.js

@@ -0,0 +1,160 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+//
+// Single-writer lock behavior for the Node fs backend. The lock file
+// (`lock.json`) is written exclusively at backend creation, released
+// on `dispose`, and tolerated when stale (owner pid is gone).
+import { promises as fs } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createNodeFsBackend } from "./node-fs-backend.js";
+const LOCK_FILENAME = "lock.json";
+const makeTmpDir = async () => fs.mkdtemp(join(tmpdir(), "data-persistence-lock-"));
+describe("node-fs-backend single-writer lock", () => {
+    let dir;
+    beforeEach(async () => {
+        dir = await makeTmpDir();
+    });
+    afterEach(async () => {
+        await fs.rm(dir, { recursive: true, force: true });
+    });
+    it("creates the lock file on construction and removes it on dispose", async () => {
+        const backend = await createNodeFsBackend(dir);
+        const lockPath = join(dir, LOCK_FILENAME);
+        const exists = await fs.stat(lockPath).then(() => true).catch(() => false);
+        expect(exists).toBe(true);
+        const text = await fs.readFile(lockPath, "utf8");
+        const record = JSON.parse(text);
+        expect(record.pid).toBe(process.pid);
+        expect(typeof record.hostname).toBe("string");
+        expect(typeof record.startedAtMs).toBe("number");
+        await backend.dispose();
+        const stillExists = await fs.stat(lockPath).then(() => true).catch(() => false);
+        expect(stillExists).toBe(false);
+    });
+    it("hides the lock file from list('.')", async () => {
+        const backend = await createNodeFsBackend(dir);
+        try {
+            const f = await backend.open("data.bin");
+            await f.writeAt(0, new Uint8Array([1]));
+            await f.close();
+            const entries = [...(await backend.list("."))].sort();
+            expect(entries).toEqual(["data.bin"]);
+        }
+        finally {
+            await backend.dispose();
+        }
+    });
+    it("rejects a second backend on the same root while the first is alive", async () => {
+        const first = await createNodeFsBackend(dir);
+        try {
+            // The second acquire should see a fresh, live owner: us.
+            // We simulate a different pid by rewriting the lock file
+            // in-place — same hostname, different alive pid.
+            const lockPath = join(dir, LOCK_FILENAME);
+            const live = {
+                pid: process.pid, // alive: kill(0) succeeds
+                hostname: (await import("node:os")).hostname(),
+                startedAtMs: Date.now(),
+            };
+            await fs.writeFile(lockPath, JSON.stringify(live));
+            // ...but trick the lock check by changing the pid to a known-
+            // alive pid of ANOTHER process: 1 (init / launchd). Signal 0
+            // to pid 1 from a non-root process raises EPERM, which our
+            // implementation correctly classifies as "alive".
+            const live2 = { ...live, pid: 1 };
+            await fs.writeFile(lockPath, JSON.stringify(live2));
+            await expect(createNodeFsBackend(dir)).rejects.toThrow(/another process \(pid 1\) is currently using/);
+        }
+        finally {
+            await first.dispose();
+        }
+    });
+    it("steals a stale lock left by a dead pid", async () => {
+        // Pre-seed a stale lock referencing a pid that almost certainly
+        // does not exist. 2**31 - 1 is well above the OS pid_max on all
+        // major platforms (Linux default 32768; macOS/BSD 99999) and
+        // fits in Node's ints. kill(0, pid) → ESRCH → "stale".
+        const lockPath = join(dir, LOCK_FILENAME);
+        const stale = {
+            pid: 2 ** 31 - 1,
+            hostname: (await import("node:os")).hostname(),
+            startedAtMs: Date.now() - 86_400_000,
+        };
+        await fs.writeFile(lockPath, JSON.stringify(stale));
+        const backend = await createNodeFsBackend(dir);
+        try {
+            // Lock was stolen and rewritten to our pid.
+            const text = await fs.readFile(lockPath, "utf8");
+            const record = JSON.parse(text);
+            expect(record.pid).toBe(process.pid);
+        }
+        finally {
+            await backend.dispose();
+        }
+    });
+    it("treats an unparseable lock file as stale", async () => {
+        const lockPath = join(dir, LOCK_FILENAME);
+        await fs.writeFile(lockPath, "not json {");
+        const backend = await createNodeFsBackend(dir);
+        try {
+            const text = await fs.readFile(lockPath, "utf8");
+            // Should now be valid JSON identifying us.
+            const record = JSON.parse(text);
+            expect(record.pid).toBe(process.pid);
+        }
+        finally {
+            await backend.dispose();
+        }
+    });
+    it("refuses a lock owned by a different host (NFS safety)", async () => {
+        const lockPath = join(dir, LOCK_FILENAME);
+        const foreign = {
+            pid: 1,
+            hostname: "some-other-host-not-this-one",
+            startedAtMs: Date.now(),
+        };
+        await fs.writeFile(lockPath, JSON.stringify(foreign));
+        await expect(createNodeFsBackend(dir)).rejects.toThrow(/owned by pid 1 on host "some-other-host-not-this-one"/);
+    });
+    it("re-entry from the same pid succeeds and refreshes the timestamp", async () => {
+        // First acquire writes the lock.
+        const first = await createNodeFsBackend(dir);
+        try {
+            const lockPath = join(dir, LOCK_FILENAME);
+            const before = JSON.parse(await fs.readFile(lockPath, "utf8"));
+            // Force a measurable time gap.
+            await new Promise(r => setTimeout(r, 5));
+            // Second acquire from the same pid should succeed
+            // (re-entry path; common during dev-server reloads).
+            const second = await createNodeFsBackend(dir);
+            try {
+                const after = JSON.parse(await fs.readFile(lockPath, "utf8"));
+                expect(after.pid).toBe(process.pid);
+                expect(after.startedAtMs).toBeGreaterThanOrEqual(before.startedAtMs);
+            }
+            finally {
+                await second.dispose();
+            }
+        }
+        finally {
+            await first.dispose();
+        }
+    });
+    it("disableLock skips lock acquisition entirely", async () => {
+        const backend = await createNodeFsBackend(dir, { disableLock: true });
+        try {
+            const lockPath = join(dir, LOCK_FILENAME);
+            const exists = await fs.stat(lockPath).then(() => true).catch(() => false);
+            expect(exists).toBe(false);
+            // And nothing throws on dispose either.
+            await backend.dispose();
+        }
+        catch (err) {
+            // Make sure dispose got called once if the test body bailed.
+            await backend.dispose?.().catch(() => { });
+            throw err;
+        }
+    });
+});
+//# sourceMappingURL=node-fs-backend-lock.node.test.js.map

package/dist/node/node-fs-backend-lock.node.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-fs-backend-lock.node.test.js","sourceRoot":"","sources":["../../src/node/node-fs-backend-lock.node.test.ts"],"names":[],"mappings":"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"}

package/dist/node/node-fs-backend.d.ts

@@ -0,0 +1,21 @@
+import type { PersistenceBackend } from "../backend/persistence-backend.js";
+/**
+ * Node `fs` backend rooted at an absolute directory. The root must
+ * exist and be a directory; create it ahead of time with `fs.mkdir`.
+ *
+ * All input paths are validated and resolved against the root; any
+ * attempt to escape the root is rejected (defense in depth — the
+ * `validateRelPath` rejection is the primary line of defense).
+ */
+/**
+ * Options for {@link createNodeFsBackend}.
+ */
+export interface NodeFsBackendOptions {
+    /**
+     * Disable the single-writer lock file. Use only when an external
+     * mechanism guarantees exclusive access (containerized single-
+     * process services, ephemeral test directories, etc.).
+     */
+    readonly disableLock?: boolean;
+}
+export declare const createNodeFsBackend: (rootPath: string, options?: NodeFsBackendOptions) => Promise<PersistenceBackend>;

package/dist/node/node-fs-backend.js

@@ -0,0 +1,186 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { promises as fs } from "node:fs";
+import { hostname } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
+import { validateRelPath } from "../backend/validate-rel-path.js";
+import { createNodeFsFile } from "./node-fs-file.js";
+/**
+ * `NodeJS.ErrnoException` is a structural type with optional `code` —
+ * Node throws plain `Error` instances at runtime, so `instanceof` is
+ * unhelpful here. Duck-type the `code` field instead, then narrow.
+ */
+const isErrnoCode = (err, code) => typeof err === "object" &&
+    err !== null &&
+    err.code === code;
+const LOCK_FILENAME = "lock.json";
+/**
+ * Acquire a single-writer lock on `root`. Writes a JSON record
+ * containing the current process's pid and start time to `lock.json`.
+ *
+ * Behavior:
+ *   - File does not exist  → create it (exclusive `wx` flag).
+ *   - File exists, owner pid is alive on this host  → throw.
+ *   - File exists, owner pid is gone (or different host)  → treat as
+ *     stale and overwrite. We DO NOT steal locks owned by a different
+ *     host because that almost certainly means the data lives on a
+ *     shared filesystem (NFS) and the other host is still writing.
+ *
+ * Returns the absolute lock path so the caller can release it.
+ *
+ * Race-condition tolerance: two processes may both observe a stale
+ * lock and both try to overwrite. We use `flag: 'wx'` for the initial
+ * acquire; if it fails with EEXIST after we've already concluded the
+ * lock is stale, we use `flag: 'w'` to overwrite. The window where
+ * both racers can write is small (microseconds) and the loser will
+ * be detected at the NEXT call (writes happen sequentially through
+ * the worker so cross-process interleaving is the only concern). For
+ * stronger guarantees a flock(2)-based lock would be needed, but
+ * Node's `fs` module does not surface flock without a native addon.
+ */
+const acquireNodeLock = async (root) => {
+    const lockPath = join(root, LOCK_FILENAME);
+    const myRecord = {
+        pid: process.pid,
+        hostname: hostname(),
+        startedAtMs: Date.now(),
+    };
+    const recordBytes = Buffer.from(JSON.stringify(myRecord), "utf8");
+    // Fast path: exclusive create. Wins the race in the common case
+    // where no prior session left a lock behind.
+    try {
+        await fs.writeFile(lockPath, recordBytes, { flag: "wx" });
+        return lockPath;
+    }
+    catch (err) {
+        if (!isErrnoCode(err, "EEXIST"))
+            throw err;
+    }
+    // A lock file already exists. Read it and decide whether to steal.
+    let existing;
+    try {
+        const text = await fs.readFile(lockPath, "utf8");
+        existing = JSON.parse(text);
+    }
+    catch {
+        // Unparseable lock file from an older / corrupt run; treat as stale.
+        await fs.writeFile(lockPath, recordBytes, { flag: "w" });
+        return lockPath;
+    }
+    if (existing.hostname !== myRecord.hostname) {
+        throw new Error(`NodeFsBackend: refusing to acquire lock at ${lockPath}: ` +
+            `owned by pid ${existing.pid} on host ${JSON.stringify(existing.hostname)} ` +
+            `(this host is ${JSON.stringify(myRecord.hostname)}). ` +
+            `If the data is on a shared filesystem and the other host crashed, ` +
+            `delete ${LOCK_FILENAME} manually.`);
+    }
+    if (existing.pid === process.pid) {
+        // Re-entry from the same process. Refresh the timestamp and
+        // continue. This handles dev-server reloads that re-import
+        // without forking, and tests that recreate the backend.
+        await fs.writeFile(lockPath, recordBytes, { flag: "w" });
+        return lockPath;
+    }
+    // Different pid, same host. Probe with signal 0 (no-op signal that
+    // verifies the process exists and we have permission to signal
+    // it). If the process is gone, the lock is stale.
+    let alive = false;
+    try {
+        process.kill(existing.pid, 0);
+        alive = true;
+    }
+    catch (err) {
+        // ESRCH = process does not exist. EPERM = exists but not ours,
+        // which on most systems still means the process is alive.
+        if (isErrnoCode(err, "EPERM"))
+            alive = true;
+    }
+    if (alive) {
+        throw new Error(`NodeFsBackend: another process (pid ${existing.pid}) is currently ` +
+            `using ${root}. If you are sure that process has exited, delete ${LOCK_FILENAME}.`);
+    }
+    // Stale lock; steal it.
+    await fs.writeFile(lockPath, recordBytes, { flag: "w" });
+    return lockPath;
+};
+export const createNodeFsBackend = async (rootPath, options = {}) => {
+    const root = resolve(rootPath);
+    // Ensure the root exists and is a directory. Failing fast here
+    // surfaces configuration errors at startup rather than mid-write.
+    const stat = await fs.stat(root);
+    if (!stat.isDirectory()) {
+        throw new Error(`NodeFsBackend root is not a directory: ${root}`);
+    }
+    // Acquire the single-writer lock. If two processes try to mount
+    // the same root, one of them must lose here — otherwise their
+    // appendJournal() calls race on the file size and corrupt the WAL.
+    const lockPath = options.disableLock
+        ? null
+        : await acquireNodeLock(root);
+    const safeJoin = (relPath) => {
+        validateRelPath(relPath);
+        const joined = resolve(join(root, relPath));
+        // Final check: the resolved path must be inside the root. This is
+        // belt-and-suspenders since validateRelPath already rejects '..'
+        // segments and absolute inputs.
+        if (joined !== root && !joined.startsWith(root + sep)) {
+            throw new Error(`Resolved path escapes root: ${JSON.stringify(relPath)}`);
+        }
+        return joined;
+    };
+    return {
+        async open(relPath) {
+            const abs = safeJoin(relPath);
+            await fs.mkdir(dirname(abs), { recursive: true });
+            return createNodeFsFile(abs);
+        },
+        async list(relPath) {
+            const target = relPath === "." ? root : safeJoin(relPath);
+            try {
+                const all = await fs.readdir(target);
+                // Hide the lock file from listings so user code sees a
+                // consistent view independent of whether locking is on.
+                if (relPath === ".")
+                    return all.filter(name => name !== LOCK_FILENAME);
+                return all;
+            }
+            catch (err) {
+                if (isErrnoCode(err, "ENOENT"))
+                    return [];
+                throw err;
+            }
+        },
+        async remove(relPath) {
+            const abs = safeJoin(relPath);
+            try {
+                await fs.unlink(abs);
+            }
+            catch (err) {
+                if (isErrnoCode(err, "ENOENT"))
+                    return;
+                throw err;
+            }
+        },
+        async rename(from, to) {
+            const fromAbs = safeJoin(from);
+            const toAbs = safeJoin(to);
+            await fs.mkdir(dirname(toAbs), { recursive: true });
+            await fs.rename(fromAbs, toAbs);
+        },
+        async dispose() {
+            if (lockPath === null)
+                return;
+            try {
+                await fs.unlink(lockPath);
+            }
+            catch (err) {
+                // Already gone — fine. Anything else, log and move on:
+                // teardown should never throw, the OS will reap us.
+                if (!isErrnoCode(err, "ENOENT")) {
+                    // eslint-disable-next-line no-console
+                    console.warn(`NodeFsBackend: failed to release lock at ${lockPath}:`, err);
+                }
+            }
+        },
+    };
+};
+//# sourceMappingURL=node-fs-backend.js.map

package/dist/node/node-fs-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-fs-backend.js","sourceRoot":"","sources":["../../src/node/node-fs-backend.ts"],"names":[],"mappings":"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"}

package/dist/node/node-fs-backend.node.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/node/node-fs-backend.node.test.js

@@ -0,0 +1,17 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { promises as fs } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runPersistenceBackendConformance } from "../backend/persistence-backend.conformance.js";
+import { createNodeFsBackend } from "./node-fs-backend.js";
+runPersistenceBackendConformance("node-fs", async () => {
+    const dir = await fs.mkdtemp(join(tmpdir(), "data-persistence-be-"));
+    const backend = await createNodeFsBackend(dir);
+    return {
+        backend,
+        cleanup: async () => {
+            await fs.rm(dir, { recursive: true, force: true });
+        },
+    };
+});
+//# sourceMappingURL=node-fs-backend.node.test.js.map

package/dist/node/node-fs-backend.node.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-fs-backend.node.test.js","sourceRoot":"","sources":["../../src/node/node-fs-backend.node.test.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,gCAAgC,EAAE,MAAM,+CAA+C,CAAC;AACjG,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,gCAAgC,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;IACnD,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,sBAAsB,CAAC,CAAC,CAAC;IACrE,MAAM,OAAO,GAAG,MAAM,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAC/C,OAAO;QACH,OAAO;QACP,OAAO,EAAE,KAAK,IAAI,EAAE;YAChB,MAAM,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACvD,CAAC;KACJ,CAAC;AACN,CAAC,CAAC,CAAC"}

package/dist/node/node-fs-file.d.ts

@@ -0,0 +1,6 @@
+import { RandomAccessFile } from "../backend/random-access-file.js";
+/**
+ * Node-fs implementation of RandomAccessFile. The given path must
+ * already be validated by the surrounding {@link NodeFsBackend}.
+ */
+export declare const createNodeFsFile: (absPath: string) => Promise<RandomAccessFile>;

package/dist/node/node-fs-file.js

@@ -0,0 +1,57 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { promises as fs, constants as fsConstants } from "node:fs";
+/**
+ * Node-fs implementation of RandomAccessFile. The given path must
+ * already be validated by the surrounding {@link NodeFsBackend}.
+ */
+export const createNodeFsFile = async (absPath) => {
+    // O_RDWR | O_CREAT: read+write, create-if-missing, never truncate.
+    // "a+" is wrong here — append mode ignores the position argument on writes,
+    // which breaks writeAt semantics (every write would land at EOF instead).
+    const handle = await fs.open(absPath, fsConstants.O_RDWR | fsConstants.O_CREAT, 0o666);
+    let closed = false;
+    const ensureOpen = () => {
+        if (closed)
+            throw new Error(`NodeFsFile is closed: ${absPath}`);
+    };
+    return {
+        async readAt(offset, length) {
+            ensureOpen();
+            const buffer = Buffer.allocUnsafe(length);
+            const { bytesRead } = await handle.read(buffer, 0, length, offset);
+            // Slice to actual bytes read; copy detached from internal buffer.
+            return new Uint8Array(buffer.subarray(0, bytesRead));
+        },
+        async writeAt(offset, bytes) {
+            ensureOpen();
+            await handle.write(bytes, 0, bytes.byteLength, offset);
+        },
+        async appendAt(bytes) {
+            ensureOpen();
+            const stat = await handle.stat();
+            const start = stat.size;
+            await handle.write(bytes, 0, bytes.byteLength, start);
+            return start + bytes.byteLength;
+        },
+        async size() {
+            ensureOpen();
+            const stat = await handle.stat();
+            return stat.size;
+        },
+        async truncate(length) {
+            ensureOpen();
+            await handle.truncate(length);
+        },
+        async sync() {
+            ensureOpen();
+            await handle.sync();
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            await handle.close();
+        },
+    };
+};
+//# sourceMappingURL=node-fs-file.js.map

package/dist/node/node-fs-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-fs-file.js","sourceRoot":"","sources":["../../src/node/node-fs-file.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,SAAS,IAAI,WAAW,EAAE,MAAM,SAAS,CAAC;AAInE;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,EAAE,OAAe,EAA6B,EAAE;IACjF,mEAAmE;IACnE,4EAA4E;IAC5E,0EAA0E;IAC1E,MAAM,MAAM,GAAe,MAAM,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,GAAG,WAAW,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACnG,IAAI,MAAM,GAAG,KAAK,CAAC;IAEnB,MAAM,UAAU,GAAG,GAAS,EAAE;QAC1B,IAAI,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,OAAO,EAAE,CAAC,CAAC;IACpE,CAAC,CAAC;IAEF,OAAO;QACH,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM;YACvB,UAAU,EAAE,CAAC;YACb,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;YAC1C,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;YACnE,kEAAkE;YAClE,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;QACzD,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK;YACvB,UAAU,EAAE,CAAC;YACb,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QAC3D,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,KAAK;YAChB,UAAU,EAAE,CAAC;YACb,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YACjC,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC;YACxB,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;YACtD,OAAO,KAAK,GAAG,KAAK,CAAC,UAAU,CAAC;QACpC,CAAC;QACD,KAAK,CAAC,IAAI;YACN,UAAU,EAAE,CAAC;YACb,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YACjC,OAAO,IAAI,CAAC,IAAI,CAAC;QACrB,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,MAAM;YACjB,UAAU,EAAE,CAAC;YACb,MAAM,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;QACD,KAAK,CAAC,IAAI;YACN,UAAU,EAAE,CAAC;YACb,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACxB,CAAC;QACD,KAAK,CAAC,KAAK;YACP,IAAI,MAAM;gBAAE,OAAO;YACnB,MAAM,GAAG,IAAI,CAAC;YACd,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACzB,CAAC;KACJ,CAAC;AACN,CAAC,CAAC"}

package/dist/node/node-fs-file.node.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/node/node-fs-file.node.test.js

@@ -0,0 +1,13 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { promises as fs } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runRandomAccessFileConformance } from "../backend/random-access-file.conformance.js";
+import { createNodeFsFile } from "./node-fs-file.js";
+let counter = 0;
+runRandomAccessFileConformance("node-fs", async () => {
+    const dir = await fs.mkdtemp(join(tmpdir(), "data-persistence-raf-"));
+    const path = join(dir, `file-${counter++}.bin`);
+    return createNodeFsFile(path);
+});
+//# sourceMappingURL=node-fs-file.node.test.js.map

package/dist/node/node-fs-file.node.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-fs-file.node.test.js","sourceRoot":"","sources":["../../src/node/node-fs-file.node.test.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,8BAA8B,EAAE,MAAM,8CAA8C,CAAC;AAC9F,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAErD,IAAI,OAAO,GAAG,CAAC,CAAC;AAChB,8BAA8B,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;IACjD,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,uBAAuB,CAAC,CAAC,CAAC;IACtE,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,QAAQ,OAAO,EAAE,MAAM,CAAC,CAAC;IAChD,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC,CAAC,CAAC"}

package/dist/node/node-fs-provider.node.test.d.ts

@@ -0,0 +1 @@
+export {};