zerodrift 1.0.0

package/dist/core/BatchModelLoader.js

@@ -0,0 +1,70 @@
+/**
+ * Coalesces concurrent on-demand index queries into a single server call.
+ * Used by `StoreManager.getOrLoadCollection` when an `onDemandIndexBatchFetcher`
+ * is configured; otherwise the per-triple `onDemandFetcher` runs directly.
+ */
+function queryKey(q) {
+    return `${q.modelName}:${q.indexKey}:${q.value}`;
+}
+export class BatchModelLoader {
+    constructor(fetcher) {
+        this.pending = [];
+        this.flushScheduled = false;
+        this.disposed = false;
+        this.fetcher = fetcher;
+    }
+    /**
+     * Schedule `query` for the next batch. The returned promise resolves with
+     * the records matching this specific triple (filtered from the per-model
+     * bag the server returns).
+     */
+    load(query) {
+        return new Promise((resolve, reject) => {
+            if (this.disposed) {
+                reject(new Error("BatchModelLoader disposed"));
+                return;
+            }
+            this.pending.push({ query, resolve, reject });
+            if (!this.flushScheduled) {
+                this.flushScheduled = true;
+                queueMicrotask(() => this.flush());
+            }
+        });
+    }
+    /** Reject any unflushed waiters. Called from `StoreManager.teardown`. */
+    dispose() {
+        this.disposed = true;
+        const stale = this.pending;
+        this.pending = [];
+        for (const req of stale) {
+            req.reject(new Error("BatchModelLoader disposed"));
+        }
+    }
+    async flush() {
+        if (this.disposed) {
+            return;
+        }
+        const batch = this.pending;
+        this.pending = [];
+        this.flushScheduled = false;
+        // Dedupe identical triples — every waiter for the same triple shares one
+        // server call.
+        const uniqueByKey = new Map();
+        for (const req of batch) {
+            uniqueByKey.set(queryKey(req.query), req.query);
+        }
+        const unique = [...uniqueByKey.values()];
+        try {
+            const results = await this.fetcher(unique);
+            for (const req of batch) {
+                const bag = results[req.query.modelName] ?? [];
+                req.resolve(bag.filter((r) => r[req.query.indexKey] === req.query.value));
+            }
+        }
+        catch (err) {
+            for (const req of batch) {
+                req.reject(err);
+            }
+        }
+    }
+}

package/dist/core/CompoundIndexFetcher.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Compound index-key collapse — when an adopter has flagged
+ * `serverSupportsCompoundIndexKeys: true`, this wrapper inspects each
+ * batched fetch and replaces N per-parent queries with one server-side
+ * compound (joined) query whenever ≥ COMPOUND_FETCH_THRESHOLD requests
+ * share a parent FK value.
+ *
+ * Example: 50 concurrent `Comment[issueId=Ix]` requests where every Issue
+ * is in cycle X collapses to one `Comment[issueId.cycleId=X]` request.
+ * The server resolves the dotted path via a join and returns the union;
+ * `BatchModelLoader.flush` already filters each waiter's bag by direct FK
+ * match (`record["issueId"] === Ix`), so callers see exactly their slice.
+ *
+ * Adopters without server JOIN support leave the flag unset; the engine
+ * fans out per-parent (existing behavior).
+ */
+import type { IndexBatchFetcher, IndexQuery } from "./BatchModelLoader";
+import { type ObjectPool } from "./ObjectPool";
+/** Switch to a compound fetch only when at least this many pending
+ * requests share a single parent FK value. Below this, the per-parent
+ * fan-out wins because the compound response would over-fetch. */
+export declare const COMPOUND_FETCH_THRESHOLD = 5;
+/**
+ * Wrap an `IndexBatchFetcher` so it transparently collapses sharable
+ * batches into compound queries before invoking `inner`. The returned
+ * fetcher has the same shape — `BatchModelLoader` doesn't know whether
+ * collapse happened.
+ *
+ * `onCompoundFetched` (optional) fires once per synthetic compound query
+ * after `inner` resolves successfully, with the per-model response bag.
+ * Used by `StoreManager` to (a) write the full bag to IDB so future
+ * direct lookups inside the compound's coverage area find their records,
+ * and (b) record the compound key in `partialIndexCoverage` so
+ * derive-on-read can short-circuit subsequent direct loads.
+ */
+export declare function wrapCompoundFetcher(inner: IndexBatchFetcher, pool: ObjectPool, options?: {
+    threshold?: number;
+    onCompoundFetched?: (compound: IndexQuery, bagForModel: Record<string, unknown>[]) => void | Promise<void>;
+}): IndexBatchFetcher;
+/**
+ * Group `queries` by `(modelName, indexKey)` and within each group, look
+ * up the parent in the pool and find a parent FK whose value is shared by
+ * ≥ threshold members. Replace the sharing subset with one compound
+ * query; non-sharing members stay direct. Returns the rewritten list.
+ */
+export declare function collapseQueries(queries: IndexQuery[], pool: ObjectPool, threshold?: number): IndexQuery[];

package/dist/core/CompoundIndexFetcher.js

@@ -0,0 +1,177 @@
+/**
+ * Compound index-key collapse — when an adopter has flagged
+ * `serverSupportsCompoundIndexKeys: true`, this wrapper inspects each
+ * batched fetch and replaces N per-parent queries with one server-side
+ * compound (joined) query whenever ≥ COMPOUND_FETCH_THRESHOLD requests
+ * share a parent FK value.
+ *
+ * Example: 50 concurrent `Comment[issueId=Ix]` requests where every Issue
+ * is in cycle X collapses to one `Comment[issueId.cycleId=X]` request.
+ * The server resolves the dotted path via a join and returns the union;
+ * `BatchModelLoader.flush` already filters each waiter's bag by direct FK
+ * match (`record["issueId"] === Ix`), so callers see exactly their slice.
+ *
+ * Adopters without server JOIN support leave the flag unset; the engine
+ * fans out per-parent (existing behavior).
+ */
+import { ModelRegistry } from "./ModelRegistry";
+import { readFk } from "./ObjectPool";
+import { PropertyType } from "./types";
+/** Switch to a compound fetch only when at least this many pending
+ * requests share a single parent FK value. Below this, the per-parent
+ * fan-out wins because the compound response would over-fetch. */
+export const COMPOUND_FETCH_THRESHOLD = 5;
+/**
+ * Wrap an `IndexBatchFetcher` so it transparently collapses sharable
+ * batches into compound queries before invoking `inner`. The returned
+ * fetcher has the same shape — `BatchModelLoader` doesn't know whether
+ * collapse happened.
+ *
+ * `onCompoundFetched` (optional) fires once per synthetic compound query
+ * after `inner` resolves successfully, with the per-model response bag.
+ * Used by `StoreManager` to (a) write the full bag to IDB so future
+ * direct lookups inside the compound's coverage area find their records,
+ * and (b) record the compound key in `partialIndexCoverage` so
+ * derive-on-read can short-circuit subsequent direct loads.
+ */
+export function wrapCompoundFetcher(inner, pool, options = {}) {
+    const threshold = options.threshold ?? COMPOUND_FETCH_THRESHOLD;
+    return async (queries) => {
+        const collapsed = collapseQueries(queries, pool, threshold);
+        const result = await inner(collapsed);
+        if (options.onCompoundFetched != null) {
+            // A compound query is the synthetic kind we added during collapse —
+            // it has a dotted `indexKey`. (Adopters never originate dotted-path
+            // queries themselves; only this collapser does.)
+            for (const q of collapsed) {
+                if (q.indexKey.includes(".")) {
+                    await options.onCompoundFetched(q, result[q.modelName] ?? []);
+                }
+            }
+        }
+        return result;
+    };
+}
+/**
+ * Group `queries` by `(modelName, indexKey)` and within each group, look
+ * up the parent in the pool and find a parent FK whose value is shared by
+ * ≥ threshold members. Replace the sharing subset with one compound
+ * query; non-sharing members stay direct. Returns the rewritten list.
+ */
+export function collapseQueries(queries, pool, threshold = COMPOUND_FETCH_THRESHOLD) {
+    // Early exit: no group can exceed the total query count, so when the
+    // whole batch is below threshold there's nothing collapsible. (A mixed
+    // batch like 4 + 6 still proceeds — total ≥ threshold; the per-bucket
+    // check below handles the small group.)
+    if (queries.length < threshold) {
+        return queries;
+    }
+    const out = [];
+    const groups = new Map();
+    for (const q of queries) {
+        const key = `${q.modelName}|${q.indexKey}`;
+        let bucket = groups.get(key);
+        if (bucket == null) {
+            bucket = [];
+            groups.set(key, bucket);
+        }
+        bucket.push(q);
+    }
+    for (const bucket of groups.values()) {
+        if (bucket.length < threshold) {
+            out.push(...bucket);
+            continue;
+        }
+        const rewritten = collapseGroup(bucket, pool, threshold);
+        out.push(...rewritten);
+    }
+    return out;
+}
+/** A bucket of `IndexQuery`s sharing `(modelName, indexKey)`. Find a
+ * parent FK whose value is shared by ≥ threshold; emit one compound
+ * query for that subset. Stragglers stay direct.
+ *
+ * NOTE: only walks one hop on the parent (e.g., Task → projectId). A
+ * future revision could recurse to match Phase A's depth-3 walk
+ * (Task → projectId → Project → workspaceId), enabling
+ * `Comment[taskId.projectId.workspaceId=W]`. The dotted-path API on the
+ * server already supports this; the rewrite logic here would need to
+ * compose the path. If you change the depth here, also update
+ * `StoreManager.isCoveredByCompound` — its derive-on-read walks the
+ * same depth and must stay in sync, otherwise reads silently miss
+ * coverage that the rewriter is now emitting. */
+function collapseGroup(bucket, pool, threshold) {
+    const sample = bucket[0];
+    // Resolve the parent model for this FK: child[indexKey] → Reference to which model?
+    const childMeta = ModelRegistry.getModelMeta(sample.modelName);
+    const fkProp = childMeta?.properties.get(sample.indexKey);
+    if (fkProp?.type !== PropertyType.Reference || fkProp.referenceTo == null) {
+        return bucket;
+    }
+    const parentModelName = fkProp.referenceTo;
+    const parentMeta = ModelRegistry.getModelMeta(parentModelName);
+    if (parentMeta == null) {
+        return bucket;
+    }
+    // Collect each parent's outgoing FK values (one hop). For each
+    // (fkName, value) pair, count how many members of the bucket share it.
+    // Members whose parent is missing from the pool can't contribute.
+    const fkCandidates = [];
+    for (const prop of parentMeta.properties.values()) {
+        if (prop.type === PropertyType.Reference && prop.referenceTo != null) {
+            fkCandidates.push(prop.name);
+        }
+    }
+    if (fkCandidates.length === 0) {
+        return bucket;
+    }
+    const sharing = new Map();
+    for (const q of bucket) {
+        const parent = pool.getById(parentModelName, q.value);
+        if (parent == null) {
+            continue;
+        }
+        for (const fk of fkCandidates) {
+            const v = readFk(parent, fk);
+            if (v == null) {
+                continue;
+            }
+            const key = `${fk}=${v}`;
+            let entry = sharing.get(key);
+            if (entry == null) {
+                entry = { fk, value: v, members: [] };
+                sharing.set(key, entry);
+            }
+            entry.members.push(q);
+        }
+    }
+    // Pick the largest sharing set ≥ threshold. Single-pass max — ties go to
+    // first-seen, which is stable enough; no need to optimize.
+    let best = null;
+    for (const entry of sharing.values()) {
+        if (entry.members.length < threshold) {
+            continue;
+        }
+        if (best == null || entry.members.length > best.members.length) {
+            best = entry;
+        }
+    }
+    if (best == null) {
+        return bucket;
+    }
+    // Emit one compound query + every non-member as direct.
+    const collapsed = [
+        {
+            modelName: sample.modelName,
+            indexKey: `${sample.indexKey}.${best.fk}`,
+            value: best.value,
+        },
+    ];
+    const memberSet = new Set(best.members);
+    for (const q of bucket) {
+        if (!memberSet.has(q)) {
+            collapsed.push(q);
+        }
+    }
+    return collapsed;
+}

package/dist/core/Database.d.ts

@@ -0,0 +1,303 @@
+/**
+ * Database — wraps IndexedDB for a single workspace.
+ *
+ * Schema Migration:
+ *   Instead of falling back to full bootstrap on every schemaHash change,
+ *   we run actual IDB migrations:
+ *     1. Open the DB at its current version to read meta
+ *     2. If schemaHash matches → use as-is
+ *     3. If schemaHash differs → close, reopen at version+1
+ *     4. In onupgradeneeded: add new stores, remove old stores, update indexes
+ *   This preserves existing data for unchanged models.
+ *
+ * Determines bootstrap type:
+ *   - Full: no DB or meta, or a critical migration that can't be handled
+ *   - Partial: DB exists with valid data, just need delta since lastSyncId
+ *   - Local: DB exists, no server contact needed (offline start)
+ */
+export interface DatabaseMeta {
+    lastSyncId: number;
+    subscribedSyncGroups: string[];
+    schemaHash: string;
+    /** IDB version number. Incremented on each client-side schema migration. */
+    dbVersion: number;
+    /**
+     * Server-side schema version. The server sends this with every bootstrap response.
+     * If the server's version changes (e.g. renamed columns, restructured models),
+     * the client detects the mismatch and forces a full bootstrap to avoid
+     * interpreting data against the wrong schema.
+     */
+    backendDatabaseVersion: number;
+    /**
+     * Per-model `schemaVersion` snapshot at the time meta was last persisted.
+     * Adapters compare this map against the current ModelRegistry on connect
+     * and clear any model whose version bumped — stale rows in IDB serialized
+     * against the old shape get wiped so the next bootstrap re-fetches them.
+     * Filled in by the adapter; callers don't need to populate it.
+     */
+    modelSchemaVersions?: Record<string, number>;
+}
+export declare enum BootstrapType {
+    Full = "full",
+    Partial = "partial",
+    Local = "local"
+}
+/**
+ * One recorded `getOrLoadCollection(modelName, indexKey, value)` query, captured
+ * with the `lastSyncId` at the time of fetch. Adopters ship these to the
+ * server on partial fetches so it can return only deltas since `firstSyncId`.
+ */
+export interface PartialIndexEntry {
+    modelName: string;
+    indexKey: string;
+    value: string;
+    firstSyncId: number;
+}
+/** A header for a server-confirmed sync action — persisted in the
+ * `__syncActions` store so crash-recovery can decide whether the awaited
+ * delta has already arrived (and whether a pending tx's target was
+ * deleted while the client was away). */
+export interface SyncActionHeader {
+    syncId: number;
+    modelName: string;
+    modelId: string;
+    action: "I" | "U" | "D" | "A" | "V" | "C";
+}
+/** Snapshot of every registered model's current `schemaVersion`. */
+export declare function currentModelVersions(): Record<string, number>;
+/**
+ * Diff stored vs current per-model schemaVersions. `cleared` lists models
+ * whose version bumped (rows + partial-index coverage wiped) and models
+ * removed from the registry (coverage wiped). `newlyAdded` lists models
+ * present in the registry but missing from a non-empty `stored` snapshot —
+ * the caller targets these in a follow-up full-bootstrap call.
+ */
+export declare function diffModelVersions(adapter: Pick<StorageAdapter, "clearModelStore" | "clearPartialIndexesForModel">, stored: Record<string, number> | undefined): Promise<{
+    cleared: string[];
+    newlyAdded: string[];
+}>;
+/**
+ * Tracks which models have at least one row in storage and notifies
+ * listeners on add/remove transitions. Composed by both `Database` and
+ * `MemoryAdapter` (the trio of mark/unmark/onChange + listener Set is
+ * adapter-agnostic, so the duplication doesn't have to live in each).
+ */
+export declare class LoadedModelsTracker {
+    private set;
+    private listeners;
+    get loadedModels(): ReadonlySet<string>;
+    /** Mark a model as having data. Notifies listeners on the first add. */
+    markLoaded(modelName: string): void;
+    /** Mark a model as empty (e.g. after `clearModelStore`). */
+    markUnloaded(modelName: string): void;
+    /** Empty the tracker without firing listeners — used at the start of
+     * `connect()` before re-seeding. */
+    reset(): void;
+    /** Seed without notifying — used by `connect()` to populate from storage. */
+    seed(modelName: string): void;
+    onChange(cb: () => void): () => void;
+    private notify;
+}
+/**
+ * Pluggable storage backend for the sync engine.
+ *
+ * The default implementation (`Database`) uses IndexedDB and is suited for
+ * browsers. Implement this interface to use a different backend — e.g.
+ * `MemoryAdapter` for Node.js agents, or a custom SQLite/Redis adapter for
+ * server-side environments that need durable off-heap storage.
+ */
+export interface StorageAdapter {
+    /** Open / initialise the storage backend. Called once before bootstrap. */
+    connect(): Promise<void>;
+    loadMeta(): Promise<DatabaseMeta | null>;
+    saveMeta(meta: DatabaseMeta): Promise<void>;
+    get currentMeta(): DatabaseMeta | null;
+    determineBootstrapType(): Promise<BootstrapType>;
+    /**
+     * Names of models present in the live registry but missing from the
+     * persisted `modelSchemaVersions` snapshot — i.e., new since the last
+     * connect. Populated during `connect()`. StoreManager runs a targeted
+     * full fetch for just these so adopters don't need to bump anything.
+     */
+    readonly newlyAddedModels: string[];
+    /**
+     * Names of models with at least one row in local storage. Seeded on
+     * `connect()` and grown as `writeModels` / `writeModelsIfAbsent` write
+     * records; shrinks when a store is fully cleared. The SSE catchup URL
+     * passes this set as `onlyModels` so the server skips deltas for models
+     * the client never touched.
+     */
+    readonly loadedModels: ReadonlySet<string>;
+    /** Subscribe to add/remove transitions on `loadedModels`. Returns an
+     * unsubscribe function. Per-row deletes don't fire — only first writes
+     * to a model and full clears do. */
+    onLoadedModelsChange(cb: () => void): () => void;
+    /** Mark a model as loaded even when no rows were written — e.g.
+     * `getOrLoadCollection` returned an empty server response, which still
+     * expresses "we want SSE deltas for this model". `writeModels` already
+     * covers the non-empty case; this is the path for empty-but-successful
+     * fetches. */
+    markModelLoaded(modelName: string): void;
+    writeModels(modelName: string, records: Record<string, unknown>[]): Promise<void>;
+    writeModelsIfAbsent(modelName: string, records: Record<string, unknown>[]): Promise<void>;
+    readAllModels(modelName: string): Promise<Record<string, unknown>[]>;
+    readModel(modelName: string, id: string): Promise<Record<string, unknown> | null>;
+    readModelsByIndex(modelName: string, indexName: string, value: string): Promise<Record<string, unknown>[]>;
+    deleteModel(modelName: string, id: string): Promise<void>;
+    deleteModels(modelName: string, ids: string[]): Promise<void>;
+    /** Delete all records matching indexName === value in a single IDB pass. */
+    deleteModelsByIndex(modelName: string, indexName: string, value: string): Promise<void>;
+    clearModelStore(modelName: string): Promise<void>;
+    cacheTransaction(data: unknown): Promise<number | null>;
+    /**
+     * Update an existing cached transaction by `idbKey`. Used to flag a
+     * transaction as awaiting a specific syncId (server-ack'd, waiting for the
+     * matching SSE delta). On crash, recovery checks the SyncAction store to
+     * decide whether the awaited delta already arrived.
+     */
+    updateCachedTransaction(idbKey: number, data: unknown): Promise<void>;
+    /** Returns `(idbKey, data)` pairs so recovery can selectively delete
+     * resolved entries without clearing the whole store. */
+    getCachedTransactions(): Promise<{
+        idbKey: number;
+        data: unknown;
+    }[]>;
+    deleteCachedTransactions(keys: number[]): Promise<void>;
+    clearCachedTransactions(): Promise<void>;
+    /**
+     * Persist headers for received SSE sync actions. Crash-recovery checks this
+     * store to (a) recognize transactions whose ack-syncId already arrived,
+     * (b) detect that a pending tx's target was deleted before the queue could
+     * flush. Headers only — `data` is not stored, since the model state is
+     * already durable in its own store.
+     */
+    recordSyncActions(actions: SyncActionHeader[]): Promise<void>;
+    hasSyncAction(syncId: number): Promise<boolean>;
+    findSyncActionsForModel(modelName: string, modelId: string): Promise<{
+        syncId: number;
+        action: string;
+    }[]>;
+    /** Drop sync actions older than `belowSyncId`. Called periodically to bound storage. */
+    pruneSyncActionsBelow(belowSyncId: number): Promise<void>;
+    /**
+     * Record that a `getOrLoadCollection(modelName, indexKey, value)` query has been
+     * fetched in full as of `firstSyncId`. Survives reload — on the next
+     * bootstrap the engine knows which scoped queries are already covered
+     * locally (and as of which point in the sync log) and can request a
+     * targeted delta instead of a full re-fetch.
+     */
+    recordPartialIndex(modelName: string, indexKey: string, value: string, firstSyncId: number): Promise<void>;
+    /** Clear coverage for a single (modelName, indexKey, value) tuple. */
+    clearPartialIndex(modelName: string, indexKey: string, value: string): Promise<void>;
+    /** Clear all coverage entries for a given model — used by schema migrations. */
+    clearPartialIndexesForModel(modelName: string): Promise<void>;
+    /** Read every recorded partial index. Called once at connect to populate the in-memory cache. */
+    loadPartialIndexes(): Promise<PartialIndexEntry[]>;
+    /**
+     * Close the storage connection without deleting any data.
+     * Called by StoreManager.teardown() during React unmount / cleanup.
+     * Data is preserved for the next page load (enables faster partial bootstrap).
+     */
+    close(): Promise<void>;
+    /**
+     * Close the connection AND permanently delete all persisted data.
+     * Use for explicit logout / factory-reset flows — NOT for routine teardown.
+     */
+    destroy(): Promise<void>;
+    get isConnected(): boolean;
+}
+export declare class Database implements StorageAdapter {
+    private db;
+    private workspaceId;
+    private meta;
+    newlyAddedModels: string[];
+    /** Set to true if connect() cleared rows for one or more models because
+     * their per-model `schemaVersion` bumped. Forces a Full bootstrap so the
+     * cleared rows refill from the server. */
+    migrationClearedModels: boolean;
+    private loadedTracker;
+    get loadedModels(): ReadonlySet<string>;
+    onLoadedModelsChange(cb: () => void): () => void;
+    markModelLoaded(modelName: string): void;
+    constructor(workspaceId: string);
+    connect(): Promise<void>;
+    /** One IDB count() per store to seed `loadedModels` with anything that
+     * survived from a prior session. Runs once per connect. */
+    private seedLoadedModels;
+    /**
+     * IDB blocks schema upgrades and deletions until all open connections close.
+     * onversionchange is the browser's signal to us: "another tab needs you to
+     * let go." Close immediately so the other tab's open/deleteDatabase call
+     * can proceed.
+     */
+    private attachVersionChangeHandler;
+    /** Open DB at its current version (no migration). */
+    private openDB;
+    /** Open DB at a specific version, triggering migration in onupgradeneeded. */
+    private openDBWithMigration;
+    /** Create the engine's reserved stores (`__`-prefixed) if they don't yet
+     * exist. Called from both first-time creation and incremental migration —
+     * adding a new system store means one entry here, not two. */
+    private ensureSystemStores;
+    /** Create all stores from scratch (first-time DB creation). */
+    private createAllStores;
+    /** Run an incremental migration: add/remove/update stores. */
+    private migrateSchema;
+    /** Create an object store for a model with its indexed properties. */
+    private createModelStore;
+    /** Add/remove indexes on an existing store to match current ModelRegistry. */
+    private migrateIndexes;
+    determineBootstrapType(): Promise<BootstrapType>;
+    loadMeta(): Promise<DatabaseMeta | null>;
+    saveMeta(meta: DatabaseMeta): Promise<void>;
+    get currentMeta(): DatabaseMeta | null;
+    writeModels(modelName: string, records: Record<string, unknown>[]): Promise<void>;
+    writeModelsIfAbsent(modelName: string, records: Record<string, unknown>[]): Promise<void>;
+    readAllModels(modelName: string): Promise<Record<string, unknown>[]>;
+    readModel(modelName: string, id: string): Promise<Record<string, unknown> | null>;
+    readModelsByIndex(modelName: string, indexName: string, value: string): Promise<Record<string, unknown>[]>;
+    deleteModel(modelName: string, id: string): Promise<void>;
+    /** Delete multiple records in a single IDB transaction. */
+    deleteModels(modelName: string, ids: string[]): Promise<void>;
+    deleteModelsByIndex(modelName: string, indexName: string, value: string): Promise<void>;
+    clearModelStore(modelName: string): Promise<void>;
+    /**
+     * Open a `__transactions` transaction, tolerating the brief window where
+     * the connection is closing but not yet nulled — a cross-tab `versionchange`
+     * upgrade, or teardown racing an SSE reconnect. In that window `this.db` is
+     * still non-null yet `.transaction()` throws `InvalidStateError` ("the
+     * database connection is closing"). Returns `null` so callers degrade
+     * gracefully: the transaction cache is a best-effort resend buffer that
+     * self-heals on the next clean connection.
+     */
+    private openTxCacheTx;
+    cacheTransaction(data: unknown): Promise<number | null>;
+    getCachedTransactions(): Promise<{
+        idbKey: number;
+        data: unknown;
+    }[]>;
+    deleteCachedTransactions(idbKeys: number[]): Promise<void>;
+    clearCachedTransactions(): Promise<void>;
+    updateCachedTransaction(idbKey: number, data: unknown): Promise<void>;
+    recordSyncActions(actions: SyncActionHeader[]): Promise<void>;
+    hasSyncAction(syncId: number): Promise<boolean>;
+    findSyncActionsForModel(modelName: string, modelId: string): Promise<{
+        syncId: number;
+        action: string;
+    }[]>;
+    pruneSyncActionsBelow(belowSyncId: number): Promise<void>;
+    recordPartialIndex(modelName: string, indexKey: string, value: string, firstSyncId: number): Promise<void>;
+    clearPartialIndex(modelName: string, indexKey: string, value: string): Promise<void>;
+    clearPartialIndexesForModel(modelName: string): Promise<void>;
+    loadPartialIndexes(): Promise<PartialIndexEntry[]>;
+    /** Close the IDB connection without deleting any data. */
+    close(): Promise<void>;
+    /** Close the connection AND delete all persisted data for this workspace. */
+    destroy(): Promise<void>;
+    get isConnected(): boolean;
+    private hasStore;
+    private idbGet;
+    private idbGetAll;
+    private idbPut;
+    private waitForTransaction;
+}