@adobe/data-persistence 0.9.90

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Adobe, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,258 @@
+# @adobe/data-persistence
+
+Incremental persistence for `@adobe/data` ECS databases — O(1) writes,
+append-only journal, crash recovery.
+
+This package is **purely additive** — it does not replace `db.toData()` /
+`db.fromData()`, which remain the canonical whole-world snapshot mechanism.
+Use this package when worlds are large enough that re-serializing the
+entire database on every save is prohibitive.
+
+## Status
+
+Functionally complete. Crash-recovery and journal-replay are tested across both runtimes; see the Crash safety section below for the precise contract and the Performance section for benchmarked baselines.
+
+## Design
+
+- **O(1) byte-range writes** to per-archetype × column files
+- **Append-only journal** for changes between checkpoints (true
+  write-ahead log: each tx is closed by a `commit` entry; replay only
+  applies entries belonging to a tx whose commit reached disk)
+- **Pluggable storage** via `PersistenceProvider` — OPFS, Node `fs`,
+  in-memory, or a custom cloud implementation
+- Workers are **optional** for Node (libuv is already async); always
+  required for OPFS (`FileSystemSyncAccessHandle` needs a worker context)
+- Single core implementation; only the `RandomAccessFile`,
+  `PersistenceBackend`, and `Transport` factories differ per runtime
+
+## Quick start
+
+### Node.js
+
+```ts
+import { mount } from "@adobe/data-persistence";
+import { createNodeFsProvider } from "@adobe/data-persistence/node";
+import { Database } from "@adobe/data/ecs";
+
+const db = Database.create(myPlugin);
+const provider = createNodeFsProvider("/tmp/my-save");
+const m = await mount(provider, db);
+
+await m.service.load(); // restore previous session
+
+// ... run game / app ...
+
+await m.service.flush();
+await m.service.checkpoint();
+await m.dispose(); // flushes, closes transport, releases lock
+```
+
+Pass `{ worker: true }` to move I/O off the calling thread into a
+`node:worker_threads` worker:
+
+```ts
+const provider = createNodeFsProvider("/tmp/my-save", { worker: true });
+```
+
+### Browser (inside a Vite app)
+
+```ts
+import { mount } from "@adobe/data-persistence";
+import { createOpfsProvider } from "@adobe/data-persistence/browser";
+import { Database } from "@adobe/data/ecs";
+
+const db = Database.create(myPlugin);
+// Omit the argument to use the per-origin OPFS root (the common case).
+const provider = createOpfsProvider();
+const m = await mount(provider, db);
+
+await m.service.load(); // restore previous session
+
+// ... run app ...
+
+await m.service.flush();
+await m.service.checkpoint();
+await m.dispose(); // flushes, closes OPFS worker, releases lock
+```
+
+See [`examples/node-basic.ts`](./examples/node-basic.ts) and
+[`examples/browser-main.ts`](./examples/browser-main.ts) for complete
+annotated examples with write and read passes.
+
+## Public entry points
+
+| Import path | Use from |
+|---|---|
+| `@adobe/data-persistence` | runtime-agnostic surface (interfaces, `mount`, `createMemoryProvider`, service factory) |
+| `@adobe/data-persistence/browser` | OPFS backend + browser worker transport + `createOpfsProvider` |
+| `@adobe/data-persistence/node` | `node:fs` backend + `node:worker_threads` transport + `createNodeFsProvider` |
+
+## API reference
+
+### `mount(provider, database, options?)`
+
+The single entry point for all persistence. Returns a `PersistenceMount`.
+
+```ts
+const m = await mount(provider, database, {
+  autoPersist: true,                  // default: true
+  checkpoint: {
+    everyNTransactions: 1000,         // default: 1000
+    idleMs: 5000,                     // default: 5000
+  },
+});
+```
+
+### `PersistenceMount`
+
+```ts
+interface PersistenceMount {
+  service: IncrementalPersistenceService;
+  dispose(): Promise<void>;
+}
+```
+
+### `IncrementalPersistenceService`
+
+```ts
+interface IncrementalPersistenceService {
+  serviceName: string;
+  save(): Promise<void>;
+  load(): Promise<void>;
+  flush(): Promise<void>;
+  checkpoint(): Promise<void>;
+  dispose(): Promise<void>;
+}
+```
+
+## Writing a custom cloud provider
+
+External implementers choose one of two seams depending on whether their
+storage supports byte-range writes.
+
+### Pattern A — byte-range capable storage
+
+Implement `PersistenceBackend` + `RandomAccessFile`. Then wrap with
+`createInprocessTransport` + `createIncrementalPersistenceService`. This
+reuses 95% of the existing code and supports the full journal + checkpoint
+strategy automatically.
+
+```ts
+import type { PersistenceProvider } from "@adobe/data-persistence";
+import { createInprocessTransport, createIncrementalPersistenceService } from "@adobe/data-persistence";
+
+export const createMyCloudProvider = (client: CloudClient): PersistenceProvider => ({
+  providerName: "MyCloudProvider",
+  async mount(database, opts) {
+    const backend = createMyCloudBackend(client); // implements PersistenceBackend
+    const transport = createInprocessTransport(backend);
+    const service = await createIncrementalPersistenceService({
+      database, backend, transport,
+      autoPersist: opts?.autoPersist,
+      checkpoint: opts?.checkpoint,
+    });
+    return {
+      service,
+      dispose: async () => { await service.dispose(); await transport.close(); },
+    };
+  },
+});
+```
+
+If your backend does not currently support byte-range writes but will in
+the future, declare it via the optional `capabilities` field:
+
+```ts
+const backend: PersistenceBackend = {
+  capabilities: { byteRangeWrites: false },
+  async open(relPath) { /* ... */ },
+  // ...
+};
+```
+
+### Pattern B — whole-file storage
+
+Implement `PersistenceProvider` directly. Inside `mount()`, observe
+`database.observe.transactions` and accumulate deltas; on
+`flush`/`checkpoint`/`dispose`, push a complete blob to the cloud. Skip
+the journal and manifest entirely — the provider author owns the delta
+strategy.
+
+```ts
+import type { PersistenceProvider, PersistenceMount } from "@adobe/data-persistence";
+
+export const createBlobProvider = (client: BlobClient): PersistenceProvider => ({
+  providerName: "BlobProvider",
+  async mount(database, opts): Promise<PersistenceMount> {
+    // Observe transactions, accumulate state, push blob on checkpoint/dispose.
+    const service = createBlobPersistenceService(client, database, opts);
+    return { service, dispose: () => service.dispose() };
+  },
+});
+```
+
+## Crash safety
+
+What we guarantee:
+
+- Clean shutdown via `dispose()` → next `load()` is byte-identical.
+- Crash between transactions → next `load()` is the last fully-committed
+  transaction. Snapshot + journal replay reconstructs the world.
+- Crash inside the journal stream itself (torn append) → the affected
+  entry is dropped; everything before it is recovered.
+- Crash with the commit marker missing for a tx → replay drops every
+  entry of that tx, so it never half-applies a multi-entity transaction.
+
+What we do **not** guarantee:
+
+- Row-level rollback of an in-flight transaction. Column-slice writes
+  are eager, so if a crash happens *during* a tx's writes, individual
+  column files may already reflect bytes from the dropped tx. Replay
+  refuses to extend the dropped tx into other entities, but bytes
+  written to its own row may persist.
+
+Full row-level atomicity would require shadow paging or a separate
+undo log, both of which trade away the O(1) write property this
+package is designed for.
+
+## Performance
+
+Two complementary guarantees:
+
+### Algorithmic complexity (O(changes))
+
+The cost of persisting a transaction T is **O(touched_columns + changed_entities)** — independent of total world size, archetype row capacity, or the number of registered archetypes. Verified by `src/service/persistence-complexity.test.ts`, which counts `PersistOp` messages emitted per transaction across worlds of N=10, 100, and 500 entities and asserts the count is identical:
+
+| Transaction shape | Ops emitted (any N) |
+|---|---|
+| Update 1 component on 1 entity | 4 (journal entry + column slice + ELT + commit) |
+| Update 3 components on 1 entity | 8 |
+| Insert (3-column archetype) | 8 |
+| Delete + 1 swap-remove side effect | 10 |
+
+For **fixed-stride columns** (number, struct, enum) `checkpoint()` scales with archetype × column count (manifest schema), not row count — column slices are written incrementally per transaction, so the checkpoint just writes the manifest and truncates the journal.
+
+For **journal-storage columns** (`"array"` typed buffers — variable-length per-row values) the checkpoint additionally writes a full per-column snapshot file whose cost is O(rowCount × mean value size) for each such column. At load time that snapshot is restored before journal replay, so these columns are fully durable across checkpoints. If your schema has no `"array"` columns, checkpoint cost remains independent of row count.
+
+### Wall-clock baseline
+
+Run with:
+
+```bash
+pnpm --filter @adobe/data-persistence run perf
+```
+
+Numbers below are from a steady-state run on an in-process transport (no worker postMessage overhead), 1000-entity world, three-component archetype:
+
+| Scenario | μs/op (mean) | μs/op (p99) | ops/sec |
+|---|---:|---:|---:|
+| tx: update 1 component on 1 entity | ~160 | ~250 | ~6,200 |
+| tx: update 3 components on 1 entity | ~350 | ~490 | ~2,850 |
+| tx: insert (3 columns) | ~350 | ~480 | ~2,900 |
+| tx: delete + swap-remove side effect | ~470 | ~620 | ~2,100 |
+| checkpoint after 1000 dirty rows | ~140 | ~350 | ~7,000 |
+| load 1000-entity snapshot | ~58 | ~125 | ~17,000 |
+
+Read these as comparative ratios, not absolute targets — the 2.2× ratio between 1-column and 3-column updates confirms the per-component-write optimization is doing useful work. The flat checkpoint cost (~140 μs regardless of row count) holds for fixed-stride-only schemas; schemas with `"array"` (journal-storage) columns incur an additional O(rowCount × mean value size) write per such column at checkpoint time.
+
+Worker-thread transports (browser OPFS, Node `worker_threads`) add 1–10 μs of `postMessage` round-trip per op on top of these numbers, plus real disk I/O at checkpoint and load.

package/dist/backend/memory-backend.d.ts

@@ -0,0 +1,6 @@
+import type { PersistenceBackend } from "./persistence-backend.js";
+/**
+ * In-memory backend used by tests and the in-process service. Stores
+ * file contents in a Map keyed by normalized relative path.
+ */
+export declare const createMemoryBackend: () => PersistenceBackend;

package/dist/backend/memory-backend.js

@@ -0,0 +1,92 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { createMemoryFile } from "./memory-file.js";
+import { validateRelPath } from "./validate-rel-path.js";
+const normalize = (relPath) => {
+    // Strip './' prefixes and trailing slashes; collapse "//".
+    return relPath
+        .split("/")
+        .filter(seg => seg !== "" && seg !== ".")
+        .join("/");
+};
+/**
+ * In-memory backend used by tests and the in-process service. Stores
+ * file contents in a Map keyed by normalized relative path.
+ */
+export const createMemoryBackend = () => {
+    // Stored bytes per file. Each "open" returns a fresh handle that
+    // syncs back to this map on writes.
+    const store = new Map();
+    const readSnapshot = (key) => store.get(key) ?? new Uint8Array(0);
+    const writeSnapshot = (key, bytes) => {
+        store.set(key, bytes);
+    };
+    return {
+        async open(relPath) {
+            validateRelPath(relPath);
+            const key = normalize(relPath);
+            const initial = readSnapshot(key);
+            const inner = createMemoryFile(initial);
+            return {
+                async readAt(offset, length) {
+                    return inner.readAt(offset, length);
+                },
+                async writeAt(offset, bytes) {
+                    await inner.writeAt(offset, bytes);
+                    const size = await inner.size();
+                    writeSnapshot(key, await inner.readAt(0, size));
+                },
+                async appendAt(bytes) {
+                    const newSize = await inner.appendAt(bytes);
+                    writeSnapshot(key, await inner.readAt(0, newSize));
+                    return newSize;
+                },
+                async size() {
+                    return inner.size();
+                },
+                async truncate(length) {
+                    await inner.truncate(length);
+                    const size = await inner.size();
+                    writeSnapshot(key, await inner.readAt(0, size));
+                },
+                async sync() {
+                    await inner.sync();
+                },
+                async close() {
+                    await inner.close();
+                },
+            };
+        },
+        async list(relPath) {
+            validateRelPath(relPath === "" ? "." : relPath);
+            const prefix = normalize(relPath);
+            const directKey = prefix.length === 0 ? "" : prefix + "/";
+            const out = new Set();
+            for (const key of store.keys()) {
+                if (prefix.length === 0 || key.startsWith(directKey)) {
+                    const rest = prefix.length === 0 ? key : key.slice(directKey.length);
+                    const head = rest.split("/")[0];
+                    if (head !== undefined && head.length > 0)
+                        out.add(head);
+                }
+            }
+            return [...out];
+        },
+        async remove(relPath) {
+            validateRelPath(relPath);
+            store.delete(normalize(relPath));
+        },
+        async rename(from, to) {
+            validateRelPath(from);
+            validateRelPath(to);
+            const fromKey = normalize(from);
+            const toKey = normalize(to);
+            const data = store.get(fromKey);
+            if (data === undefined) {
+                throw new Error(`rename: source does not exist: ${JSON.stringify(from)}`);
+            }
+            store.set(toKey, data);
+            store.delete(fromKey);
+        },
+    };
+};
+//# sourceMappingURL=memory-backend.js.map

package/dist/backend/memory-backend.js.map

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

package/dist/backend/memory-backend.test.d.ts

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

package/dist/backend/memory-backend.test.js

@@ -0,0 +1,7 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { createMemoryBackend } from "./memory-backend.js";
+import { runPersistenceBackendConformance } from "./persistence-backend.conformance.js";
+runPersistenceBackendConformance("memory", async () => ({
+    backend: createMemoryBackend(),
+}));
+//# sourceMappingURL=memory-backend.test.js.map

package/dist/backend/memory-backend.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-backend.test.js","sourceRoot":"","sources":["../../src/backend/memory-backend.test.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,gCAAgC,EAAE,MAAM,sCAAsC,CAAC;AAExF,gCAAgC,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;IACpD,OAAO,EAAE,mBAAmB,EAAE;CACjC,CAAC,CAAC,CAAC"}

package/dist/backend/memory-file.d.ts

@@ -0,0 +1,7 @@
+import { RandomAccessFile } from "./random-access-file.js";
+/**
+ * In-memory RandomAccessFile backed by a growable Uint8Array. Used by
+ * tests and as the in-process backend implementation. Behaves
+ * identically across Node and browser runtimes.
+ */
+export declare const createMemoryFile: (initial?: Uint8Array) => RandomAccessFile;

package/dist/backend/memory-file.js

@@ -0,0 +1,90 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/**
+ * In-memory RandomAccessFile backed by a growable Uint8Array. Used by
+ * tests and as the in-process backend implementation. Behaves
+ * identically across Node and browser runtimes.
+ */
+export const createMemoryFile = (initial) => {
+    let buffer = initial ? new Uint8Array(initial) : new Uint8Array(0);
+    let length = buffer.byteLength;
+    let closed = false;
+    const ensureOpen = () => {
+        if (closed)
+            throw new Error("MemoryFile is closed");
+    };
+    const ensureCapacity = (required) => {
+        if (required <= buffer.byteLength)
+            return;
+        // Grow by powers of two so amortized cost stays O(1).
+        let newCapacity = Math.max(buffer.byteLength * 2, 64);
+        while (newCapacity < required)
+            newCapacity *= 2;
+        const grown = new Uint8Array(newCapacity);
+        grown.set(buffer.subarray(0, length));
+        buffer = grown;
+    };
+    return {
+        async readAt(offset, requestedLength) {
+            ensureOpen();
+            if (offset < 0 || requestedLength < 0) {
+                throw new RangeError(`readAt: offset and length must be non-negative (offset=${offset}, length=${requestedLength})`);
+            }
+            const end = Math.min(offset + requestedLength, length);
+            const actualLength = Math.max(0, end - offset);
+            if (actualLength === 0)
+                return new Uint8Array(0);
+            // Copy out so the caller cannot mutate our internal buffer.
+            return new Uint8Array(buffer.buffer, buffer.byteOffset + offset, actualLength).slice();
+        },
+        async writeAt(offset, bytes) {
+            ensureOpen();
+            if (offset < 0) {
+                throw new RangeError(`writeAt: offset must be non-negative (offset=${offset})`);
+            }
+            const end = offset + bytes.byteLength;
+            ensureCapacity(end);
+            buffer.set(bytes, offset);
+            if (end > length)
+                length = end;
+        },
+        async appendAt(bytes) {
+            ensureOpen();
+            const start = length;
+            const end = start + bytes.byteLength;
+            ensureCapacity(end);
+            buffer.set(bytes, start);
+            length = end;
+            return length;
+        },
+        async size() {
+            ensureOpen();
+            return length;
+        },
+        async truncate(newLength) {
+            ensureOpen();
+            if (newLength < 0) {
+                throw new RangeError(`truncate: length must be non-negative (length=${newLength})`);
+            }
+            if (newLength > length) {
+                ensureCapacity(newLength);
+                // Zero-fill the grown region.
+                buffer.fill(0, length, newLength);
+            }
+            else {
+                // Zero-fill the freed region so subsequent grows do not
+                // expose stale bytes.
+                buffer.fill(0, newLength, length);
+            }
+            length = newLength;
+        },
+        async sync() {
+            ensureOpen();
+        },
+        async close() {
+            closed = true;
+            buffer = new Uint8Array(0);
+            length = 0;
+        },
+    };
+};
+//# sourceMappingURL=memory-file.js.map

package/dist/backend/memory-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-file.js","sourceRoot":"","sources":["../../src/backend/memory-file.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAIvD;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,OAAoB,EAAoB,EAAE;IACvE,IAAI,MAAM,GAAe,OAAO,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;IAC/E,IAAI,MAAM,GAAW,MAAM,CAAC,UAAU,CAAC;IACvC,IAAI,MAAM,GAAG,KAAK,CAAC;IAEnB,MAAM,UAAU,GAAG,GAAS,EAAE;QAC1B,IAAI,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;IACxD,CAAC,CAAC;IAEF,MAAM,cAAc,GAAG,CAAC,QAAgB,EAAQ,EAAE;QAC9C,IAAI,QAAQ,IAAI,MAAM,CAAC,UAAU;YAAE,OAAO;QAC1C,sDAAsD;QACtD,IAAI,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;QACtD,OAAO,WAAW,GAAG,QAAQ;YAAE,WAAW,IAAI,CAAC,CAAC;QAChD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,WAAW,CAAC,CAAC;QAC1C,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QACtC,MAAM,GAAG,KAAK,CAAC;IACnB,CAAC,CAAC;IAEF,OAAO;QACH,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,eAAuB;YAChD,UAAU,EAAE,CAAC;YACb,IAAI,MAAM,GAAG,CAAC,IAAI,eAAe,GAAG,CAAC,EAAE,CAAC;gBACpC,MAAM,IAAI,UAAU,CAAC,0DAA0D,MAAM,YAAY,eAAe,GAAG,CAAC,CAAC;YACzH,CAAC;YACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,eAAe,EAAE,MAAM,CAAC,CAAC;YACvD,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,MAAM,CAAC,CAAC;YAC/C,IAAI,YAAY,KAAK,CAAC;gBAAE,OAAO,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;YACjD,4DAA4D;YAC5D,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,EAAE,YAAY,CAAC,CAAC,KAAK,EAAE,CAAC;QAC3F,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,MAAc,EAAE,KAAiB;YAC3C,UAAU,EAAE,CAAC;YACb,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;gBACb,MAAM,IAAI,UAAU,CAAC,gDAAgD,MAAM,GAAG,CAAC,CAAC;YACpF,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,GAAG,KAAK,CAAC,UAAU,CAAC;YACtC,cAAc,CAAC,GAAG,CAAC,CAAC;YACpB,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAC1B,IAAI,GAAG,GAAG,MAAM;gBAAE,MAAM,GAAG,GAAG,CAAC;QACnC,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,KAAiB;YAC5B,UAAU,EAAE,CAAC;YACb,MAAM,KAAK,GAAG,MAAM,CAAC;YACrB,MAAM,GAAG,GAAG,KAAK,GAAG,KAAK,CAAC,UAAU,CAAC;YACrC,cAAc,CAAC,GAAG,CAAC,CAAC;YACpB,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YACzB,MAAM,GAAG,GAAG,CAAC;YACb,OAAO,MAAM,CAAC;QAClB,CAAC;QACD,KAAK,CAAC,IAAI;YACN,UAAU,EAAE,CAAC;YACb,OAAO,MAAM,CAAC;QAClB,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,SAAiB;YAC5B,UAAU,EAAE,CAAC;YACb,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;gBAChB,MAAM,IAAI,UAAU,CAAC,iDAAiD,SAAS,GAAG,CAAC,CAAC;YACxF,CAAC;YACD,IAAI,SAAS,GAAG,MAAM,EAAE,CAAC;gBACrB,cAAc,CAAC,SAAS,CAAC,CAAC;gBAC1B,8BAA8B;gBAC9B,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;YACtC,CAAC;iBAAM,CAAC;gBACJ,wDAAwD;gBACxD,sBAAsB;gBACtB,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;YACtC,CAAC;YACD,MAAM,GAAG,SAAS,CAAC;QACvB,CAAC;QACD,KAAK,CAAC,IAAI;YACN,UAAU,EAAE,CAAC;QACjB,CAAC;QACD,KAAK,CAAC,KAAK;YACP,MAAM,GAAG,IAAI,CAAC;YACd,MAAM,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;YAC3B,MAAM,GAAG,CAAC,CAAC;QACf,CAAC;KACJ,CAAC;AACN,CAAC,CAAC"}

package/dist/backend/memory-file.test.d.ts

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

package/dist/backend/memory-file.test.js

@@ -0,0 +1,5 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { createMemoryFile } from "./memory-file.js";
+import { runRandomAccessFileConformance } from "./random-access-file.conformance.js";
+runRandomAccessFileConformance("memory", () => createMemoryFile());
+//# sourceMappingURL=memory-file.test.js.map

package/dist/backend/memory-file.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-file.test.js","sourceRoot":"","sources":["../../src/backend/memory-file.test.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,8BAA8B,EAAE,MAAM,qCAAqC,CAAC;AAErF,8BAA8B,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,gBAAgB,EAAE,CAAC,CAAC"}

package/dist/backend/persistence-backend.conformance.d.ts

@@ -0,0 +1,10 @@
+import type { PersistenceBackend } from "./persistence-backend.js";
+/**
+ * Conformance suite for PersistenceBackend implementations. The factory
+ * is invoked per test (returning a fresh backend) and the optional
+ * teardown is invoked after each test.
+ */
+export declare const runPersistenceBackendConformance: (name: string, setup: () => Promise<{
+    backend: PersistenceBackend;
+    cleanup?: () => Promise<void>;
+}>) => void;

package/dist/backend/persistence-backend.conformance.js

@@ -0,0 +1,104 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+/**
+ * Conformance suite for PersistenceBackend implementations. The factory
+ * is invoked per test (returning a fresh backend) and the optional
+ * teardown is invoked after each test.
+ */
+export const runPersistenceBackendConformance = (name, setup) => {
+    describe(`PersistenceBackend conformance: ${name}`, () => {
+        let backend;
+        let cleanup;
+        beforeEach(async () => {
+            const created = await setup();
+            backend = created.backend;
+            cleanup = created.cleanup;
+        });
+        afterEach(async () => {
+            if (cleanup)
+                await cleanup();
+        });
+        test("open creates an empty file", async () => {
+            const file = await backend.open("foo.bin");
+            try {
+                expect(await file.size()).toBe(0);
+            }
+            finally {
+                await file.close();
+            }
+        });
+        test("write then re-open round-trips contents", async () => {
+            {
+                const file = await backend.open("foo.bin");
+                await file.writeAt(0, new Uint8Array([1, 2, 3]));
+                await file.close();
+            }
+            {
+                const file = await backend.open("foo.bin");
+                try {
+                    const read = await file.readAt(0, 3);
+                    expect(Array.from(read)).toEqual([1, 2, 3]);
+                }
+                finally {
+                    await file.close();
+                }
+            }
+        });
+        test("nested paths work", async () => {
+            const file = await backend.open("a/b/c.bin");
+            try {
+                await file.writeAt(0, new Uint8Array([42]));
+                expect(await file.size()).toBe(1);
+            }
+            finally {
+                await file.close();
+            }
+        });
+        test("list returns immediate children", async () => {
+            for (const relPath of ["a/x.bin", "a/y.bin", "a/sub/z.bin", "b/q.bin"]) {
+                const file = await backend.open(relPath);
+                await file.writeAt(0, new Uint8Array([1]));
+                await file.close();
+            }
+            const aChildren = [...(await backend.list("a"))].sort();
+            expect(aChildren).toEqual(["sub", "x.bin", "y.bin"]);
+            const root = [...(await backend.list("."))].sort();
+            expect(root).toEqual(["a", "b"]);
+        });
+        test("remove deletes a file", async () => {
+            const file = await backend.open("foo.bin");
+            await file.writeAt(0, new Uint8Array([1]));
+            await file.close();
+            await backend.remove("foo.bin");
+            const reopened = await backend.open("foo.bin");
+            try {
+                expect(await reopened.size()).toBe(0);
+            }
+            finally {
+                await reopened.close();
+            }
+        });
+        test("remove of non-existent file is a no-op", async () => {
+            await expect(backend.remove("does/not/exist.bin")).resolves.toBeUndefined();
+        });
+        test("rename moves a file's contents", async () => {
+            const file = await backend.open("from.bin");
+            await file.writeAt(0, new Uint8Array([7, 8, 9]));
+            await file.close();
+            await backend.rename("from.bin", "to.bin");
+            const renamed = await backend.open("to.bin");
+            try {
+                const read = await renamed.readAt(0, 3);
+                expect(Array.from(read)).toEqual([7, 8, 9]);
+            }
+            finally {
+                await renamed.close();
+            }
+        });
+        test("rejects path traversal attempts", async () => {
+            await expect(backend.open("../etc/passwd")).rejects.toThrow();
+            await expect(backend.open("/etc/passwd")).rejects.toThrow();
+        });
+    });
+};
+//# sourceMappingURL=persistence-backend.conformance.js.map

package/dist/backend/persistence-backend.conformance.js.map

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