@abloatai/ablo 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.27.0
+
+### Minor Changes
+
+- **Claims can now be held for long-running work by heartbeating — on both transports.** A claim's TTL is crash cleanup, not a work estimate; work that outlives it (a 30-minute report, a long agent run) keeps its lease by beating. `claim({ heartbeat: true })` beats automatically until release; `held.heartbeat()` beats by hand. A lapsed lease answers the next beat with `AbloClaimedError` (`claim_lost`) — for a socketless worker, the failed beat _is_ the loss notification, and any write attempted under the old lease is independently rejected by its `readAt` guard.
+
+- **Beats carry progress and pressure.** `heartbeat({ details })` stores lightweight progress as the claim's peer-visible `meta.progress` (last beat wins, via `claim.state`); every beat's answer reports `queueDepth` — how many participants wait in line behind the lease — observable per auto-beat with the new `onHeartbeat` claim option.
+
+- **`ablo.claims.heartbeatAll({ ttl })`** extends every lease the credential holds in one request (`POST /v1/claims/heartbeat`) — the stateless twin of the WebSocket keepalive, for workers holding many rows.
+
+- **Keepalive renewals extend but never shorten a lease**, so an explicit work-duration `ttl` now survives pings and brief reconnects instead of collapsing to the liveness window.
+
+- **README.** The quick start leads with a runnable example, and a new _Background workers_ section shows the enqueue-on-your-own-queue / heartbeat-the-claim pattern end to end.
+
 ## 0.26.0
 
 ### Minor Changes

package/README.md

@@ -39,10 +39,10 @@ Under the hood, you define your data once with a Zod schema and get the same
 typed model client for every actor — people, server actions, and agents:
 
 ```ts
-await ablo.task.create({ data })                  // create
-await ablo.task.retrieve({ id })                  // read
-await ablo.task.update({ id, data })              // update
-await using task = await ablo.task.claim({ id })  // claim for safe, slow agent work
+await ablo.weatherReports.create({ data })                  // create
+await ablo.weatherReports.retrieve({ id })                  // read
+await ablo.weatherReports.update({ id, data })              // update
+await using claim = await ablo.weatherReports.claim({ id }) // hold for slow agent work
 ```
 
 The schema is the public contract. It gives you typed model methods, realtime
@@ -63,8 +63,9 @@ yet? A **sandbox** `sk_test` key holds throwaway **test data** — like Stripe t
 mode — so you can explore before pointing it at your Postgres. Test-mode only; in
 production every row lives in your database.)
 
-**Built for** collaborative editors, AI agent workflows, and internal tools —
-anywhere people and agents change shared state and everyone has to see it live.
+**Built for** collaborative editors, AI agent workflows, background workers on
+your own infrastructure, and internal tools — anywhere people and agents change
+shared state and everyone has to see it live.
 
 ## Set up
 
@@ -111,62 +112,15 @@ instead of guessing:
 
 ## Quick Start
 
+One schema, one client, one write path for humans and agents — this runs as-is
+after `ablo push`:
+
 ```ts
 import Ablo from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
-```
-
-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/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';
-
-type WeatherReport = Model<'weatherReports'>; // fully typed from YOUR schema
-```
-
-(The same `Register` binding types every hook and client — it's the
-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({
-  // Reserved fields (id, createdAt, updatedAt, organizationId, createdBy) are
-  // provided automatically — don't declare them.
+  // id, createdAt, updatedAt, organizationId, createdBy come free on every model
   weatherReports: model({
     location: z.string(),
     status: z.enum(['pending', 'ready']),
@@ -174,29 +128,21 @@ const schema = defineSchema({
   }),
 });
 
-const ablo = Ablo({
-  schema,
-  apiKey: process.env.ABLO_API_KEY, // written to .env.local by `npx ablo push`
-});
-// Your Postgres is connected once via `npx ablo connect` (logical replication) —
-// not passed here. Ablo tails its WAL; your rows never leave your database.
-
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 await ablo.ready();
 
 const created = await ablo.weatherReports.create({
-  data: {
-    location: 'Stockholm',
-    status: 'pending',
-  },
+  data: { location: 'Stockholm', status: 'pending' },
 });
 
-// An agent claims the row, does its slow work, then writes back. While the
-// claim is held nobody else can overwrite it; anyone else who tries waits in
-// line and re-reads the result. This is the whole point of Ablo.
+// Claim the row before slow work — anyone else waits in line, then re-reads.
 await using claim = await ablo.weatherReports.claim({ id: created.id });
-const report = claim.data;
-const forecast = await fetchForecast(report.location); // slow: API or LLM call
-await ablo.weatherReports.update({ id: report.id, data: { status: 'ready', forecast } });
+const forecast = await fetchForecast(claim.data.location); // slow: API or LLM call
+await ablo.weatherReports.update({
+  id: created.id,
+  data: { status: 'ready', forecast },
+  claim, // the write completes the claimed work and releases the lease
+});
 
 const ready = ablo.weatherReports.get(created.id);
 console.log({ id: ready?.id, status: ready?.status });
@@ -210,6 +156,38 @@ Expected output:
 { id: '...', status: 'ready' }
 ```
 
+### TypeScript setup (once, scaffolded for you)
+
+`npx ablo init` writes `ablo/register.ts` next to your schema. It binds your
+schema to the SDK's types once — the same declaration-merging shape
+[TanStack Router uses](https://tanstack.com/router/latest/docs/framework/react/guide/type-safety) —
+so every hook and client infers from it:
+
+```ts
+// ablo/register.ts — scaffolded by `npx ablo init`
+import type { schema } from './schema';
+declare module '@abloatai/ablo' {
+  interface Register { Schema: typeof schema }
+}
+export {};
+```
+
+```ts
+import type { Model } from '@abloatai/ablo/schema';
+
+type WeatherReport = Model<'weatherReports'>; // fully typed from your schema
+```
+
+To pass the client around, take the type from the value — the tRPC /
+Drizzle idiom:
+
+```ts
+export const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+export type Sync = typeof sync;
+
+function persist(client: Sync) { /* ... */ }
+```
+
 ## Reading
 
 Two ways to read, depending on whether you can wait. `get(id)` / `getAll({ where })`
@@ -262,7 +240,11 @@ meanwhile, or worse, acts on stale state. `claim` holds the row across that gap:
 await using claim = await ablo.weatherReports.claim({ id: 'report_stockholm' });
 const report = claim.data;
 const forecast = await weatherAgent.getWeather(report.location);
-await ablo.weatherReports.update({ id: report.id, data: { forecast, status: 'ready' } });
+await ablo.weatherReports.update({
+  id: report.id,
+  data: { forecast, status: 'ready' },
+  claim, // attribute the write to the held claim
+});
 ```
 
 If someone else holds the row, `claim()` waits in a fair queue, then re-reads —
@@ -311,6 +293,46 @@ try {
 See [Coordination](./docs/coordination.md) for the full `claim` / `claim.state` /
 `claim.queue` / `claim.release` reference.
 
+## Background workers — jobs that run for minutes, not seconds
+
+Your API route enqueues a job on your own queue (SQS, EventBridge, anything);
+a worker on your own infrastructure does the slow part. **Keep that queue —
+Ablo is the worker's data layer.** It covers the two things every queue leaves
+to you: keeping the row safe, and showing progress live.
+
+Long work holds its claim by **heartbeating** — the same pattern as an SQS
+visibility heartbeat or a Temporal activity heartbeat:
+
+```ts
+// on your worker — stateless HTTP, no socket to hold
+await using claim = await ablo.weatherReports.claim({
+  id: msg.reportId,
+  ttl: '10m',
+  heartbeat: true,                 // beats automatically until release
+  onHeartbeatLost: () => abort(),  // the lease is gone → stop working
+});
+
+for (const step of steps) {
+  await runStep(step);
+  // write progress to the row — every subscribed UI updates live
+  await ablo.weatherReports.update({ id: msg.reportId, data: { progress: step.pct }, claim });
+}
+```
+
+- A worker that **crashes** stops beating; the row frees within one beat and
+  the next worker takes over.
+- A worker that **wakes up late** learns it on its next beat
+  (`AbloClaimedError`), and the write path rejects its stale writes anyway.
+- **Retries stay on your queue** — the redelivered job claims the now-free
+  row, reads its current state, and resumes.
+- A worker holding **many rows** extends them all in one call:
+  `ablo.claims.heartbeatAll({ ttl: '5m' })`.
+
+SQS's heartbeat protects the *message* from redelivery; Ablo's protects the
+*row* from concurrent and stale writes. SQS is at-least-once, so two workers
+will eventually get the same job — the claim is what keeps that from
+corrupting data.
+
 ## React
 
 In a React app it's the **same `ablo.<model>` API** — just mounted through a
@@ -445,14 +467,8 @@ connects:
 | **Logical replication** (primary) | `npx ablo connect` prints the setup SQL (`wal_level=logical`, a publication, a `REPLICATION` role); `npx ablo connect --register` tells Ablo to replicate it. Ablo tails the WAL — it never runs DDL on, writes to, owns, or migrates your database. | Your database can grant a `REPLICATION` role (most can). |
 | **Signed endpoint** (fallback) | Your app exposes one route built from an ORM adapter (`prismaDataSource` / `drizzleDataSource`); Ablo sends signed requests and your app touches its own database. Needs no database configuration. | Your database **can't** grant a replication role (a locked-down managed DB). |
 
-(No database yet? A **sandbox** `sk_test` key lets you try Ablo's full API and
-coordination with throwaway **test data** — like Stripe test mode — before you
-connect your own Postgres. Test-mode only: in production your rows always live in
-your database and Ablo holds just the transaction log, never your data.)
-
-Your database is the system of record. The old `databaseUrl` dial-in (Ablo
-holding a read/write connection) is **deprecated and being removed** — connect
-via logical replication instead. See
+Your database is the system of record — Ablo holds the transaction log and
+coordination, never your rows. See
 [Connect Your Database](./docs/data-sources.md).
 
 ## Configuration
@@ -466,7 +482,7 @@ Every other option has correct defaults:
 | --- | --- | --- | --- |
 | `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` | `—` | **Deprecated — being removed.** The old dial-in (Ablo holding a read/write connection to your DB). Connect via `npx ablo connect` (logical replication) instead; Ablo tails your WAL rather than dialing in. See [Connect Your Database](./docs/data-sources.md). |
+| `databaseUrl` | `string \| null` | `—` | Deprecated. Connect via `npx ablo connect` instead — see [Connect Your Database](./docs/data-sources.md). |
 
 Keep `apiKey` in trusted server runtimes. In the browser, `<AbloProvider>`
 authenticates with the signed-in user's session; the raw-key path is gated
@@ -519,7 +535,7 @@ contract; there are no retry or timeout knobs to tune.
 - [Guarantees](./docs/guarantees.md) — confirmed writes, stale-write protection, claim coordination, and agent lifecycle.
 - [Integration Guide](./docs/integration-guide.md) — integrate React, your database, multiplayer, and agents.
 - [React](./docs/react.md) — `<AbloProvider>`, `useAblo`, presence, status, and bootstrap gating.
-- [Coordination](./docs/coordination.md) — `claim` / `claim.state` / `claim.queue` / `claim.release` reference: hold a row across slow agent work, and observe the line waiting behind it.
+- [Coordination](./docs/coordination.md) — `claim` / `claim.state` / `claim.queue` / `claim.release` / `heartbeat` reference: hold a row across slow agent work — minutes or hours, via heartbeats — and observe the line waiting behind it.
 - [Client Behavior](./docs/client-behavior.md) — options, errors, retries, timeouts, and public imports.
 - [Connect Your Database](./docs/data-sources.md) — connect your Postgres by logical replication (`npx ablo connect`) or, as a fallback, a signed endpoint; your database is the system of record either way.
 - [Existing Python Backend](./docs/examples/existing-python-backend.md) — migrate existing Python endpoints to multiplayer and agent-safe writes gradually.

package/dist/BaseSyncedStore.d.ts

@@ -1,28 +1,27 @@
 /**
- * BaseSyncedStore — Generic sync store base class for the SDK.
+ * The base class that application-specific sync stores extend. It supplies the
+ * shared orchestration for reads, writes, delta processing, and bootstrap, and
+ * exports the core types those stores build on.
  *
- * Exports the core types, interfaces, and a base class that app-specific
- * stores extend. The base class provides query/mutation/delta/bootstrap
- * orchestration. Subclasses add domain-specific lazy-loading, collaboration
- * events, and model enrichment.
- *
- * Design: The app's SyncedStore extends this and adds its own methods.
- * This file only contains types and the abstract contract — the actual
- * implementation stays in the app's SyncedStore.ts until we incrementally
- * pull generic methods into this base class.
+ * A subclass adds its own domain behavior — lazy-loaded relations,
+ * collaboration events, and model enrichment — by overriding the protected
+ * extension points defined here. The heavy lifting is delegated to injected
+ * collaborators: {@link SyncClient} owns pool writes and the transaction
+ * queue, {@link Database} owns local persistence, {@link InstanceCache} holds the
+ * in-memory models, and {@link ModelRegistry} holds their metadata.
  */
 import type { RecoveryClass } from './errorCodes.js';
 import { ConnectionManager } from './sync/ConnectionManager.js';
-import { AreaOfInterestManager } from './sync/AreaOfInterestManager.js';
+import { SubscriptionManager } from './sync/SubscriptionManager.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';
+import type { InstanceCache } from './InstanceCache.js';
 import { ModelRegistry } from './ModelRegistry.js';
 import { SyncWebSocket, type SyncDelta, type SyncGroupChangePayload, type GroupAddedPayload, type GroupRemovedPayload, type BootstrapHint, type BootstrapDataEvent, type PresenceUpdateEvent, type EventMap, type DefaultCollaborationEvents } from './sync/SyncWebSocket.js';
 import { QueryProcessor } from './core/QueryProcessor.js';
 import { Model } from './Model.js';
-import { ModelScope } from './ObjectPool.js';
+import { ModelScope } from './InstanceCache.js';
 import type { Schema } from './schema/schema.js';
 import type { SyncStatus, LocalMutation } from './core/storeContract.js';
 import type { AuthCredentialSource } from './auth/credentialSource.js';
@@ -56,7 +55,7 @@ export interface SyncedStoreConfig {
      */
     enrichmentPlan?: readonly EnrichmentPlanEntry[];
     /**
-     * Foreign-key indexes to register on the ObjectPool at construction
+     * Foreign-key indexes to register on the InstanceCache at construction
      * time. Replaces the subclass override of `registerForeignKeys` for
      * per-model FK registration. Merged with schema-derived entries
      * (relations marked `{ index: true }` on `belongsTo`). Both sets
@@ -79,8 +78,7 @@ export interface UserContext {
     kind?: 'user' | 'agent' | 'system';
     /** Restricted (`rk_`) API key for `kind: 'agent'` — the agent's
      *  bearer credential. Sent in the `ablo.bearer.<token>` WebSocket
-     *  subprotocol, never in the URL. (Field name predates the
-     *  Biscuit→opaque-key migration.) */
+     *  subprotocol, never in the URL. */
     capabilityToken?: string;
     /** Server-authoritative sync groups, supplied by auth/capability
      *  exchange. The SDK does not invent org/user/default groups; app
@@ -119,16 +117,15 @@ export { ModelScope };
 export type { SyncDelta, SyncGroupChangePayload, GroupAddedPayload, GroupRemovedPayload, BootstrapHint, BootstrapDataEvent, PresenceUpdateEvent, };
 export { deriveSyncPlanFromSchema } from './sync/syncPlan.js';
 /**
- * BaseSyncedStore — abstract base for app-specific sync stores.
- *
- * Provides the dependency structure, observable status, and protected
- * accessors that subclasses use. The actual sync orchestration (initialize,
- * delta processing, bootstrap, query, save, delete, etc.) lives in the
- * app's concrete subclass for now — methods will be pulled up into this
- * base class incrementally as they are genericized.
+ * The abstract base class that application-specific sync stores extend. It
+ * carries the injected collaborators, the observable sync status, and the
+ * orchestration for initialization, delta processing, bootstrap, and the
+ * read and write API. A subclass supplies its own domain behavior by
+ * overriding the protected extension points defined here and by typing its
+ * collaboration events through the generic parameter.
  *
- * Subclasses MUST call `super(dependencies, config)` and then set up
- * their own MobX observables.
+ * A subclass must call `super(dependencies, config)` and then set up its own
+ * MobX observables.
  *
  * Generic over `TCollaboration` — an app-defined event map for real-time
  * collaboration events (cursors, selections, presence beyond the core set).
@@ -150,7 +147,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     syncStatus: SyncStatus;
     protected readonly syncClient: SyncClient;
     protected readonly database: Database;
-    protected readonly objectPool: ObjectPool;
+    protected readonly objectPool: InstanceCache;
     protected readonly modelRegistry: ModelRegistry;
     protected readonly auth?: AuthCredentialSource;
     /**
@@ -166,7 +163,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * to whichever instance is current, so callers (the React participant
      * hook) never hold a stale reference. Null until `setupWebSocketSync`.
      */
-    protected areaOfInterest: AreaOfInterestManager | null;
+    protected areaOfInterest: SubscriptionManager | 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;
@@ -185,22 +182,22 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     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.
+     * Bring a scope into view and subscribe to its sync groups. With
+     * `{ hydrate: true }`, also backfill the groups' current state into the pool
+     * once the subscription is active. The order matters: subscribing first
+     * guarantees no live delta is missed in the gap before the snapshot lands.
+     * Hydration is best-effort — a failed backfill never rejects `enterScope`,
+     * and the live delta stream keeps flowing regardless.
      */
     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.
+     * Backfill the current state of `syncGroups` into the pool with a side-effect-free
+     * scoped snapshot fetch followed by the version-guarded scoped apply. The call
+     * is idempotent (it skips groups already hydrated) and single-flight (concurrent
+     * enters of the same group share one fetch). On error the groups are left
+     * unmarked, 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. */
@@ -246,15 +243,14 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     constructor(dependencies: {
         syncClient: SyncClient;
         database: Database;
-        objectPool: ObjectPool;
+        objectPool: InstanceCache;
         modelRegistry: ModelRegistry;
         /**
-         * Optional schema. When provided, `deriveSyncPlanFromSchema` walks
-         * the schema's models + relations to auto-populate FK indexes and
-         * the enrichment plan from declarative annotations. Class-based
-         * subclass users (like Ablo's legacy SyncedStore) typically pass
-         * explicit `config.foreignKeyIndexes` / `config.enrichmentPlan`
-         * instead.
+         * Optional schema. When provided, {@link deriveSyncPlanFromSchema} walks
+         * the schema's models and relations to auto-populate foreign-key indexes
+         * and the enrichment plan from their declarative annotations. Subclasses
+         * that register model classes directly can instead pass explicit
+         * `config.foreignKeyIndexes` / `config.enrichmentPlan`.
          */
         schema?: TSchema;
         /** Sync server URL for WebSocket connection. Converted to wss:// automatically. */
@@ -263,17 +259,17 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
         auth?: AuthCredentialSource;
     }, config?: SyncedStoreConfig);
     /**
-     * Register foreign key indexes for O(1) lookups.
+     * Register foreign-key indexes for constant-time lookups.
      *
-     * Legacy override hook — in Phase 2 the preferred way to declare FK
-     * indexes is via `config.foreignKeyIndexes` at construction time, or
-     * by marking the `belongsTo` relation with `{ index: true }` in the
-     * schema. This hook still fires AFTER the schema-derived + config
-     * registrations, so subclasses can layer additional FKs on top.
+     * This is an override hook. The preferred way to declare a foreign-key
+     * index is `config.foreignKeyIndexes` at construction time, or marking the
+     * `belongsTo` relation with `{ index: true }` in the schema. The hook fires
+     * after the schema-derived and config registrations, so a subclass can
+     * layer additional indexes on top.
      */
     protected registerForeignKeys(): void;
     /**
-     * Enrich delta data with related models from the ObjectPool.
+     * Enrich delta data with related models from the InstanceCache.
      *
      * Base implementation walks `this.enrichmentPlan` — entries populated
      * from the schema's `{ enrich: true }` relations and from
@@ -390,11 +386,12 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      */
     performCredentialRefresh(): Promise<'refreshed' | 'session_error' | 'network_error'>;
     /**
-     * THE auth-recovery backbone for HTTP transports (lazy query lane etc.):
-     * classify-driven single-flight re-mint with the same FSM outcome routing
-     * the WS probe and proactive pre-roll use. `'retry'` ⇒ a fresh credential
-     * is in the credential source, replay the request ONCE. Full contract on
-     * {@link CredentialLifecycle.recoverFromAuthRejection}.
+     * The authentication-recovery path for HTTP transports, such as the lazy
+     * query lane. It runs a single-flight credential re-mint driven by the
+     * rejection's recovery class, routing outcomes through the same state
+     * machine the WebSocket probe uses. `'retry'` means a fresh credential is
+     * now in the credential source and the request should be replayed once.
+     * Full contract on {@link CredentialLifecycle.recoverFromAuthRejection}.
      */
     recoverFromAuthRejection(recovery: RecoveryClass): Promise<'retry' | 'stop'>;
     /**
@@ -406,11 +403,11 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      */
     nudgeReconnect(): void;
     /**
-     * Install the access-credential lifecycle the CLIENT owns: register
-     * `getToken` as the reactive re-mint hook AND arm the browser-only
-     * proactive pre-roll (refresh timer + OS-wake re-mint). Idempotent
-     * (a second call replaces the first); torn down on {@link disconnect}.
-     * Full rationale on {@link CredentialLifecycle.start}.
+     * Install the client-owned access-credential lifecycle: register `getToken`
+     * as the reactive re-mint hook and arm the browser-only proactive refresh
+     * (a refresh timer plus an OS-wake re-mint). Idempotent — a second call
+     * replaces the first — and torn down on {@link disconnect}. Full rationale
+     * on {@link CredentialLifecycle.start}.
      */
     startCredentialLifecycle(getToken: CredentialRefresher, opts?: {
         proactiveInNode?: boolean;
@@ -431,8 +428,9 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      */
     protected handleGroupAdded(payload: GroupAddedPayload, syncId: number): Promise<void>;
     /**
-     * Handle an actionType 'S' (GroupRemoved) delta — SECURITY clear of local
-     * state + full re-bootstrap. See {@link groupChange.handleGroupRemoved}.
+     * Handle an actionType 'S' (GroupRemoved) delta: for safety, clear the
+     * revoked local state and trigger a full re-bootstrap. See
+     * {@link groupChange.handleGroupRemoved}.
      */
     protected handleGroupRemoved(delta: SyncDelta): Promise<void>;
     /** Compute new sync groups after applying additions and removals */
@@ -453,8 +451,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     protected checkSyncGroupShrinkage(): Promise<void>;
     /** Narrow context the bootstrap-apply leaf talks back through. */
     private poolContext;
-    /** Apply bootstrap data to the ObjectPool with ghost removal */
-    /** Apply bootstrap data to the ObjectPool. Delegates pool writes to SyncClient. */
+    /** Apply bootstrap data to the {@link InstanceCache}, removing entities that are no longer present (ghost removal). Pool writes are delegated to {@link SyncClient}. */
     protected applyBootstrapToPool(bootstrapResult: BootstrapResult, protectedIds?: ReadonlySet<string>): RehydrationStats;
     /**
      * Initialize the sync engine with user context.
@@ -553,23 +550,24 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     /**
      * 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.
+     * A `delta_batch` WebSocket event (a reconnect or catch-up replay) already
+     * carries the full set of missed deltas. Routing it through the per-delta
+     * `processDeltaWithBatching` path would re-chunk it via the live-traffic
+     * debounce timer and `maxBatchSize` force-flush, so a 300-delta catch-up
+     * would fan out into several separate `flushPendingDeltas` cycles — each its
+     * own local write, pool mutation, `models:changed` emit, and re-render, so
+     * the UI visibly repaints 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.
+     * Instead, this runs the per-delta bookkeeping (deduplication, ack, version
+     * vector, watermark, group-change routing, delete cascade) for every delta
+     * without scheduling a flush, then flushes once — collapsing the whole frame
+     * into a single local write, pool mutation, `models:changed` emit, and
+     * re-render. The post-bootstrap replay of deltas queued during bootstrap
+     * uses the same path.
      *
-     * (Named `applyDeltaFrame`, not `processDeltaBatch`, to avoid confusion
-     * with `Database.processDeltaBatch` — the lower-level IDB write this
-     * eventually drives through `flushPendingDeltas`.)
+     * It is named `applyDeltaFrame`, not `processDeltaBatch`, to avoid confusion
+     * with {@link Database.processDeltaBatch} — the lower-level local write this
+     * eventually drives through `flushPendingDeltas`.
      */
     protected applyDeltaFrame(deltas: SyncDelta[]): void;
     /**
@@ -597,8 +595,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * skips both the scan AND the allocation.
      */
     protected cascadeCancelTransactionsForDeletedParent(parentModelName: string, parentId: string): void;
-    /** Flush pending deltas with deduplication and batched ObjectPool mutations */
-    /** Flush pending deltas with deduplication. Delegates pool writes to SyncClient. */
+    /** Flush pending deltas with deduplication. Pool writes are delegated to {@link SyncClient}. */
     protected flushPendingDeltas(): Promise<void>;
     /** Check if a model type is local-only (no sync). Override for domain-specific models. */
     protected isLocalOnlyModel(_modelName: string): boolean;
@@ -663,10 +660,10 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      */
     create<K extends keyof TSchema['models'] & string>(typename: K, data: Record<string, unknown>): import('./schema/schema.js').InferModel<TSchema, K> | null;
     /**
-     * Legacy class-based query entry point — kept for callers that still pass
-     * a Model constructor + options object. New code should use the typed
-     * `store.query.<modelKey>` namespace instead, which returns properly
-     * inferred schema types without needing a class value or cast.
+     * Query entry point for callers that hold a {@link Model} constructor and an
+     * options object. It filters, orders, and paginates the matching models from
+     * the pool. Prefer the schema-typed read surface (`ablo.<model>.list`) where
+     * you can, since it infers concrete row types without a class value or cast.
      */
     queryByClass(modelClass: ModelConstructor<Model>, options?: {
         predicate?: (model: Model) => boolean;
@@ -695,7 +692,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     protected incrementPendingChanges(): void;
     protected decrementPendingChanges(): void;
     protected updateSyncStatus(updates: Partial<SyncStatus>): void;
-    get pool(): ObjectPool;
+    get pool(): InstanceCache;
     get lastSyncId(): number;
     get isReady(): boolean;
     get isSyncing(): boolean;