@abloatai/ablo 0.10.1 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.11.0
+
+### Minor Changes
+
+- Canonical `claim` vocabulary, sync-group area-of-interest, and richer claim-rejection errors.
+  - **`intent` → `claim` everywhere.** The coordination primitive is now a `Claim` across the public surface: `useClaim` replaces `useIntent`, the `Ablo.Claim.*` namespace replaces `Ablo.Intent.*`, and module augmentation registers `Claims` instead of `Intents` on the `Register` interface. The underlying wire frames moved from `intent_*` to `claim_*` — clients and servers must run a `claim_*`-aware build together.
+  - **Sync-group area of interest.** A client's read interest is no longer frozen at connect: the new `update_subscription` frame drives live re-indexing, and `enterScope` / `leaveScope` / `pinScope` / `unpinScope` let a store narrow or widen what it streams. `AreaOfInterestManager` adds hysteresis (warm-TTL), claim-pinning, reconcile coalescing, and an LRU cap so narrowing the view never shrinks the write allowlist.
+  - **Richer claim-rejection errors.** Rejections (over WebSocket and HTTP) now carry `heldByClaim` and `policyReason`, and `AbloClaimedError` exposes a typed `claims` array so callers can see exactly who holds the contested rows.
+  - **Coordination vocabulary consolidation.** Participant identity is canonical `user` | `agent` | `system`; the server stamps `participantKind` on every presence emit and clients read it, so non-human peers surface correctly.
+
 ## 0.10.1
 
 ### Patch Changes

package/README.md

@@ -104,6 +104,7 @@ instead of guessing:
 ```ts
 import Ablo from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
+```
 
 Register the schema once (init scaffolds this `ablo.d.ts`), and every type
 is one parameter away — no `typeof schema` re-stating, anywhere:
@@ -127,7 +128,7 @@ type WeatherReport = Model<'weatherReports'>; // fully typed from YOUR schema
 TanStack-Router pattern: declare the source of truth once, everything
 infers from it.)
 
-
+```ts
 const schema = defineSchema({
   weatherReports: model({
     location: z.string(),

package/dist/BaseSyncedStore.d.ts

@@ -12,6 +12,8 @@
  * pull generic methods into this base class.
  */
 import { ConnectionManager } from './sync/ConnectionManager.js';
+import { AreaOfInterestManager } from './sync/AreaOfInterestManager.js';
+import { type ParticipantScope } from './sync/participants.js';
 import type { SyncClient } from './SyncClient.js';
 import type { Database, BootstrapResult } from './Database.js';
 import type { ObjectPool } from './ObjectPool.js';
@@ -237,6 +239,20 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      */
     protected readonly schema?: TSchema;
     protected syncWebSocket: SyncWebSocket<TCollaboration> | null;
+    /**
+     * Dynamic read interest (area-of-interest) over the connection's sync
+     * groups. Lives alongside `syncWebSocket` and is recreated with it; the
+     * stable `enterScope`/`leaveScope`/`pinScope`/`unpinScope` methods forward
+     * to whichever instance is current, so callers (the React participant
+     * hook) never hold a stale reference. Null until `setupWebSocketSync`.
+     */
+    protected areaOfInterest: AreaOfInterestManager | null;
+    /** Sync groups whose current state has been backfilled into the pool
+     *  (hydrate-on-enter). Cleared when the pool is reset on (re)bootstrap. */
+    private readonly hydratedGroups;
+    /** In-flight scoped hydrations, keyed by group — single-flights concurrent
+     *  enters of the same scope so they share one fetch. */
+    private readonly hydratingGroups;
     private _syncServerUrl?;
     /**
      * Public accessor for the underlying SyncWebSocket. Used by the
@@ -247,6 +263,32 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * `initialize()`.
      */
     getSyncWebSocket(): SyncWebSocket<TCollaboration> | null;
+    private scopeToGroups;
+    /**
+     * Bring a scope into view → subscribe to its groups. With
+     * `{ hydrate: true }`, ALSO backfill the groups' current state into the pool
+     * after the subscription is active (the game "spawn snapshot + delta stream"
+     * pattern): subscribe-first so no live delta is missed in the gap, then
+     * snapshot. Hydration is soft — a failed backfill never rejects `enterScope`
+     * and the live tail still flows.
+     */
+    enterScope(scope: ParticipantScope, opts?: {
+        hydrate?: boolean;
+    }): Promise<void>;
+    /**
+     * Backfill the current state of `syncGroups` into the pool via a PURE scoped
+     * snapshot fetch + the version-guarded, ghost-free scoped apply. Idempotent
+     * (skips groups already hydrated) and single-flight (concurrent enters of the
+     * same group share one fetch). Soft-fails: on error the groups are NOT marked
+     * hydrated, so a later re-enter retries.
+     */
+    protected hydrateGroups(syncGroups: readonly string[]): Promise<void>;
+    /** Leave a scope → its groups go warm (hysteresis), then drop on sweep. */
+    leaveScope(scope: ParticipantScope): Promise<void>;
+    /** Pin a scope (active claim / prominence) → never warms while pinned. */
+    pinScope(scope: ParticipantScope): Promise<void>;
+    /** Release a pin → the group transitions to warm rather than dropping. */
+    unpinScope(scope: ParticipantScope): Promise<void>;
     protected readonly queryProcessor: QueryProcessor;
     /**
      * Runtime behavior flags only — the three schema/config arrays
@@ -630,6 +672,39 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     protected deduplicateDeltas(deltas: SyncDelta[]): SyncDelta[];
     /** Process incoming delta with smart batching */
     protected processDeltaWithBatching(delta: SyncDelta): void;
+    /**
+     * Apply a complete, server-delivered delta frame atomically.
+     *
+     * A `delta_batch` WS event (reconnect/catch-up replay) already carries
+     * the FULL set of missed deltas. Routing it through the per-delta
+     * `processDeltaWithBatching` path re-chunks it via the live-traffic
+     * debounce timer + `maxBatchSize` force-flush, so a 300-delta catch-up
+     * fans out into ~6 separate `flushPendingDeltas` cycles — each its own
+     * IDB write, pool mutation, `models:changed` emit, and React re-render.
+     * The decks gallery visibly re-sorts and "pops in" once per chunk.
+     *
+     * Here we run the per-delta bookkeeping (dedup, ack, version vector,
+     * watermark, G/S routing, D cascade) for every delta WITHOUT scheduling
+     * a flush, then flush ONCE — collapsing the whole frame into a single
+     * IDB write + pool mutation + `models:changed` + re-render. Same code
+     * for the post-bootstrap replay of deltas queued during bootstrap.
+     *
+     * (Named `applyDeltaFrame`, not `processDeltaBatch`, to avoid confusion
+     * with `Database.processDeltaBatch` — the lower-level IDB write this
+     * eventually drives through `flushPendingDeltas`.)
+     */
+    protected applyDeltaFrame(deltas: SyncDelta[]): void;
+    /**
+     * Per-delta bookkeeping + enqueue. Returns `true` when the delta was
+     * pushed onto `pendingDeltas` (a regular batchable I/U/C/D delta that a
+     * subsequent flush must drain), `false` when it was skipped (dedup),
+     * deferred (bootstrap queue), or handled immediately out-of-band (G/S
+     * sync-group mutations). Does NOT schedule a flush — callers decide
+     * whether to debounce (live) or flush atomically (catch-up frame).
+     */
+    protected enqueueDelta(delta: SyncDelta): boolean;
+    /** Debounce a flush for live single-delta traffic. */
+    protected scheduleDeltaFlush(): void;
     /**
      * Cancel pending transactions for child entities when a parent is deleted.
      *

package/dist/BaseSyncedStore.js

@@ -14,6 +14,8 @@
 import { makeObservable, observable, computed, runInAction } from 'mobx';
 import { AbloConnectionError, AbloValidationError, toAbloError } from './errors.js';
 import { ConnectionManager } from './sync/ConnectionManager.js';
+import { AreaOfInterestManager } from './sync/AreaOfInterestManager.js';
+import { resolveParticipantSyncGroups, } from './sync/participants.js';
 import { PropertyType } from './types/index.js';
 import { SyncWebSocket, } from './sync/SyncWebSocket.js';
 import { QueryProcessor } from './core/QueryProcessor.js';
@@ -131,6 +133,20 @@ export class BaseSyncedStore {
     schema;
     // ── Real-time sync ──
     syncWebSocket = null;
+    /**
+     * Dynamic read interest (area-of-interest) over the connection's sync
+     * groups. Lives alongside `syncWebSocket` and is recreated with it; the
+     * stable `enterScope`/`leaveScope`/`pinScope`/`unpinScope` methods forward
+     * to whichever instance is current, so callers (the React participant
+     * hook) never hold a stale reference. Null until `setupWebSocketSync`.
+     */
+    areaOfInterest = null;
+    /** Sync groups whose current state has been backfilled into the pool
+     *  (hydrate-on-enter). Cleared when the pool is reset on (re)bootstrap. */
+    hydratedGroups = new Set();
+    /** In-flight scoped hydrations, keyed by group — single-flights concurrent
+     *  enters of the same scope so they share one fetch. */
+    hydratingGroups = new Map();
     _syncServerUrl;
     /**
      * Public accessor for the underlying SyncWebSocket. Used by the
@@ -143,6 +159,98 @@ export class BaseSyncedStore {
     getSyncWebSocket() {
         return this.syncWebSocket;
     }
+    // ── Area-of-interest (dynamic read subscription) ─────────────────
+    //
+    // `enterScope`/`leaveScope` move the connection's read interest as the
+    // user navigates (open/close a deck, sheet, doc); `pinScope`/`unpinScope`
+    // express prominence (an active claim keeps a group subscribed). All four
+    // resolve the scope to sync-group strings through the SAME resolver the
+    // claim path uses (`resolveParticipantSyncGroups`), so read interest and
+    // write claims always agree on the string for a given entity. No-ops
+    // before the socket exists. Soft state — they never reject for an offline
+    // transport (see `AreaOfInterestManager.reconcile`).
+    scopeToGroups(scope) {
+        return resolveParticipantSyncGroups(scope, this.schema);
+    }
+    /**
+     * Bring a scope into view → subscribe to its groups. With
+     * `{ hydrate: true }`, ALSO backfill the groups' current state into the pool
+     * after the subscription is active (the game "spawn snapshot + delta stream"
+     * pattern): subscribe-first so no live delta is missed in the gap, then
+     * snapshot. Hydration is soft — a failed backfill never rejects `enterScope`
+     * and the live tail still flows.
+     */
+    enterScope(scope, opts) {
+        const mgr = this.areaOfInterest;
+        if (!mgr)
+            return Promise.resolve();
+        const groups = this.scopeToGroups(scope);
+        const subscribed = Promise.all(groups.map((g) => mgr.enter(g))).then(() => undefined);
+        if (!opts?.hydrate)
+            return subscribed;
+        return subscribed.then(() => this.hydrateGroups(groups));
+    }
+    /**
+     * Backfill the current state of `syncGroups` into the pool via a PURE scoped
+     * snapshot fetch + the version-guarded, ghost-free scoped apply. Idempotent
+     * (skips groups already hydrated) and single-flight (concurrent enters of the
+     * same group share one fetch). Soft-fails: on error the groups are NOT marked
+     * hydrated, so a later re-enter retries.
+     */
+    async hydrateGroups(syncGroups) {
+        const need = syncGroups.filter((g) => !this.hydratedGroups.has(g) && !this.hydratingGroups.has(g));
+        if (need.length === 0) {
+            // Nothing new to fetch, but await any in-flight hydration for the
+            // requested groups so callers can sequence on completion.
+            await Promise.all(syncGroups
+                .map((g) => this.hydratingGroups.get(g))
+                .filter((p) => p !== undefined));
+            return;
+        }
+        const work = (async () => {
+            try {
+                const data = await this.database.fetchScopedBootstrapData(need);
+                this.syncClient.applyBootstrapDataToPool(data, undefined, { scoped: true });
+                for (const g of need)
+                    this.hydratedGroups.add(g);
+            }
+            catch (err) {
+                getContext().logger.warn('[BaseSyncedStore] scoped hydrate failed', {
+                    syncGroups: need,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                // Soft-fail — leave `need` un-hydrated so a re-enter retries.
+            }
+            finally {
+                for (const g of need)
+                    this.hydratingGroups.delete(g);
+            }
+        })();
+        for (const g of need)
+            this.hydratingGroups.set(g, work);
+        await work;
+    }
+    /** Leave a scope → its groups go warm (hysteresis), then drop on sweep. */
+    leaveScope(scope) {
+        const mgr = this.areaOfInterest;
+        if (!mgr)
+            return Promise.resolve();
+        return Promise.all(this.scopeToGroups(scope).map((g) => mgr.leave(g))).then(() => undefined);
+    }
+    /** Pin a scope (active claim / prominence) → never warms while pinned. */
+    pinScope(scope) {
+        const mgr = this.areaOfInterest;
+        if (!mgr)
+            return Promise.resolve();
+        return Promise.all(this.scopeToGroups(scope).map((g) => mgr.pin(g))).then(() => undefined);
+    }
+    /** Release a pin → the group transitions to warm rather than dropping. */
+    unpinScope(scope) {
+        const mgr = this.areaOfInterest;
+        if (!mgr)
+            return Promise.resolve();
+        return Promise.all(this.scopeToGroups(scope).map((g) => mgr.unpin(g))).then(() => undefined);
+    }
     // ── Internal helpers ──
     queryProcessor;
     /**
@@ -519,6 +627,10 @@ export class BaseSyncedStore {
             runInAction(() => { this.dataReady = false; });
             this.modelTypesHydrated.clear();
             this.modelTypeHydrationInFlight.clear();
+            // The pool is being wiped + re-bootstrapped, so the scoped-hydrate ledger
+            // is stale — clear it so re-entered groups backfill again.
+            this.hydratedGroups.clear();
+            this.hydratingGroups.clear();
             getContext().logger.info('[BaseSyncedStore] Bootstrap state reset complete');
         }
         catch {
@@ -1127,8 +1239,10 @@ export class BaseSyncedStore {
         this.bootstrapDeltaQueue = null;
         if (!queue || queue.length === 0)
             return;
-        for (const delta of queue)
-            this.processDeltaWithBatching(delta);
+        // Deltas that landed during bootstrap are a complete frame — apply
+        // them atomically (one flush, one re-render) rather than dribbling
+        // each back through the live debounce path.
+        this.applyDeltaFrame(queue);
     }
     /**
      * Factory for the internal `ConnectionManager`. Override to return
@@ -1300,6 +1414,14 @@ export class BaseSyncedStore {
                 batchedDeltas: true,
             },
         });
+        // Area-of-interest manager — owns dynamic read-subscription over this
+        // connection. baseGroups (the org/user scopes) are always subscribed;
+        // enterScope/leaveScope move per-entity interest. Recreated with the
+        // socket; torn down via the disposer pushed below.
+        this.areaOfInterest = new AreaOfInterestManager({
+            transport: this.syncWebSocket,
+            baseGroups: this.resolveSyncGroups(context),
+        });
         // Connection events → forward to connection lifecycle callback
         const onConnected = this.syncWebSocket.subscribe('connected', () => {
             this.syncClient.markConnected();
@@ -1310,6 +1432,12 @@ export class BaseSyncedStore {
             else {
                 this.updateSyncStatus({ offlineSince: undefined });
             }
+            // Re-assert read interest on every (re)connect. After a transient
+            // reconnect the socket re-sends its URL groups, but interest may have
+            // changed while offline; after a full reconnect the new socket's URL
+            // carries only base groups. `resync` re-pushes the current desired set
+            // so the server-side index matches what the user is actually viewing.
+            void this.areaOfInterest?.resync();
         });
         const onDisconnected = this.syncWebSocket.subscribe('disconnected', () => {
             this.syncClient.disconnect();
@@ -1325,7 +1453,10 @@ export class BaseSyncedStore {
             this.processDeltaWithBatching(delta);
         });
         const onDeltaBatch = this.syncWebSocket.subscribe('delta_batch', (deltas) => {
-            deltas.forEach((delta) => this.processDeltaWithBatching(delta));
+            // A catch-up/reconnect frame is already complete — apply it as ONE
+            // atomic flush so the gallery re-renders once, not once per 50-delta
+            // chunk. See `applyDeltaFrame`.
+            this.applyDeltaFrame(deltas);
         });
         // Bootstrap events
         const onBootstrapRequired = this.syncWebSocket.subscribe('bootstrap_required', (hint) => { this.handleBootstrapRequired(hint); });
@@ -1374,7 +1505,7 @@ export class BaseSyncedStore {
             getContext().logger.warn('[BaseSyncedStore] WebSocket reconnection gave up', { attempts });
             this.updateSyncStatus({ state: 'reconnecting' });
         });
-        this.disposers.push(onConnected, onDisconnected, onReconnecting, onDelta, onDeltaBatch, onBootstrapRequired, onBootstrapData, onPresenceUpdate, onError, onSessionError, onHandshakeFailed, onReconnectFailed);
+        this.disposers.push(onConnected, onDisconnected, onReconnecting, onDelta, onDeltaBatch, onBootstrapRequired, onBootstrapData, onPresenceUpdate, onError, onSessionError, onHandshakeFailed, onReconnectFailed, () => { this.areaOfInterest?.dispose(); this.areaOfInterest = null; });
         // ── Connection FSM ────────────────────────────────────────────
         // Instantiate + start the SDK's ConnectionManager so every
         // consumer gets correct online/offline recovery. Previously this
@@ -1547,9 +1678,59 @@ export class BaseSyncedStore {
     }
     /** Process incoming delta with smart batching */
     processDeltaWithBatching(delta) {
+        if (!this.enqueueDelta(delta))
+            return;
+        this.scheduleDeltaFlush();
+    }
+    /**
+     * Apply a complete, server-delivered delta frame atomically.
+     *
+     * A `delta_batch` WS event (reconnect/catch-up replay) already carries
+     * the FULL set of missed deltas. Routing it through the per-delta
+     * `processDeltaWithBatching` path re-chunks it via the live-traffic
+     * debounce timer + `maxBatchSize` force-flush, so a 300-delta catch-up
+     * fans out into ~6 separate `flushPendingDeltas` cycles — each its own
+     * IDB write, pool mutation, `models:changed` emit, and React re-render.
+     * The decks gallery visibly re-sorts and "pops in" once per chunk.
+     *
+     * Here we run the per-delta bookkeeping (dedup, ack, version vector,
+     * watermark, G/S routing, D cascade) for every delta WITHOUT scheduling
+     * a flush, then flush ONCE — collapsing the whole frame into a single
+     * IDB write + pool mutation + `models:changed` + re-render. Same code
+     * for the post-bootstrap replay of deltas queued during bootstrap.
+     *
+     * (Named `applyDeltaFrame`, not `processDeltaBatch`, to avoid confusion
+     * with `Database.processDeltaBatch` — the lower-level IDB write this
+     * eventually drives through `flushPendingDeltas`.)
+     */
+    applyDeltaFrame(deltas) {
+        let enqueuedAny = false;
+        for (const delta of deltas) {
+            if (this.enqueueDelta(delta))
+                enqueuedAny = true;
+        }
+        if (!enqueuedAny)
+            return;
+        // Cancel any pending live-traffic timer — the frame is complete, so
+        // there is nothing to wait for. Flush everything in one pass.
+        if (this.batchTimer) {
+            clearTimeout(this.batchTimer);
+            this.batchTimer = null;
+        }
+        void this.flushPendingDeltas().catch(this.handleFlushError);
+    }
+    /**
+     * Per-delta bookkeeping + enqueue. Returns `true` when the delta was
+     * pushed onto `pendingDeltas` (a regular batchable I/U/C/D delta that a
+     * subsequent flush must drain), `false` when it was skipped (dedup),
+     * deferred (bootstrap queue), or handled immediately out-of-band (G/S
+     * sync-group mutations). Does NOT schedule a flush — callers decide
+     * whether to debounce (live) or flush atomically (catch-up frame).
+     */
+    enqueueDelta(delta) {
         // Dedup guard — skip already-processed deltas
         if (delta.id > 0 && delta.id <= this.highestProcessedSyncId)
-            return;
+            return false;
         // Confirm awaiting transactions via sync ID threshold (before batching)
         this.syncClient.onDeltaReceived(delta.id);
         // Update version vector
@@ -1560,7 +1741,7 @@ export class BaseSyncedStore {
         // Queue during active bootstrap
         if (this.bootstrapDeltaQueue !== null) {
             this.bootstrapDeltaQueue.push(delta);
-            return;
+            return false;
         }
         // Advance watermark
         this.syncClient.position.advanceApplied(delta.id);
@@ -1568,13 +1749,13 @@ export class BaseSyncedStore {
         // (addedGroups/removedGroups) and incremental (group/userId) payloads.
         if (delta.actionType === 'G') {
             void this.handleSyncGroupChange(delta);
-            return;
+            return false;
         }
         // Sync group removed — handle immediately. Clears affected local state
         // and forces re-bootstrap with the updated group list.
         if (delta.actionType === 'S') {
             void this.handleGroupRemoved(delta);
-            return;
+            return false;
         }
         // DELETE — fire the cascade cancel immediately (O(1) via FK index;
         // must run BEFORE any subsequent update on the same model lands so
@@ -1590,6 +1771,10 @@ export class BaseSyncedStore {
             this.cascadeCancelTransactionsForDeletedParent(delta.modelName, delta.modelId);
         }
         this.pendingDeltas.push(delta);
+        return true;
+    }
+    /** Debounce a flush for live single-delta traffic. */
+    scheduleDeltaFlush() {
         if (this.batchTimer)
             clearTimeout(this.batchTimer);
         if (this.pendingDeltas.length >= this.smartSyncOptions.maxBatchSize) {

package/dist/Database.d.ts

@@ -91,6 +91,14 @@ export declare class Database {
     private bootstrapHelper;
     /** The pre-configured query helper for lazy-loading data from the sync server. */
     get helper(): BootstrapHelper;
+    /**
+     * PURE scoped snapshot fetch for hydrate-on-enter (P4). Returns the FULL
+     * current rows of the given sync groups, with NO side effects — unlike
+     * {@link bootstrapFromServer}, it does not persist to IndexedDB and does not
+     * touch the connection's `subscribedSyncGroups` (which the shrinkage check
+     * owns). The caller applies the result to the pool via the SCOPED apply path.
+     */
+    fetchScopedBootstrapData(syncGroups: readonly string[]): Promise<BootstrapData>;
     private currentDbInfo;
     private workspaceDb;
     /**
@@ -195,7 +203,7 @@ export declare class Database {
          * but the switch returns a no-op verify if one slips through (e.g.
          * replayed from the bootstrap queue) rather than crashing the engine.
          */
-        actionType: 'I' | 'U' | 'D' | 'A' | 'V' | 'C' | 'G' | 'S';
+        actionType: 'I' | 'U' | 'D' | 'A' | 'V' | 'C' | 'G' | 'S' | 'M';
         modelName: string;
         modelId: string;
         data: ModelData | null;
@@ -235,7 +243,7 @@ export declare class Database {
          * shouldn't reach batch processing, but the switch inside returns
          * no-op verify for them if one slips through.
          */
-        actionType: 'I' | 'U' | 'D' | 'A' | 'V' | 'C' | 'G' | 'S';
+        actionType: 'I' | 'U' | 'D' | 'A' | 'V' | 'C' | 'G' | 'S' | 'M';
         modelName: string;
         modelId: string;
         data: ModelData | null;

package/dist/Database.js

@@ -20,6 +20,17 @@ export class Database {
     get helper() {
         return this.bootstrapHelper;
     }
+    /**
+     * PURE scoped snapshot fetch for hydrate-on-enter (P4). Returns the FULL
+     * current rows of the given sync groups, with NO side effects — unlike
+     * {@link bootstrapFromServer}, it does not persist to IndexedDB and does not
+     * touch the connection's `subscribedSyncGroups` (which the shrinkage check
+     * owns). The caller applies the result to the pool via the SCOPED apply path.
+     */
+    async fetchScopedBootstrapData(syncGroups) {
+        // No lastSyncId → a full snapshot of exactly these groups.
+        return this.bootstrapHelper.fetchBootstrap(undefined, syncGroups);
+    }
     // Database state
     currentDbInfo = null;
     workspaceDb = null;
@@ -764,7 +775,10 @@ export class Database {
             // ========================================================================
             // CONFLICT CHECK: Skip UPDATE/INSERT if DELETE exists with higher syncId
             // ========================================================================
-            if (delta.actionType === 'U' || delta.actionType === 'I' || delta.actionType === 'C') {
+            if (delta.actionType === 'U' ||
+                delta.actionType === 'I' ||
+                delta.actionType === 'C' ||
+                delta.actionType === 'M') {
                 const key = `${delta.modelName}:${delta.modelId}`;
                 const deleteSyncId = deleteSyncIds.get(key);
                 if (deleteSyncId !== undefined) {

package/dist/SyncClient.d.ts

@@ -503,7 +503,18 @@ export declare class SyncClient extends EventEmitter {
     applyBootstrapDataToPool(bootstrapData: {
         models?: Record<string, unknown[]>;
         failedModels?: string[];
-    }, protectedIds?: ReadonlySet<string>): {
+    }, protectedIds?: ReadonlySet<string>, options?: {
+        /**
+         * SCOPED backfill (P4 hydrate-on-enter): the snapshot covers only the
+         * groups just entered, NOT the whole type. Two behaviors change to keep
+         * it from corrupting the pool:
+         *   - upsert is version-guarded ({@link ObjectPool.upsertIfNewer}) so a
+         *     concurrent live delta isn't clobbered back to the snapshot version;
+         *   - ghost removal is SKIPPED — a subset snapshot must never evict rows
+         *     of the same type that belong to other (unhydrated) groups.
+         */
+        scoped?: boolean;
+    }): {
         added: number;
         updated: number;
         removed: number;