@abloatai/ablo 0.26.0 → 0.27.0

package/dist/Database.d.ts

@@ -1,11 +1,14 @@
 /**
- * Database - Simplified persistence layer
- * Fixed bootstrap triggering and data flow
+ * The local persistence layer for synced models. It stores rows in the
+ * browser's IndexedDB (or in-memory maps when run headlessly), applies inbound
+ * deltas to that store, and fetches the bootstrap snapshot from your sync
+ * server. {@link BaseSyncedStore} drives it, and {@link InstanceCache} holds the
+ * in-memory mirror of what this class persists.
  */
 import { type DatabaseInfo, type WorkspaceMetadata } from './core/DatabaseManager.js';
 import { ModelRegistry } from './ModelRegistry.js';
 import { LoadStrategy } from './types/index.js';
-import type { BootstrapHelper, BootstrapData } from './sync/BootstrapHelper.js';
+import type { BootstrapFetcher, BootstrapData } from './sync/BootstrapFetcher.js';
 import { InMemoryObjectStore } from './adapters/inMemoryStorage.js';
 /** Generic record type for model data */
 type ModelData = Record<string, unknown>;
@@ -43,19 +46,17 @@ interface PersistedTransaction {
     [key: string]: unknown;
 }
 /**
- * Bootstrap strategies (aligned with Linear's architecture):
+ * How a session establishes its baseline state at startup.
  *
- * 'full' - Full bootstrap from server
- *   - Fetch complete snapshot from server
- *   - Clear IndexedDB
- *   - Load snapshot data
- *   - Use snapshot's lastSyncId
+ * 'full' — Fetch a complete snapshot from the server, clear the local store,
+ *   load the snapshot, and adopt its `lastSyncId`.
  *
- * 'local' - Local-only bootstrap (skip server fetch)
- *   - Use existing IndexedDB data
- *   - Hydrate ObjectPool from IndexedDB
- *   - Connect WebSocket with stored lastSyncId
- *   - Receive deltas from lastSyncId+1 onwards
+ * 'partial' — Fetch only the deltas since the stored `lastSyncId` and apply
+ *   them on top of the existing local data.
+ *
+ * 'local' — Skip the server entirely: hydrate the {@link InstanceCache} from the
+ *   local store, connect the WebSocket with the stored `lastSyncId`, and
+ *   receive deltas from there onward. Used when offline with valid local data.
  */
 export type BootstrapType = 'full' | 'partial' | 'local';
 export interface BootstrapRequirements {
@@ -67,7 +68,7 @@ export interface BootstrapRequirements {
 export interface BootstrapResult {
     modelsLoaded: number;
     modelsStored: number;
-    /** The raw bootstrap response — callers can apply models directly to ObjectPool */
+    /** The raw bootstrap response — callers can apply models directly to InstanceCache */
     bootstrapData: BootstrapData;
     /**
      * Results of applying partial-bootstrap deltas to IDB. Present only when
@@ -90,13 +91,13 @@ export declare class Database {
     private modelRegistry;
     private bootstrapHelper;
     /** The pre-configured query helper for lazy-loading data from the sync server. */
-    get helper(): BootstrapHelper;
+    get helper(): BootstrapFetcher;
     /**
-     * PURE scoped snapshot fetch for hydrate-on-enter (P4). Returns the FULL
-     * current rows of the given sync groups, with NO side effects — unlike
+     * Fetch the current rows of the given sync groups as a side-effect-free
+     * snapshot, used to hydrate a scope as the user enters it. Unlike
      * {@link bootstrapFromServer}, it does not persist to IndexedDB and does not
-     * touch the connection's `subscribedSyncGroups` (which the shrinkage check
-     * owns). The caller applies the result to the pool via the SCOPED apply path.
+     * change the connection's subscribed sync groups. The caller applies the
+     * result to the pool through the scoped apply path.
      */
     fetchScopedBootstrapData(syncGroups: readonly string[]): Promise<BootstrapData>;
     private currentDbInfo;
@@ -128,7 +129,7 @@ export declare class Database {
     private inMemoryStores;
     /** In-memory workspace metadata when inMemory=true. */
     private inMemoryMetadata;
-    constructor(modelRegistry: ModelRegistry, bootstrapHelper: BootstrapHelper, options?: {
+    constructor(modelRegistry: ModelRegistry, bootstrapHelper: BootstrapFetcher, options?: {
         inMemory?: boolean;
     });
     /**
@@ -150,17 +151,14 @@ export declare class Database {
     private logPreservedFields;
     open(userId: string, organizationId: string, version?: number): Promise<void>;
     /**
-     * Compact a record before persisting to IndexedDB
-     * - Removes null/undefined fields
-     * - Removes empty arrays and empty objects
-     * - Drops redundant fields: __typename, __class, clientId, syncStatus
-     *
-     * ARCHITECTURE: By design, this method receives plain objects, not MobX observables:
-     * - WebSocket deltas: Already JSON-parsed (SyncedStore.ts:889)
-     * - Optimistic updates: Models call toJSON() which uses toJS() (SlideLayer.ts:224)
-     * - Bootstrap data: Plain JSON from server
+     * Shrink a record before persisting it. Drops `undefined` fields, empty
+     * arrays, empty objects, and the redundant markers `__typename`, `__class`,
+     * `clientId`, and `syncStatus`. Explicit `null` values are preserved, since
+     * a null is a meaningful "clear this field" in a nullable column.
      *
-     * Note: We do NOT drop required defaults; server provides them.
+     * By design this receives plain objects, never live observables: WebSocket
+     * deltas arrive already parsed, optimistic updates come through `toJSON()`,
+     * and bootstrap data is plain JSON from the server.
      */
     private compactRecord;
     /**
@@ -174,7 +172,9 @@ export declare class Database {
      */
     requiredBootstrap(): Promise<BootstrapRequirements>;
     /**
-     * Bootstrap database with data from Go server
+     * Fetch a bootstrap snapshot (or delta batch) from the sync server and load
+     * it into the local store, then return a {@link BootstrapResult} the caller
+     * applies to the {@link InstanceCache}.
      */
     bootstrapFromServer(requirements: BootstrapRequirements, 
     /** Full sync-group subscription list — what the WS subscribes to
@@ -183,17 +183,16 @@ export declare class Database {
      *  team-derived groups. */
     syncGroups: readonly string[], onProgress?: (loaded: number) => void): Promise<BootstrapResult>;
     /**
-     * Process incoming delta from WebSocket - simplified
+     * Apply a single inbound delta from the WebSocket to the local store.
      *
-     * ⚠️ PERFORMANCE NOTE: This method is called for each individual delta.
-     * For batch processing, use processDeltaBatch() instead to avoid
-     * transaction overhead (2x transactions per delta = major bottleneck).
+     * This handles one delta at a time. To apply several, prefer
+     * {@link processDeltaBatch}, which commits them in one IndexedDB transaction
+     * rather than two transactions per delta.
      *
-     * 📝 PARTIAL DELTA PATTERN:
-     * - Server sends only changed fields: {id, position: {...}, updatedAt}
-     * - UPDATE deltas are MERGED with existing records: {...existing, ...delta}
-     * - This preserves fields not included in the delta (e.g., deckId, title)
-     * - Explicit null values ARE preserved: {position: null} clears the field
+     * 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,
+     * clearing that field.
      */
     processDelta(delta: {
         syncId?: number;
@@ -214,27 +213,20 @@ export declare class Database {
         data?: ModelData | null;
     }>;
     /**
-     * ✅ PERFORMANCE FIX: Process multiple deltas in a single IndexedDB transaction
-     *
-     * This method dramatically improves sync performance by:
-     * 1. Batch-reading all existing records for UPDATEs (outside transaction for speed)
-     * 2. Opening a single transaction per store for all writes
-     * 3. Merging UPDATE deltas with existing data to preserve unmodified fields
-     * 4. Updating metadata only once at the end with highest syncId
-     *
-     * Performance impact: 186 deltas goes from ~372 transactions to just 1 transaction
+     * Apply many deltas to the local store in as few IndexedDB transactions as
+     * possible. Deltas are grouped by store, and each store's writes commit in a
+     * single transaction, so a batch of 186 deltas becomes roughly one
+     * transaction per store instead of two per delta.
      *
-     * 📝 PARTIAL DELTA MERGE PATTERN:
-     * - UPDATE deltas contain only changed fields
-     * - We merge with existing: {...existing, ...delta}
-     * - Preserves deckId, title, settings etc. when updating just position
-     * - Handles explicit null: {field: null} clears the field correctly
+     * The method reads the existing records for update deltas up front, then
+     * merges each update onto its existing record so fields the delta omits are
+     * preserved and an explicit null still clears its field. It advances the
+     * persisted sync cursor once, to the highest committed sync id.
      *
-     * 🔄 LINEAR-STYLE CONFLICT RESOLUTION:
-     * - Builds a map of DELETE deltas with their syncIds
-     * - Before processing UPDATE/INSERT, checks for DELETE with higher syncId
-     * - Skips stale updates for entities that will be/were deleted
-     * - Prevents 404 errors from fetching already-deleted entities
+     * Conflict resolution follows a delete-wins rule: it first indexes the
+     * delete deltas by entity, then skips any insert or update whose sync id is
+     * at or below a delete for the same entity. This avoids resurrecting a
+     * deleted entity and avoids fetching one that no longer exists.
      */
     processDeltaBatch(deltas: {
         syncId?: number;
@@ -268,7 +260,7 @@ export declare class Database {
         /**
          * Highest syncId whose IDB store transaction actually committed in this
          * batch. The runtime delta cursor (WS `lastSyncId`, server-side
-         * `lastAckedSyncId`) must only advance to THIS value — not the input
+         * `lastAckedSyncId`) must only advance to this value — not the input
          * batch's range max — or it diverges from the persisted view and the
          * next catch-up request skips the un-persisted gap forever. Mirrors
          * the metadata-cursor invariant at `updateWorkspaceMetadata` below.
@@ -283,13 +275,7 @@ export declare class Database {
     /** Get data by index. `value` is an IDB key — string, number, Date,
      *  BufferSource, or array thereof. */
     getDataByIndex(modelName: string, indexName: string, value: IDBValidKey): Promise<ModelData[]>;
-    /**
-     * Update workspace metadata
-     */
-    /**
-     * Get the last sync ID from workspace metadata
-     */
-    /** Read workspace metadata from IDB (returns null if db not open). */
+    /** Read workspace metadata from IndexedDB. Returns null when the database is not open. */
     getWorkspaceMetadata(): Promise<WorkspaceMetadata | null>;
     getLastSyncId(): Promise<number>;
     updateWorkspaceMetadata(metadata: Partial<WorkspaceMetadata>): Promise<void>;

package/dist/Database.js

@@ -1,6 +1,9 @@
 /**
- * Database - Simplified persistence layer
- * Fixed bootstrap triggering and data flow
+ * The local persistence layer for synced models. It stores rows in the
+ * browser's IndexedDB (or in-memory maps when run headlessly), applies inbound
+ * deltas to that store, and fetches the bootstrap snapshot from your sync
+ * 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';
@@ -22,11 +25,11 @@ export class Database {
         return this.bootstrapHelper;
     }
     /**
-     * PURE scoped snapshot fetch for hydrate-on-enter (P4). Returns the FULL
-     * current rows of the given sync groups, with NO side effects — unlike
+     * Fetch the current rows of the given sync groups as a side-effect-free
+     * snapshot, used to hydrate a scope as the user enters it. Unlike
      * {@link bootstrapFromServer}, it does not persist to IndexedDB and does not
-     * touch the connection's `subscribedSyncGroups` (which the shrinkage check
-     * owns). The caller applies the result to the pool via the SCOPED apply path.
+     * change the connection's subscribed sync groups. The caller applies the
+     * result to the pool through the scoped apply path.
      */
     async fetchScopedBootstrapData(syncGroups) {
         // No lastSyncId → a full snapshot of exactly these groups.
@@ -156,17 +159,14 @@ export class Database {
         getContext().logger.info(`Database opened: ${this.currentDbInfo.name} (${readiness.readyStores.length}/${readiness.totalStores} stores ready)`);
     }
     /**
-     * Compact a record before persisting to IndexedDB
-     * - Removes null/undefined fields
-     * - Removes empty arrays and empty objects
-     * - Drops redundant fields: __typename, __class, clientId, syncStatus
+     * Shrink a record before persisting it. Drops `undefined` fields, empty
+     * arrays, empty objects, and the redundant markers `__typename`, `__class`,
+     * `clientId`, and `syncStatus`. Explicit `null` values are preserved, since
+     * a null is a meaningful "clear this field" in a nullable column.
      *
-     * ARCHITECTURE: By design, this method receives plain objects, not MobX observables:
-     * - WebSocket deltas: Already JSON-parsed (SyncedStore.ts:889)
-     * - Optimistic updates: Models call toJSON() which uses toJS() (SlideLayer.ts:224)
-     * - Bootstrap data: Plain JSON from server
-     *
-     * Note: We do NOT drop required defaults; server provides them.
+     * By design this receives plain objects, never live observables: WebSocket
+     * deltas arrive already parsed, optimistic updates come through `toJSON()`,
+     * and bootstrap data is plain JSON from the server.
      */
     compactRecord(_modelName, data) {
         if (!data || typeof data !== 'object')
@@ -177,8 +177,8 @@ export class Database {
             if (key === '__typename' || key === '__class' || key === 'clientId' || key === 'syncStatus') {
                 continue;
             }
-            // FIXED: Only skip undefined, preserve explicit null values
-            // Null is semantically meaningful in Prisma schemas (nullable fields)
+            // Skip only `undefined`; preserve explicit `null`, which is a
+            // meaningful value for a nullable column.
             if (value === undefined) {
                 continue;
             }
@@ -272,26 +272,24 @@ export class Database {
         // point). Invalid → 0 → full bootstrap, the safe degradation.
         const metadataLastSyncId = syncPositionSchema.shape.persisted.safeParse(metadata?.lastSyncId).data ?? 0;
         const dataAge = metadata?.updatedAt ? Date.now() - metadata.updatedAt.getTime() : Infinity;
-        // ── Zero-style cache-validity check ──────────────────────────
+        // ── Cache-validity check ─────────────────────────────────────
         //
         // The cursor (lastSyncId) is only valid if the data it refers to
-        // actually exists in the stores. If IDB was cleared (or this is a
-        // fresh in-memory session), the metadata's lastSyncId is stale —
-        // sending it to the server would trigger a partial bootstrap that
-        // returns zero deltas because the gap is 0, leaving the client
-        // with an empty ObjectPool.
+        // actually exists in the stores. If the local store was cleared (or
+        // this is a fresh in-memory session), the metadata's lastSyncId is
+        // stale — sending it to the server would trigger a partial bootstrap
+        // that returns zero deltas because the gap is 0, leaving the client
+        // with an empty InstanceCache.
         //
-        // Zero solves this by co-locating the cursor with the cached data:
-        // if the data is gone, the cursor is gone. We achieve the same
-        // property by sampling the actual stores — if they're empty, the
-        // cursor is meaningless regardless of what metadata claims.
+        // The fix is to sample the actual stores: if they hold no rows, the
+        // cursor is meaningless regardless of what the metadata claims.
         const dataExists = this.inMemory
             ? false // In-memory mode: no persistent data across sessions
             : await this.storeManager.hasAnyData();
         // The effective lastSyncId: only trust the metadata cursor when
         // we've confirmed the data it refers to actually exists in the stores.
         const lastSyncId = dataExists ? metadataLastSyncId : 0;
-        // 🔍 DIAGNOSTIC: Log database state
+        // Log the resolved database state for diagnostics.
         getContext().logger.debug('[Database.requiredBootstrap] State check', {
             readinessReady: readiness.ready,
             hasMetadata: !!metadata,
@@ -312,7 +310,8 @@ export class Database {
             getContext().logger.info('Offline detected with local data - using local bootstrap');
         }
         else {
-            // SERVER-AUTHORITATIVE: Always use full bootstrap when online.
+            // 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', {
                 reason: offline ? 'offline_no_data' : 'server_authoritative',
@@ -329,7 +328,9 @@ export class Database {
         };
     }
     /**
-     * Bootstrap database with data from Go server
+     * Fetch a bootstrap snapshot (or delta batch) from the sync server and load
+     * it into the local store, then return a {@link BootstrapResult} the caller
+     * applies to the {@link InstanceCache}.
      */
     async bootstrapFromServer(requirements, 
     /** Full sync-group subscription list — what the WS subscribes to
@@ -348,8 +349,8 @@ export class Database {
             modelsToLoad: requirements.modelsToLoad,
         });
         try {
-            // ✅ FETCH FIRST (before any destructive operations)
-            // This prevents data loss if the network request fails
+            // 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)', {
                 type: requirements.type,
@@ -363,8 +364,9 @@ export class Database {
                 hasDeltas: !!bootstrapData.deltas,
                 deltaCount: bootstrapData.deltaCount ?? 0,
             });
-            // ✅ Only clear AFTER successful fetch (transactional safety)
-            // IMPORTANT: Clear if the SERVER says it's a full snapshot, regardless of what we asked.
+            // Clear only after a successful fetch, for transactional safety.
+            // Clear when the server says the response is a full snapshot,
+            // regardless of what type was requested.
             if (bootstrapData.type === 'full') {
                 await this.clear();
             }
@@ -379,7 +381,7 @@ export class Database {
                 // Apply deltas to IndexedDB using processDeltaBatch for better performance.
                 // Capture the return value so the pool can be updated by the caller —
                 // without this, partial-bootstrap DELETEs persist to IDB but don't
-                // evict entities from the in-memory ObjectPool, leaving ghost rows
+                // evict entities from the in-memory InstanceCache, leaving ghost rows
                 // visible on the canvas until a full reload rebuilds the pool.
                 let deltasApplied = 0;
                 let deltaResults;
@@ -501,17 +503,16 @@ export class Database {
     }
     // bootstrapSpecificModels removed per request
     /**
-     * Process incoming delta from WebSocket - simplified
+     * Apply a single inbound delta from the WebSocket to the local store.
      *
-     * ⚠️ PERFORMANCE NOTE: This method is called for each individual delta.
-     * For batch processing, use processDeltaBatch() instead to avoid
-     * transaction overhead (2x transactions per delta = major bottleneck).
+     * This handles one delta at a time. To apply several, prefer
+     * {@link processDeltaBatch}, which commits them in one IndexedDB transaction
+     * rather than two transactions per delta.
      *
-     * 📝 PARTIAL DELTA PATTERN:
-     * - Server sends only changed fields: {id, position: {...}, updatedAt}
-     * - UPDATE deltas are MERGED with existing records: {...existing, ...delta}
-     * - This preserves fields not included in the delta (e.g., deckId, title)
-     * - Explicit null values ARE preserved: {position: null} clears the field
+     * 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,
+     * clearing that field.
      */
     async processDelta(delta) {
         const { actionType, modelName, modelId, data, syncId } = delta;
@@ -519,7 +520,7 @@ export class Database {
         if (!store) {
             return { action: 'verify', modelName, modelId };
         }
-        // Best-practice gating: ignore already-applied deltas by comparing with persisted lastSyncId
+        // Idempotency gate: ignore already-applied deltas by comparing with the persisted lastSyncId
         try {
             const lastApplied = await this.getLastSyncId();
             const incomingId = typeof syncId === 'number' ? syncId : undefined;
@@ -572,11 +573,12 @@ export class Database {
                 return { action: 'add', modelName, modelId, data: compacted };
             }
             case 'U': {
-                // ✅ UPDATE: MUST merge with existing record (partial delta pattern)
-                // Read existing record first
+                // Update: merge onto the existing record (partial-delta pattern).
+                // Read the existing record first.
                 const existing = await store.get(modelId);
-                // CRITICAL FIX: Skip UPDATE if there's no existing record to merge with
-                // Creating a record from partial UPDATE data causes corruption (missing deckId, etc.)
+                // 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).
                 if (!existing) {
                     getContext().observability.breadcrumb('Skipping UPDATE delta - no existing record to merge with', 'sync.database', 'warning', {
                         modelName,
@@ -619,7 +621,7 @@ export class Database {
                     getContext().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 ObjectPool inconsistently
+                    // Surface failure so caller does not mutate InstanceCache inconsistently
                     throw err;
                 }
                 return { action: 'remove', modelName, modelId };
@@ -659,27 +661,20 @@ export class Database {
         }
     }
     /**
-     * ✅ PERFORMANCE FIX: Process multiple deltas in a single IndexedDB transaction
-     *
-     * This method dramatically improves sync performance by:
-     * 1. Batch-reading all existing records for UPDATEs (outside transaction for speed)
-     * 2. Opening a single transaction per store for all writes
-     * 3. Merging UPDATE deltas with existing data to preserve unmodified fields
-     * 4. Updating metadata only once at the end with highest syncId
+     * Apply many deltas to the local store in as few IndexedDB transactions as
+     * possible. Deltas are grouped by store, and each store's writes commit in a
+     * single transaction, so a batch of 186 deltas becomes roughly one
+     * transaction per store instead of two per delta.
      *
-     * Performance impact: 186 deltas goes from ~372 transactions to just 1 transaction
+     * The method reads the existing records for update deltas up front, then
+     * merges each update onto its existing record so fields the delta omits are
+     * preserved and an explicit null still clears its field. It advances the
+     * persisted sync cursor once, to the highest committed sync id.
      *
-     * 📝 PARTIAL DELTA MERGE PATTERN:
-     * - UPDATE deltas contain only changed fields
-     * - We merge with existing: {...existing, ...delta}
-     * - Preserves deckId, title, settings etc. when updating just position
-     * - Handles explicit null: {field: null} clears the field correctly
-     *
-     * 🔄 LINEAR-STYLE CONFLICT RESOLUTION:
-     * - Builds a map of DELETE deltas with their syncIds
-     * - Before processing UPDATE/INSERT, checks for DELETE with higher syncId
-     * - Skips stale updates for entities that will be/were deleted
-     * - Prevents 404 errors from fetching already-deleted entities
+     * Conflict resolution follows a delete-wins rule: it first indexes the
+     * delete deltas by entity, then skips any insert or update whose sync id is
+     * at or below a delete for the same entity. This avoids resurrecting a
+     * deleted entity and avoids fetching one that no longer exists.
      */
     async processDeltaBatch(deltas) {
         if ((!this.workspaceDb && !this.inMemory) || this.isClosing || deltas.length === 0) {
@@ -722,14 +717,11 @@ export class Database {
         }
         // Prepare results aligned with input order
         const results = new Array(deltas.length);
-        // ========================================================================
-        // LINEAR-STYLE CONFLICT RESOLUTION: Build DELETE syncId index
-        // ========================================================================
-        // Per Linear's architecture: "If the syncId of the deleting action is larger,
-        // the model will not be created." This prevents processing stale UPDATE deltas
-        // for entities that have been cascade-deleted (where DELETE delta exists).
-        // ========================================================================
-        const deleteSyncIds = new Map(); // key: "ModelName:modelId" -> DELETE syncId
+        // Build a delete index for conflict resolution. When a delete has a sync
+        // id at or above a later insert or update for the same entity, that entity
+        // is not (re)created — which drops stale updates for cascade-deleted
+        // entities.
+        const deleteSyncIds = new Map(); // key: "ModelName:modelId" -> delete syncId
         for (const delta of deltas) {
             if (delta.actionType === 'D' && delta.syncId) {
                 const key = `${delta.modelName}:${delta.modelId}`;
@@ -749,18 +741,17 @@ export class Database {
         }
         // Group deltas by store for efficient transaction management.
         //
-        // We intentionally track TWO highwater marks: `highestSyncId` for the
-        // total range seen, and `highestPersistedSyncId` accumulated only from
-        // deltas whose store transaction actually succeeded. The cursor
-        // advance (at `updateWorkspaceMetadata`) uses ONLY the persisted one.
+        // The method tracks two high-water marks: `highestSyncId` for the total
+        // range seen, and `highestPersistedSyncId`, accumulated only from deltas
+        // whose store transaction actually committed. The cursor advance (at
+        // `updateWorkspaceMetadata`) uses only the persisted one.
         //
-        // Without this split, a single store-level IDB failure (e.g. compact
-        // record missing required field, validation abort) silently advances
-        // the cursor past deltas that never wrote to IDB. Next partial
-        // bootstrap asks "what's new since {advanced cursor}?" and the
-        // skipped rows fall into the already-seen range forever — the
-        // observed "postgres has the deck, IDB doesn't, full reload can't
-        // recover it" failure mode.
+        // Without this split, a single store-level failure (a compacted record
+        // missing a required field, a validation abort) would advance the cursor
+        // past deltas that never wrote to IndexedDB. The next partial bootstrap
+        // would ask "what's new since {advanced cursor}?", the skipped rows would
+        // fall into the already-seen range forever, and the local store would stay
+        // permanently behind the server with no way to recover on reload.
         const deltasByStore = new Map();
         let highestSyncId = 0;
         let highestPersistedSyncId = 0;
@@ -773,9 +764,8 @@ export class Database {
             if (typeof deltaSyncIdNum === 'number' && !isNaN(deltaSyncIdNum) && deltaSyncIdNum > highestSyncId) {
                 highestSyncId = deltaSyncIdNum;
             }
-            // ========================================================================
-            // CONFLICT CHECK: Skip UPDATE/INSERT if DELETE exists with higher syncId
-            // ========================================================================
+            // Conflict check: skip an insert or update when a delete for the same
+            // entity has an equal or higher sync id.
             if (delta.actionType === 'U' ||
                 delta.actionType === 'I' ||
                 delta.actionType === 'C' ||
@@ -823,8 +813,8 @@ export class Database {
             if (!store)
                 continue;
             try {
-                // ✅ BEST PRACTICE: Batch read-modify-write pattern
-                // Step 1: Identify which deltas need existing data (UPDATEs)
+                // Batch read-modify-write.
+                // Step 1: Identify which deltas need existing data (updates)
                 const updateDeltas = storeDeltas.filter(({ delta }) => delta.actionType === 'U');
                 const updateIds = updateDeltas.map(({ delta }) => delta.modelId);
                 // Step 2: Batch read all existing records in a SINGLE IDB transaction
@@ -849,8 +839,9 @@ export class Database {
                         }
                     }
                 }
-                // ✅ SELF-HEALING: Fetch missing records for UPDATE deltas
-                // Track IDs that failed to fetch (404 = entity deleted, skip the delta)
+                // Self-heal by fetching missing records for update deltas.
+                // Track ids that failed to fetch (a 404 means the entity was deleted,
+                // 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...`);
@@ -924,13 +915,11 @@ export class Database {
                             });
                             break;
                         case 'U': {
-                            // ✅ UPDATE: Merge delta with existing record (already fetched)
+                            // Update: merge the delta onto the existing record (already fetched).
                             const existing = existingRecords.get(modelId);
-                            // ========================================================================
-                            // SKIP STALE DELTAS: If entity doesn't exist locally AND failed to fetch
-                            // from server (404), this is a stale UPDATE for a deleted entity.
-                            // Per Linear's architecture, skip it instead of creating incomplete data.
-                            // ========================================================================
+                            // Skip a stale update: if the entity is neither in the local
+                            // 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', {
                                     modelName,
@@ -939,8 +928,9 @@ export class Database {
                                 stagedResults.push({ action: 'verify', modelName, modelId, idx });
                                 break; // Skip this delta
                             }
-                            // CRITICAL FIX: Skip UPDATE if there's no existing record to merge with
-                            // Creating a record from partial UPDATE data causes corruption (missing deckId, etc.)
+                            // 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).
                             if (!existing) {
                                 getContext().observability.breadcrumb('Batch: Skipping UPDATE delta - no existing record', 'sync.database', 'warning', {
                                     modelName,
@@ -994,8 +984,8 @@ export class Database {
                     tx.onerror = () => { reject(tx.error); };
                 });
                 // Only commit staged results to the global results if the transaction succeeded.
-                // Also advance `highestPersistedSyncId` ONLY for deltas in this successful tx
-                // — so the cursor can't advance past rows that never wrote to IDB.
+                // Advance `highestPersistedSyncId` only for deltas in this successful
+                // transaction, so the cursor can't advance past rows that never wrote to IDB.
                 for (const r of stagedResults) {
                     // Resolve the originating delta so we can carry its
                     // transactionId through to the result. Echo detection in
@@ -1104,13 +1094,7 @@ export class Database {
         const store = this.getRequiredStore(modelName);
         return await store.getAllFromIndex(indexName, value);
     }
-    /**
-     * Update workspace metadata
-     */
-    /**
-     * Get the last sync ID from workspace metadata
-     */
-    /** Read workspace metadata from IDB (returns null if db not open). */
+    /** Read workspace metadata from IndexedDB. Returns null when the database is not open. */
     async getWorkspaceMetadata() {
         if (this.inMemory)
             return this.inMemoryMetadata;