@adobe/data-persistence 0.9.90

package/dist/encoder/journal-snapshot-codec.test.js

@@ -0,0 +1,96 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { decodeJournalSnapshot, encodeJournalSnapshot, } from "./journal-snapshot-codec.js";
+const utf8 = (s) => new TextEncoder().encode(s);
+describe("journal-snapshot-codec", () => {
+    it("round-trips an empty row list", () => {
+        const buf = encodeJournalSnapshot([]);
+        const rows = decodeJournalSnapshot(buf);
+        expect(rows).toHaveLength(0);
+    });
+    it("round-trips a single present row", () => {
+        const encoded = utf8(JSON.stringify("hello"));
+        const buf = encodeJournalSnapshot([encoded]);
+        const rows = decodeJournalSnapshot(buf);
+        expect(rows).toHaveLength(1);
+        expect(JSON.parse(new TextDecoder().decode(rows[0]))).toBe("hello");
+    });
+    it("round-trips many rows", () => {
+        const input = ["alpha", "beta", "gamma"].map((s) => utf8(JSON.stringify(s)));
+        const buf = encodeJournalSnapshot(input);
+        const rows = decodeJournalSnapshot(buf);
+        expect(rows).toHaveLength(3);
+        for (let i = 0; i < input.length; i++) {
+            expect(JSON.parse(new TextDecoder().decode(rows[i]))).toBe(["alpha", "beta", "gamma"][i]);
+        }
+    });
+    it("encodes undefined rows as ABSENT and decodes back to undefined", () => {
+        const buf = encodeJournalSnapshot([undefined, utf8('"present"'), undefined]);
+        const rows = decodeJournalSnapshot(buf);
+        expect(rows).toHaveLength(3);
+        expect(rows[0]).toBeUndefined();
+        expect(JSON.parse(new TextDecoder().decode(rows[1]))).toBe("present");
+        expect(rows[2]).toBeUndefined();
+    });
+    it("encodes empty Uint8Array as ABSENT", () => {
+        const buf = encodeJournalSnapshot([new Uint8Array(0)]);
+        const rows = decodeJournalSnapshot(buf);
+        expect(rows[0]).toBeUndefined();
+    });
+    it("torn count header returns empty array", () => {
+        const truncated = new ArrayBuffer(2); // less than 4 bytes for count
+        const rows = decodeJournalSnapshot(truncated);
+        expect(rows).toHaveLength(0);
+    });
+    it("torn record len header returns prefix only", () => {
+        const full = encodeJournalSnapshot([
+            utf8('"a"'),
+            utf8('"b"'),
+            utf8('"c"'),
+        ]);
+        // Truncate to include the count + first record + half the second record's header
+        // count(4) + len(4) + 3 bytes for "a" (utf8 of JSON.stringify("a") = '"a"' = 3 chars)
+        // + 2 bytes of the second record's len header
+        const truncated = full.slice(0, 4 + 4 + 3 + 2);
+        const rows = decodeJournalSnapshot(truncated);
+        expect(rows).toHaveLength(3);
+        // First row is intact
+        expect(JSON.parse(new TextDecoder().decode(rows[0]))).toBe("a");
+        // Remaining rows should be undefined (torn)
+        expect(rows[1]).toBeUndefined();
+        expect(rows[2]).toBeUndefined();
+    });
+    it("torn record body returns prefix only", () => {
+        const full = encodeJournalSnapshot([
+            utf8('"first"'),
+            utf8('"second"'),
+        ]);
+        // Keep count + first full record + second record's len header but truncate the body
+        // '"first"' is 7 bytes
+        const truncated = full.slice(0, 4 + 4 + 7 + 4 + 2);
+        const rows = decodeJournalSnapshot(truncated);
+        expect(rows).toHaveLength(2);
+        expect(JSON.parse(new TextDecoder().decode(rows[0]))).toBe("first");
+        expect(rows[1]).toBeUndefined();
+    });
+    it("round-trips array values (JSON arrays as row values)", () => {
+        const input = [
+            utf8(JSON.stringify(["tag-a", "tag-b"])),
+            utf8(JSON.stringify(["tag-c"])),
+        ];
+        const buf = encodeJournalSnapshot(input);
+        const rows = decodeJournalSnapshot(buf);
+        expect(rows).toHaveLength(2);
+        expect(JSON.parse(new TextDecoder().decode(rows[0]))).toEqual(["tag-a", "tag-b"]);
+        expect(JSON.parse(new TextDecoder().decode(rows[1]))).toEqual(["tag-c"]);
+    });
+    it("produces distinct Uint8Array slices (no shared backing buffer)", () => {
+        const input = [utf8('"x"'), utf8('"y"')];
+        const buf = encodeJournalSnapshot(input);
+        const rows = decodeJournalSnapshot(buf);
+        // Modifying one row should not affect the other
+        rows[0][0] = 0xff;
+        expect(rows[1][0]).not.toBe(0xff);
+    });
+});
+//# sourceMappingURL=journal-snapshot-codec.test.js.map

package/dist/encoder/journal-snapshot-codec.test.js.map

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

package/dist/encoder/types.d.ts

@@ -0,0 +1,72 @@
+import type { TypedBufferType } from "@adobe/data/typed-buffer";
+/**
+ * Manifest written to `meta.json` describing the on-disk layout for a
+ * specific database snapshot. Versioned for forward-compatible schema
+ * evolution.
+ */
+export interface Manifest {
+    readonly version: 1;
+    readonly checkpointId: number;
+    readonly archetypes: {
+        readonly [archetypeId: number]: ArchetypeManifest;
+    };
+    /** Entity → archetypeId,rowIndex packed file metadata. */
+    readonly entityLocation: {
+        readonly stride: number;
+    };
+    /**
+     * Component intern table: numeric componentId → component name. Journal
+     * entries reference components by id (u16) for fixed binary header
+     * size; this table lets the loader map ids back to live column names
+     * during journal replay.
+     */
+    readonly components: {
+        readonly [componentId: number]: string;
+    };
+}
+export interface ArchetypeManifest {
+    readonly id: number;
+    readonly name: string;
+    readonly rowCount: number;
+    readonly rowCapacity: number;
+    readonly columns: {
+        readonly [component: string]: ColumnManifest;
+    };
+}
+export interface ColumnManifest {
+    readonly component: string;
+    /** Bytes per row for fixed-stride columns, or 0 for journal-only columns. */
+    readonly stride: number;
+    /** "fixed" stores in column file; "journal" stores in journal entries only. */
+    readonly storage: "fixed" | "journal" | "manifest";
+    /** TypedBufferType from @adobe/data. */
+    readonly bufferType: TypedBufferType;
+}
+/**
+ * A slice of column bytes ready to be transferred to the worker. The
+ * `bytes` ArrayBuffer is intended for zero-copy postMessage transfer.
+ */
+export interface EncodedColumnSlice {
+    readonly archetypeId: number;
+    readonly component: string;
+    readonly rowOffset: number;
+    readonly bytes: ArrayBuffer;
+}
+/**
+ * Per-column encoder. Selected at archetype-registration time based on
+ * the column's underlying TypedBufferType.
+ */
+export interface ColumnEncoder {
+    readonly storage: ColumnManifest["storage"];
+    readonly stride: number;
+    /**
+     * Encode a contiguous range of rows into a transferable buffer.
+     * Returns null when the column type stores nothing per row (const).
+     */
+    encodeRows(rowStart: number, rowCount: number): EncodedColumnSlice["bytes"] | null;
+    /**
+     * For variable-length columns, encode a single row's value as JSON
+     * bytes for inclusion in a journal entry.
+     */
+    encodeRowValue(rowIndex: number): Uint8Array | null;
+}

package/dist/encoder/types.js

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/encoder/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/encoder/types.ts"],"names":[],"mappings":"AAAA,uDAAuD"}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+export type { RandomAccessFile } from "./backend/random-access-file.js";
+export { createMemoryFile } from "./backend/memory-file.js";
+export type { PersistenceBackend, PersistenceBackendCapabilities, } from "./backend/persistence-backend.js";
+export { createMemoryBackend } from "./backend/memory-backend.js";
+export { validateRelPath } from "./backend/validate-rel-path.js";
+export type { Transport, PersistOp, PersistMessage, AckMessage } from "./transport/transport.js";
+export { createInprocessTransport } from "./transport/inprocess-transport.js";
+export type { ColumnEncoder, EncodedColumnSlice, Manifest, ArchetypeManifest, ColumnManifest, } from "./encoder/types.js";
+export { createColumnEncoder } from "./encoder/create-column-encoder.js";
+export type { JournalEntry, JournalEntryKind } from "./journal/journal-entry.js";
+export { encodeJournalEntry, decodeJournalEntry, decodeJournalStream } from "./journal/journal-codec.js";
+export type { PersistenceProvider, ProviderMountOptions, PersistenceMount, } from "./provider/persistence-provider.js";
+export { mount } from "./provider/mount.js";
+export { createMemoryProvider } from "./provider/create-memory-provider.js";
+export type { IncrementalPersistenceService, IncrementalPersistenceServiceOptions, } from "./service/incremental-persistence-service.js";
+export { createIncrementalPersistenceService } from "./service/create-incremental-persistence-service.js";
+/**
+ * @deprecated Use `IncrementalPersistenceService` instead.
+ */
+export type { WorkerPersistenceService, WorkerPersistenceServiceOptions, MountOptions } from "./service/worker-persistence-service.js";
+/**
+ * @deprecated Use `createIncrementalPersistenceService` instead.
+ */
+export { createWorkerPersistenceService } from "./service/create-worker-persistence-service.js";

package/dist/index.js

@@ -0,0 +1,15 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export { createMemoryFile } from "./backend/memory-file.js";
+export { createMemoryBackend } from "./backend/memory-backend.js";
+export { validateRelPath } from "./backend/validate-rel-path.js";
+export { createInprocessTransport } from "./transport/inprocess-transport.js";
+export { createColumnEncoder } from "./encoder/create-column-encoder.js";
+export { encodeJournalEntry, decodeJournalEntry, decodeJournalStream } from "./journal/journal-codec.js";
+export { mount } from "./provider/mount.js";
+export { createMemoryProvider } from "./provider/create-memory-provider.js";
+export { createIncrementalPersistenceService } from "./service/create-incremental-persistence-service.js";
+/**
+ * @deprecated Use `createIncrementalPersistenceService` instead.
+ */
+export { createWorkerPersistenceService } from "./service/create-worker-persistence-service.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAOvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAM5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAGjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,oCAAoC,CAAC;AAS9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAGzE,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AASzG,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAM5E,OAAO,EAAE,mCAAmC,EAAE,MAAM,qDAAqD,CAAC;AAQ1G;;GAEG;AACH,OAAO,EAAE,8BAA8B,EAAE,MAAM,gDAAgD,CAAC"}

package/dist/journal/journal-codec.d.ts

@@ -0,0 +1,28 @@
+import { JournalEntry } from "./journal-entry.js";
+/**
+ * Encode a single journal entry into a freshly-allocated, transferable
+ * ArrayBuffer ready for `postMessage`'s transfer list (or for direct
+ * `appendAt` after wrapping in a Uint8Array). Allocates exactly one
+ * buffer per call; variable-length payload is copied in.
+ *
+ * Returning `ArrayBuffer` (not `Uint8Array`) lets the call site avoid
+ * an extra copy when it just needs to forward the bytes to a worker.
+ */
+export declare const encodeJournalEntry: (entry: JournalEntry) => ArrayBuffer;
+/**
+ * Decode a single journal entry from a buffer at the given offset. Throws
+ * if the kind code is unknown or if the buffer is shorter than the
+ * declared payload.
+ *
+ * @returns the decoded entry plus the offset of the next entry.
+ */
+export declare const decodeJournalEntry: (buffer: ArrayBufferLike, offset: number) => {
+    entry: JournalEntry;
+    nextOffset: number;
+};
+/**
+ * Decode all journal entries in a buffer. Stops at first truncation,
+ * which represents a partial write that crashed mid-entry; entries up
+ * to that point are returned.
+ */
+export declare const decodeJournalStream: (buffer: ArrayBufferLike) => readonly JournalEntry[];

package/dist/journal/journal-codec.js

@@ -0,0 +1,82 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { JOURNAL_HEADER_BYTES, JournalEntryKindCode, JournalEntryKindName, } from "./journal-entry.js";
+/**
+ * Encode a single journal entry into a freshly-allocated, transferable
+ * ArrayBuffer ready for `postMessage`'s transfer list (or for direct
+ * `appendAt` after wrapping in a Uint8Array). Allocates exactly one
+ * buffer per call; variable-length payload is copied in.
+ *
+ * Returning `ArrayBuffer` (not `Uint8Array`) lets the call site avoid
+ * an extra copy when it just needs to forward the bytes to a worker.
+ */
+export const encodeJournalEntry = (entry) => {
+    const total = JOURNAL_HEADER_BYTES + entry.bytes.byteLength;
+    const buffer = new ArrayBuffer(total);
+    const view = new DataView(buffer);
+    view.setUint32(0, entry.txId, true);
+    view.setFloat64(4, entry.timestampMs, true);
+    view.setUint8(12, JournalEntryKindCode[entry.kind]);
+    view.setInt32(13, entry.entity, true);
+    view.setUint16(17, entry.archetypeId, true);
+    view.setUint32(19, entry.rowIndex, true);
+    view.setUint16(23, entry.componentId, true);
+    view.setUint32(25, entry.bytes.byteLength, true);
+    if (entry.bytes.byteLength > 0) {
+        new Uint8Array(buffer, JOURNAL_HEADER_BYTES).set(entry.bytes);
+    }
+    return buffer;
+};
+/**
+ * Decode a single journal entry from a buffer at the given offset. Throws
+ * if the kind code is unknown or if the buffer is shorter than the
+ * declared payload.
+ *
+ * @returns the decoded entry plus the offset of the next entry.
+ */
+export const decodeJournalEntry = (buffer, offset) => {
+    const view = new DataView(buffer, offset);
+    const kindCode = view.getUint8(12);
+    const kind = JournalEntryKindName[kindCode];
+    if (kind === undefined) {
+        throw new Error(`Unknown journal entry kind code: ${kindCode}`);
+    }
+    const txId = view.getUint32(0, true);
+    const timestampMs = view.getFloat64(4, true);
+    const entity = view.getInt32(13, true);
+    const archetypeId = view.getUint16(17, true);
+    const rowIndex = view.getUint32(19, true);
+    const componentId = view.getUint16(23, true);
+    const byteLen = view.getUint32(25, true);
+    const payloadStart = offset + JOURNAL_HEADER_BYTES;
+    if (payloadStart + byteLen > buffer.byteLength) {
+        throw new Error(`Journal entry payload truncated at offset ${offset}: declared ${byteLen} bytes, only ${buffer.byteLength - payloadStart} available`);
+    }
+    const bytes = new Uint8Array(buffer, payloadStart, byteLen).slice();
+    return {
+        entry: { txId, timestampMs, kind, entity, archetypeId, rowIndex, componentId, bytes },
+        nextOffset: payloadStart + byteLen,
+    };
+};
+/**
+ * Decode all journal entries in a buffer. Stops at first truncation,
+ * which represents a partial write that crashed mid-entry; entries up
+ * to that point are returned.
+ */
+export const decodeJournalStream = (buffer) => {
+    const out = [];
+    let offset = 0;
+    while (offset + JOURNAL_HEADER_BYTES <= buffer.byteLength) {
+        try {
+            const { entry, nextOffset } = decodeJournalEntry(buffer, offset);
+            out.push(entry);
+            offset = nextOffset;
+        }
+        catch {
+            // Truncated tail (partial write at crash) — ignore the
+            // remainder and return what we have.
+            break;
+        }
+    }
+    return out;
+};
+//# sourceMappingURL=journal-codec.js.map

package/dist/journal/journal-codec.js.map

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

package/dist/journal/journal-codec.test.d.ts

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

package/dist/journal/journal-codec.test.js

@@ -0,0 +1,106 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { JOURNAL_HEADER_BYTES } from "./journal-entry.js";
+import { decodeJournalEntry, decodeJournalStream, encodeJournalEntry } from "./journal-codec.js";
+const sample = (overrides = {}) => ({
+    txId: 42,
+    timestampMs: 1735_000_000_000,
+    kind: "update",
+    entity: 17,
+    archetypeId: 7,
+    rowIndex: 13,
+    componentId: 3,
+    bytes: new Uint8Array([1, 2, 3, 4]),
+    ...overrides,
+});
+// Tests work in Uint8Array space, so wrap the codec's ArrayBuffer
+// return for ergonomic .set / .subarray access.
+const encodeBytes = (entry) => new Uint8Array(encodeJournalEntry(entry));
+describe("journal codec", () => {
+    it("round-trips a single entry", () => {
+        const entry = sample();
+        const buf = encodeBytes(entry);
+        expect(buf.byteLength).toBe(JOURNAL_HEADER_BYTES + entry.bytes.byteLength);
+        const { entry: decoded, nextOffset } = decodeJournalEntry(buf.buffer, 0);
+        expect(decoded.txId).toBe(entry.txId);
+        expect(decoded.timestampMs).toBe(entry.timestampMs);
+        expect(decoded.kind).toBe(entry.kind);
+        expect(decoded.entity).toBe(entry.entity);
+        expect(decoded.archetypeId).toBe(entry.archetypeId);
+        expect(decoded.rowIndex).toBe(entry.rowIndex);
+        expect(decoded.componentId).toBe(entry.componentId);
+        expect(Array.from(decoded.bytes)).toEqual([1, 2, 3, 4]);
+        expect(nextOffset).toBe(buf.byteLength);
+    });
+    it("round-trips an entry with empty payload (e.g. delete)", () => {
+        const entry = sample({ kind: "delete", componentId: 0, bytes: new Uint8Array(0) });
+        const buf = encodeBytes(entry);
+        expect(buf.byteLength).toBe(JOURNAL_HEADER_BYTES);
+        const { entry: decoded } = decodeJournalEntry(buf.buffer, 0);
+        expect(decoded.kind).toBe("delete");
+        expect(decoded.bytes.byteLength).toBe(0);
+    });
+    it("decodes a stream of multiple entries", () => {
+        const entries = [
+            sample({ txId: 1 }),
+            sample({ txId: 2, kind: "insert", bytes: new Uint8Array([9, 9, 9]) }),
+            sample({ txId: 3, kind: "delete", componentId: 0, bytes: new Uint8Array(0) }),
+        ];
+        const concat = new Uint8Array(entries.reduce((sum, e) => sum + JOURNAL_HEADER_BYTES + e.bytes.byteLength, 0));
+        let offset = 0;
+        for (const e of entries) {
+            const enc = encodeBytes(e);
+            concat.set(enc, offset);
+            offset += enc.byteLength;
+        }
+        const decoded = decodeJournalStream(concat.buffer);
+        expect(decoded.length).toBe(3);
+        expect(decoded.map(d => d.txId)).toEqual([1, 2, 3]);
+        expect(decoded[1].kind).toBe("insert");
+    });
+    it("decodeJournalStream tolerates a truncated tail entry", () => {
+        const entry = sample({ bytes: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]) });
+        const enc = encodeBytes(entry);
+        const truncated = enc.subarray(0, enc.byteLength - 3);
+        const decoded = decodeJournalStream(truncated.buffer.slice(truncated.byteOffset, truncated.byteOffset + truncated.byteLength));
+        expect(decoded.length).toBe(0);
+    });
+    it("decodeJournalStream returns the prefix when only the tail is torn", () => {
+        const ok = encodeBytes(sample({ txId: 100 }));
+        const torn = encodeBytes(sample({ txId: 101, bytes: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]) }));
+        const tornShort = torn.subarray(0, torn.byteLength - 3);
+        const total = ok.byteLength + tornShort.byteLength;
+        const buf = new Uint8Array(total);
+        buf.set(ok, 0);
+        buf.set(tornShort, ok.byteLength);
+        const decoded = decodeJournalStream(buf.buffer);
+        expect(decoded.length).toBe(1);
+        expect(decoded[0].txId).toBe(100);
+    });
+    it("rejects unknown kind code", () => {
+        const buf = encodeBytes(sample());
+        new DataView(buf.buffer).setUint8(12, 99);
+        expect(() => decodeJournalEntry(buf.buffer, 0)).toThrow(/Unknown journal entry kind code/);
+    });
+    it("preserves negative entity values (ephemeral / sentinel)", () => {
+        const entry = sample({ entity: -1 });
+        const buf = encodeBytes(entry);
+        const { entry: decoded } = decodeJournalEntry(buf.buffer, 0);
+        expect(decoded.entity).toBe(-1);
+    });
+    it("preserves a large positive entity id", () => {
+        const entry = sample({ entity: 0x7fff_fffe });
+        const buf = encodeBytes(entry);
+        const { entry: decoded } = decodeJournalEntry(buf.buffer, 0);
+        expect(decoded.entity).toBe(0x7fff_fffe);
+    });
+    it("returns a fresh, transferable ArrayBuffer (zero-copy worker handoff)", () => {
+        const buf = encodeJournalEntry(sample());
+        // Type guarantee: encodeJournalEntry returns ArrayBuffer (not
+        // SharedArrayBuffer / Uint8Array) so the call site can list
+        // it directly in postMessage's transfer set.
+        expect(buf).toBeInstanceOf(ArrayBuffer);
+        expect(buf.byteLength).toBe(JOURNAL_HEADER_BYTES + 4);
+    });
+});
+//# sourceMappingURL=journal-codec.test.js.map

package/dist/journal/journal-codec.test.js.map

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

package/dist/journal/journal-entry.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Wire codes for each journal entry kind. This is the single source of
+ * truth — `JournalEntryKind` and `JournalEntryKindName` are both
+ * derived from it so they can never drift.
+ *
+ *   insert  - a new row was inserted into an archetype
+ *   update  - an existing row was updated
+ *   delete  - an entity was deleted
+ *   migrate - an entity moved from one archetype to another
+ *   commit  - end-of-transaction marker. Carries no per-row payload;
+ *             its presence at txId T tells the replayer that all
+ *             entries for T are durable. Replay buffers data entries
+ *             by txId and only applies a tx once its commit entry is
+ *             seen — torn tails (incomplete tx never reached commit)
+ *             are dropped wholesale, preserving transactional
+ *             atomicity across crashes.
+ */
+export declare const JournalEntryKindCode: {
+    readonly insert: 1;
+    readonly update: 2;
+    readonly delete: 3;
+    readonly migrate: 4;
+    readonly commit: 5;
+};
+export type JournalEntryKind = keyof typeof JournalEntryKindCode;
+export declare const JournalEntryKindName: Readonly<Record<number, JournalEntryKind>>;
+/**
+ * A single journal entry. Variable-length payloads (`bytes`) are JSON
+ * for variable-length columns, or empty for delete/migrate.
+ *
+ * Wire format (little-endian):
+ *
+ *   u32 txId
+ *   f64 timestampMs
+ *   u8  kindCode
+ *   i32 entity            (signed; the affected entity id)
+ *   u16 archetypeId       (0 for delete entries — entity has no archetype)
+ *   u32 rowIndex          (0 for delete entries)
+ *   u16 componentId       (0 when not applicable, e.g. delete)
+ *   u32 byteLen
+ *   bytes... (byteLen bytes)
+ *
+ * Total fixed-header size: 29 bytes.
+ *
+ * `entity` is required for crash-recovery replay: after restoring the
+ * checkpoint snapshot, the journal carries the entity → (archetype, row)
+ * mapping for everything that happened since, plus the per-row column
+ * bytes needed to reconstruct any partially-written rows.
+ */
+export interface JournalEntry {
+    readonly txId: number;
+    readonly timestampMs: number;
+    readonly kind: JournalEntryKind;
+    /** The entity affected by this entry. */
+    readonly entity: number;
+    readonly archetypeId: number;
+    readonly rowIndex: number;
+    /** Numeric id from the manifest's component intern table (0 = none). */
+    readonly componentId: number;
+    /** JSON-encoded payload for variable-length columns; empty otherwise. */
+    readonly bytes: Uint8Array;
+}
+export declare const JOURNAL_HEADER_BYTES = 29;

package/dist/journal/journal-entry.js

@@ -0,0 +1,28 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/**
+ * Wire codes for each journal entry kind. This is the single source of
+ * truth — `JournalEntryKind` and `JournalEntryKindName` are both
+ * derived from it so they can never drift.
+ *
+ *   insert  - a new row was inserted into an archetype
+ *   update  - an existing row was updated
+ *   delete  - an entity was deleted
+ *   migrate - an entity moved from one archetype to another
+ *   commit  - end-of-transaction marker. Carries no per-row payload;
+ *             its presence at txId T tells the replayer that all
+ *             entries for T are durable. Replay buffers data entries
+ *             by txId and only applies a tx once its commit entry is
+ *             seen — torn tails (incomplete tx never reached commit)
+ *             are dropped wholesale, preserving transactional
+ *             atomicity across crashes.
+ */
+export const JournalEntryKindCode = {
+    insert: 1,
+    update: 2,
+    delete: 3,
+    migrate: 4,
+    commit: 5,
+};
+export const JournalEntryKindName = Object.fromEntries(Object.entries(JournalEntryKindCode).map(([name, code]) => [code, name]));
+export const JOURNAL_HEADER_BYTES = 29;
+//# sourceMappingURL=journal-entry.js.map

package/dist/journal/journal-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal-entry.js","sourceRoot":"","sources":["../../src/journal/journal-entry.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAChC,MAAM,EAAE,CAAC;IACT,MAAM,EAAE,CAAC;IACT,MAAM,EAAE,CAAC;IACT,OAAO,EAAE,CAAC;IACV,MAAM,EAAE,CAAC;CACH,CAAC;AAIX,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,WAAW,CAClD,MAAM,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAC7B,CAAC;AAuChD,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC"}

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

@@ -0,0 +1,34 @@
+import type { PersistenceProvider } from "../provider/persistence-provider.js";
+export interface NodeFsProviderOptions {
+    /**
+     * When `true`, delegates all storage I/O to a `node:worker_threads`
+     * worker so that file operations never block the event loop.
+     *
+     * When `false` (the default), runs storage operations in-process using
+     * `fs.promises` which is already non-blocking via libuv.
+     */
+    readonly worker?: boolean;
+    /**
+     * Override the worker bootstrap script URL. Only used when
+     * `worker: true`. Defaults to the built `node-worker-bootstrap.js`
+     * shipped alongside this package.
+     */
+    readonly workerScript?: URL;
+}
+/**
+ * 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 declare const createNodeFsProvider: (root: string, options?: NodeFsProviderOptions) => PersistenceProvider;