@braidlabs/data 0.1.1

package/src/lib/events.js

@@ -0,0 +1,337 @@
+import { drainOutbox } from './flush.js';
+import { sharedInvalidator } from './invalidation.js';
+import { createOutbox } from './outbox.js';
+import { createIntentRegistry, } from './intents.js';
+const EVENT_COLLECTION = 'skew-events';
+const DEFAULT_TTL_MS = 60 * 60 * 1000;
+const DEFAULT_MAX_DEPTH = 500;
+/** The queue owner for a consumer's events, kept clear of its mutation outbox's lock and records. */
+const queueOwner = (consumer) => `events:${consumer}`;
+/** The tag that says "your event queue moved" — the same wake-up trick the overlay uses. */
+const wakeTag = (consumer) => `skew:events#${consumer}`;
+/** One mutation id per channel+type, so `drainOutbox` can find the handler by name after a reload. */
+const runnerId = (channel, type) => `event:${channel}:${type}`;
+export function createEventBus(options) {
+    const partition = options.partition ?? (() => 'default');
+    const invalidator = options.invalidator ?? sharedInvalidator({ partition: partition() });
+    const schemas = new Map();
+    const channels = new Map();
+    const handlers = new Map();
+    const maxAttempts = options.maxAttempts ?? 5;
+    /** This consumer's own durable queue. One outbox, every channel's events. */
+    const queue = options.driver
+        ? createOutbox({
+            driver: options.driver,
+            owner: queueOwner(options.consumer),
+            partition: partition(),
+            collection: EVENT_COLLECTION,
+        })
+        : null;
+    /** Projects a value to one reader's version, exactly as the context bus does. */
+    function project(type, value, as) {
+        const schema = schemas.get(type);
+        if (!schema)
+            return structuredClone(value);
+        const envelope = as === undefined || as === schema.version ? schema.write(value) : schema.write(value, { as });
+        return structuredClone(envelope.payload);
+    }
+    function openWire(name) {
+        const wireName = `skew:events:${partition()}:${name}`;
+        if (options.broadcastChannel)
+            return options.broadcastChannel(wireName);
+        return typeof BroadcastChannel === 'undefined'
+            ? undefined
+            : new BroadcastChannel(wireName);
+    }
+    function channelState(name, channelOptions) {
+        // One entity's channel is not another's, so the identity carries it — while the contract stays
+        // registered under the logical name, because every fund's selection has the same shape.
+        const key = channelOptions.entity ? `${name}@${channelOptions.entity}` : name;
+        const existing = channels.get(key);
+        if (existing)
+            return existing;
+        const scope = channelOptions.scope ?? 'page';
+        const wire = scope === 'origin' ? openWire(key) : undefined;
+        const created = {
+            name,
+            key,
+            options: channelOptions,
+            state: undefined,
+            conflict: null,
+            stateListeners: new Set(),
+            wire,
+        };
+        // A BroadcastChannel never delivers to its own sender, so a message arriving here is always from
+        // another context — no de-duplication needed, which is the same property invalidation relies on.
+        wire?.addEventListener('message', (event) => {
+            const message = event.data;
+            if (message?.kind === 'state')
+                applyState(created, message.value, { local: false });
+            if (message?.kind === 'event' && message.event)
+                deliverLive(message.event);
+        });
+        channels.set(key, created);
+        return created;
+    }
+    /**
+     * Applies a new state value and tells the subscribers.
+     *
+     * Conflict is compared only against a value this context published: another context's broadcast is
+     * news, not a disagreement. Two publishers racing end in last-write-wins, and the policy decides
+     * whether anyone is told — the same contract, and the same words, as a mutation's confirmation.
+     */
+    function applyState(channel, value, { local }) {
+        const previous = channel.state;
+        let stored = value;
+        if (local && previous !== undefined && !same(previous, value)) {
+            const policy = channel.options.onConflict ?? 'raise';
+            const conflict = {
+                expected: previous,
+                actual: value,
+                paths: differingKeys(previous, value),
+            };
+            if (typeof policy === 'function')
+                stored = policy(conflict);
+            else if (policy === 'raise')
+                channel.conflict = conflict;
+        }
+        channel.state = stored;
+        for (const subscription of [...channel.stateListeners]) {
+            // Isolated per subscriber: one application's bad deploy must not present as a different
+            // application silently failing to update.
+            try {
+                subscription.listener(project(channel.name, stored, subscription.as));
+            }
+            catch (error) {
+                options.onEventError?.(`[skew/data] a "${channel.name}" state subscriber threw`, error);
+            }
+        }
+    }
+    /** Fan-out to handlers in this context. Used by at-most-once, and by the queue drain. */
+    function deliverLive(event) {
+        for (const handler of [...(handlers.get(runnerId(event.channel, event.type)) ?? [])]) {
+            try {
+                void handler(event);
+            }
+            catch (error) {
+                options.onEventError?.(`[skew/data] a "${event.type}" handler threw`, error);
+            }
+        }
+    }
+    /**
+     * Writes one entry per registered consumer, then wakes them.
+     *
+     * The emitting application is included: its own handlers are served by draining, not by a direct
+     * call, so a durable event is delivered by exactly one path no matter who is listening. Two paths
+     * would mean a mounted consumer handled the event twice.
+     */
+    async function enqueue(event, channel) {
+        if (!options.driver) {
+            throw new TypeError('[skew/data] at-least-once delivery needs a `driver` on the bus: an event that must survive ' +
+                'a reload has to be written somewhere. Pass one, or emit at-most-once.');
+        }
+        const recipients = options.consumers?.length ? options.consumers : [options.consumer];
+        const ttl = channel.options.ttlMs ?? DEFAULT_TTL_MS;
+        const depth = channel.options.maxDepth ?? DEFAULT_MAX_DEPTH;
+        for (const consumer of recipients) {
+            const consumerQueue = createOutbox({
+                driver: options.driver,
+                owner: queueOwner(consumer),
+                partition: partition(),
+                collection: EVENT_COLLECTION,
+            });
+            await trim(consumerQueue, consumer, channel.key, ttl, depth);
+            await consumerQueue.enqueue({ mutationId: runnerId(event.channel, event.type), input: event });
+        }
+        // One tag for every consumer: the wake-up crosses realms and, with cross-context invalidation on,
+        // tabs — which is the whole reason a queued event reaches an application that was not running.
+        invalidator.invalidate(...recipients.map(wakeTag));
+    }
+    /**
+     * Enforces the retention bounds before adding to a queue.
+     *
+     * Both bounds are needed and both are reported. Fan-out retention is unbounded by nature —
+     * consumers × events × until-handled — so a queue with no policy is a storage quota that dies
+     * unattended, and one that drops silently is worse than one that fills up.
+     */
+    async function trim(consumerQueue, consumer, channelKey, ttlMs, maxDepth) {
+        // Scoped to this channel: one consumer's queue holds every channel's events, and a busy channel
+        // must not evict a quiet one's — least of all one entity's evicting another's.
+        const mine = (await consumerQueue.mine()).filter((entry) => entry.input.channel === channelKey);
+        const cutoff = Date.now() - ttlMs;
+        for (const entry of mine) {
+            const event = entry.input;
+            if (Date.parse(event.at) >= cutoff)
+                continue;
+            await consumerQueue.remove(entry.id);
+            options.onEventError?.(`[skew/data] dropped "${event.type}" for "${consumer}" — it sat in the queue past its ${ttlMs}ms window`, event);
+        }
+        const remaining = (await consumerQueue.mine()).filter((entry) => entry.input.channel === channelKey);
+        const excess = remaining.length + 1 - maxDepth;
+        for (const entry of remaining.slice(0, Math.max(0, excess))) {
+            await consumerQueue.remove(entry.id);
+            options.onEventError?.(`[skew/data] dropped "${entry.input.type}" for "${consumer}" — the queue is at its ${maxDepth} limit`, entry.input);
+        }
+    }
+    /**
+     * Drains this consumer's queue through `drainOutbox`.
+     *
+     * Everything about *how* a queue drains — one at a time across tabs, oldest first, stop at the
+     * first failure, abandon loudly after `maxAttempts` — is the same code that replays mutations. A
+     * second implementation of those rules would be a second set of bugs, and this package already
+     * paid for that lesson once.
+     */
+    /**
+     * Serializes this bus's own flushes, for the reason the data client had to.
+     *
+     * The cross-context lock declines a drain another context is already running, which is right —
+     * waiting would drain a queue that context has already emptied. Applied to *one* bus's overlapping
+     * calls that rule is a trap: an emit wakes us, the wake-up flush is still finishing, and the
+     * caller's own `flush()` reports `skipped` and quietly does nothing. Within one bus, a second
+     * flush waits for the first and then runs, picking up whatever arrived in between.
+     */
+    let flushing = null;
+    async function flush() {
+        if (flushing)
+            await flushing.catch(() => undefined);
+        const run = drain();
+        flushing = run;
+        try {
+            return await run;
+        }
+        finally {
+            if (flushing === run)
+                flushing = null;
+        }
+    }
+    async function drain() {
+        if (!queue)
+            return { sent: 0, failed: 0, remaining: 0, skipped: false };
+        return drainOutbox({
+            outbox: queue,
+            owner: queueOwner(options.consumer),
+            runnerFor: (mutationId) => {
+                const registered = handlers.get(mutationId);
+                if (!registered?.size)
+                    return undefined;
+                return async (input) => {
+                    const event = input;
+                    // Sequentially: handlers for one event type on one consumer are ordered by registration,
+                    // and a throwing handler must fail the entry so it is retried rather than lost.
+                    for (const handler of [...registered])
+                        await handler(event);
+                };
+            },
+            maxAttempts,
+            ...(options.onEventError === undefined ? {} : { onError: options.onEventError }),
+        });
+    }
+    const intents = createIntentRegistry({
+        consumer: options.consumer,
+        // Intents project through the same registered contracts state and events do, so an application
+        // declares a shape once and every path respects it.
+        schemaFor: (intent) => schemas.get(intent),
+        ...(options.onEventError === undefined ? {} : { onEventError: options.onEventError }),
+    });
+    // Woken by any context that queued something for us — including our own emit.
+    const stopWaking = invalidator.subscribe(() => [wakeTag(options.consumer)], () => void flush().catch(() => undefined));
+    return {
+        channel(name, channelOptions = {}) {
+            const channel = channelState(name, channelOptions);
+            return {
+                name,
+                broadcast(value) {
+                    applyState(channel, value, { local: true });
+                    channel.wire?.postMessage({ kind: 'state', value: channel.state });
+                },
+                state(readOptions) {
+                    return channel.state === undefined ? undefined : project(name, channel.state, readOptions?.as);
+                },
+                subscribe(listener, subscribeOptions) {
+                    const subscription = {
+                        listener: listener,
+                        ...(subscribeOptions?.as === undefined ? {} : { as: subscribeOptions.as }),
+                    };
+                    channel.stateListeners.add(subscription);
+                    // Called immediately with the current value: a fragment that mounts late still needs to
+                    // know what is true, which is the half of FDC3's broadcast that *is* state.
+                    if (channel.state !== undefined) {
+                        try {
+                            subscription.listener(project(name, channel.state, subscription.as));
+                        }
+                        catch (error) {
+                            options.onEventError?.(`[skew/data] a "${name}" state subscriber threw on subscribe`, error);
+                        }
+                    }
+                    const unsubscribe = () => void channel.stateListeners.delete(subscription);
+                    subscribeOptions?.signal?.addEventListener('abort', unsubscribe, { once: true });
+                    return unsubscribe;
+                },
+                async emit(type, payload, emitOptions) {
+                    const event = {
+                        eventId: crypto.randomUUID(),
+                        // The instance, not the logical name: a handler on fund f1 must not be handed f2's
+                        // event, and retention must not let one entity evict another's queue.
+                        channel: channel.key,
+                        type,
+                        payload,
+                        at: new Date().toISOString(),
+                        source: options.consumer,
+                    };
+                    if ((emitOptions?.delivery ?? 'at-most-once') === 'at-least-once') {
+                        await enqueue(event, channel);
+                        return;
+                    }
+                    deliverLive(event);
+                    channel.wire?.postMessage({ kind: 'event', event });
+                },
+                addEventListener(type, handler, subscribeOptions) {
+                    const id = runnerId(channel.key, type);
+                    let registered = handlers.get(id);
+                    if (!registered) {
+                        registered = new Set();
+                        handlers.set(id, registered);
+                    }
+                    const wrapped = async (event) => {
+                        await handler({
+                            ...event,
+                            payload: project(type, event.payload, subscribeOptions?.as),
+                        });
+                    };
+                    registered.add(wrapped);
+                    const unsubscribe = () => void registered.delete(wrapped);
+                    subscribeOptions?.signal?.addEventListener('abort', unsubscribe, { once: true });
+                    return unsubscribe;
+                },
+                conflict: () => channel.conflict,
+                acknowledgeConflict: () => void (channel.conflict = null),
+            };
+        },
+        register(type, schema) {
+            schemas.set(type, schema);
+        },
+        addIntentListener: intents.addIntentListener,
+        raiseIntent: intents.raiseIntent,
+        candidates: intents.candidates,
+        flush,
+        close() {
+            stopWaking();
+            for (const channel of channels.values())
+                channel.wire?.close();
+            channels.clear();
+            handlers.clear();
+            invalidator.close();
+        },
+    };
+}
+/** Which top-level keys two states disagree about. Same rule as a mutation's conflict. */
+function differingKeys(previous, next) {
+    const before = (previous ?? {});
+    const after = (next ?? {});
+    const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+    return [...keys].filter((key) => !same(before[key], after[key]));
+}
+function same(a, b) {
+    return a === b || JSON.stringify(a) === JSON.stringify(b);
+}
+//# sourceMappingURL=events.js.map

package/src/lib/events.js.map

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

package/src/lib/flush.d.ts

@@ -0,0 +1,49 @@
+import type { Outbox, QueuedEntry } from './outbox.js';
+/**
+ * Draining a queue: one implementation, used by the framework-neutral client and by every binding.
+ *
+ * This lived in two places once — here and in Angular's `OutboxService` — and the copies had already
+ * drifted apart on what to do with an entry nobody can replay. Ordering, locking, retry, and give-up
+ * are exactly the rules that must not have two answers, so they have one.
+ */
+export interface FlushResult {
+    sent: number;
+    failed: number;
+    /** Entries still queued when the drain stopped. */
+    remaining: number;
+    /** True when another context held the lock and this call did no work. */
+    skipped: boolean;
+}
+/** Replays one queued write. Receives the entry's stored input, never a closure. */
+export type MutationRunner = (input: unknown, entry: QueuedEntry) => Promise<unknown>;
+export interface DrainOptions {
+    outbox: Outbox;
+    /** Which application's queue this is. The flush lock is per owner. */
+    owner: string;
+    /** How this caller finds the runner for a mutation kind. */
+    runnerFor: (mutationId: string) => MutationRunner | undefined;
+    /** Attempts before an entry is abandoned. */
+    maxAttempts?: number;
+    /** Reports an entry that could not be replayed. Never silent. */
+    onError?: (message: string, detail?: unknown) => void;
+    /** Called after each successful send, so a caller can invalidate what the write touched. */
+    onSent?: (entry: QueuedEntry) => void;
+    /** Called after each abandoned entry, for the same reason. */
+    onAbandoned?: (entry: QueuedEntry) => void;
+}
+/**
+ * Drains one owner's queue, oldest first, under a lock held across tabs and realms.
+ *
+ * Four rules, each with a failure behind it:
+ *
+ * - **Strictly sequential.** Queued writes routinely depend on each other — create a thing, then
+ *   rename the thing — and replaying them in parallel races them into the wrong order.
+ * - **A failure stops the drain** rather than skipping ahead, for the same reason.
+ * - **A permanently failing entry is abandoned loudly.** The user navigated away believing it saved,
+ *   so its disappearance has to be reported to someone who can act on it.
+ * - **An entry with no runner is kept, not dropped.** It means the app did not re-register that
+ *   mutation kind at start-up, or renamed it between deploys — and dropping it discards a write the
+ *   user was told had succeeded. Keeping it means a later build (or a rollback) can still send it,
+ *   and `outbox.remove` is there for an operator who decides otherwise.
+ */
+export declare function drainOutbox(options: DrainOptions): Promise<FlushResult>;

package/src/lib/flush.js

@@ -0,0 +1,60 @@
+import { outboxFlushLock, withLock } from './locks.js';
+/**
+ * Drains one owner's queue, oldest first, under a lock held across tabs and realms.
+ *
+ * Four rules, each with a failure behind it:
+ *
+ * - **Strictly sequential.** Queued writes routinely depend on each other — create a thing, then
+ *   rename the thing — and replaying them in parallel races them into the wrong order.
+ * - **A failure stops the drain** rather than skipping ahead, for the same reason.
+ * - **A permanently failing entry is abandoned loudly.** The user navigated away believing it saved,
+ *   so its disappearance has to be reported to someone who can act on it.
+ * - **An entry with no runner is kept, not dropped.** It means the app did not re-register that
+ *   mutation kind at start-up, or renamed it between deploys — and dropping it discards a write the
+ *   user was told had succeeded. Keeping it means a later build (or a rollback) can still send it,
+ *   and `outbox.remove` is there for an operator who decides otherwise.
+ */
+export async function drainOutbox(options) {
+    const maxAttempts = options.maxAttempts ?? 5;
+    // Declined rather than queued: a flush waiting behind another tab's would run against a queue that
+    // tab had already drained. Per owner, so an unrelated application's disjoint queue does not wait.
+    const outcome = await withLock(outboxFlushLock(options.owner), async () => {
+        let sent = 0;
+        let failed = 0;
+        // Snapshot: entries queued mid-drain wait for the next pass.
+        for (const entry of await options.outbox.mine()) {
+            const runner = options.runnerFor(entry.mutationId);
+            if (!runner) {
+                options.onError?.(`[skew/data] no registered mutation for "${entry.mutationId}" — the entry stays queued. ` +
+                    'Register this mutation kind during start-up so a queue rehydrated from storage has ' +
+                    'somewhere to go.', entry);
+                failed += 1;
+                break;
+            }
+            try {
+                await runner(entry.input, entry);
+                await options.outbox.remove(entry.id);
+                options.onSent?.(entry);
+                sent += 1;
+            }
+            catch (error) {
+                failed += 1;
+                const message = error instanceof Error ? error.message : String(error);
+                const attempts = await options.outbox.recordFailure(entry.id, message);
+                if (attempts >= maxAttempts) {
+                    options.onError?.(`[skew/data] giving up on "${entry.mutationId}" after ${attempts} attempts`, error);
+                    await options.outbox.remove(entry.id);
+                    options.onAbandoned?.(entry);
+                }
+                break;
+            }
+        }
+        return { sent, failed, remaining: (await options.outbox.mine()).length };
+    });
+    return outcome.acquired
+        ? { ...outcome.value, skipped: false }
+        : // Reported rather than folded into `sent: 0`, which also happens when a drain ran and
+            // everything failed — conflating them makes a dead server look like a busy tab.
+            { sent: 0, failed: 0, remaining: (await options.outbox.mine()).length, skipped: true };
+}
+//# sourceMappingURL=flush.js.map

package/src/lib/flush.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flush.js","sourceRoot":"","sources":["../../../../../libs/data/src/lib/flush.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAuCvD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAAqB;IACrD,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,CAAC,CAAC;IAE7C,mGAAmG;IACnG,kGAAkG;IAClG,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,eAAe,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,KAAK,IAAI,EAAE;QACxE,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,IAAI,MAAM,GAAG,CAAC,CAAC;QAEf,6DAA6D;QAC7D,KAAK,MAAM,KAAK,IAAI,MAAM,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;YAChD,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YAEnD,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,OAAO,CAAC,OAAO,EAAE,CACf,2CAA2C,KAAK,CAAC,UAAU,8BAA8B;oBACvF,qFAAqF;oBACrF,kBAAkB,EACpB,KAAK,CACN,CAAC;gBACF,MAAM,IAAI,CAAC,CAAC;gBACZ,MAAM;YACR,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;gBACjC,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBACtC,OAAO,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;gBACxB,IAAI,IAAI,CAAC,CAAC;YACZ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,IAAI,CAAC,CAAC;gBACZ,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACvE,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;gBAEvE,IAAI,QAAQ,IAAI,WAAW,EAAE,CAAC;oBAC5B,OAAO,CAAC,OAAO,EAAE,CAAC,6BAA6B,KAAK,CAAC,UAAU,WAAW,QAAQ,WAAW,EAAE,KAAK,CAAC,CAAC;oBACtG,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;oBACtC,OAAO,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC;gBAC/B,CAAC;gBACD,MAAM;YACR,CAAC;QACH,CAAC;QAED,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;IAC3E,CAAC,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC,QAAQ;QACrB,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE;QACtC,CAAC,CAAC,sFAAsF;YACtF,gFAAgF;YAChF,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC7F,CAAC"}

package/src/lib/indexeddb-driver.d.ts

@@ -0,0 +1,29 @@
+import type { RecordDriver } from './record-store.js';
+export interface IndexedDbDriverOptions {
+    /** Database name. One per application is normal; collections are object stores within it. */
+    database?: string;
+    /** Collections to create. IndexedDB can only create stores during a version upgrade. */
+    collections: readonly string[];
+    /** Injectable for tests. */
+    indexedDB?: IDBFactory;
+    /**
+     * Injectable for tests, alongside `indexedDB`.
+     *
+     * Both are needed to substitute the implementation: `IDBKeyRange` is a separate global rather than
+     * something reachable from the factory, so injecting only the factory leaves the range queries
+     * reaching for whatever the environment happens to have — which is nothing, outside a browser.
+     */
+    keyRange?: typeof IDBKeyRange;
+}
+/**
+ * IndexedDB, as the source of truth.
+ *
+ * Why this rather than a KV shim over the same database: every operation below is **one
+ * transaction over one record**. There is no read-modify-write anywhere, so two realms or two tabs
+ * writing concurrently cannot lose each other's work — which a `get`-then-`set` shim absolutely can,
+ * whatever storage sits underneath it.
+ *
+ * The `[partition, seq]` compound index is what makes `list` a range scan rather than a full read
+ * plus filter, and it is why partitions stay cheap as the store grows.
+ */
+export declare function indexedDbRecordDriver(options: IndexedDbDriverOptions): RecordDriver;