@abloatai/ablo 0.25.0 → 0.27.0

package/dist/Database.js

@@ -1,9 +1,13 @@
 /**
- * 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';
+import { ModelRegistry } from './ModelRegistry.js';
 import { LoadStrategy } from './types/index.js';
 import { getContext } from './context.js';
 import { AbloConnectionError, AbloValidationError } from './errors.js';
@@ -21,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.
@@ -105,7 +109,7 @@ export class Database {
     logPreservedFields(modelName, modelId, existing, delta) {
         if (modelName === 'Activity')
             return;
-        const requiredFields = this.essentialFields[modelName] || [];
+        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', {
@@ -155,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')
@@ -176,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;
             }
@@ -271,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,
@@ -311,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',
@@ -324,11 +324,13 @@ export class Database {
             type,
             modelsToLoad,
             lastSyncId,
-            syncGroups: metadata?.syncGroups || [],
+            syncGroups: metadata?.syncGroups ?? [],
         };
     }
     /**
-     * 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
@@ -347,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,
@@ -360,16 +362,17 @@ export class Database {
                 lastSyncId: bootstrapData.lastSyncId,
                 hasModels: !!bootstrapData.models,
                 hasDeltas: !!bootstrapData.deltas,
-                deltaCount: bootstrapData.deltaCount || 0,
+                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();
             }
             // Handle partial bootstrap (delta batch)
             if (bootstrapData.type === 'partial') {
-                const deltas = bootstrapData.deltas || [];
+                const deltas = bootstrapData.deltas ?? [];
                 getContext().logger.info('Processing partial bootstrap with delta batch', {
                     deltaCount: deltas.length,
                     fromSyncId: requirements.lastSyncId,
@@ -378,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;
@@ -500,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;
@@ -518,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;
@@ -571,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,
@@ -618,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 };
@@ -658,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
-     *
-     * 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.
      */
     async processDeltaBatch(deltas) {
         if ((!this.workspaceDb && !this.inMemory) || this.isClosing || deltas.length === 0) {
@@ -721,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}`;
@@ -748,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;
@@ -772,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' ||
@@ -783,7 +774,7 @@ export class Database {
                 const deleteSyncId = deleteSyncIds.get(key);
                 if (deleteSyncId !== undefined) {
                     // DELETE exists for this entity
-                    const deltaSyncId = delta.syncId || 0;
+                    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)', {
@@ -822,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
@@ -848,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...`);
@@ -923,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,
@@ -938,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,
@@ -989,12 +980,12 @@ export class Database {
                 }
                 // Wait for transaction to complete
                 await new Promise((resolve, reject) => {
-                    tx.oncomplete = () => resolve();
-                    tx.onerror = () => reject(tx.error);
+                    tx.oncomplete = () => { resolve(); };
+                    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
@@ -1103,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;
@@ -1122,13 +1107,7 @@ export class Database {
             return 0;
         }
         const metadata = await this.databaseManager.getWorkspaceMetadata(this.workspaceDb);
-        return metadata?.lastSyncId || 0;
-    }
-    async getVersionVector() {
-        if (!this.workspaceDb)
-            return null;
-        const metadata = await this.databaseManager.getWorkspaceMetadata(this.workspaceDb);
-        return (metadata?.versions || null);
+        return metadata?.lastSyncId ?? 0;
     }
     async updateWorkspaceMetadata(metadata) {
         // In-memory mode: store in local variable

package/dist/{ObjectPool.d.ts → InstanceCache.d.ts}

@@ -1,8 +1,10 @@
 /**
- * ObjectPool - In-memory model cache with deduplication
- *
- * Pure memory management without database or registry dependencies.
- * Uses static ModelRegistry for model class lookup only.
+ * InstanceCache is the in-memory cache of live model instances, keyed by id and
+ * deduplicated so each entity has a single instance. It maintains type and
+ * foreign-key indexes for fast lookups, evicts entries under a size cap, and
+ * notifies subscribers and query views as models are added, updated, or
+ * removed. It holds a {@link ModelRegistry} to map between model names and
+ * constructor classes, but performs no persistence of its own.
  */
 import { Model } from './Model.js';
 import { ModelRegistry } from './ModelRegistry.js';
@@ -23,9 +25,10 @@ interface DeltaInfo {
     syncId?: number;
 }
 /**
- * ObjectPool - Pure in-memory model cache with deduplication
+ * The in-memory cache of model instances, keyed by id and deduplicated so each
+ * entity resolves to a single instance.
  */
-export declare class ObjectPool {
+export declare class InstanceCache {
     private entries;
     private typeIndex;
     private accessTimes;
@@ -45,12 +48,6 @@ export declare class ObjectPool {
     subscribe<T extends Model>(modelClass: ModelConstructor<T>, callback: (model: T) => void): () => void;
     private notifySubscribers;
     constructor(config?: PoolConfig, modelRegistry?: ModelRegistry);
-    /**
-     * 🔧 PRODUCTION FIX: Initialize type indexes for all registered models
-     * This prevents the "No type index found" error in production where constructor
-     * references are lost due to minification.
-     */
-    private initializeTypeIndexes;
     private resolveModel;
     get<T extends Model = Model>(id: string): T | undefined;
     /**
@@ -115,7 +112,7 @@ export declare class ObjectPool {
         /**
          * Throw (instead of warn + return null) when the wire names a model
          * this client never registered. Passed by the developer-await read
-         * path (`HydrationCoordinator`'s network leg) so a schema collision
+         * path (`OnDemandLoader`'s network leg) so a schema collision
          * — the org's pushed schema names `Document` but this client only
          * registered `documents` — surfaces AT the row that failed, with the
          * known-model list and `ablo status` pointer, instead of bubbling up