@abloatai/humans 0.64.3 → 0.64.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.64.3",
+  "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.3",
+    "@abloatai/transaction": "0.64.5",
     "events": "^3.3.0",
     "mobx": "^6.13.7",
     "uuid": "^11.1.0",

package/src/local/BaseSyncedStore.ts

@@ -168,6 +168,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/src/local/Database.ts

@@ -6,7 +6,7 @@
  * in-memory mirror of what this class persists.
  */
 import { DatabaseManager, type DatabaseInfo, type WorkspaceMetadata } from './stores/DatabaseManager.js';
-import type { PersistenceIdentity } from './stores/persistenceIdentity.js';
+import { persistenceIdentityMatches, type PersistenceIdentity } from './stores/persistenceIdentity.js';
 import { StoreManager } from './stores/StoreManager.js';
 import { ModelRegistry } from './ModelRegistry.js';
 import { LoadStrategy } from '@abloatai/transaction/types';
@@ -226,6 +226,9 @@ export class Database {
     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;
     }
 
@@ -233,6 +236,7 @@ export class Database {
     // 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) {
@@ -264,6 +268,9 @@ export class Database {
       version
     );
 
+    // Both persistence layers must share the complete authenticated authority.
+    this.bootstrapHelper.setCacheScope(this.currentDbInfo.name);
+
     // Register database
     await this.databaseManager.registerDatabase(this.currentDbInfo);
 
@@ -278,6 +285,21 @@ 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)`
@@ -599,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);
@@ -665,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
@@ -1468,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/client/storeLifecycle.ts

@@ -325,6 +325,7 @@ export function startStoreLifecycle<S extends SchemaRecord>(
           capabilityToken,
           syncGroups,
           deliveryPartition,
+          operations: resolved.authority.operations,
           bootstrapMode: resolvedBootstrapMode,
         });
         let current = gen.next();

package/src/local/stores/DatabaseManager.ts

@@ -33,6 +33,8 @@ export interface DatabaseInfo {
   projectId: string | null;
   branchId: string;
   branchRoot: boolean;
+  syncGroups?: readonly string[];
+  operations?: readonly string[];
   schemaHash: string;
   schemaVersion: number;
   userVersion?: number;
@@ -175,6 +177,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,
@@ -204,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')); };
     });
@@ -343,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')); };
     });
@@ -384,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/stores/persistenceIdentity.ts

@@ -1,8 +1,7 @@
 import { AbloConnectionError } from '@abloatai/transaction/errors';
 
 /**
- * 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;
@@ -11,6 +10,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 {
@@ -21,9 +22,15 @@ export interface PersistedIdentityMetadata {
   readonly projectId?: string | null;
   readonly branchId?: string;
   readonly branchRoot?: boolean;
+  readonly syncGroups?: readonly string[];
+  readonly operations?: readonly string[];
 }
 
-export const PERSISTENCE_NAMESPACE_VERSION = 4;
+export const PERSISTENCE_NAMESPACE_VERSION = 5;
+
+function scopeKey(values: readonly string[] = []): string {
+  return JSON.stringify([...new Set(values)].sort());
+}
 
 function canonicalIdentity(
   identity: PersistenceIdentity,
@@ -36,6 +43,8 @@ function canonicalIdentity(
     identity.organizationId,
     identity.participantKind,
     identity.participantId,
+    scopeKey(identity.syncGroups),
+    scopeKey(identity.operations),
     userVersion,
   ]);
 }
@@ -76,6 +85,8 @@ export function persistenceIdentityMatches(
     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/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
+      )
     );
   }
 
@@ -406,8 +411,8 @@ export 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 {
-    if (cacheScope.trim().length === 0) return;
+  setCacheScope(cacheScope: string | null): void {
+    if (cacheScope !== null && cacheScope.trim().length === 0) return;
     this.options.cacheScope = cacheScope;
   }
 
@@ -587,7 +592,7 @@ export class BootstrapFetcher {
       });
 
       // Persist for offline fallback
-      if (this.options.cacheScope) {
+      if (!syncGroupsOverride && this.options.cacheScope) {
         this.saveCachedBootstrap(this.options.cacheScope, data);
       }
       return data;
@@ -604,7 +609,7 @@ export class BootstrapFetcher {
       }
 
       // 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) {
@@ -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')) },
       );
     }
 
@@ -1129,7 +1149,7 @@ export class BootstrapFetcher {
 
   // Cache helpers for offline bootstrap
   private getBootstrapCacheKey(orgId: string): string {
-    return `ablo:bootstrap:${orgId}`;
+    return `ablo:bootstrap:v5:${JSON.stringify([orgId, this.options.baseUrl, [...new Set(this.options.syncGroups)].sort()])}`;
   }
   private saveCachedBootstrap(orgId: string, data: BootstrapData): void {
     if (typeof window === 'undefined') return;
@@ -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 {

package/src/local/sync/initialize.ts

@@ -42,6 +42,7 @@ export function* initialize<TCollaboration extends EventMap<TCollaboration>>(
     if (host.initialized) return { success: true };
 
     host.userContext = context;
+    let persistenceReady = false;
 
     try {
       host.updateSyncStatus({ state: 'syncing', progress: 0 });
@@ -56,8 +57,12 @@ export function* initialize<TCollaboration extends EventMap<TCollaboration>>(
         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(
@@ -182,13 +187,13 @@ export function* initialize<TCollaboration extends EventMap<TCollaboration>>(
       }
 
       // 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(