@adobe/data-persistence 0.9.90

package/dist/perftest/perf-harness.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Minimal async-aware performance harness for the persistence layer.
+ *
+ * Differs from `packages/data/src/perftest/perf-test.ts` in two ways:
+ *
+ *   1. `run` is `async` because every persistence operation drains
+ *      through a transport whose acks resolve on a microtask. A
+ *      sync-only harness would either record zero (work hasn't
+ *      finished) or include only the synchronous `send()` push,
+ *      which would be misleading.
+ *
+ *   2. There's a `setupBatch` hook called once per measurement loop
+ *      iteration. Some scenarios (e.g. "steady delete") consume an
+ *      entity per iteration; this lets the scenario refill its
+ *      working set without that cost being attributed to `run()`.
+ *
+ * The harness is intentionally tiny — it owns warmup, auto-tuning,
+ * the measurement window, and printing. Scenarios own everything
+ * else (database, transport, backend, scoring).
+ */
+export interface PerfScenario {
+    /**
+     * Friendly name shown in the results table.
+     */
+    readonly name: string;
+    /**
+     * One-time setup (database creation, populating N entities, etc).
+     * Called once per `n` choice during auto-tune; the measurement
+     * window itself reuses the resulting state.
+     */
+    setup(n: number): Promise<void>;
+    /**
+     * Optional per-iteration setup. Returns a cost-free reference
+     * (entity ids, indices, etc) that `run()` can use without
+     * computing it during measurement. Called once per `run()` call.
+     */
+    setupBatch?(): Promise<unknown>;
+    /**
+     * The measured operation. Must perform exactly ONE logical
+     * persistence operation (one transaction, one checkpoint, one
+     * load — whatever the scenario says it measures). Returns when
+     * the operation has fully drained on the persistence side.
+     */
+    run(batch: unknown): Promise<void>;
+    /**
+     * Tear down the database, dispose the service, close the
+     * transport. Called once per scenario.
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Auto-tune seed. Scenarios with high per-op cost should set
+     * this lower than the default (1000) so the first probe doesn't
+     * waste the budget.
+     */
+    readonly startN?: number;
+}
+export interface PerfResult {
+    readonly name: string;
+    readonly n: number;
+    readonly samples: number;
+    readonly meanUs: number;
+    readonly minUs: number;
+    readonly p50Us: number;
+    readonly p99Us: number;
+    readonly opsPerSec: number;
+}
+/**
+ * Run a single scenario through the warmup + measurement pipeline.
+ */
+export declare const runScenario: (scenario: PerfScenario) => Promise<PerfResult>;
+/**
+ * Run all scenarios sequentially and print a results table.
+ */
+export declare const runAll: (scenarios: readonly PerfScenario[]) => Promise<readonly PerfResult[]>;

package/dist/perftest/perf-harness.js

@@ -0,0 +1,147 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+const DEFAULT_START_N = 1000;
+// Target per-iteration time: 0.5–150 ms. Below 0.5 ms timing
+// resolution dominates; above 150 ms we get too few samples in the
+// 1-second budget for stable percentiles. The wide upper bound is
+// deliberate — scenarios whose cold probe drifts to ~70 ms because
+// of GC noise should NOT trigger auto-tune to halve N, because the
+// halved version is then evaluated under DIFFERENT per-tx overhead
+// proportions and produces non-comparable numbers across runs.
+const TARGET_MIN_MS = 0.5;
+const TARGET_MAX_MS = 150;
+const MIN_AUTO_N = 1;
+const MAX_AUTO_N = 100_000;
+const WARMUP_MS = 100;
+const MEASURE_BUDGET_MS = 1000;
+const now = () => performance.now();
+const percentile = (sortedAsc, p) => {
+    if (sortedAsc.length === 0)
+        return 0;
+    const idx = Math.min(sortedAsc.length - 1, Math.floor((p / 100) * sortedAsc.length));
+    return sortedAsc[idx];
+};
+/**
+ * Auto-tune `n` so a single `run()` lands in TARGET_MIN_MS..TARGET_MAX_MS.
+ * Returns the chosen n and (re-)leaves the scenario set up at that n.
+ */
+const tuneN = async (scenario) => {
+    let n = scenario.startN ?? DEFAULT_START_N;
+    for (let attempt = 0; attempt < 4; attempt++) {
+        await scenario.cleanup().catch(() => undefined);
+        await scenario.setup(n);
+        const batch = scenario.setupBatch ? await scenario.setupBatch() : undefined;
+        const start = now();
+        await scenario.run(batch);
+        const elapsed = Math.max(now() - start, 0.001);
+        if (elapsed >= TARGET_MIN_MS && elapsed <= TARGET_MAX_MS)
+            return n;
+        const target = (TARGET_MIN_MS + TARGET_MAX_MS) / 2;
+        const ratio = target / elapsed;
+        const next = Math.max(MIN_AUTO_N, Math.min(MAX_AUTO_N, Math.round(n * ratio)));
+        if (next === n)
+            return n;
+        n = next;
+    }
+    return n;
+};
+/**
+ * Run a single scenario through the warmup + measurement pipeline.
+ */
+export const runScenario = async (scenario) => {
+    const n = await tuneN(scenario);
+    // Warmup: keep calling run() (re-batching as needed) for ~100ms so
+    // V8 fully optimizes hot functions before any sample is recorded.
+    const warmupEnd = now() + WARMUP_MS;
+    while (now() < warmupEnd) {
+        const batch = scenario.setupBatch ? await scenario.setupBatch() : undefined;
+        await scenario.run(batch);
+    }
+    // Measurement window. We sample as many runs as fit into the
+    // budget. Each sample is ms-per-run-of-N-ops; we convert to
+    // μs-per-op by dividing by n at report time.
+    const samplesMs = [];
+    const budgetEnd = now() + MEASURE_BUDGET_MS;
+    while (now() < budgetEnd) {
+        const batch = scenario.setupBatch ? await scenario.setupBatch() : undefined;
+        const start = now();
+        await scenario.run(batch);
+        const elapsed = now() - start;
+        samplesMs.push(elapsed);
+    }
+    await scenario.cleanup().catch(() => undefined);
+    if (samplesMs.length === 0) {
+        // Pathological: even a single run blew the budget. Report
+        // a single sample so callers can still see SOMETHING.
+        return {
+            name: scenario.name,
+            n,
+            samples: 0,
+            meanUs: NaN,
+            minUs: NaN,
+            p50Us: NaN,
+            p99Us: NaN,
+            opsPerSec: NaN,
+        };
+    }
+    const samplesUs = samplesMs.map(ms => (ms * 1000) / n);
+    const sorted = [...samplesUs].sort((a, b) => a - b);
+    const mean = samplesUs.reduce((a, b) => a + b, 0) / samplesUs.length;
+    const min = sorted[0];
+    const p50 = percentile(sorted, 50);
+    const p99 = percentile(sorted, 99);
+    const opsPerSec = mean > 0 ? 1_000_000 / mean : Infinity;
+    return {
+        name: scenario.name,
+        n,
+        samples: samplesMs.length,
+        meanUs: mean,
+        minUs: min,
+        p50Us: p50,
+        p99Us: p99,
+        opsPerSec,
+    };
+};
+/**
+ * Run all scenarios sequentially and print a results table.
+ */
+export const runAll = async (scenarios) => {
+    const results = [];
+    for (const scenario of scenarios) {
+        process.stdout.write(`  ${scenario.name} ... `);
+        const start = now();
+        try {
+            const result = await runScenario(scenario);
+            results.push(result);
+            const wall = ((now() - start) / 1000).toFixed(1);
+            process.stdout.write(`${result.meanUs.toFixed(2)} μs/op  (${result.samples} samples, ${wall}s wall)\n`);
+        }
+        catch (err) {
+            process.stdout.write(`FAILED: ${err.message}\n`);
+            throw err;
+        }
+    }
+    printTable(results);
+    return results;
+};
+const printTable = (results) => {
+    if (results.length === 0)
+        return;
+    const rows = results.map(r => ({
+        scenario: r.name,
+        N: r.n,
+        samples: r.samples,
+        "μs/op (mean)": r.meanUs.toFixed(2),
+        "μs/op (min)": r.minUs.toFixed(2),
+        "μs/op (p50)": r.p50Us.toFixed(2),
+        "μs/op (p99)": r.p99Us.toFixed(2),
+        "ops/sec": Math.round(r.opsPerSec).toLocaleString(),
+    }));
+    if (typeof console.table === "function") {
+        console.table(rows);
+    }
+    else {
+        for (const row of rows)
+            console.log(row);
+    }
+};
+//# sourceMappingURL=perf-harness.js.map

package/dist/perftest/perf-harness.js.map

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

package/dist/perftest/persistence-perf.d.ts

@@ -0,0 +1,2 @@
+import type { PerfScenario } from "./perf-harness.js";
+export declare const persistenceScenarios: readonly PerfScenario[];

package/dist/perftest/persistence-perf.js

@@ -0,0 +1,290 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Database } from "@adobe/data/ecs";
+import { F32, Vec3 } from "@adobe/data/math";
+import { createMemoryBackend } from "../backend/memory-backend.js";
+import { createWorkerPersistenceService } from "../service/create-worker-persistence-service.js";
+// All scenarios share this database shape so wall-time numbers
+// are directly comparable across scenarios. Three components, one
+// archetype — small enough that per-tx work is dominated by the
+// persistence layer itself, not the schema's encoder cost.
+const createTestDb = () => {
+    const plugin = Database.Plugin.create({
+        components: {
+            position: Vec3.schema,
+            velocity: Vec3.schema,
+            mass: F32.schema,
+        },
+        archetypes: {
+            Particle: ["position", "velocity", "mass"],
+        },
+        transactions: {
+            spawn(t, args) {
+                return t.archetypes.Particle.insert({
+                    position: [args.x, args.y, args.z],
+                    velocity: [0, 0, 0],
+                    mass: args.mass,
+                });
+            },
+            move(t, args) {
+                t.update(args.entity, { position: [args.x, args.y, args.z] });
+            },
+            updateAll(t, args) {
+                t.update(args.entity, {
+                    position: [args.x, args.y, args.z],
+                    velocity: [args.vx, args.vy, args.vz],
+                    mass: args.mass,
+                });
+            },
+            kill(t, entity) {
+                t.delete(entity);
+            },
+        },
+    });
+    return Database.create(plugin);
+};
+const setupPopulated = async (n) => {
+    const db = createTestDb();
+    const backend = createMemoryBackend();
+    const service = await createWorkerPersistenceService({
+        database: db,
+        backend,
+        // Disable both checkpoint paths so they never fire during a
+        // measurement window and skew numbers. Each scenario that
+        // wants to measure checkpoint cost calls it explicitly.
+        checkpoint: { everyNTransactions: 0, idleMs: 0 },
+    });
+    const ids = [];
+    for (let i = 0; i < n; i++) {
+        const id = db.transactions.spawn({ x: i, y: i, z: i, mass: 1 });
+        ids.push(id);
+    }
+    await service.flush();
+    return { db, service, ids };
+};
+/**
+ * Steady-state per-tx update touching ONE component on ONE entity.
+ *
+ * This is the dominant case in real workloads: gameplay tick that
+ * moves a few entities per frame. The per-component-write
+ * optimization (architectural review #4) targets this case
+ * specifically — its win shows up here as a 3× drop vs writing all
+ * three columns per tx.
+ */
+const moveOneComponent = () => {
+    let state = null;
+    let cursor = 0;
+    return {
+        name: "tx: update 1 component on 1 entity (steady)",
+        startN: 200,
+        async setup(n) {
+            state = await setupPopulated(1000);
+            cursor = 0;
+            void n; // n here is iterations per measurement, not world size
+        },
+        async run() {
+            const s = state;
+            for (let i = 0; i < 200; i++) {
+                const e = s.ids[cursor];
+                cursor = (cursor + 1) % s.ids.length;
+                s.db.transactions.move({ entity: e, x: i, y: i, z: i });
+            }
+            await s.service.flush();
+        },
+        async cleanup() {
+            await state?.service.dispose();
+            state = null;
+        },
+    };
+};
+const moveAllComponents = () => {
+    let state = null;
+    let cursor = 0;
+    return {
+        name: "tx: update 3 components on 1 entity",
+        startN: 200,
+        async setup() {
+            state = await setupPopulated(1000);
+            cursor = 0;
+        },
+        async run() {
+            const s = state;
+            for (let i = 0; i < 200; i++) {
+                const e = s.ids[cursor];
+                cursor = (cursor + 1) % s.ids.length;
+                s.db.transactions.updateAll({
+                    entity: e,
+                    x: i, y: i, z: i,
+                    vx: -i, vy: -i, vz: -i,
+                    mass: i + 1,
+                });
+            }
+            await s.service.flush();
+        },
+        async cleanup() {
+            await state?.service.dispose();
+            state = null;
+        },
+    };
+};
+const insertSteady = () => {
+    let state = null;
+    return {
+        name: "tx: insert (3 columns)",
+        startN: 200,
+        async setup() {
+            state = await setupPopulated(1000);
+        },
+        async run() {
+            const s = state;
+            for (let i = 0; i < 200; i++) {
+                s.db.transactions.spawn({ x: i, y: i, z: i, mass: 1 });
+            }
+            await s.service.flush();
+        },
+        async cleanup() {
+            await state?.service.dispose();
+            state = null;
+        },
+    };
+};
+/**
+ * Steady-state delete with the swap-remove side effect: the
+ * persistence service detects the moved entity and emits a synthetic
+ * full-row update for it. This scenario refills the working set in
+ * setupBatch so the iteration count is pinned.
+ */
+const deleteWithSwap = () => {
+    let state = null;
+    let killCount = 0;
+    return {
+        name: "tx: delete + swap-remove side effect",
+        startN: 100,
+        async setup() {
+            state = await setupPopulated(2000);
+            killCount = 0;
+        },
+        async setupBatch() {
+            // Refill the working set so each measurement iteration
+            // has a known number of victims to kill. Done OUTSIDE
+            // run() so its cost isn't attributed to delete.
+            const s = state;
+            while (s.ids.length < 1000) {
+                const id = s.db.transactions.spawn({ x: 0, y: 0, z: 0, mass: 1 });
+                s.ids.push(id);
+            }
+            await s.service.flush();
+        },
+        async run() {
+            const s = state;
+            for (let i = 0; i < 100; i++) {
+                // Always delete from the middle so swap-remove
+                // actually triggers (deleting the LAST row would not).
+                const idx = Math.floor(s.ids.length / 2);
+                const e = s.ids[idx];
+                s.ids.splice(idx, 1);
+                s.db.transactions.kill(e);
+                killCount += 1;
+            }
+            await s.service.flush();
+        },
+        async cleanup() {
+            void killCount;
+            await state?.service.dispose();
+            state = null;
+        },
+    };
+};
+const checkpointAfterUpdates = () => {
+    let state = null;
+    let cursor = 0;
+    return {
+        name: "checkpoint: after 1k updates",
+        startN: 1,
+        async setup() {
+            state = await setupPopulated(1000);
+            cursor = 0;
+        },
+        async setupBatch() {
+            // Dirty 1k rows since the last checkpoint so the
+            // checkpoint actually has work to do (write a full
+            // manifest, then truncate the journal).
+            const s = state;
+            for (let i = 0; i < 1000; i++) {
+                const e = s.ids[cursor];
+                cursor = (cursor + 1) % s.ids.length;
+                s.db.transactions.move({ entity: e, x: i, y: i, z: i });
+            }
+            await s.service.flush();
+        },
+        async run() {
+            await state.service.checkpoint();
+        },
+        async cleanup() {
+            await state?.service.dispose();
+            state = null;
+        },
+    };
+};
+/**
+ * Cold-start load(): populate, checkpoint, dispose, then create a
+ * fresh service with a fresh database against the SAME backend and
+ * measure load() time. This is the single-shot recovery path users
+ * see at app startup.
+ */
+const loadCold = () => {
+    let backend = null;
+    let svc = null;
+    let db = null;
+    return {
+        name: "load: 1k entities, single-shot",
+        startN: 1,
+        async setup() {
+            // One-time prep: build a fully-checkpointed snapshot in
+            // the backend that we'll re-load each iteration.
+            const seedDb = createTestDb();
+            backend = createMemoryBackend();
+            const seedSvc = await createWorkerPersistenceService({
+                database: seedDb,
+                backend,
+                checkpoint: { everyNTransactions: 0, idleMs: 0 },
+            });
+            for (let i = 0; i < 1000; i++) {
+                seedDb.transactions.spawn({ x: i, y: i, z: i, mass: 1 });
+            }
+            await seedSvc.flush();
+            await seedSvc.checkpoint();
+            await seedSvc.dispose();
+        },
+        async setupBatch() {
+            // A fresh database + service per iteration — load() is a
+            // one-shot operation and reusing the same service would
+            // make replay no-op after the first iteration.
+            if (svc !== null)
+                await svc.dispose();
+            db = createTestDb();
+            svc = await createWorkerPersistenceService({
+                database: db,
+                backend: backend,
+                checkpoint: { everyNTransactions: 0, idleMs: 0 },
+            });
+        },
+        async run() {
+            await svc.load();
+        },
+        async cleanup() {
+            await svc?.dispose();
+            svc = null;
+            db = null;
+            backend = null;
+        },
+    };
+};
+export const persistenceScenarios = [
+    moveOneComponent(),
+    moveAllComponents(),
+    insertSteady(),
+    deleteWithSwap(),
+    checkpointAfterUpdates(),
+    loadCold(),
+];
+//# sourceMappingURL=persistence-perf.js.map

package/dist/perftest/persistence-perf.js.map

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

package/dist/perftest/run.d.ts

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

package/dist/perftest/run.js

@@ -0,0 +1,28 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { runAll } from "./perf-harness.js";
+import { persistenceScenarios } from "./persistence-perf.js";
+/**
+ * Persistence perftest entry point.
+ *
+ * Run with:
+ *
+ *     pnpm --filter @adobe/data-persistence run perf
+ *
+ * The runner uses the in-process transport so wall-time numbers
+ * exclude postMessage overhead and isolate the persistence
+ * service's own per-tx cost. Worker-thread / web-worker numbers
+ * will add 1–10 μs of postMessage round-trip per op on top of
+ * what's reported here.
+ */
+const main = async () => {
+    console.log("@adobe/data-persistence perftest");
+    console.log("================================");
+    console.log("(in-process transport; reported numbers exclude postMessage overhead)");
+    console.log("");
+    await runAll(persistenceScenarios);
+};
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=run.js.map

package/dist/perftest/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/perftest/run.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAE7D;;;;;;;;;;;;GAYG;AACH,MAAM,IAAI,GAAG,KAAK,IAAmB,EAAE;IACnC,OAAO,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;IAChD,OAAO,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;IAChD,OAAO,CAAC,GAAG,CAAC,uEAAuE,CAAC,CAAC;IACrF,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChB,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;AACvC,CAAC,CAAC;AAEF,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC1B,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC,CAAC,CAAC"}

package/dist/provider/create-memory-provider.d.ts

@@ -0,0 +1,16 @@
+import type { PersistenceProvider } from "./persistence-provider.js";
+/**
+ * Creates an in-memory persistence provider. All data is lost when the
+ * mount is disposed.
+ *
+ * Primarily useful for tests and for prototyping without configuring a
+ * real storage backend.
+ *
+ * ```ts
+ * import { mount } from "@adobe/data-persistence";
+ * import { createMemoryProvider } from "@adobe/data-persistence";
+ *
+ * const m = await mount(createMemoryProvider(), database);
+ * ```
+ */
+export declare const createMemoryProvider: () => PersistenceProvider;

package/dist/provider/create-memory-provider.js

@@ -0,0 +1,44 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { createMemoryBackend } from "../backend/memory-backend.js";
+import { createInprocessTransport } from "../transport/inprocess-transport.js";
+import { createIncrementalPersistenceService } from "../service/create-incremental-persistence-service.js";
+/**
+ * Creates an in-memory persistence provider. All data is lost when the
+ * mount is disposed.
+ *
+ * Primarily useful for tests and for prototyping without configuring a
+ * real storage backend.
+ *
+ * ```ts
+ * import { mount } from "@adobe/data-persistence";
+ * import { createMemoryProvider } from "@adobe/data-persistence";
+ *
+ * const m = await mount(createMemoryProvider(), database);
+ * ```
+ */
+export const createMemoryProvider = () => {
+    // A single backend shared across all mounts from this provider instance,
+    // so that a second mount can load data written by a previous mount.
+    const backend = createMemoryBackend();
+    return {
+        providerName: "MemoryProvider",
+        async mount(database, mountOptions) {
+            const transport = 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-memory-provider.js.map

package/dist/provider/create-memory-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-memory-provider.js","sourceRoot":"","sources":["../../src/provider/create-memory-provider.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAGvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,wBAAwB,EAAE,MAAM,qCAAqC,CAAC;AAC/E,OAAO,EAAE,mCAAmC,EAAE,MAAM,sDAAsD,CAAC;AAG3G;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAwB,EAAE;IAC1D,yEAAyE;IACzE,oEAAoE;IACpE,MAAM,OAAO,GAAG,mBAAmB,EAAE,CAAC;IAEtC,OAAO;QACP,YAAY,EAAE,gBAAgB;QAE9B,KAAK,CAAC,KAAK,CACP,QAA0D,EAC1D,YAAmC;YAEnC,MAAM,SAAS,GAAG,wBAAwB,CAAC,OAAO,CAAC,CAAC;YACpD,MAAM,OAAO,GAAG,MAAM,mCAAmC,CAAC;gBACtD,QAAQ;gBACR,OAAO;gBACP,SAAS;gBACT,WAAW,EAAE,YAAY,EAAE,WAAW;gBACtC,UAAU,EAAE,YAAY,EAAE,UAAU;aACvC,CAAC,CAAC;YAEH,OAAO;gBACH,OAAO;gBACP,KAAK,CAAC,OAAO;oBACT,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;oBACxB,MAAM,SAAS,CAAC,KAAK,EAAE,CAAC;gBAC5B,CAAC;aACJ,CAAC;QACN,CAAC;KACA,CAAC;AACN,CAAC,CAAC"}

package/dist/provider/mount.d.ts

@@ -0,0 +1,20 @@
+import type { Database } from "@adobe/data/ecs";
+import type { PersistenceMount, PersistenceProvider, ProviderMountOptions } from "./persistence-provider.js";
+/**
+ * Mount a persistence session using the supplied provider.
+ *
+ * This is the single entry point for all persistence. The provider
+ * encapsulates the storage strategy — Node.js `fs`, OPFS, in-memory, or
+ * a custom cloud implementation.
+ *
+ * ```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();
+ * ```
+ */
+export declare const mount: (provider: PersistenceProvider, database: Database<any, any, any, any, any, any, any, any>, options?: ProviderMountOptions) => Promise<PersistenceMount>;