@abloatai/humans 0.64.3 → 0.64.5

package/dist/local/BaseSyncedStore.d.ts

@@ -109,6 +109,8 @@ export interface UserContext {
      *  structure comes from schema-declared scopes and server-issued
      *  authorization. */
     syncGroups?: readonly string[];
+    /** Server-confirmed operation grants; also partition persisted replicas. */
+    operations?: readonly string[];
     /**
      * How aggressively this participant should pull baseline state at
      * startup.

package/dist/local/Database.d.ts

@@ -6,7 +6,7 @@
  * in-memory mirror of what this class persists.
  */
 import { type DatabaseInfo, type WorkspaceMetadata } from './stores/DatabaseManager.js';
-import type { PersistenceIdentity } from './stores/persistenceIdentity.js';
+import { type PersistenceIdentity } from './stores/persistenceIdentity.js';
 import { ModelRegistry } from './ModelRegistry.js';
 import { LoadStrategy } from '@abloatai/transaction/types';
 import type { RuntimeContext } from './RuntimeContext.js';

package/dist/local/Database.js

@@ -6,6 +6,7 @@
  * in-memory mirror of what this class persists.
  */
 import { DatabaseManager } from './stores/DatabaseManager.js';
+import { persistenceIdentityMatches } from './stores/persistenceIdentity.js';
 import { StoreManager } from './stores/StoreManager.js';
 import { ModelRegistry } from './ModelRegistry.js';
 import { LoadStrategy } from '@abloatai/transaction/types';
@@ -142,12 +143,16 @@ export class Database {
     async open(identity, version = 1) {
         this.isClosing = false;
         if (this.workspaceDb && this.currentDbInfo) {
+            if (!persistenceIdentityMatches(this.currentDbInfo, identity)) {
+                throw new AbloConnectionError('Dispose the client before changing persistence authority.', { code: 'db_identity_mismatch' });
+            }
             return;
         }
         // ── In-memory mode: skip IndexedDB entirely ──────────────────
         // Creates InMemoryObjectStore instances for all registered models.
         // Bootstrap via HTTP still works; only local persistence is skipped.
         if (this.inMemory) {
+            this.bootstrapHelper.setCacheScope(null);
             this.runtime.logger.debug('Opening in-memory database (headless mode)');
             const allModels = this.modelRegistry.getRegisteredModelNames();
             for (const modelName of allModels) {
@@ -164,6 +169,8 @@ export class Database {
         // Initialize meta database
         await this.databaseManager.initializeMetaDatabase();
         this.currentDbInfo = await this.databaseManager.calculateDatabaseInfo(identity, version);
+        // Both persistence layers must share the complete authenticated authority.
+        this.bootstrapHelper.setCacheScope(this.currentDbInfo.name);
         // Register database
         await this.databaseManager.registerDatabase(this.currentDbInfo);
         // Open workspace database
@@ -172,6 +179,20 @@ export class Database {
         });
         // Initialize stores
         await this.storeManager.initializeStores(this.workspaceDb);
+        // A live group addition can have widened a previous client's replica after
+        // it opened this namespace. Check persisted coverage before restoring rows
+        // or pending writes, not after the first WebSocket reconnect.
+        const metadata = await this.getWorkspaceMetadata();
+        const allowed = new Set(identity.syncGroups ?? []);
+        if (metadata?.subscribedSyncGroups.some(group => !allowed.has(group))) {
+            // Preserve pending writes for their original authority; never replay them
+            // into a narrower replica or silently discard them.
+            await this.close();
+            throw new AbloConnectionError('Persisted sync groups exceed the current authority.', {
+                code: 'db_identity_mismatch',
+            });
+        }
+        await this.updateWorkspaceMetadata({ subscribedSyncGroups: [...allowed] });
         const readiness = await this.storeManager.checkReadinessOfStores();
         this.runtime.logger.info(`Database opened: ${this.currentDbInfo.name} (${readiness.readyStores.length}/${readiness.totalStores} stores ready)`);
     }
@@ -451,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);
@@ -497,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')
@@ -1121,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/client/storeLifecycle.js

@@ -202,6 +202,7 @@ export function startStoreLifecycle(deps) {
                     capabilityToken,
                     syncGroups,
                     deliveryPartition,
+                    operations: resolved.authority.operations,
                     bootstrapMode: resolvedBootstrapMode,
                 });
                 let current = gen.next();

package/dist/local/stores/DatabaseManager.d.ts

@@ -17,6 +17,8 @@ export interface DatabaseInfo {
     projectId: string | null;
     branchId: string;
     branchRoot: boolean;
+    syncGroups?: readonly string[];
+    operations?: readonly string[];
     schemaHash: string;
     schemaVersion: number;
     userVersion?: number;

package/dist/local/stores/DatabaseManager.js

@@ -116,6 +116,8 @@ export class DatabaseManager {
             projectId: identity.projectId,
             branchId: identity.branchId,
             branchRoot: identity.branchRoot,
+            syncGroups: [...new Set(identity.syncGroups ?? [])].sort(),
+            operations: [...new Set(identity.operations ?? [])].sort(),
             schemaHash,
             schemaVersion,
             userVersion,
@@ -140,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')); };
         });
@@ -268,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')); };
         });
@@ -302,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/stores/persistenceIdentity.d.ts

@@ -1,6 +1,5 @@
 /**
- * The complete authenticated branch that owns one local replica. A branch id
- * is authoritative.
+ * The authenticated branch, groups and permissions that own one local replica.
  */
 export interface PersistenceIdentity {
     readonly participantId: string;
@@ -9,6 +8,8 @@ export interface PersistenceIdentity {
     readonly projectId: string | null;
     readonly branchId: string;
     readonly branchRoot: boolean;
+    readonly syncGroups?: readonly string[];
+    readonly operations?: readonly string[];
 }
 export interface PersistedIdentityMetadata {
     readonly namespaceVersion?: number;
@@ -18,8 +19,10 @@ export interface PersistedIdentityMetadata {
     readonly projectId?: string | null;
     readonly branchId?: string;
     readonly branchRoot?: boolean;
+    readonly syncGroups?: readonly string[];
+    readonly operations?: readonly string[];
 }
-export declare const PERSISTENCE_NAMESPACE_VERSION = 4;
+export declare const PERSISTENCE_NAMESPACE_VERSION = 5;
 /** Collision-resistant IndexedDB name for one authenticated data plane. */
 export declare function persistenceDatabaseName(identity: PersistenceIdentity, userVersion?: number): Promise<string>;
 /** Defense-in-depth check after namespace lookup and before persisted reads. */

package/dist/local/stores/persistenceIdentity.js

@@ -1,5 +1,8 @@
 import { AbloConnectionError } from '@abloatai/transaction/errors';
-export const PERSISTENCE_NAMESPACE_VERSION = 4;
+export const PERSISTENCE_NAMESPACE_VERSION = 5;
+function scopeKey(values = []) {
+    return JSON.stringify([...new Set(values)].sort());
+}
 function canonicalIdentity(identity, userVersion) {
     return JSON.stringify([
         PERSISTENCE_NAMESPACE_VERSION,
@@ -8,6 +11,8 @@ function canonicalIdentity(identity, userVersion) {
         identity.organizationId,
         identity.participantKind,
         identity.participantId,
+        scopeKey(identity.syncGroups),
+        scopeKey(identity.operations),
         userVersion,
     ]);
 }
@@ -33,5 +38,7 @@ export function persistenceIdentityMatches(info, identity) {
         info.participantKind === identity.participantKind &&
         (info.projectId ?? null) === identity.projectId &&
         info.branchId === identity.branchId &&
-        (info.branchRoot ?? false) === identity.branchRoot);
+        (info.branchRoot ?? false) === identity.branchRoot &&
+        scopeKey(info.syncGroups) === scopeKey(identity.syncGroups) &&
+        scopeKey(info.operations) === scopeKey(identity.operations));
 }

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;
@@ -171,7 +172,7 @@ export declare class BootstrapFetcher {
      * Update the offline-cache namespace once auth has resolved the server-side
      * account scope. This is intentionally not a public organizationId input.
      */
-    setCacheScope(cacheScope: string): void;
+    setCacheScope(cacheScope: string | null): void;
     setSyncGroups(syncGroups: readonly string[] | undefined): void;
     /**
      * Sets a fixed credential for callers that construct the helper directly.

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;
@@ -256,7 +259,7 @@ export class BootstrapFetcher {
      * account scope. This is intentionally not a public organizationId input.
      */
     setCacheScope(cacheScope) {
-        if (cacheScope.trim().length === 0)
+        if (cacheScope !== null && cacheScope.trim().length === 0)
             return;
         this.options.cacheScope = cacheScope;
     }
@@ -410,7 +413,7 @@ export class BootstrapFetcher {
                     : 0,
             });
             // Persist for offline fallback
-            if (this.options.cacheScope) {
+            if (!syncGroupsOverride && this.options.cacheScope) {
                 this.saveCachedBootstrap(this.options.cacheScope, data);
             }
             return data;
@@ -427,7 +430,7 @@ export class BootstrapFetcher {
                 throw ablo;
             }
             // Transient failure after exhausting retries → cached fallback.
-            const cached = this.options.cacheScope
+            const cached = !syncGroupsOverride && this.options.cacheScope
                 ? this.loadCachedBootstrap(this.options.cacheScope)
                 : null;
             if (cached) {
@@ -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());
     }
@@ -859,7 +872,7 @@ export class BootstrapFetcher {
     }
     // Cache helpers for offline bootstrap
     getBootstrapCacheKey(orgId) {
-        return `ablo:bootstrap:${orgId}`;
+        return `ablo:bootstrap:v5:${JSON.stringify([orgId, this.options.baseUrl, [...new Set(this.options.syncGroups)].sort()])}`;
     }
     saveCachedBootstrap(orgId, data) {
         if (typeof window === 'undefined')
@@ -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/dist/local/sync/initialize.js

@@ -3,6 +3,7 @@ export function* initialize(host, context, signal) {
     if (host.initialized)
         return { success: true };
     host.userContext = context;
+    let persistenceReady = false;
     try {
         host.updateSyncStatus({ state: 'syncing', progress: 0 });
         // The commit outbox and offline mutation journal live in IndexedDB.
@@ -15,7 +16,10 @@ export function* initialize(host, context, signal) {
             projectId: context.projectId ?? context.organizationId,
             branchId: context.branchId,
             branchRoot: context.branchRoot ?? false,
+            syncGroups: host.resolveSyncGroups(context),
+            operations: context.operations,
         });
+        persistenceReady = true;
         // Propagate identity only after storage is ready, then restore sealed
         // requests before accepting fresh mutations.
         yield host.syncClient.initialize(context.userId, context.organizationId);
@@ -117,13 +121,13 @@ export function* initialize(host, context, signal) {
             return { success: false, error: error };
         }
         // Fallback: show local data if available
-        if (host.objectPool.size === 0) {
+        if (persistenceReady && host.objectPool.size === 0) {
             try {
                 yield host.syncClient.hydrateFromDatabase();
             }
             catch { }
         }
-        if (host.objectPool.size > 0) {
+        if (persistenceReady && host.objectPool.size > 0) {
             host.dataReady = true;
             host.initialized = true;
             host.updateSyncStatus(host.syncWebSocket.isConnected()