zerodrift 1.0.0

package/dist/core/Database.js

@@ -0,0 +1,837 @@
+/**
+ * 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)
+ */
+import { ModelRegistry } from "./ModelRegistry";
+export var BootstrapType;
+(function (BootstrapType) {
+    BootstrapType["Full"] = "full";
+    BootstrapType["Partial"] = "partial";
+    BootstrapType["Local"] = "local";
+})(BootstrapType || (BootstrapType = {}));
+/** Snapshot of every registered model's current `schemaVersion`. */
+export function currentModelVersions() {
+    const out = {};
+    for (const meta of ModelRegistry.allModels()) {
+        out[meta.name] = meta.schemaVersion;
+    }
+    return out;
+}
+/**
+ * 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 async function diffModelVersions(adapter, stored) {
+    const cleared = [];
+    const newlyAdded = [];
+    const current = currentModelVersions();
+    const storedMap = stored ?? {};
+    const knownStored = Object.keys(storedMap).length > 0;
+    for (const [name, version] of Object.entries(current)) {
+        const previous = storedMap[name];
+        if (previous == null) {
+            // No record for this model. Treat as "newly added" only when the
+            // adopter has previously persisted some versions (i.e. they upgraded
+            // the engine *and* added a model). Otherwise it's a legacy meta and we
+            // trust the existing rows.
+            if (knownStored) {
+                newlyAdded.push(name);
+            }
+            continue;
+        }
+        if (previous === version) {
+            continue;
+        }
+        await adapter.clearModelStore(name);
+        await adapter.clearPartialIndexesForModel(name);
+        cleared.push(name);
+    }
+    // Models removed from the registry: clear leftover partial-index rows so
+    // the `__partialIndexes` store doesn't accumulate orphans. (The model's
+    // own object store is already deleted by the IDB schema migration.)
+    for (const name of Object.keys(storedMap)) {
+        if (!(name in current)) {
+            await adapter.clearPartialIndexesForModel(name);
+            cleared.push(name);
+        }
+    }
+    return { cleared, newlyAdded };
+}
+/**
+ * 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 class LoadedModelsTracker {
+    constructor() {
+        this.set = new Set();
+        this.listeners = new Set();
+    }
+    get loadedModels() {
+        return this.set;
+    }
+    /** Mark a model as having data. Notifies listeners on the first add. */
+    markLoaded(modelName) {
+        if (this.set.has(modelName)) {
+            return;
+        }
+        this.set.add(modelName);
+        this.notify();
+    }
+    /** Mark a model as empty (e.g. after `clearModelStore`). */
+    markUnloaded(modelName) {
+        if (!this.set.has(modelName)) {
+            return;
+        }
+        this.set.delete(modelName);
+        this.notify();
+    }
+    /** Empty the tracker without firing listeners — used at the start of
+     * `connect()` before re-seeding. */
+    reset() {
+        this.set.clear();
+    }
+    /** Seed without notifying — used by `connect()` to populate from storage. */
+    seed(modelName) {
+        this.set.add(modelName);
+    }
+    onChange(cb) {
+        this.listeners.add(cb);
+        return () => this.listeners.delete(cb);
+    }
+    notify() {
+        for (const cb of this.listeners) {
+            try {
+                cb();
+            }
+            catch {
+                // A misbehaving listener mustn't reject the write that triggered it.
+            }
+        }
+    }
+}
+export class Database {
+    get loadedModels() {
+        return this.loadedTracker.loadedModels;
+    }
+    onLoadedModelsChange(cb) {
+        return this.loadedTracker.onChange(cb);
+    }
+    markModelLoaded(modelName) {
+        this.loadedTracker.markLoaded(modelName);
+    }
+    constructor(workspaceId) {
+        this.db = null;
+        this.meta = null;
+        this.newlyAddedModels = [];
+        /** 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. */
+        this.migrationClearedModels = false;
+        this.loadedTracker = new LoadedModelsTracker();
+        this.workspaceId = workspaceId;
+    }
+    // =========================================================================
+    // Connection with schema migration
+    // =========================================================================
+    async connect() {
+        // Reset per-connect flags so reconnects don't carry forward a previous
+        // session's "force Full" signal.
+        this.migrationClearedModels = false;
+        this.newlyAddedModels = [];
+        this.loadedTracker.reset();
+        // Gracefully handle environments without IndexedDB (Node.js, agents).
+        // All methods guard on this.db == null, so the engine runs in-memory.
+        if (typeof indexedDB === "undefined") {
+            return;
+        }
+        const dbName = `sync_${this.workspaceId}`;
+        // Step 1: Open at current version to read meta and check schema
+        this.db = await this.openDB(dbName);
+        const meta = await this.loadMeta();
+        // Step 2: If schema matches (or first-time connect with no saved meta),
+        // the DB is already in the right shape — no migration needed.
+        // On a first connect, createAllStores just ran via onupgradeneeded and
+        // created all current model stores; closing and reopening would only risk
+        // losing that work on some IDB implementations.
+        if (meta == null || meta.schemaHash === ModelRegistry.schemaHash) {
+            return;
+        }
+        // Step 3: Schema changed. Close and reopen at a higher version to trigger migration.
+        const oldVersion = this.db.version;
+        const newVersion = (meta.dbVersion ?? oldVersion) + 1;
+        this.db.close();
+        this.db = null;
+        // Step 4: Reopen at newVersion → triggers onupgradeneeded
+        this.db = await this.openDBWithMigration(dbName, newVersion);
+        // Step 5: Diff per-model schemaVersions. Bumped models get their rows +
+        // partial-index coverage wiped (the IDB structure migrated in step 4 but
+        // the rows are still in the old shape). Newly added models are reported
+        // for a targeted follow-up fetch by StoreManager.
+        if (meta != null) {
+            const { cleared, newlyAdded } = await diffModelVersions(this, meta.modelSchemaVersions);
+            this.migrationClearedModels = cleared.length > 0;
+            // migrateSchema already pushed any model whose IDB store was newly
+            // created (covering the legacy-meta + new-model case where stored
+            // versions are empty); on the typical "adopter added a new model" path
+            // both sources fire for the same name, so we dedupe.
+            this.newlyAddedModels = [
+                ...new Set([...this.newlyAddedModels, ...newlyAdded]),
+            ];
+        }
+        // Update the dbVersion + per-model versions in meta after migration
+        if (meta != null) {
+            meta.dbVersion = newVersion;
+            meta.schemaHash = ModelRegistry.schemaHash;
+            meta.modelSchemaVersions = currentModelVersions();
+            await this.saveMeta(meta);
+        }
+        await this.seedLoadedModels();
+    }
+    /** One IDB count() per store to seed `loadedModels` with anything that
+     * survived from a prior session. Runs once per connect. */
+    async seedLoadedModels() {
+        if (this.db == null) {
+            return;
+        }
+        const names = [...this.db.objectStoreNames].filter((name) => !name.startsWith("__"));
+        if (names.length === 0) {
+            return;
+        }
+        const tx = this.db.transaction(names, "readonly");
+        await Promise.all(names.map((name) => new Promise((resolve, reject) => {
+            const r = tx.objectStore(name).count();
+            r.onsuccess = () => {
+                if (r.result > 0) {
+                    this.loadedTracker.seed(name);
+                }
+                resolve();
+            };
+            r.onerror = () => reject(r.error);
+        })));
+    }
+    /**
+     * 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.
+     */
+    attachVersionChangeHandler(db) {
+        db.onversionchange = () => {
+            db.close();
+            this.db = null;
+        };
+    }
+    /** Open DB at its current version (no migration). */
+    openDB(dbName) {
+        return new Promise((resolve, reject) => {
+            const request = indexedDB.open(dbName);
+            request.onupgradeneeded = (event) => {
+                // First time creating this DB — set up everything from scratch
+                this.createAllStores(event.target.result);
+            };
+            request.onsuccess = () => {
+                const db = request.result;
+                this.attachVersionChangeHandler(db);
+                resolve(db);
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /** Open DB at a specific version, triggering migration in onupgradeneeded. */
+    openDBWithMigration(dbName, version) {
+        return new Promise((resolve, reject) => {
+            const request = indexedDB.open(dbName, version);
+            request.onblocked = () => {
+                console.warn(`[DB] upgrade to v${version} blocked — another tab has "${dbName}" open`);
+            };
+            request.onupgradeneeded = (event) => {
+                const db = event.target.result;
+                // IMPORTANT: use the upgrade transaction from the event, not db.transaction().
+                // IDB doesn't allow new transactions during an upgrade.
+                const upgradeTx = event.target.transaction;
+                this.migrateSchema(db, upgradeTx);
+            };
+            request.onsuccess = () => {
+                const db = request.result;
+                this.attachVersionChangeHandler(db);
+                resolve(db);
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
+    // =========================================================================
+    // Schema migration logic
+    //
+    // Diffs the current IDB object stores against the ModelRegistry:
+    //   - New models → create object store + indexes
+    //   - Removed models → delete object store
+    //   - Changed models → add/remove indexes
+    // =========================================================================
+    /** 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. */
+    ensureSystemStores(db) {
+        if (!db.objectStoreNames.contains("__meta")) {
+            db.createObjectStore("__meta");
+        }
+        if (!db.objectStoreNames.contains("__transactions")) {
+            db.createObjectStore("__transactions", { autoIncrement: true });
+        }
+        if (!db.objectStoreNames.contains("__partialIndexes")) {
+            db.createObjectStore("__partialIndexes", {
+                keyPath: ["modelName", "indexKey", "value"],
+            });
+        }
+        if (!db.objectStoreNames.contains("__syncActions")) {
+            const syncActions = db.createObjectStore("__syncActions", {
+                keyPath: ["syncId", "modelName", "modelId"],
+            });
+            syncActions.createIndex("byModel", ["modelName", "modelId"]);
+            syncActions.createIndex("bySyncId", "syncId");
+        }
+    }
+    /** Create all stores from scratch (first-time DB creation). */
+    createAllStores(db) {
+        this.ensureSystemStores(db);
+        for (const modelMeta of ModelRegistry.allModels()) {
+            this.createModelStore(db, modelMeta.name);
+        }
+    }
+    /** Run an incremental migration: add/remove/update stores. */
+    migrateSchema(db, upgradeTx) {
+        this.ensureSystemStores(db);
+        const registeredModels = new Set(ModelRegistry.allModels().map((m) => m.name));
+        const existingStores = new Set();
+        for (let i = 0; i < db.objectStoreNames.length; i++) {
+            const name = db.objectStoreNames[i];
+            if (!name.startsWith("__")) {
+                existingStores.add(name);
+            }
+        }
+        // Add new model stores
+        for (const modelName of registeredModels) {
+            if (!existingStores.has(modelName)) {
+                this.createModelStore(db, modelName);
+                this.newlyAddedModels.push(modelName);
+            }
+        }
+        // Remove stores for models that no longer exist
+        for (const storeName of existingStores) {
+            if (!registeredModels.has(storeName)) {
+                db.deleteObjectStore(storeName);
+            }
+        }
+        // Update indexes on existing stores using the upgrade transaction
+        for (const modelName of registeredModels) {
+            if (existingStores.has(modelName)) {
+                this.migrateIndexes(upgradeTx, modelName);
+            }
+        }
+    }
+    /** Create an object store for a model with its indexed properties. */
+    createModelStore(db, modelName) {
+        const store = db.createObjectStore(modelName, { keyPath: "id" });
+        const meta = ModelRegistry.getModelMeta(modelName);
+        if (meta != null) {
+            for (const [propName, propMeta] of meta.properties) {
+                if (propMeta.indexed === true) {
+                    store.createIndex(propName, propName, { unique: false });
+                }
+            }
+        }
+    }
+    /** Add/remove indexes on an existing store to match current ModelRegistry. */
+    migrateIndexes(upgradeTx, modelName) {
+        const meta = ModelRegistry.getModelMeta(modelName);
+        if (meta == null) {
+            return;
+        }
+        // Use the upgrade transaction — the only transaction that can modify indexes.
+        const store = upgradeTx.objectStore(modelName);
+        // Indexes that should exist based on current metadata
+        const wantedIndexes = new Set();
+        for (const [propName, propMeta] of meta.properties) {
+            if (propMeta.indexed === true) {
+                wantedIndexes.add(propName);
+            }
+        }
+        // Remove indexes that shouldn't exist anymore
+        const existingIndexes = [];
+        for (let i = 0; i < store.indexNames.length; i++) {
+            existingIndexes.push(store.indexNames[i]);
+        }
+        for (const indexName of existingIndexes) {
+            if (!wantedIndexes.has(indexName)) {
+                store.deleteIndex(indexName);
+            }
+        }
+        // Add indexes that don't exist yet
+        for (const indexName of wantedIndexes) {
+            if (!store.indexNames.contains(indexName)) {
+                store.createIndex(indexName, indexName, { unique: false });
+            }
+        }
+    }
+    // =========================================================================
+    // Bootstrap type detection
+    // =========================================================================
+    async determineBootstrapType() {
+        const meta = await this.loadMeta();
+        // No meta → first time → full bootstrap
+        if (meta == null) {
+            return BootstrapType.Full;
+        }
+        // If migration added new model stores AND there's no prior sync, fall
+        // back to Full — there's nothing to fetch deltas against. With a
+        // lastSyncId in hand, partial bootstrap proceeds and StoreManager runs
+        // a targeted fullBootstrap call for just `newlyAddedModels` after.
+        if (this.newlyAddedModels.length > 0 && meta.lastSyncId <= 0) {
+            return BootstrapType.Full;
+        }
+        // A schemaVersion bump cleared rows for one or more models — partial
+        // bootstrap won't refill them (it only ships deltas since lastSyncId).
+        // Force a Full bootstrap so cleared model stores get repopulated.
+        if (this.migrationClearedModels) {
+            return BootstrapType.Full;
+        }
+        // Valid data exists
+        if (meta.lastSyncId > 0) {
+            return BootstrapType.Partial;
+        }
+        return BootstrapType.Local;
+    }
+    // =========================================================================
+    // Meta
+    // =========================================================================
+    async loadMeta() {
+        if (this.db == null) {
+            return null;
+        }
+        try {
+            const result = await this.idbGet("__meta", "meta");
+            this.meta = result;
+            return result;
+        }
+        catch {
+            // __meta store might not exist yet (first open before upgrade)
+            return null;
+        }
+    }
+    async saveMeta(meta) {
+        if (this.db == null) {
+            return;
+        }
+        // Default the per-model schemaVersion snapshot from the live registry
+        // when the caller didn't provide one — so bumps are detectable on the
+        // next connect. Caller-supplied values win.
+        const merged = {
+            ...meta,
+            modelSchemaVersions: meta.modelSchemaVersions ?? currentModelVersions(),
+        };
+        this.meta = merged;
+        await this.idbPut("__meta", merged, "meta");
+    }
+    get currentMeta() {
+        return this.meta;
+    }
+    // =========================================================================
+    // Model data operations
+    // =========================================================================
+    async writeModels(modelName, records) {
+        if (!this.hasStore(modelName) || records.length === 0) {
+            return;
+        }
+        const tx = this.db.transaction(modelName, "readwrite");
+        const store = tx.objectStore(modelName);
+        for (const record of records) {
+            store.put(record);
+        }
+        await this.waitForTransaction(tx);
+        this.loadedTracker.markLoaded(modelName);
+    }
+    async writeModelsIfAbsent(modelName, records) {
+        if (!this.hasStore(modelName) || records.length === 0) {
+            return;
+        }
+        // IDB transactions on a single connection are serialized, so no gap between
+        // the read and write can let a concurrent write slip through.
+        const existingKeys = await new Promise((resolve, reject) => {
+            const r = this.db.transaction(modelName, "readonly")
+                .objectStore(modelName)
+                .getAllKeys();
+            r.onsuccess = () => resolve(new Set(r.result));
+            r.onerror = () => reject(r.error);
+        });
+        const newRecords = records.filter((r) => !existingKeys.has(r.id));
+        if (newRecords.length === 0) {
+            return;
+        }
+        const tx = this.db.transaction(modelName, "readwrite");
+        const store = tx.objectStore(modelName);
+        for (const record of newRecords) {
+            store.put(record);
+        }
+        await this.waitForTransaction(tx);
+        this.loadedTracker.markLoaded(modelName);
+    }
+    async readAllModels(modelName) {
+        if (!this.hasStore(modelName)) {
+            return [];
+        }
+        return this.idbGetAll(modelName);
+    }
+    async readModel(modelName, id) {
+        if (!this.hasStore(modelName)) {
+            return null;
+        }
+        return this.idbGet(modelName, id);
+    }
+    async readModelsByIndex(modelName, indexName, value) {
+        if (!this.hasStore(modelName)) {
+            return [];
+        }
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction(modelName, "readonly");
+            const store = tx.objectStore(modelName);
+            if (store.indexNames.contains(indexName)) {
+                const r = store.index(indexName).getAll(value);
+                r.onsuccess = () => resolve(r.result ?? []);
+                r.onerror = () => reject(r.error);
+            }
+            else {
+                // Fallback: full scan + filter (slower, but correct)
+                const r = store.getAll();
+                r.onsuccess = () => resolve((r.result ?? []).filter((rec) => rec[indexName] === value));
+                r.onerror = () => reject(r.error);
+            }
+        });
+    }
+    async deleteModel(modelName, id) {
+        if (!this.hasStore(modelName)) {
+            return;
+        }
+        const tx = this.db.transaction(modelName, "readwrite");
+        tx.objectStore(modelName).delete(id);
+        return this.waitForTransaction(tx);
+    }
+    /** Delete multiple records in a single IDB transaction. */
+    async deleteModels(modelName, ids) {
+        if (!this.hasStore(modelName) || ids.length === 0) {
+            return;
+        }
+        const tx = this.db.transaction(modelName, "readwrite");
+        const store = tx.objectStore(modelName);
+        for (const id of ids) {
+            store.delete(id);
+        }
+        return this.waitForTransaction(tx);
+    }
+    async deleteModelsByIndex(modelName, indexName, value) {
+        if (!this.hasStore(modelName)) {
+            return;
+        }
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction(modelName, "readwrite");
+            const store = tx.objectStore(modelName);
+            const request = store.indexNames.contains(indexName)
+                ? store.index(indexName).openCursor(IDBKeyRange.only(value))
+                : store.openCursor();
+            request.onsuccess = (event) => {
+                const cursor = event.target.result;
+                if (cursor == null) {
+                    return;
+                }
+                if (!store.indexNames.contains(indexName) &&
+                    cursor.value[indexName] !== value) {
+                    cursor.continue();
+                    return;
+                }
+                cursor.delete();
+                cursor.continue();
+            };
+            request.onerror = () => reject(request.error);
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+    async clearModelStore(modelName) {
+        if (!this.hasStore(modelName)) {
+            return;
+        }
+        const tx = this.db.transaction(modelName, "readwrite");
+        tx.objectStore(modelName).clear();
+        await this.waitForTransaction(tx);
+        this.loadedTracker.markUnloaded(modelName);
+    }
+    // =========================================================================
+    // Transaction cache
+    // =========================================================================
+    /**
+     * 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.
+     */
+    openTxCacheTx(mode) {
+        if (this.db == null) {
+            return null;
+        }
+        try {
+            return this.db.transaction("__transactions", mode);
+        }
+        catch (err) {
+            if (err?.name === "InvalidStateError") {
+                return null;
+            }
+            throw err;
+        }
+    }
+    async cacheTransaction(data) {
+        const tx = this.openTxCacheTx("readwrite");
+        if (tx == null) {
+            return null;
+        }
+        return new Promise((resolve, reject) => {
+            const r = tx.objectStore("__transactions").add(data);
+            r.onsuccess = () => resolve(r.result);
+            r.onerror = () => reject(r.error);
+        });
+    }
+    async getCachedTransactions() {
+        const tx = this.openTxCacheTx("readonly");
+        if (tx == null) {
+            return [];
+        }
+        return new Promise((resolve, reject) => {
+            const store = tx.objectStore("__transactions");
+            const out = [];
+            const cursor = store.openCursor();
+            cursor.onsuccess = () => {
+                const c = cursor.result;
+                if (c == null) {
+                    resolve(out);
+                    return;
+                }
+                out.push({ idbKey: c.primaryKey, data: c.value });
+                c.continue();
+            };
+            cursor.onerror = () => reject(cursor.error);
+        });
+    }
+    async deleteCachedTransactions(idbKeys) {
+        if (idbKeys.length === 0) {
+            return;
+        }
+        const tx = this.openTxCacheTx("readwrite");
+        if (tx == null) {
+            return;
+        }
+        const store = tx.objectStore("__transactions");
+        for (const key of idbKeys) {
+            store.delete(key);
+        }
+        return this.waitForTransaction(tx);
+    }
+    async clearCachedTransactions() {
+        const tx = this.openTxCacheTx("readwrite");
+        if (tx == null) {
+            return;
+        }
+        tx.objectStore("__transactions").clear();
+        return this.waitForTransaction(tx);
+    }
+    async updateCachedTransaction(idbKey, data) {
+        const tx = this.openTxCacheTx("readwrite");
+        if (tx == null) {
+            return;
+        }
+        tx.objectStore("__transactions").put(data, idbKey);
+        return this.waitForTransaction(tx);
+    }
+    // =========================================================================
+    // SyncAction store — persisted change-log headers for crash recovery.
+    // =========================================================================
+    async recordSyncActions(actions) {
+        if (this.db == null || actions.length === 0) {
+            return;
+        }
+        const tx = this.db.transaction("__syncActions", "readwrite");
+        const store = tx.objectStore("__syncActions");
+        for (const a of actions) {
+            store.put(a);
+        }
+        return this.waitForTransaction(tx);
+    }
+    async hasSyncAction(syncId) {
+        if (this.db == null) {
+            return false;
+        }
+        return new Promise((resolve, reject) => {
+            const r = this.db.transaction("__syncActions", "readonly")
+                .objectStore("__syncActions")
+                .index("bySyncId")
+                .getKey(syncId);
+            r.onsuccess = () => resolve(r.result != null);
+            r.onerror = () => reject(r.error);
+        });
+    }
+    async findSyncActionsForModel(modelName, modelId) {
+        if (this.db == null) {
+            return [];
+        }
+        return new Promise((resolve, reject) => {
+            const r = this.db.transaction("__syncActions", "readonly")
+                .objectStore("__syncActions")
+                .index("byModel")
+                .getAll([modelName, modelId]);
+            r.onsuccess = () => {
+                const rows = (r.result ?? []);
+                resolve(rows.map((row) => ({ syncId: row.syncId, action: row.action })));
+            };
+            r.onerror = () => reject(r.error);
+        });
+    }
+    async pruneSyncActionsBelow(belowSyncId) {
+        if (this.db == null) {
+            return;
+        }
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction("__syncActions", "readwrite");
+            const store = tx.objectStore("__syncActions");
+            const cursor = store
+                .index("bySyncId")
+                .openCursor(IDBKeyRange.upperBound(belowSyncId, true));
+            cursor.onsuccess = () => {
+                const c = cursor.result;
+                if (c == null) {
+                    return;
+                }
+                c.delete();
+                c.continue();
+            };
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+    // =========================================================================
+    // Partial-index coverage store
+    //
+    // Records `(modelName, indexKey, value)` triples for which getOrLoadCollection has
+    // fetched in full. Survives reload — on next bootstrap the engine populates
+    // its in-memory cache from this store and skips redundant network/IDB work.
+    // =========================================================================
+    async recordPartialIndex(modelName, indexKey, value, firstSyncId) {
+        if (this.db == null) {
+            return;
+        }
+        const tx = this.db.transaction("__partialIndexes", "readwrite");
+        tx.objectStore("__partialIndexes").put({
+            modelName,
+            indexKey,
+            value,
+            firstSyncId,
+        });
+        return this.waitForTransaction(tx);
+    }
+    async clearPartialIndex(modelName, indexKey, value) {
+        if (this.db == null) {
+            return;
+        }
+        const tx = this.db.transaction("__partialIndexes", "readwrite");
+        tx.objectStore("__partialIndexes").delete([modelName, indexKey, value]);
+        return this.waitForTransaction(tx);
+    }
+    async clearPartialIndexesForModel(modelName) {
+        if (this.db == null) {
+            return;
+        }
+        const tx = this.db.transaction("__partialIndexes", "readwrite");
+        // IDB delete accepts a key range — drops every entry whose first compound
+        // component is `modelName` in a single op.
+        tx.objectStore("__partialIndexes").delete(IDBKeyRange.bound([modelName], [modelName, []], false, false));
+        return this.waitForTransaction(tx);
+    }
+    async loadPartialIndexes() {
+        if (this.db == null) {
+            return [];
+        }
+        return this.idbGetAll("__partialIndexes");
+    }
+    // =========================================================================
+    // Cleanup
+    // =========================================================================
+    /** Close the IDB connection without deleting any data. */
+    async close() {
+        this.db?.close();
+        this.db = null;
+    }
+    /** Close the connection AND delete all persisted data for this workspace. */
+    async destroy() {
+        await this.close();
+        if (typeof indexedDB !== "undefined") {
+            indexedDB.deleteDatabase(`sync_${this.workspaceId}`);
+        }
+    }
+    get isConnected() {
+        return this.db !== null;
+    }
+    // =========================================================================
+    // Helpers
+    // =========================================================================
+    hasStore(name) {
+        return this.db != null && this.db.objectStoreNames.contains(name);
+    }
+    idbGet(storeName, key) {
+        return new Promise((resolve, reject) => {
+            const r = this.db.transaction(storeName, "readonly")
+                .objectStore(storeName)
+                .get(key);
+            r.onsuccess = () => resolve(r.result ?? null);
+            r.onerror = () => reject(r.error);
+        });
+    }
+    idbGetAll(storeName) {
+        return new Promise((resolve, reject) => {
+            const r = this.db.transaction(storeName, "readonly")
+                .objectStore(storeName)
+                .getAll();
+            r.onsuccess = () => resolve(r.result ?? []);
+            r.onerror = () => reject(r.error);
+        });
+    }
+    idbPut(storeName, value, key) {
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction(storeName, "readwrite");
+            tx.objectStore(storeName).put(value, key);
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+    waitForTransaction(tx) {
+        return new Promise((resolve, reject) => {
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+}