@abloatai/ablo 0.10.1 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.11.1
+
+### Patch Changes
+
+- 7f91f6e: DX hardening from a real onboarding session — onboarding, CLI, coordination, types, and docs.
+
+  **Client behavior**
+  - `databaseUrl` is now an explicit, server-only option: `Ablo(...)` no longer auto-reads `process.env.DATABASE_URL`. A stray `DATABASE_URL` (common — Prisma/Drizzle/docker set it) no longer silently flips the client into connection-string mode; a one-time warning points at the explicit option. Passing `databaseUrl: process.env.DATABASE_URL` explicitly is unchanged.
+  - Claims/presence are now observable from any client (including Node agents): reading a row enters its entity sync group (read-interest) and claiming pins it (write-intent), so `ablo.<model>.claim.state({ id })` reports co-participants without any manual subscribe step — whether the observer arrives before the claim (live delta) or after it (subscribe-time backfill). The claim **holder** now also sees its own claim via `claim.state`. **Requires a coordinated `sync-server` deploy** (the subscribe-time claim backfill + the entity-scope subscription gate that lets an org-authority agent key narrow into a row's group live server-side); the client package change alone does not deliver cross-client agent observation.
+
+  **CLI**
+  - `ablo init` detects the `src/app` layout (routes + the `@/ablo` import alias resolve correctly), writes the **real** stored sandbox key into `.env.local` instead of a placeholder, and scaffolds `ablo/register.ts` (a regular module, not a colliding `ablo.d.ts`).
+  - `ablo <command> --help` / `-h` now prints usage instead of erroring with "unknown flag", and `migrate` is listed in the top-level help.
+  - `ablo dev --no-watch` now exits after one push instead of watching forever.
+
+  **Types**
+  - Name the client with `typeof sync` (the value-inferred idiom, like tRPC's `typeof appRouter` / Drizzle's `typeof db`) — `ReturnType<typeof Ablo>` collapses to the untyped client and should not be used. No bespoke client-type generic is needed.
+  - `model_claim_not_configured` message clarified: claiming needs no per-model schema configuration; every model is claimable through the standard client.
+
+  **Docs**
+  - Reconciled the self-contradictory `databaseUrl` story (it is an explicit, server-only option, not auto-read from the environment; consistent casing), documented that the sandbox can host rows (apiKey only, no database), explained why a localhost Postgres can't be the system of record, and led the connect-your-database flow with `ablo pull`/`ablo check` over `ablo migrate`. Fixed stale `api.md` vocabulary (`object: 'claim'`, `participantKind: 'user' | 'agent' | 'system'`).
+
+- 7f91f6e: Docs: document the completed `intent` → `claim` rename. Adds a 0.11.0 migration entry (`useIntent` → `useClaim`, `Register.Intents` → `Register.Claims`, `Ablo.Intent.*` → `Ablo.Claim.*`, and the coordinated client/server deploy for the `claim_*` wire frames), a `useClaim` section in the React reference, and fixes the stale `participantKind` union to the canonical `'user' | 'agent' | 'system'`.
+
+## 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

@@ -54,10 +54,12 @@ claims are visible while the work is still in progress.
 `llms.txt`  ·  **upgrading?** see the
 [Version History & Migration Guide](./docs/migration.md)
 
-It works with the auth and database you already have. **Your database is the
-system of record — Ablo never hosts your data.** Ablo is the transaction layer
-on top of it: realtime data is scoped to *sync groups* from your own identity,
-and every committed row lives in your Postgres.
+It works with the auth and database you already have. **In production, your
+database is the system of record.** Ablo is the transaction layer on top of it:
+realtime data is scoped to *sync groups* from your own identity, and every
+committed row lives in your Postgres. (Trying Ablo with no database yet? The
+hosted **sandbox** can host rows in Ablo's test plane — apiKey only, like
+Stripe test mode — so you can explore before pointing it at your Postgres.)
 
 **Built for** collaborative editors, AI agent workflows, and internal tools —
 anywhere people and agents change shared state and everyone has to see it live.
@@ -65,18 +67,24 @@ anywhere people and agents change shared state and everyone has to see it live.
 ## Set up
 
 The CLI takes you from nothing to a synced schema — it handles the account,
-the key, and the env file. You bring one thing: a Postgres `DATABASE_URL`
-(local, Neon, RDS — any will do; **your database is the system of record,
-Ablo never hosts your data**).
+the key, and the env file. You bring one thing: a Postgres you already have —
+the same `DATABASE_URL` (local, Neon, RDS — any will do) that backs your auth,
+audit, and log tables. Ablo syncs a *subset* of models against it; **in
+production, your database is the system of record**.
 
 ```bash
 npm install @abloatai/ablo
 npx ablo login     # opens the browser: sign in (or sign up) → a sk_test_ key is saved locally
 npx ablo init      # scaffolds ablo/schema.ts (offers to log in if you skipped it)
-npx ablo migrate   # creates the synced tables in YOUR Postgres (reads DATABASE_URL)
-npx ablo push       # pushes your schema (sandbox), writes ABLO_API_KEY to .env.local, watches for changes
+npx ablo push      # pushes your schema (sandbox), writes ABLO_API_KEY to .env.local, watches for changes
 ```
 
+Then point Ablo at the tables for your synced models. Most teams **already
+have those tables** (often Prisma- or Drizzle-managed) — adopt them with
+`npx ablo pull` / `npx ablo check`, the common case. Let Ablo own its own
+tables instead? `npx ablo migrate` provisions them in your Postgres (reads
+`DATABASE_URL`). Either way your other tables are left untouched.
+
 After `ablo push`, the [Quick Start](#quick-start) below runs as-is —
 `ABLO_API_KEY` is already in `.env.local` (frameworks load it automatically;
 plain Node: `node --env-file=.env.local app.ts`). `npx ablo status` shows
@@ -104,19 +112,26 @@ 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:
+The schema is registered once (init scaffolds `ablo/register.ts` for you), and
+every type is one parameter away — no `typeof schema` re-stating, anywhere:
 
 ```ts
-// ablo.d.ts — once per project
-import type { schema } from './ablo/schema';
+// ablo/register.ts — scaffolded by `npx ablo init`, sits beside ablo/schema.ts
+import type { schema } from './schema';
 declare module '@abloatai/ablo' {
   interface Register { Schema: typeof schema }
 }
 export {};
 ```
 
+It's a regular `.ts` module, not a hand-authored `.d.ts`. The top-level
+`import type { schema }` makes the `declare module` block *merge* into (augment)
+the SDK's `Register` interface instead of colliding with it — the same shape
+[TanStack Router uses in `src/router.tsx`](https://tanstack.com/router/latest/docs/framework/react/guide/type-safety). Any `.ts` file in your
+`tsconfig` `include` works; it never needs to be imported.
+
 ```ts
 import type { Model } from '@abloatai/ablo/schema';
 
@@ -127,7 +142,26 @@ type WeatherReport = Model<'weatherReports'>; // fully typed from YOUR schema
 TanStack-Router pattern: declare the source of truth once, everything
 infers from it.)
 
+### Naming the client type
+
+When you need to pass the client around (a function parameter, a context value),
+**infer the type from the value** — `type Sync = typeof sync`:
+
+```ts
+export const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+export type Sync = typeof sync; // fully-typed, schema-aware
 
+function persist(client: Sync) { /* ... */ }
+```
+
+This is the same idiom as tRPC's `type AppRouter = typeof appRouter` and
+Drizzle's `typeof db` — the factory resolves the typed overload at the call
+site, so `typeof sync` carries your schema. Do **not** write
+`ReturnType<typeof Ablo>`: that collapses to the untyped last overload and
+loses your model types. There is no bespoke client-type generic to import —
+`typeof` your client value is the type.
+
+```ts
 const schema = defineSchema({
   weatherReports: model({
     location: z.string(),
@@ -139,7 +173,7 @@ const schema = defineSchema({
 const ablo = Ablo({
   schema,
   apiKey: process.env.ABLO_API_KEY, // written to .env.local by `npx ablo push`
-  databaseUrl: process.env.DATABASE_URL, // your Postgres — rows live here, never with Ablo
+  databaseUrl: process.env.DATABASE_URL, // your Postgres, passed explicitly — rows live here
 });
 
 await ablo.ready();
@@ -387,29 +421,35 @@ curl https://api.abloatai.com/v1/commits \
 
 ## Your Database
 
-Every schema model is backed by **your own database** — Ablo is the transaction
-layer on top of it, never the home for your rows. Two ways to connect it:
+In production, every schema model is backed by **your own database** — Ablo is
+the transaction layer on top of it. Two ways to connect it:
 
 | | How Ablo reaches your Postgres | Use when |
 | --- | --- | --- |
-| **Connection string** (default) | `databaseUrl` at init. Ablo registers the connection once (sent over TLS, stored sealed, never echoed back) and commits each write directly — through a non-superuser role, behind row-level security. | You can hand over a scoped connection string. |
+| **Connection string** (primary) | `databaseUrl` at init — passed explicitly, never auto-read from the environment. Ablo registers the connection once (sent over TLS, stored sealed, never echoed back) and commits each write directly — through a non-superuser role, behind row-level security. | You can hand over a scoped connection string. |
 | **Signed endpoint** | Your app exposes one route built from an ORM adapter (`prismaDataSource` / `drizzleDataSource`); Ablo sends signed commit requests and your app writes its own database. | Database credentials must never leave your infrastructure. |
 
-Same product, same truth either way: your database is the system of record. See
+(No database yet? The hosted **sandbox** can host rows in Ablo's test plane —
+omit `databaseUrl` and pass an `apiKey` only, like Stripe test mode — so you can
+try Ablo before connecting your Postgres.)
+
+Same product, same truth either way: in production your database is the system of
+record. See
 [Connect Your Database](./docs/data-sources.md) for both shapes.
 
 ## Configuration
 
-`Ablo({ ... })` takes three things: your schema, your key, and your database —
-the last either as `databaseUrl` here or as a signed
-[Data Source endpoint](./docs/data-sources.md) in your app. Every other option
-has correct defaults:
+`Ablo({ ... })` takes your schema, your key, and — in production — your database,
+either as an explicit `databaseUrl` here or as a signed
+[Data Source endpoint](./docs/data-sources.md) in your app. (`databaseUrl` is
+never auto-read from the environment; omit it to try Ablo against the hosted
+sandbox.) Every other option has correct defaults:
 
 | Option | Type | Default | Purpose |
 | --- | --- | --- | --- |
 | `schema` | `Schema` | — (required) | Typed model proxies (`ablo.<model>.*`) |
 | `apiKey` | `string \| ApiKeySetter \| null` | `process.env.ABLO_API_KEY` | Server key — a string, or an async function for rotation |
-| `databaseUrl` | `string \| null` | `process.env.DATABASE_URL` | Your Postgres, registered as the data plane. Server runtimes only — the SDK throws if it sees this in a browser. Omit it when your app exposes a signed [Data Source endpoint](./docs/data-sources.md) instead. |
+| `databaseUrl` | `string \| null` | `—` | Your Postgres, registered as the data plane. **Must be passed explicitly — it is not auto-read from the environment.** If you have a `DATABASE_URL` set for another tool (Prisma, Drizzle, docker-compose), `Ablo()` ignores it unless you pass `databaseUrl` explicitly. Server runtimes only — the SDK throws if it sees this in a browser. Omit it when your app exposes a signed [Data Source endpoint](./docs/data-sources.md) instead, or when trying Ablo against the hosted sandbox. |
 
 Keep `apiKey` in trusted server runtimes. In the browser, `<AbloProvider>`
 authenticates with the signed-in user's session; the raw-key path is gated

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;