@abloatai/humans 0.64.4 → 0.64.5

package/dist/local/Database.js

@@ -472,6 +472,9 @@ export class Database {
                     }));
                     // Use batch processing for better performance
                     const batch = await this.processDeltaBatch(formattedDeltas);
+                    if (batch.persistedSyncId < Math.max(...formattedDeltas.map(delta => delta.syncId))) {
+                        throw new Error('Could not persist all bootstrap changes; local storage must recover before retrying.');
+                    }
                     deltaResults = batch.results;
                     deltasApplied = formattedDeltas.length;
                     onProgress?.(deltasApplied);
@@ -518,38 +521,17 @@ export class Database {
                     this.runtime.logger.debug(`[Bootstrap] NO IDB STORE for ${modelName} — ${modelData.length} items DROPPED`);
                     continue;
                 }
-                let writeErrors = 0;
-                // Store all items to IndexedDB (compacted)
+                // Fail before marking the model or snapshot persisted. A dropped row
+                // must be retried, not hidden behind an advanced bootstrap cursor.
                 for (const item of modelData) {
-                    try {
-                        const compacted = this.compactRecord(modelName, item);
-                        await store.put(compacted);
-                        modelsStored++;
-                        modelsLoaded++;
-                        // Report progress every 10 items
-                        if (modelsLoaded % 10 === 0) {
-                            onProgress?.(modelsLoaded);
-                        }
-                    }
-                    catch (error) {
-                        writeErrors++;
-                        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);
+                    const compacted = this.compactRecord(modelName, item);
+                    await store.put(compacted);
+                    modelsStored++;
+                    modelsLoaded++;
+                    if (modelsLoaded % 10 === 0)
+                        onProgress?.(modelsLoaded);
                 }
-                catch { }
+                await this.setModelPersisted(modelName, true);
             }
             // Update workspace metadata with bootstrap snapshot's lastSyncId
             // Note: This method is only called for 'full' bootstrap (not 'local')
@@ -1142,6 +1124,7 @@ export class Database {
                 // Wait for transaction to complete
                 await new Promise((resolve, reject) => {
                     tx.oncomplete = () => { resolve(); };
+                    tx.onabort = () => { reject(tx.error ?? new DOMException('IndexedDB transaction aborted', 'AbortError')); };
                     tx.onerror = () => { reject(tx.error); };
                 });
                 // Only commit staged results to the global results if the transaction

package/dist/local/stores/DatabaseManager.js

@@ -142,6 +142,7 @@ export class DatabaseManager {
             tx.oncomplete = () => {
                 resolve();
             };
+            tx.onabort = () => { reject(indexedDbError(tx.error, 'registry transaction')); };
             tx.onerror = () => { reject(indexedDbError(tx.error, 'registry transaction')); };
             request.onerror = () => { reject(indexedDbError(request.error, 'registry write')); };
         });
@@ -270,6 +271,7 @@ export class DatabaseManager {
             const store = tx.objectStore('__meta');
             const request = store.put(metadata, 'metadata');
             tx.oncomplete = () => { resolve(); };
+            tx.onabort = () => { reject(indexedDbError(tx.error, 'workspace metadata transaction')); };
             tx.onerror = () => { reject(indexedDbError(tx.error, 'workspace metadata transaction')); };
             request.onerror = () => { reject(indexedDbError(request.error, 'workspace metadata write')); };
         });
@@ -304,6 +306,7 @@ export class DatabaseManager {
             };
             const request = store.put(persistenceData, modelName);
             tx.oncomplete = () => { resolve(); };
+            tx.onabort = () => { reject(indexedDbError(tx.error, 'model persistence transaction')); };
             tx.onerror = () => { reject(indexedDbError(tx.error, 'model persistence transaction')); };
             request.onerror = () => { reject(indexedDbError(request.error, 'model persistence write')); };
         });

package/dist/local/stores/ObjectStore.js

@@ -41,6 +41,7 @@ export class ObjectStore {
                 const store = tx.objectStore(this.storeName);
                 const request = store.add(data);
                 tx.oncomplete = () => { resolve(); };
+                tx.onabort = () => { reject(tx.error ?? new DOMException('IndexedDB transaction aborted', 'AbortError')); };
                 tx.onerror = () => { reject(tx.error ?? new Error('IndexedDB transaction error')); };
                 request.onerror = () => { reject(request.error ?? new Error('IndexedDB request error')); };
             }
@@ -93,6 +94,7 @@ export class ObjectStore {
                 const store = tx.objectStore(this.storeName);
                 const request = store.put(data);
                 tx.oncomplete = () => { resolve(); };
+                tx.onabort = () => { reject(tx.error ?? new DOMException('IndexedDB transaction aborted', 'AbortError')); };
                 tx.onerror = () => { reject(tx.error ?? new Error('IndexedDB transaction error')); };
                 request.onerror = () => { reject(request.error ?? new Error('IndexedDB request error')); };
             }
@@ -197,6 +199,7 @@ export class ObjectStore {
                 const store = tx.objectStore(this.storeName);
                 const request = store.delete(id);
                 tx.oncomplete = () => { resolve(); };
+                tx.onabort = () => { reject(tx.error ?? new DOMException('IndexedDB transaction aborted', 'AbortError')); };
                 tx.onerror = () => { reject(tx.error ?? new Error('IndexedDB transaction error')); };
                 request.onerror = () => { reject(request.error ?? new Error('IndexedDB request error')); };
             }
@@ -233,6 +236,7 @@ export class ObjectStore {
                 const store = tx.objectStore(this.storeName);
                 const request = store.clear();
                 tx.oncomplete = () => { resolve(); };
+                tx.onabort = () => { reject(tx.error ?? new DOMException('IndexedDB transaction aborted', 'AbortError')); };
                 tx.onerror = () => { reject(tx.error ?? new Error('IndexedDB transaction error')); };
                 request.onerror = () => { reject(request.error ?? new Error('IndexedDB request error')); };
             }

package/dist/local/sync/BootstrapFetcher.d.ts

@@ -141,6 +141,7 @@ export declare class BootstrapFetcher {
      * through its models {@link CHUNK_CONCURRENCY} at a time; each request may
      * spend `fetchTimeout` waiting for response headers and `stallTimeout`
      * waiting for the next body chunk, and may be retried `maxRetries` times.
+     * Capacity recovery has a separate `fetchTimeout` window.
      */
     get budgetMs(): number;
     get baseUrl(): string;

package/dist/local/sync/BootstrapFetcher.js

@@ -9,6 +9,7 @@
 import { globalRuntime } from '../context.js';
 import { AbloError, AbloSessionError, AbloConnectionError, translateHttpError, toAbloError, isRetryableCode } from '@abloatai/transaction/errors';
 import { withAuthHeaders } from '@abloatai/transaction/auth/credentialSource';
+import { retryAfterSecondsFromHeader } from '@abloatai/transaction/wire/rateLimit';
 import { classifySchemaDrift, describeSchemaDrift, } from './schemaDrift.js';
 // SyncObservability replaced by this.runtime.observability
 import { parseBootstrapResponse } from './schemas.js';
@@ -111,11 +112,13 @@ export class BootstrapFetcher {
      * through its models {@link CHUNK_CONCURRENCY} at a time; each request may
      * spend `fetchTimeout` waiting for response headers and `stallTimeout`
      * waiting for the next body chunk, and may be retried `maxRetries` times.
+     * Capacity recovery has a separate `fetchTimeout` window.
      */
     get budgetMs() {
         const models = Math.max(this.options.instantModels?.length ?? 1, 1);
         const waves = Math.ceil(models / CHUNK_CONCURRENCY);
-        return (waves * (this.options.fetchTimeout + this.options.stallTimeout) * this.options.maxRetries);
+        return (waves * ((this.options.fetchTimeout + this.options.stallTimeout) * this.options.maxRetries +
+            this.options.fetchTimeout));
     }
     get baseUrl() {
         return this.options.baseUrl;
@@ -447,7 +450,8 @@ export class BootstrapFetcher {
      */
     async fetchWithRetries(url, lane) {
         let lastError = null;
-        for (let attempt = 0; attempt < this.options.maxRetries; attempt++) {
+        const capacityDeadline = Date.now() + this.options.fetchTimeout;
+        for (let attempt = 0; attempt < this.options.maxRetries;) {
             try {
                 return await this.fetchOnce(url, lane);
             }
@@ -474,8 +478,17 @@ export class BootstrapFetcher {
                 this.runtime.observability.breadcrumb('Bootstrap fetch failed', 'sync.bootstrap', 'warning', {
                     attempt: attempt + 1,
                 });
-                if (attempt < this.options.maxRetries - 1) {
-                    await this.delay(this.options.retryDelay * Math.pow(2, attempt));
+                const delayMs = Math.max(this.options.retryDelay * Math.pow(2, attempt), (ablo.retryAfterSeconds ?? 0) * 1_000);
+                const capacity = ablo.code === 'instance_at_capacity' && ablo.retryAfterSeconds !== undefined;
+                // Admission has not run the request yet. Allow its recovery window
+                // without spending the attempts reserved for actual fetch failures.
+                if (ablo.retryAfterSeconds !== undefined && Date.now() + delayMs >= capacityDeadline) {
+                    throw ablo;
+                }
+                if (!capacity)
+                    attempt++;
+                if (capacity || attempt < this.options.maxRetries) {
+                    await this.delay(delayMs, lane);
                 }
             }
         }
@@ -609,7 +622,7 @@ export class BootstrapFetcher {
             // Translate the canonical envelope first so the server's specific code
             // and message survive (for example `api_key_required` or
             // `jwt_issuer_untrusted`).
-            const translated = translateHttpError(res.status, parsed ?? `Bootstrap fetch failed: ${res.status} ${res.statusText}`, res.headers.get('x-request-id') ?? undefined);
+            const translated = translateHttpError(res.status, parsed ?? `Bootstrap fetch failed: ${res.status} ${res.statusText}`, res.headers.get('x-request-id') ?? undefined, { retryAfterSeconds: retryAfterSecondsFromHeader(res.headers.get('retry-after')) });
             // Only a genuine session or JWT expiry — or a bare auth failure carrying
             // no structured code — should drive the sign-in redirect. A specific auth
             // code like `api_key_required` is not an expired session: signing in again
@@ -764,7 +777,7 @@ export class BootstrapFetcher {
             // Same code-aware handling as the primary bootstrap fetch: preserve the
             // server's specific code/message; only a genuine expiry (or a bare,
             // code-less auth failure) drives the sign-in redirect.
-            const translated = translateHttpError(response.status, parsed ?? `Bootstrap fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
+            const translated = translateHttpError(response.status, parsed ?? `Bootstrap fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined, { retryAfterSeconds: retryAfterSecondsFromHeader(response.headers.get('retry-after')) });
             if (translated.code === 'session_expired' ||
                 translated.code === 'jwt_expired' ||
                 ((response.status === 401 || response.status === 403) &&
@@ -828,7 +841,7 @@ export class BootstrapFetcher {
                     // Keep as string.
                 }
             }
-            throw translateHttpError(response.status, parsed ?? `Entity fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
+            throw translateHttpError(response.status, parsed ?? `Entity fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined, { retryAfterSeconds: retryAfterSecondsFromHeader(response.headers.get('retry-after')) });
         }
         return (await response.json());
     }
@@ -901,8 +914,22 @@ export class BootstrapFetcher {
     /**
      * Helper to delay execution
      */
-    delay(ms) {
-        return new Promise((resolve) => setTimeout(resolve, ms));
+    async delay(ms, lane) {
+        const controller = new AbortController();
+        this.activeControllers.set(controller, lane);
+        let timer;
+        try {
+            await new Promise((resolve, reject) => {
+                timer = setTimeout(resolve, ms);
+                controller.signal.addEventListener('abort', () => {
+                    reject(classifyRequestFailure(undefined, controller, 'Bootstrap retry aborted'));
+                }, { once: true });
+            });
+        }
+        finally {
+            clearTimeout(timer);
+            this.activeControllers.delete(controller);
+        }
     }
     /**
      * Get health status of sync engine

package/dist/local/sync/OnDemandLoader.d.ts

@@ -81,9 +81,8 @@ export interface FetchOptions<T> {
     };
     readonly limit?: number;
     /**
-     * Freshness mode. When omitted, the default is derived from the model's
-     * load strategy: `lazy` models default to `'unknown'` (local-first), while
-     * `instant`/`partial` models default to `'complete'`.
+     * Freshness mode. Omitted and `'unknown'` use local-first reads for every
+     * load strategy. A previously hydrated query relies on the live stream.
      *
      * `'complete'`: wait for the network round-trip even if local data exists,
      * so the caller observes server-confirmed state (read-after-write).

package/dist/local/sync/OnDemandLoader.js

@@ -117,19 +117,20 @@ export class OnDemandLoader {
         }
         const clauses = normalizeWhere(options?.where);
         const queryKey = stableKey(modelName, clauses, options?.orderBy, options?.limit, options?.expand);
-        // Single-flight: an identical hydration is already in flight.
-        const inFlight = this.inFlight.get(queryKey);
+        // A local-first read cannot satisfy an authoritative caller.
+        const flightKey = `${options?.type === 'complete' ? 'complete' : 'unknown'}:${queryKey}`;
+        const inFlight = this.inFlight.get(flightKey);
         if (inFlight)
             return inFlight;
         const work = this.runFetch(modelName, typename, ModelClass, clauses, options, queryKey);
-        this.inFlight.set(queryKey, work);
+        this.inFlight.set(flightKey, work);
         // The rejection (if any) reaches callers via the returned `work`; this
         // side-chain only clears the single-flight slot. Without the trailing
         // catch, `.finally()` mirrors the rejection into a second, unhandled
         // promise even when every caller handles theirs.
         void work
             .finally(() => {
-            this.inFlight.delete(queryKey);
+            this.inFlight.delete(flightKey);
         })
             .catch(() => undefined);
         return work;
@@ -175,11 +176,8 @@ export class OnDemandLoader {
         // network, then mark this query hydrated so future reads serve local.
         const networkModels = await this.fetchFromNetwork(modelName, typename, clauses, options);
         this.hydratedKeys.add(queryKey);
-        if (networkModels.length > 0)
-            return applyLimit(networkModels, options?.limit);
-        // Network returned nothing — fall back to whatever's local (e.g. a
-        // complete read whose server result was empty but IDB still holds rows).
-        return applyLimit(await this.readLocal(modelName, typename, ModelClass, clauses, hasExpand, expand), options?.limit);
+        // An empty authoritative answer is absence, not permission to serve stale rows.
+        return applyLimit(networkModels, options?.limit);
     }
     /**
      * Read a query's rows from local storage only — pool first, then IndexedDB
@@ -223,12 +221,13 @@ export class OnDemandLoader {
         const network = await this.queryNetwork(modelName, clauses, options);
         const networkRows = network.rows;
         const evidenceById = new Map(network.evidence.map((entry) => [entry.id, entry.stamp]));
+        const acceptedRows = [];
         const networkModels = networkRows
             // Strict: a row the server returned whose type name this client never
             // registered is a genuine schema collision (the pushed schema differs
             // from the local one). Throw here, naming the cause, rather than silently
             // dropping the row and failing downstream as `entity_not_found`.
-            .map((raw) => this.hydrateOne(raw, { kind: 'network', position: snapshotPosition(raw, evidenceById, network.position) }, typename, { strict: true }))
+            .map((raw) => this.hydrateOne(raw, { kind: 'network', position: snapshotPosition(raw, evidenceById, network.position) }, typename, { strict: true, acceptedRows }))
             .filter((m) => m !== null);
         for (const model of networkModels) {
             const stamp = evidenceById.get(model.id);
@@ -241,9 +240,8 @@ export class OnDemandLoader {
         }
         if (networkModels.length > 0) {
             this.opts.objectPool.addBatch(networkModels, ModelScope.live);
-            // Background IDB write — don't block the caller. Expanded children are
-            // persisted to their own stores inside `queryNetwork`/`hydrateExpanded`.
-            void this.persistToIdb(modelName, networkRows);
+            // Persist only accepted snapshots: a stale response must not roll disk back.
+            await this.persistToIdb(modelName, acceptedRows);
         }
         return networkModels;
     }
@@ -377,6 +375,7 @@ export class OnDemandLoader {
                 if (this.opts.objectPool.watermarks.isAheadOf(existing, origin.position))
                     return existing;
                 const stamped = this.stampTypename(obj, typename);
+                opts?.acceptedRows?.push(stamped);
                 // Retain pending local fields while accepting the server's others —
                 // the same local-first merge contract SyncClient's delta resolver uses.
                 const localChanges = existing.getChanges();
@@ -397,7 +396,12 @@ export class OnDemandLoader {
         // re-populate it). The typename comes from the schema relation
         // (`'Block'`, `'Section'`, etc.) so no guessing involved.
         const stamped = this.stampTypename(obj, typename);
-        return this.opts.objectPool.createFromData(stamped, undefined, opts);
+        const model = this.opts.objectPool.createFromData(stamped, undefined, opts);
+        if (model && origin.kind === 'network') {
+            this.opts.objectPool.watermarks.advance(model, origin.position);
+            opts?.acceptedRows?.push(stamped);
+        }
+        return model;
     }
     /**
      * Stamp `__typename` onto a row when it's known (from the schema's
@@ -472,7 +476,7 @@ export class OnDemandLoader {
         // own typed pool, then leave the nested arrays in place on the
         // primary row.
         if (options?.expand && options.expand.length > 0) {
-            this.hydrateExpanded(modelName, normalized, options.expand, position);
+            await this.hydrateExpanded(modelName, normalized, options.expand, position);
         }
         return { rows: normalized, evidence, position };
     }
@@ -483,7 +487,8 @@ export class OnDemandLoader {
      * `__typename` field gets mangled by `postgres.camel` (`__typename`
      * → `_Typename`), so the SDK can't trust whatever string lands.
      */
-    hydrateExpanded(parentModelName, rows, relationNames, position) {
+    async hydrateExpanded(parentModelName, rows, relationNames, position) {
+        const writes = [];
         const parentDef = this.getModelDef(parentModelName);
         // Nested rows carry no evidence of their own; the read floor at issue
         // time is what they provably reflect. A floor of zero says nothing.
@@ -505,8 +510,7 @@ export class OnDemandLoader {
                 const stampedItems = [];
                 for (const item of items) {
                     const stamped = this.stampTypename(item, targetTypename);
-                    stampedItems.push(stamped);
-                    const m = this.hydrateOne(stamped, origin);
+                    const m = this.hydrateOne(stamped, origin, targetTypename, { acceptedRows: stampedItems });
                     if (m)
                         models.push(m);
                 }
@@ -518,24 +522,22 @@ export class OnDemandLoader {
                 // this, expand-fetched relations live only inside the parent's row
                 // and are lost to a lazy child query after a cold start.
                 if (stampedItems.length > 0 && targetKey) {
-                    void this.persistToIdb(targetKey, stampedItems);
+                    writes.push(this.persistToIdb(targetKey, stampedItems));
                 }
             }
         }
+        await Promise.all(writes);
     }
     async persistToIdb(modelName, rows) {
+        if (rows.length === 0)
+            return;
         const store = this.opts.database.getStore(this.resolveTypename(modelName));
+        // Before ready(), callers may have a graph but no initialized storage.
         if (!store)
             return;
-        for (const row of rows) {
-            try {
-                await store.put(row);
-            }
-            catch {
-                // IDB writes are best-effort — a transient quota/transaction
-                // failure shouldn't break the hydration's primary purpose.
-            }
-        }
+        // Enqueue together, before yielding: a later delta must not be followed by
+        // an older row from the tail of this query's sequential write loop.
+        await Promise.all(rows.map((row) => store.put(row)));
     }
     resolveTypename(modelName) {
         // Schema is the source of truth for wire typenames. The model proxy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.64.4",
+  "version": "0.64.5",
   "description": "The optional human-facing local-state package for Ablo: presence, live queries, and React bindings.",
   "license": "Apache-2.0",
   "type": "module",
@@ -85,7 +85,7 @@
     "directory": "packages/humans"
   },
   "dependencies": {
-    "@abloatai/transaction": "0.64.4",
+    "@abloatai/transaction": "0.64.5",
     "events": "^3.3.0",
     "mobx": "^6.13.7",
     "uuid": "^11.1.0",

package/src/local/Database.ts

@@ -621,6 +621,9 @@ export class Database {
 
           // Use batch processing for better performance
           const batch = await this.processDeltaBatch(formattedDeltas);
+          if (batch.persistedSyncId < Math.max(...formattedDeltas.map(delta => delta.syncId))) {
+            throw new Error('Could not persist all bootstrap changes; local storage must recover before retrying.');
+          }
           deltaResults = batch.results;
           deltasApplied = formattedDeltas.length;
           onProgress?.(deltasApplied);
@@ -687,48 +690,16 @@ export class Database {
           );
           continue;
         }
-        let writeErrors = 0;
-        // Store all items to IndexedDB (compacted)
+        // Fail before marking the model or snapshot persisted. A dropped row
+        // must be retried, not hidden behind an advanced bootstrap cursor.
         for (const item of modelData) {
-          try {
-            const compacted = this.compactRecord(modelName, item as ModelData);
-            await store.put(compacted);
-            modelsStored++;
-            modelsLoaded++;
-
-            // Report progress every 10 items
-            if (modelsLoaded % 10 === 0) {
-              onProgress?.(modelsLoaded);
-            }
-          } catch (error) {
-            writeErrors++;
-            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',
-          );
+          const compacted = this.compactRecord(modelName, item as ModelData);
+          await store.put(compacted);
+          modelsStored++;
+          modelsLoaded++;
+          if (modelsLoaded % 10 === 0) onProgress?.(modelsLoaded);
         }
-
-        // Mark model as persisted after successful write
-        try {
-          await this.setModelPersisted(modelName, true);
-        } catch {}
+        await this.setModelPersisted(modelName, true);
       }
 
       // Update workspace metadata with bootstrap snapshot's lastSyncId
@@ -1490,6 +1461,7 @@ export class Database {
         // Wait for transaction to complete
         await new Promise<void>((resolve, reject) => {
           tx.oncomplete = () => { resolve(); };
+          tx.onabort = () => { reject(tx.error ?? new DOMException('IndexedDB transaction aborted', 'AbortError')); };
           tx.onerror = () => { reject(tx.error); };
         });
         // Only commit staged results to the global results if the transaction

package/src/local/stores/DatabaseManager.ts

@@ -208,6 +208,7 @@ export class DatabaseManager {
         resolve();
       };
 
+      tx.onabort = () => { reject(indexedDbError(tx.error, 'registry transaction')); };
       tx.onerror = () => { reject(indexedDbError(tx.error, 'registry transaction')); };
       request.onerror = () => { reject(indexedDbError(request.error, 'registry write')); };
     });
@@ -347,6 +348,7 @@ export class DatabaseManager {
       const request = store.put(metadata, 'metadata');
 
       tx.oncomplete = () => { resolve(); };
+      tx.onabort = () => { reject(indexedDbError(tx.error, 'workspace metadata transaction')); };
       tx.onerror = () => { reject(indexedDbError(tx.error, 'workspace metadata transaction')); };
       request.onerror = () => { reject(indexedDbError(request.error, 'workspace metadata write')); };
     });
@@ -388,6 +390,7 @@ export class DatabaseManager {
       const request = store.put(persistenceData, modelName);
 
       tx.oncomplete = () => { resolve(); };
+      tx.onabort = () => { reject(indexedDbError(tx.error, 'model persistence transaction')); };
       tx.onerror = () => { reject(indexedDbError(tx.error, 'model persistence transaction')); };
       request.onerror = () => { reject(indexedDbError(request.error, 'model persistence write')); };
     });

package/src/local/stores/ObjectStore.ts

@@ -54,6 +54,7 @@ export class ObjectStore implements ObjectStoreContract {
         const request = store.add(data);
 
         tx.oncomplete = () => { resolve(); };
+        tx.onabort = () => { reject(tx.error ?? new DOMException('IndexedDB transaction aborted', 'AbortError')); };
         tx.onerror = () => { reject(tx.error ?? new Error('IndexedDB transaction error')); };
         request.onerror = () => { reject(request.error ?? new Error('IndexedDB request error')); };
       } catch (error) {
@@ -110,6 +111,7 @@ export class ObjectStore implements ObjectStoreContract {
         const request = store.put(data);
 
         tx.oncomplete = () => { resolve(); };
+        tx.onabort = () => { reject(tx.error ?? new DOMException('IndexedDB transaction aborted', 'AbortError')); };
         tx.onerror = () => { reject(tx.error ?? new Error('IndexedDB transaction error')); };
         request.onerror = () => { reject(request.error ?? new Error('IndexedDB request error')); };
       } catch (error) {
@@ -223,6 +225,7 @@ export class ObjectStore implements ObjectStoreContract {
         const request = store.delete(id);
 
         tx.oncomplete = () => { resolve(); };
+        tx.onabort = () => { reject(tx.error ?? new DOMException('IndexedDB transaction aborted', 'AbortError')); };
         tx.onerror = () => { reject(tx.error ?? new Error('IndexedDB transaction error')); };
         request.onerror = () => { reject(request.error ?? new Error('IndexedDB request error')); };
       } catch (error) {
@@ -261,6 +264,7 @@ export class ObjectStore implements ObjectStoreContract {
         const request = store.clear();
 
         tx.oncomplete = () => { resolve(); };
+        tx.onabort = () => { reject(tx.error ?? new DOMException('IndexedDB transaction aborted', 'AbortError')); };
         tx.onerror = () => { reject(tx.error ?? new Error('IndexedDB transaction error')); };
         request.onerror = () => { reject(request.error ?? new Error('IndexedDB request error')); };
       } catch (error) {

package/src/local/sync/BootstrapFetcher.ts

@@ -107,6 +107,7 @@ import { globalRuntime } from '../context.js';
 import type { RuntimeContext } from '../RuntimeContext.js';
 import { AbloError, AbloSessionError, AbloConnectionError, translateHttpError, toAbloError, isRetryableCode } from '@abloatai/transaction/errors';
 import { withAuthHeaders, type AuthTokenGetter } from '@abloatai/transaction/auth/credentialSource';
+import { retryAfterSecondsFromHeader } from '@abloatai/transaction/wire/rateLimit';
 import {
   classifySchemaDrift,
   describeSchemaDrift,
@@ -244,12 +245,16 @@ export class BootstrapFetcher {
    * through its models {@link CHUNK_CONCURRENCY} at a time; each request may
    * spend `fetchTimeout` waiting for response headers and `stallTimeout`
    * waiting for the next body chunk, and may be retried `maxRetries` times.
+   * Capacity recovery has a separate `fetchTimeout` window.
    */
   get budgetMs(): number {
     const models = Math.max(this.options.instantModels?.length ?? 1, 1);
     const waves = Math.ceil(models / CHUNK_CONCURRENCY);
     return (
-      waves * (this.options.fetchTimeout + this.options.stallTimeout) * this.options.maxRetries
+      waves * (
+        (this.options.fetchTimeout + this.options.stallTimeout) * this.options.maxRetries +
+        this.options.fetchTimeout
+      )
     );
   }
 
@@ -625,7 +630,8 @@ export class BootstrapFetcher {
    */
   private async fetchWithRetries(url: string, lane: CancelLane): Promise<BootstrapData> {
     let lastError: Error | null = null;
-    for (let attempt = 0; attempt < this.options.maxRetries; attempt++) {
+    const capacityDeadline = Date.now() + this.options.fetchTimeout;
+    for (let attempt = 0; attempt < this.options.maxRetries;) {
       try {
         return await this.fetchOnce(url, lane);
       } catch (error) {
@@ -664,8 +670,19 @@ export class BootstrapFetcher {
           attempt: attempt + 1,
         });
 
-        if (attempt < this.options.maxRetries - 1) {
-          await this.delay(this.options.retryDelay * Math.pow(2, attempt));
+        const delayMs = Math.max(
+          this.options.retryDelay * Math.pow(2, attempt),
+          (ablo.retryAfterSeconds ?? 0) * 1_000,
+        );
+        const capacity = ablo.code === 'instance_at_capacity' && ablo.retryAfterSeconds !== undefined;
+        // Admission has not run the request yet. Allow its recovery window
+        // without spending the attempts reserved for actual fetch failures.
+        if (ablo.retryAfterSeconds !== undefined && Date.now() + delayMs >= capacityDeadline) {
+          throw ablo;
+        }
+        if (!capacity) attempt++;
+        if (capacity || attempt < this.options.maxRetries) {
+          await this.delay(delayMs, lane);
         }
       }
     }
@@ -827,6 +844,7 @@ export class BootstrapFetcher {
         res.status,
         parsed ?? `Bootstrap fetch failed: ${res.status} ${res.statusText}`,
         res.headers.get('x-request-id') ?? undefined,
+        { retryAfterSeconds: retryAfterSecondsFromHeader(res.headers.get('retry-after')) },
       );
       // Only a genuine session or JWT expiry — or a bare auth failure carrying
       // no structured code — should drive the sign-in redirect. A specific auth
@@ -1019,6 +1037,7 @@ export class BootstrapFetcher {
         response.status,
         parsed ?? `Bootstrap fetch failed: ${response.status} ${response.statusText}`,
         response.headers.get('x-request-id') ?? undefined,
+        { retryAfterSeconds: retryAfterSecondsFromHeader(response.headers.get('retry-after')) },
       );
       if (
         translated.code === 'session_expired' ||
@@ -1095,6 +1114,7 @@ export class BootstrapFetcher {
         response.status,
         parsed ?? `Entity fetch failed: ${response.status} ${response.statusText}`,
         response.headers.get('x-request-id') ?? undefined,
+        { retryAfterSeconds: retryAfterSecondsFromHeader(response.headers.get('retry-after')) },
       );
     }
 
@@ -1168,8 +1188,21 @@ export class BootstrapFetcher {
   /**
    * Helper to delay execution
    */
-  private delay(ms: number): Promise<void> {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+  private async delay(ms: number, lane: CancelLane): Promise<void> {
+    const controller = new AbortController();
+    this.activeControllers.set(controller, lane);
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await new Promise<void>((resolve, reject) => {
+        timer = setTimeout(resolve, ms);
+        controller.signal.addEventListener('abort', () => {
+          reject(classifyRequestFailure(undefined, controller, 'Bootstrap retry aborted'));
+        }, { once: true });
+      });
+    } finally {
+      clearTimeout(timer);
+      this.activeControllers.delete(controller);
+    }
   }
 
   /**

package/src/local/sync/OnDemandLoader.ts

@@ -85,9 +85,8 @@ export interface FetchOptions<T> {
   readonly orderBy?: { [K in keyof T]?: 'asc' | 'desc' };
   readonly limit?: number;
   /**
-   * Freshness mode. When omitted, the default is derived from the model's
-   * load strategy: `lazy` models default to `'unknown'` (local-first), while
-   * `instant`/`partial` models default to `'complete'`.
+   * Freshness mode. Omitted and `'unknown'` use local-first reads for every
+   * load strategy. A previously hydrated query relies on the live stream.
    *
    * `'complete'`: wait for the network round-trip even if local data exists,
    * so the caller observes server-confirmed state (read-after-write).
@@ -240,19 +239,20 @@ export class OnDemandLoader {
     const clauses = normalizeWhere(options?.where);
     const queryKey = stableKey(modelName, clauses, options?.orderBy, options?.limit, options?.expand);
 
-    // Single-flight: an identical hydration is already in flight.
-    const inFlight = this.inFlight.get(queryKey);
+    // A local-first read cannot satisfy an authoritative caller.
+    const flightKey = `${options?.type === 'complete' ? 'complete' : 'unknown'}:${queryKey}`;
+    const inFlight = this.inFlight.get(flightKey);
     if (inFlight) return inFlight;
 
     const work = this.runFetch(modelName, typename, ModelClass, clauses, options, queryKey);
-    this.inFlight.set(queryKey, work);
+    this.inFlight.set(flightKey, work);
     // The rejection (if any) reaches callers via the returned `work`; this
     // side-chain only clears the single-flight slot. Without the trailing
     // catch, `.finally()` mirrors the rejection into a second, unhandled
     // promise even when every caller handles theirs.
     void work
       .finally(() => {
-        this.inFlight.delete(queryKey);
+        this.inFlight.delete(flightKey);
       })
       .catch(() => undefined);
     return work;
@@ -313,14 +313,8 @@ export class OnDemandLoader {
     // network, then mark this query hydrated so future reads serve local.
     const networkModels = await this.fetchFromNetwork(modelName, typename, clauses, options);
     this.hydratedKeys.add(queryKey);
-    if (networkModels.length > 0) return applyLimit(networkModels, options?.limit);
-
-    // Network returned nothing — fall back to whatever's local (e.g. a
-    // complete read whose server result was empty but IDB still holds rows).
-    return applyLimit(
-      await this.readLocal(modelName, typename, ModelClass, clauses, hasExpand, expand),
-      options?.limit,
-    );
+    // An empty authoritative answer is absence, not permission to serve stale rows.
+    return applyLimit(networkModels, options?.limit);
   }
 
   /**
@@ -379,6 +373,7 @@ export class OnDemandLoader {
     const network = await this.queryNetwork(modelName, clauses, options);
     const networkRows = network.rows;
     const evidenceById = new Map(network.evidence.map((entry) => [entry.id, entry.stamp]));
+    const acceptedRows: unknown[] = [];
     const networkModels = networkRows
       // Strict: a row the server returned whose type name this client never
       // registered is a genuine schema collision (the pushed schema differs
@@ -389,7 +384,7 @@ export class OnDemandLoader {
           raw,
           { kind: 'network', position: snapshotPosition(raw, evidenceById, network.position) },
           typename,
-          { strict: true },
+          { strict: true, acceptedRows },
         ),
       )
       .filter((m): m is Model => m !== null);
@@ -405,9 +400,8 @@ export class OnDemandLoader {
 
     if (networkModels.length > 0) {
       this.opts.objectPool.addBatch(networkModels, ModelScope.live);
-      // Background IDB write — don't block the caller. Expanded children are
-      // persisted to their own stores inside `queryNetwork`/`hydrateExpanded`.
-      void this.persistToIdb(modelName, networkRows);
+      // Persist only accepted snapshots: a stale response must not roll disk back.
+      await this.persistToIdb(modelName, acceptedRows);
     }
 
     return networkModels;
@@ -538,7 +532,7 @@ export class OnDemandLoader {
     raw: unknown,
     origin: HydrationOrigin,
     typename?: string,
-    opts?: { strict?: boolean },
+    opts?: { strict?: boolean; acceptedRows?: unknown[] },
   ): Model | null {
     if (!raw || typeof raw !== 'object') return null;
     const obj = raw as Record<string, unknown>;
@@ -559,6 +553,7 @@ export class OnDemandLoader {
         if (this.opts.objectPool.watermarks.isAheadOf(existing, origin.position)) return existing;
 
         const stamped = this.stampTypename(obj, typename) as Record<string, unknown>;
+        opts?.acceptedRows?.push(stamped);
         // Retain pending local fields while accepting the server's others —
         // the same local-first merge contract SyncClient's delta resolver uses.
         const localChanges = existing.getChanges();
@@ -581,7 +576,12 @@ export class OnDemandLoader {
     // re-populate it). The typename comes from the schema relation
     // (`'Block'`, `'Section'`, etc.) so no guessing involved.
     const stamped = this.stampTypename(obj, typename) as Record<string, unknown>;
-    return this.opts.objectPool.createFromData(stamped, undefined, opts);
+    const model = this.opts.objectPool.createFromData(stamped, undefined, opts);
+    if (model && origin.kind === 'network') {
+      this.opts.objectPool.watermarks.advance(model, origin.position);
+      opts?.acceptedRows?.push(stamped);
+    }
+    return model;
   }
 
   /**
@@ -672,7 +672,7 @@ export class OnDemandLoader {
     // own typed pool, then leave the nested arrays in place on the
     // primary row.
     if (options?.expand && options.expand.length > 0) {
-      this.hydrateExpanded(modelName, normalized, options.expand, position);
+      await this.hydrateExpanded(modelName, normalized, options.expand, position);
     }
     return { rows: normalized, evidence, position };
   }
@@ -684,12 +684,13 @@ export class OnDemandLoader {
    * `__typename` field gets mangled by `postgres.camel` (`__typename`
    * → `_Typename`), so the SDK can't trust whatever string lands.
    */
-  private hydrateExpanded(
+  private async hydrateExpanded(
     parentModelName: string,
     rows: unknown[],
     relationNames: readonly string[],
     position: number,
-  ): void {
+  ): Promise<void> {
+    const writes: Promise<void>[] = [];
     const parentDef = this.getModelDef(parentModelName);
     // Nested rows carry no evidence of their own; the read floor at issue
     // time is what they provably reflect. A floor of zero says nothing.
@@ -710,8 +711,7 @@ export class OnDemandLoader {
         const stampedItems: unknown[] = [];
         for (const item of items) {
           const stamped = this.stampTypename(item, targetTypename);
-          stampedItems.push(stamped);
-          const m = this.hydrateOne(stamped, origin);
+          const m = this.hydrateOne(stamped, origin, targetTypename, { acceptedRows: stampedItems });
           if (m) models.push(m);
         }
         if (models.length > 0) {
@@ -722,23 +722,21 @@ export class OnDemandLoader {
         // this, expand-fetched relations live only inside the parent's row
         // and are lost to a lazy child query after a cold start.
         if (stampedItems.length > 0 && targetKey) {
-          void this.persistToIdb(targetKey, stampedItems);
+          writes.push(this.persistToIdb(targetKey, stampedItems));
         }
       }
     }
+    await Promise.all(writes);
   }
 
   private async persistToIdb(modelName: string, rows: unknown[]): Promise<void> {
+    if (rows.length === 0) return;
     const store = this.opts.database.getStore(this.resolveTypename(modelName));
+    // Before ready(), callers may have a graph but no initialized storage.
     if (!store) return;
-    for (const row of rows) {
-      try {
-        await store.put(row as Record<string, unknown>);
-      } catch {
-        // IDB writes are best-effort — a transient quota/transaction
-        // failure shouldn't break the hydration's primary purpose.
-      }
-    }
+    // Enqueue together, before yielding: a later delta must not be followed by
+    // an older row from the tail of this query's sequential write loop.
+    await Promise.all(rows.map((row) => store.put(row as Record<string, unknown>)));
   }
 
   private resolveTypename(modelName: string): string {