@abloatai/ablo 0.34.1 → 0.36.0

package/dist/Database.js

@@ -5,14 +5,14 @@
  * server. {@link BaseSyncedStore} drives it, and {@link InstanceCache} holds the
  * in-memory mirror of what this class persists.
  */
-import { DatabaseManager } from './core/DatabaseManager.js';
-import { StoreManager } from './core/StoreManager.js';
+import { DatabaseManager } from './stores/DatabaseManager.js';
+import { StoreManager } from './stores/StoreManager.js';
 import { ModelRegistry } from './ModelRegistry.js';
-import { LoadStrategy } from './types/index.js';
-import { getContext } from './context.js';
-import { AbloConnectionError, AbloValidationError } from './errors.js';
+import { LoadStrategy } from './transaction/types/index.js';
+import { globalRuntime } from './context.js';
+import { AbloConnectionError, AbloValidationError } from './transaction/errors.js';
 import { InMemoryObjectStore } from './adapters/inMemoryStorage.js';
-import { syncPositionSchema } from './sync/syncPosition.js';
+import { logPositionSchema } from './transaction/logPosition.js';
 import { highestPersistedPrefixSyncId } from './sync/persistedPrefix.js';
 /**
  * Request identity excludes local timing metadata for re-entrant seals: a
@@ -110,7 +110,7 @@ export class Database {
     /** Essential fields that must be preserved during partial UPDATE merges.
      * Sourced from SyncEngineConfig.essentialFields — consumers define their own. */
     get essentialFields() {
-        return getContext().config.essentialFields;
+        return this.runtime.config.essentialFields;
     }
     /**
      * When true, all IndexedDB operations are replaced with in-memory Maps.
@@ -121,13 +121,15 @@ export class Database {
      *   new Database(registry, bootstrap, { inMemory: true })
      */
     inMemory;
+    runtime;
     /** In-memory stores used when inMemory=true. Keyed by model name. */
     inMemoryStores = new Map();
     /** In-memory workspace metadata when inMemory=true. */
     inMemoryMetadata = null;
     constructor(modelRegistry, bootstrapHelper, options) {
-        this.databaseManager = new DatabaseManager();
-        this.storeManager = new StoreManager(modelRegistry);
+        this.runtime = options?.runtime ?? globalRuntime;
+        this.databaseManager = new DatabaseManager(this.runtime);
+        this.storeManager = new StoreManager(modelRegistry, this.runtime);
         this.modelRegistry = modelRegistry;
         this.bootstrapHelper = bootstrapHelper;
         this.inMemory = options?.inMemory ?? false;
@@ -149,7 +151,7 @@ export class Database {
             ? this.inMemoryStores.get(modelName)
             : this.storeManager.getStore(modelName);
         if (!store && context) {
-            getContext().observability.breadcrumb(`Store not found for model: ${modelName}`, 'sync.database', 'warning', { context });
+            this.runtime.observability.breadcrumb(`Store not found for model: ${modelName}`, 'sync.database', 'warning', { context });
         }
         return store;
     }
@@ -170,7 +172,7 @@ export class Database {
         const requiredFields = this.essentialFields[modelName] ?? [];
         const preserved = requiredFields.filter((field) => existing[field] !== undefined && delta[field] === undefined);
         if (preserved.length > 0) {
-            getContext().logger.debug('[Database] UPDATE merged - preserved fields', {
+            this.runtime.logger.debug('[Database] UPDATE merged - preserved fields', {
                 modelName,
                 modelId: modelId.slice(0, 12),
                 deltaFields: Object.keys(delta),
@@ -188,7 +190,7 @@ export class Database {
         // Creates InMemoryObjectStore instances for all registered models.
         // Bootstrap via HTTP still works; only local persistence is skipped.
         if (this.inMemory) {
-            getContext().logger.debug('Opening in-memory database (headless mode)');
+            this.runtime.logger.debug('Opening in-memory database (headless mode)');
             const allModels = this.modelRegistry.getRegisteredModelNames();
             for (const modelName of allModels) {
                 const storeName = `store_${modelName.toLowerCase()}`;
@@ -196,11 +198,11 @@ export class Database {
             }
             // Create a __transactions store for the offline queue
             this.inMemoryStores.set('__transactions', new InMemoryObjectStore('__transactions', '__transactions'));
-            getContext().logger.info(`In-memory database opened: ${this.inMemoryStores.size} stores`);
+            this.runtime.logger.info(`In-memory database opened: ${this.inMemoryStores.size} stores`);
             return;
         }
         // ── Browser mode: IndexedDB (existing behavior, unchanged) ───
-        getContext().logger.debug('Opening IndexedDB database');
+        this.runtime.logger.debug('Opening IndexedDB database');
         // Initialize meta database
         await this.databaseManager.initializeMetaDatabase();
         // Calculate database info
@@ -208,13 +210,13 @@ export class Database {
         // Register database
         await this.databaseManager.registerDatabase(this.currentDbInfo);
         // Open workspace database
-        this.workspaceDb = await this.databaseManager.openWorkspaceDatabase(this.currentDbInfo, async (db, tx) => {
-            await this.storeManager.createStores(db, tx);
+        this.workspaceDb = await this.databaseManager.openWorkspaceDatabase(this.currentDbInfo, async (db) => {
+            await this.storeManager.createStores(db);
         });
         // Initialize stores
         await this.storeManager.initializeStores(this.workspaceDb);
         const readiness = await this.storeManager.checkReadinessOfStores();
-        getContext().logger.info(`Database opened: ${this.currentDbInfo.name} (${readiness.readyStores.length}/${readiness.totalStores} stores ready)`);
+        this.runtime.logger.info(`Database opened: ${this.currentDbInfo.name} (${readiness.readyStores.length}/${readiness.totalStores} stores ready)`);
     }
     /**
      * Shrink a record before persisting it. Drops `undefined` fields, empty
@@ -277,7 +279,7 @@ export class Database {
      */
     markRequiresFullBootstrap() {
         this._forceFullBootstrap = true;
-        getContext().logger.info('[Database] Marked for forced full bootstrap (sync group change)');
+        this.runtime.logger.info('[Database] Marked for forced full bootstrap (sync group change)');
     }
     /**
      * Smart bootstrap requirements based on data freshness
@@ -309,7 +311,7 @@ export class Database {
             this._forceFullBootstrap = false;
             const instantModels = this.modelRegistry.getModelsByLoadStrategy(LoadStrategy.instant);
             const lazyModels = this.modelRegistry.getModelsByLoadStrategy(LoadStrategy.lazy);
-            getContext().logger.info('[Database.requiredBootstrap] Forced FULL bootstrap (sync group change)');
+            this.runtime.logger.info('[Database.requiredBootstrap] Forced FULL bootstrap (sync group change)');
             return {
                 type: 'full',
                 modelsToLoad: [...instantModels, ...lazyModels],
@@ -328,7 +330,7 @@ export class Database {
         // (a corrupted negative/float cursor would previously pass `|| 0`,
         // which only catches falsy, and get sent to the server as the resume
         // point). Invalid → 0 → full bootstrap, the safe degradation.
-        const metadataLastSyncId = syncPositionSchema.shape.persisted.safeParse(metadata?.lastSyncId).data ?? 0;
+        const metadataLastSyncId = logPositionSchema.shape.persisted.safeParse(metadata?.lastSyncId).data ?? 0;
         const dataAge = metadata?.updatedAt ? Date.now() - metadata.updatedAt.getTime() : Infinity;
         // ── Cache-validity check ─────────────────────────────────────
         //
@@ -348,7 +350,7 @@ export class Database {
         // we've confirmed the data it refers to actually exists in the stores.
         const lastSyncId = dataExists ? metadataLastSyncId : 0;
         // Log the resolved database state for diagnostics.
-        getContext().logger.debug('[Database.requiredBootstrap] State check', {
+        this.runtime.logger.debug('[Database.requiredBootstrap] State check', {
             readinessReady: readiness.ready,
             hasMetadata: !!metadata,
             metadataLastSyncId,
@@ -365,13 +367,13 @@ export class Database {
         if (offline && hasLocalData) {
             // Offline with data - use local bootstrap (only option when offline)
             type = 'local';
-            getContext().logger.info('Offline detected with local data - using local bootstrap');
+            this.runtime.logger.info('Offline detected with local data - using local bootstrap');
         }
         else {
             // The server is the source of truth: always use a full bootstrap
             // when online.
             type = 'full';
-            getContext().logger.info('Full bootstrap - server is source of truth', {
+            this.runtime.logger.info('Full bootstrap - server is source of truth', {
                 reason: offline ? 'offline_no_data' : 'server_authoritative',
                 hasLocalData,
                 lastSyncId,
@@ -396,12 +398,12 @@ export class Database {
      *  shrinkage check. Caller supplies the complete list, not just
      *  team-derived groups. */
     syncGroups, onProgress) {
-        getContext().logger.debug('Starting bootstrap fetch', {
+        this.runtime.logger.debug('Starting bootstrap fetch', {
             type: requirements.type,
             lastSyncId: requirements.lastSyncId,
             modelsToLoad: requirements.modelsToLoad,
         });
-        getContext().logger.info('Database: Starting bootstrap from Go server', {
+        this.runtime.logger.info('Database: Starting bootstrap from Go server', {
             type: requirements.type,
             syncGroups,
             modelsToLoad: requirements.modelsToLoad,
@@ -410,12 +412,12 @@ export class Database {
             // Fetch before any destructive operation, so a failed network
             // request can't leave the local store empty.
             const startTime = typeof performance !== 'undefined' ? performance.now() : Date.now();
-            getContext().logger.info('Fetching bootstrap data from server (before clearing local data)', {
+            this.runtime.logger.info('Fetching bootstrap data from server (before clearing local data)', {
                 type: requirements.type,
                 lastSyncId: requirements.lastSyncId,
             });
             const bootstrapData = await this.bootstrapHelper.fetchBootstrap(requirements.lastSyncId);
-            getContext().logger.debug('Received bootstrap response', {
+            this.runtime.logger.debug('Received bootstrap response', {
                 type: bootstrapData.type,
                 lastSyncId: bootstrapData.lastSyncId,
                 hasModels: !!bootstrapData.models,
@@ -431,7 +433,7 @@ export class Database {
             // Handle partial bootstrap (delta batch)
             if (bootstrapData.type === 'partial') {
                 const deltas = bootstrapData.deltas ?? [];
-                getContext().logger.info('Processing partial bootstrap with delta batch', {
+                this.runtime.logger.info('Processing partial bootstrap with delta batch', {
                     deltaCount: deltas.length,
                     fromSyncId: requirements.lastSyncId,
                     toSyncId: bootstrapData.lastSyncId,
@@ -444,13 +446,18 @@ export class Database {
                 let deltasApplied = 0;
                 let deltaResults;
                 if (deltas.length > 0) {
-                    // Convert server delta format to processDelta format
+                    // Narrow the wire delta to what processDelta reads. The field names
+                    // are the wire's own — the only change is `id` becoming `syncId`.
+                    // A group-change frame carries its payload as a JSON string, decoded
+                    // here exactly as the live delta path does in BaseSyncedStore.
                     const formattedDeltas = deltas.map((delta) => ({
                         syncId: delta.id,
-                        actionType: delta.operation,
+                        actionType: delta.actionType,
                         modelName: delta.modelName,
-                        modelId: delta.entityId,
-                        data: delta.data,
+                        modelId: delta.modelId,
+                        data: typeof delta.data === 'string'
+                            ? JSON.parse(delta.data)
+                            : delta.data,
                     }));
                     // Use batch processing for better performance
                     const batch = await this.processDeltaBatch(formattedDeltas);
@@ -466,7 +473,7 @@ export class Database {
                     updatedAt: new Date(),
                 });
                 const elapsed = (typeof performance !== 'undefined' ? performance.now() : Date.now()) - startTime;
-                getContext().logger.info(`Partial bootstrap complete in ${elapsed.toFixed(2)}ms`, {
+                this.runtime.logger.info(`Partial bootstrap complete in ${elapsed.toFixed(2)}ms`, {
                     deltasApplied,
                     lastSyncId: bootstrapData.lastSyncId,
                 });
@@ -483,21 +490,21 @@ export class Database {
             for (const [modelName, modelData] of Object.entries(bootstrapData.models)) {
                 // Handle null, undefined, or non-array data
                 if (!modelData) {
-                    getContext().observability.breadcrumb(`No data received for ${modelName}`, 'sync.bootstrap', 'warning');
+                    this.runtime.observability.breadcrumb(`No data received for ${modelName}`, 'sync.bootstrap', 'warning');
                     continue;
                 }
                 if (!Array.isArray(modelData)) {
-                    getContext().observability.breadcrumb(`Skipping non-array data for ${modelName}`, 'sync.bootstrap', 'warning');
+                    this.runtime.observability.breadcrumb(`Skipping non-array data for ${modelName}`, 'sync.bootstrap', 'warning');
                     continue;
                 }
                 // Skip empty arrays silently (expected for some models)
                 if (modelData.length === 0) {
-                    getContext().logger.debug(`No ${modelName} items to store (empty array)`);
+                    this.runtime.logger.debug(`No ${modelName} items to store (empty array)`);
                     continue;
                 }
                 const store = this.getStore(modelName, 'bootstrap');
                 if (!store) {
-                    getContext().logger.debug(`[Bootstrap] NO IDB STORE for ${modelName} — ${modelData.length} items DROPPED`);
+                    this.runtime.logger.debug(`[Bootstrap] NO IDB STORE for ${modelName} — ${modelData.length} items DROPPED`);
                     continue;
                 }
                 let writeErrors = 0;
@@ -515,11 +522,18 @@ export class Database {
                     }
                     catch (error) {
                         writeErrors++;
-                        getContext().observability.breadcrumb(`Failed to store ${modelName} item`, 'sync.database', 'error', {
+                        this.runtime.observability.breadcrumb(`Failed to store ${modelName} item`, 'sync.database', 'error', {
                             error: error instanceof Error ? error.message : String(error),
                         });
                     }
                 }
+                // The model is marked persisted below whether or not every item landed,
+                // because a partial store is still what the next sync reconciles
+                // against. Counted and surfaced here so a partial does not read as a
+                // clean bootstrap.
+                if (writeErrors > 0) {
+                    this.runtime.observability.breadcrumb(`Stored ${modelName} with ${writeErrors} of ${modelData.length} items dropped`, 'sync.database', 'warning');
+                }
                 // Mark model as persisted after successful write
                 try {
                     await this.setModelPersisted(modelName, true);
@@ -536,8 +550,8 @@ export class Database {
                 updatedAt: new Date(),
             });
             const elapsed = (typeof performance !== 'undefined' ? performance.now() : Date.now()) - startTime;
-            getContext().logger.info(`Bootstrap complete: ${modelsLoaded} items loaded, ${modelsStored} stored to IndexedDB in ${elapsed.toFixed(2)}ms`);
-            getContext().analytics?.capture('bootstrap_success', {
+            this.runtime.logger.info(`Bootstrap complete: ${modelsLoaded} items loaded, ${modelsStored} stored to IndexedDB in ${elapsed.toFixed(2)}ms`);
+            this.runtime.analytics?.capture('bootstrap_success', {
                 responseTime: elapsed,
                 modelsLoaded,
             });
@@ -545,12 +559,12 @@ export class Database {
         }
         catch (error) {
             // Comprehensive error logging for bootstrap failures
-            getContext().observability.captureBootstrapFailure(error, {
+            this.runtime.observability.captureBootstrapFailure(error, {
                 type: requirements.type,
                 navigatorOnline: typeof navigator !== 'undefined' ? navigator.onLine : undefined,
             });
             // Track bootstrap failure telemetry
-            getContext().analytics?.capture('bootstrap_failed', {
+            this.runtime.analytics?.capture('bootstrap_failed', {
                 bootstrapType: requirements.type,
                 lastSyncId: requirements.lastSyncId,
                 errorMessage: error instanceof Error ? error.message : String(error),
@@ -569,7 +583,7 @@ export class Database {
      *
      * Update deltas carry only the changed fields, so they are merged onto the
      * existing record rather than replacing it. That preserves fields the delta
-     * omits (such as deckId or title), and an explicit null is kept as a value,
+     * omits (such as reportId or title), and an explicit null is kept as a value,
      * clearing that field.
      */
     async processDelta(delta) {
@@ -605,7 +619,7 @@ export class Database {
             // newly created, it was newly visible. We fall through to the 'I' case
             // after a debug trace so the two can be disambiguated in logs.
             case 'C':
-                getContext().observability.breadcrumb('Applying covering delta (gained permission)', 'sync.database', 'info', { modelName, modelId: modelId.slice(0, 12) });
+                this.runtime.observability.breadcrumb('Applying covering delta (gained permission)', 'sync.database', 'info', { modelName, modelId: modelId.slice(0, 12) });
             // falls through
             case 'I': {
                 // Skip when the delta payload was empty/null. IDB rejects
@@ -623,7 +637,7 @@ export class Database {
                     }
                 }
                 catch (err) {
-                    getContext().observability.breadcrumb(`IndexedDB put failed for ${modelName}:${modelId}`, 'sync.database', 'error', {
+                    this.runtime.observability.breadcrumb(`IndexedDB put failed for ${modelName}:${modelId}`, 'sync.database', 'error', {
                         error: err instanceof Error ? err.message : String(err),
                     });
                     throw err; // Re-throw to see the actual error
@@ -636,9 +650,9 @@ export class Database {
                 const existing = await store.get(modelId);
                 // Skip the update when there's no existing record to merge with:
                 // building a record from partial update data would corrupt it
-                // (missing deckId, and so on).
+                // (missing reportId, and so on).
                 if (!existing) {
-                    getContext().observability.breadcrumb('Skipping UPDATE delta - no existing record to merge with', 'sync.database', 'warning', {
+                    this.runtime.observability.breadcrumb('Skipping UPDATE delta - no existing record to merge with', 'sync.database', 'warning', {
                         modelName,
                         modelId: modelId.slice(0, 12),
                     });
@@ -659,7 +673,7 @@ export class Database {
                     }
                 }
                 catch (err) {
-                    getContext().observability.breadcrumb(`IndexedDB put failed for ${modelName}:${modelId}`, 'sync.database', 'error', {
+                    this.runtime.observability.breadcrumb(`IndexedDB put failed for ${modelName}:${modelId}`, 'sync.database', 'error', {
                         error: err instanceof Error ? err.message : String(err),
                     });
                     throw err;
@@ -676,7 +690,7 @@ export class Database {
                     }
                 }
                 catch (err) {
-                    getContext().observability.breadcrumb(`IndexedDB delete failed for ${modelName}:${modelId}`, 'sync.database', 'error', {
+                    this.runtime.observability.breadcrumb(`IndexedDB delete failed for ${modelName}:${modelId}`, 'sync.database', 'error', {
                         error: err instanceof Error ? err.message : String(err),
                     });
                     // Surface failure so caller does not mutate InstanceCache inconsistently
@@ -694,7 +708,7 @@ export class Database {
                     }
                 }
                 catch (err) {
-                    getContext().observability.breadcrumb(`IndexedDB archive put failed for ${modelName}:${modelId}`, 'sync.database', 'error', {
+                    this.runtime.observability.breadcrumb(`IndexedDB archive put failed for ${modelName}:${modelId}`, 'sync.database', 'error', {
                         error: err instanceof Error ? err.message : String(err),
                     });
                     throw err;
@@ -710,12 +724,16 @@ export class Database {
             // queue), we return a no-op verify rather than crashing the engine.
             case 'G':
             case 'S':
-                getContext().observability.breadcrumb(`Group membership delta (${actionType}) reached processDelta — should be handled upstream`, 'sync.database', 'warning', { modelName, modelId: modelId.slice(0, 12), actionType });
+                this.runtime.observability.breadcrumb(`Group membership delta (${actionType}) reached processDelta — should be handled upstream`, 'sync.database', 'warning', { modelName, modelId: modelId.slice(0, 12), actionType });
                 return { action: 'verify', modelName, modelId, data: null };
-            default:
-                throw new AbloValidationError(`Unknown action type: ${actionType}`, {
-                    code: 'db_unknown_action_type',
-                });
+            default: {
+                // The switch above is exhaustive over the declared action types, so
+                // this branch is only reachable when a value escapes the type — hence
+                // stringifying whatever actually arrived rather than the `never`.
+                const _exhaustive = actionType;
+                void _exhaustive;
+                throw new AbloValidationError(`Unknown action type: ${JSON.stringify(actionType)}`, { code: 'db_unknown_action_type' });
+            }
         }
     }
     /**
@@ -792,7 +810,7 @@ export class Database {
             }
         }
         if (deleteSyncIds.size > 0) {
-            getContext().logger.debug('[Database.processDeltaBatch] Built DELETE index for conflict resolution', {
+            this.runtime.logger.debug('[Database.processDeltaBatch] Built DELETE index for conflict resolution', {
                 deleteCount: deleteSyncIds.size,
                 totalDeltas: deltas.length,
             });
@@ -826,8 +844,7 @@ export class Database {
             // entity has an equal or higher sync id.
             if (delta.actionType === 'U' ||
                 delta.actionType === 'I' ||
-                delta.actionType === 'C' ||
-                delta.actionType === 'M') {
+                delta.actionType === 'C') {
                 const key = `${delta.modelName}:${delta.modelId}`;
                 const deleteSyncId = deleteSyncIds.get(key);
                 if (deleteSyncId !== undefined) {
@@ -835,7 +852,7 @@ export class Database {
                     const deltaSyncId = delta.syncId ?? 0;
                     if (deleteSyncId >= deltaSyncId) {
                         // DELETE has equal or higher syncId - skip this UPDATE/INSERT
-                        getContext().logger.debug('[Database.processDeltaBatch] Skipping stale delta (DELETE wins)', {
+                        this.runtime.logger.debug('[Database.processDeltaBatch] Skipping stale delta (DELETE wins)', {
                             modelName: delta.modelName,
                             modelId: delta.modelId.slice(0, 12),
                             actionType: delta.actionType,
@@ -862,7 +879,7 @@ export class Database {
             deltasByStore.get(delta.modelName).push({ idx, delta });
         });
         if (skippedDueToConflict > 0) {
-            getContext().logger.info('[Database.processDeltaBatch] Conflict resolution summary', {
+            this.runtime.logger.info('[Database.processDeltaBatch] Conflict resolution summary', {
                 skippedDueToConflict,
                 totalDeltas: deltas.length,
                 deleteCount: deleteSyncIds.size,
@@ -892,8 +909,8 @@ export class Database {
                             }
                         }
                     }
-                    catch (error) {
-                        getContext().observability.breadcrumb(`Batch read failed for ${modelName}, falling back to individual reads`, 'sync.database', 'warning');
+                    catch {
+                        this.runtime.observability.breadcrumb(`Batch read failed for ${modelName}, falling back to individual reads`, 'sync.database', 'warning');
                         // Fallback: mark all as missing for self-healing
                         for (const id of updateIds) {
                             missingIds.add(id);
@@ -905,7 +922,7 @@ export class Database {
                 // so its delta is skipped).
                 const failedToFetch = new Set();
                 if (missingIds.size > 0) {
-                    getContext().logger.info(`[Database.processDeltaBatch] Found ${missingIds.size} missing records for ${modelName}, fetching from server...`);
+                    this.runtime.logger.info(`[Database.processDeltaBatch] Found ${missingIds.size} missing records for ${modelName}, fetching from server...`);
                     // Fetch sequentially to avoid overwhelming server
                     for (const id of missingIds) {
                         try {
@@ -913,24 +930,24 @@ export class Database {
                             if (fetchedRecord) {
                                 const compacted = this.compactRecord(modelName, fetchedRecord);
                                 existingRecords.set(id, compacted);
-                                getContext().logger.debug(`[Database.processDeltaBatch] Successfully fetched missing record: ${modelName}:${id}`);
+                                this.runtime.logger.debug(`[Database.processDeltaBatch] Successfully fetched missing record: ${modelName}:${id}`);
                             }
                             else {
                                 // fetchEntity returns null for 404 — entity was deleted, skip the delta
                                 failedToFetch.add(id);
-                                getContext().logger.debug(`[Database.processDeltaBatch] Entity not found (deleted): ${modelName}:${id}`);
+                                this.runtime.logger.debug(`[Database.processDeltaBatch] Entity not found (deleted): ${modelName}:${id}`);
                             }
                         }
                         catch (error) {
                             // Unexpected error (5xx, network failure) — mark for skipping and report
                             failedToFetch.add(id);
-                            getContext().observability.breadcrumb(`Failed to fetch missing record ${modelName}:${id}`, 'sync.database', 'warning', {
+                            this.runtime.observability.breadcrumb(`Failed to fetch missing record ${modelName}:${id}`, 'sync.database', 'warning', {
                                 error: error instanceof Error ? error.message : String(error),
                             });
                         }
                     }
                     if (failedToFetch.size > 0) {
-                        getContext().logger.info(`[Database.processDeltaBatch] Skipping ${failedToFetch.size} stale UPDATE deltas for deleted entities`, {
+                        this.runtime.logger.info(`[Database.processDeltaBatch] Skipping ${failedToFetch.size} stale UPDATE deltas for deleted entities`, {
                             modelName,
                             failedCount: failedToFetch.size,
                             totalMissing: missingIds.size,
@@ -982,7 +999,7 @@ export class Database {
                             // store nor fetchable from the server (a 404), it was deleted,
                             // so skip it rather than create an incomplete record.
                             if (!existing && failedToFetch.has(modelId)) {
-                                getContext().logger.debug('[Database.processDeltaBatch] Skipping UPDATE for deleted entity', {
+                                this.runtime.logger.debug('[Database.processDeltaBatch] Skipping UPDATE for deleted entity', {
                                     modelName,
                                     modelId: modelId.slice(0, 12),
                                 });
@@ -991,9 +1008,9 @@ export class Database {
                             }
                             // Skip the update when there's no existing record to merge with:
                             // building a record from partial update data would corrupt it
-                            // (missing deckId, and so on).
+                            // (missing reportId, and so on).
                             if (!existing) {
-                                getContext().observability.breadcrumb('Batch: Skipping UPDATE delta - no existing record', 'sync.database', 'warning', {
+                                this.runtime.observability.breadcrumb('Batch: Skipping UPDATE delta - no existing record', 'sync.database', 'warning', {
                                     modelName,
                                     modelId: modelId.slice(0, 12),
                                 });
@@ -1063,13 +1080,13 @@ export class Database {
                 }
             }
             catch (err) {
-                // Surface the IDB error directly — `captureTransactionFailure`
+                // Surface the IDB error directly — `captureMutationFailure`
                 // routes to Sentry, but during interactive debugging the console
                 // needs to show the specific failure (e.g. `ConstraintError`,
                 // `DataError`, `AbortError`) so we can find what's wrong with
                 // the `compacted` payload shape or store schema.
                 const idbErr = err instanceof Error ? err : new Error(String(err));
-                getContext().logger.debug('[Database.processDeltaBatch] store tx FAILED', {
+                this.runtime.logger.debug('[Database.processDeltaBatch] store tx FAILED', {
                     modelName,
                     storeDeltasCount: storeDeltas.length,
                     errorName: idbErr.name,
@@ -1082,7 +1099,7 @@ export class Database {
                             : typeof delta.data,
                     })),
                 });
-                getContext().observability.captureTransactionFailure({
+                this.runtime.observability.captureMutationFailure({
                     context: 'batch-indexeddb-operation',
                     modelName,
                     error: idbErr,
@@ -1108,7 +1125,7 @@ export class Database {
                 await this.updateWorkspaceMetadata({ lastSyncId: highestPersistedSyncId });
             }
             catch (err) {
-                getContext().observability.breadcrumb('Failed to update metadata after batch', 'sync.database', 'error', {
+                this.runtime.observability.breadcrumb('Failed to update metadata after batch', 'sync.database', 'error', {
                     error: err instanceof Error ? err.message : String(err),
                 });
             }
@@ -1118,7 +1135,7 @@ export class Database {
             // persisted" signal loud when it actually happens. If this fires
             // repeatedly on the same sync IDs, a specific row is un-writable
             // (validation? compact issue?) and needs fixing at that layer.
-            getContext().logger.debug('[Database.processDeltaBatch] cursor withheld due to failed store tx', {
+            this.runtime.logger.debug('[Database.processDeltaBatch] cursor withheld due to failed store tx', {
                 seen: highestSyncId,
                 persisted: highestPersistedSyncId,
                 gap: highestSyncId - highestPersistedSyncId,
@@ -1138,7 +1155,7 @@ export class Database {
     async putRecord(modelName, id, data) {
         const store = this.getStore(modelName, 'putRecord');
         if (!store) {
-            getContext().observability.breadcrumb(`Store not found for putRecord: ${modelName}`, 'sync.database', 'warning');
+            this.runtime.observability.breadcrumb(`Store not found for putRecord: ${modelName}`, 'sync.database', 'warning');
             return;
         }
         const compacted = this.compactRecord(modelName, data);
@@ -1181,7 +1198,7 @@ export class Database {
         // Graceful degradation: skip if database is closing or not open
         // This prevents "Database not opened" errors during React Strict Mode cleanup
         if (!this.workspaceDb || this.isClosing) {
-            getContext().observability.breadcrumb('updateWorkspaceMetadata: Database not open or closing', 'sync.database', 'warning', {
+            this.runtime.observability.breadcrumb('updateWorkspaceMetadata: Database not open or closing', 'sync.database', 'warning', {
                 hasDb: !!this.workspaceDb,
                 isClosing: this.isClosing,
             });
@@ -1473,13 +1490,13 @@ export class Database {
         }
         await this.databaseManager.close();
         this.currentDbInfo = null;
-        getContext().logger.debug('Database closed');
+        this.runtime.logger.debug('Database closed');
     }
     async clear(options = {}) {
         await this.storeManager.clearAllStores();
         if (options.includeWriteJournal) {
             await this.transactionStore.clear();
         }
-        getContext().logger.info('All stores cleared');
+        this.runtime.logger.info('All stores cleared');
     }
 }

package/dist/InstanceCache.d.ts

@@ -8,9 +8,10 @@
  */
 import { Model } from './Model.js';
 import { ModelRegistry } from './ModelRegistry.js';
-import { ModelScope } from './types/index.js';
-import { ViewRegistry } from './core/ViewRegistry.js';
-import { QueryView, type QueryViewOptions } from './core/QueryView.js';
+import type { RuntimeContext } from './RuntimeContext.js';
+import { ModelScope } from './transaction/types/index.js';
+import { ViewRegistry } from './views/ViewRegistry.js';
+import { QueryView, type QueryViewOptions } from './views/QueryView.js';
 /** Constructor type for Model subclasses - uses abstract to handle variance */
 type ModelConstructor<T extends Model> = abstract new (...args: never[]) => T;
 export { ModelScope };
@@ -19,6 +20,8 @@ interface PoolConfig {
     maxAge?: number;
     gcInterval?: number;
     useWeakRefs?: boolean;
+    /** The owning client's runtime. Defaults to the module-global bridge. */
+    runtime?: RuntimeContext;
 }
 interface DeltaInfo {
     action?: string;
@@ -38,6 +41,7 @@ export declare class InstanceCache {
     private foreignKeyConfig;
     private metrics;
     private config;
+    private readonly runtime;
     private gcTimer?;
     readonly registry: ModelRegistry;
     readonly viewRegistry: ViewRegistry;
@@ -50,6 +54,27 @@ export declare class InstanceCache {
     constructor(config?: PoolConfig, modelRegistry?: ModelRegistry);
     private resolveModel;
     get<T extends Model = Model>(id: string): T | undefined;
+    /**
+     * Look a row up **within one model**.
+     *
+     * The pool is a single id space: `get(id)` returns whatever row carries that
+     * id, whatever model it belongs to. That is the correct storage shape — ids
+     * are globally unique, the same premise as Relay's Global Object
+     * Identification — but it means an *untyped* lookup cannot stand in for a
+     * typed one. Apollo and EmberData avoid the question by keying their identity
+     * maps on `Type:id`; with unique ids the equivalent guarantee comes from
+     * stating the expected model at the lookup instead.
+     *
+     * Returns `undefined` for a row belonging to another model: from the asking
+     * model's perspective that id is simply absent. Callers that must tell "not
+     * here" apart from "here, but another model's" should compare against
+     * {@link get}.
+     *
+     * Prefer this over `get()` anywhere the caller knows which model it wants —
+     * `get()` returning another model's row has caused three product bugs, most
+     * recently a resize gesture that reverted after every commit.
+     */
+    getOfType<T extends Model = Model>(id: string, modelName: string): T | undefined;
     /**
      * Add model with deduplication support
      */
@@ -97,7 +122,7 @@ export declare class InstanceCache {
      * data. Cleaner than `createFromData({ __typename, ...data })` — the
      * typename lives in the arg list, not hidden inside the data object.
      *
-     * Used for optimistic local writes: `pool.create('Slide', { id, deckId, ... })`.
+     * Used for optimistic local writes: `pool.create('Section', { id, reportId, ... })`.
      * For hydration from server deltas (where `__typename` already rides on
      * the payload), use `createFromData(data)` directly — that path is kept
      * because the wire format attaches the discriminator to the data itself.
@@ -178,8 +203,8 @@ export declare class InstanceCache {
      * Register a foreign key field for indexing on a model type.
      * Call once during app initialization (e.g., after model registration).
      *
-     * Example: registerForeignKey('SlideLayer', 'slideId')
-     * This enables getByForeignKey('SlideLayer', 'slideId', someSlideId) → O(1) lookup
+     * Example: registerForeignKey('Block', 'sectionId')
+     * This enables getByForeignKey('Block', 'sectionId', someSectionId) → O(1) lookup
      */
     registerForeignKey(modelName: string, fieldName: string): void;
     /**