@abloatai/ablo 0.34.1 → 0.35.0

package/README.md

@@ -66,10 +66,21 @@ claims are visible while the work is still in progress.
 [Version History & Migration Guide](./docs/migration.md)
 
 It works with the auth and database you already have. **In production, your
-database is the system of record.** Ablo is the sync + coordination layer on top
-of it: it consumes your Postgres' logical-replication stream, scopes realtime
-data to *sync groups* from your own identity, and your application keeps owning
-the write path — every row lives in your Postgres. (Trying Ablo with no database
+database is the system of record.** You write through Ablo, and Ablo writes to
+your Postgres: the call enters Ablo's commit chokepoint — where claims, ordering,
+and idempotency are enforced — and lands in your own tables through a scoped
+writer role. The commit is accepted (`queued`) the moment Ablo takes it; when the
+row surfaces in your write-ahead log, the receipt is promoted to `confirmed`.
+**The WAL echo is how Ablo confirms, not how it writes** — your database, not
+Ablo, is the source of truth for row state, and that same stream is what keeps
+every connected client current, scoped to *sync groups* from your own identity.
+
+The writer role is non-superuser and cannot bypass RLS. Before each write Ablo
+sets your tenant context on the connection, so your own row-level security
+policies enforce against Ablo exactly as they do against your app. Ablo runs no
+DDL and owns no schema — your migration tool stays in charge of the shape of your
+database, and Ablo holds only the ordered transaction log and the coordination
+state, never your rows. (Trying Ablo with no database
 yet? A **sandbox** `sk_test` key holds throwaway **test data** — like Stripe test
 mode — so you can explore before pointing it at your Postgres. Test-mode only; in
 production every row lives in your database.)
@@ -91,7 +102,8 @@ production, your database is the system of record**.
 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 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
+npx ablo dev       # the same push, watching ablo/schema.ts and re-pushing on save
 ```
 
 Then point Ablo at the tables for your synced models. Most teams **already
@@ -124,7 +136,7 @@ instead of guessing:
 
 ## Quick Start
 
-One schema, one client, one write path for humans and agents — this runs as-is
+One schema, one client, one write path for agents, servers, and people — this runs as-is
 after `ablo push`:
 
 ```ts
@@ -156,7 +168,7 @@ await ablo.weatherReports.update({
   claim, // the write completes the claimed work and releases the lease
 });
 
-const ready = ablo.weatherReports.get(created.id);
+const ready = ablo.weatherReports.local.retrieve(created.id);
 console.log({ id: ready?.id, status: ready?.status });
 
 await ablo.dispose();
@@ -202,16 +214,15 @@ function persist(client: Sync) { /* ... */ }
 
 ## Reading
 
-Two ways to read, depending on whether you can wait. `get(id)` / `getAll({ where })`
-/ `getCount({ where })` are instant — they read what's already local and re-render
-on their own when it changes, so they're what your UI uses. `retrieve(id)` /
-`list({ where })` go ask the server and return a `Promise`, for when you need the
-authoritative answer right now.
+Two ways to read, depending on whether you can wait. `retrieve({ id })` /
+`list({ where })` answer from what's local and go ask the server when they have
+to, so they return a `Promise`. Put `local.` in front and the read is restricted
+to what's already here — instant, reactive in render, and what your UI uses.
 
 ```ts
-ablo.weatherReports.get('report_stockholm');
+ablo.weatherReports.local.retrieve('report_stockholm');
 
-const pending = ablo.weatherReports.getAll({
+const pending = ablo.weatherReports.local.list({
   where: { status: 'pending' },
   orderBy: { location: 'asc' },
   limit: 20,
@@ -373,7 +384,7 @@ function App() {
 }
 
 function Report({ id }: { id: string }) {
-  const report = useAblo((ablo) => ablo.weatherReports.get(id));
+  const report = useAblo((ablo) => ablo.weatherReports.local.retrieve(id));
   const ablo = useAblo();
 
   if (!report) return null;
@@ -392,7 +403,7 @@ method as the server example above.
 
 `<AbloProvider>` owns the connection — no API key in the browser. That's the
 whole loop: read with `useAblo(selector)`, write with `ablo.<model>`, and every
-other client (human or agent) on that row sees it in real time. See
+other client (agent or human) on that row sees it in real time. See
 [React](./docs/react.md) for the `<AbloProvider>` prop surface (`client`,
 `userId`, `fallback`, `onError`) — schema, scope, and team membership live on the
 `Ablo({ … })` client you pass it — plus status hooks.
@@ -402,7 +413,7 @@ other client (human or agent) on that row sees it in real time. See
 Ablo is **not** an auth provider — you keep your own (Clerk, Auth0, NextAuth,
 whatever). Ablo's job starts after you've authenticated a request: you tell it
 *who* is connecting, and it scopes their realtime data to the right **sync
-groups** (named channels like `org:acme` or `deck:abc123` that are both the unit
+groups** (named channels like `org:acme` or `workspace:abc123` that are both the unit
 of fan-out and the unit of access).
 
 The model is a proxy: your `ABLO_API_KEY` stays on your trusted server, your
@@ -434,19 +445,25 @@ browser.
 
 ## Multiplayer
 
-There is no separate multiplayer mode. When human UI, server actions, and agent
-workers share the same schema and write through `ablo.<model>`, they all see
+There is no separate multiplayer mode. When agent workers, server actions, and
+human UI share the same schema and write through `ablo.<model>`, they all see
 each other's changes in real time — that's the default, not a feature you turn on.
 
 - `ablo.<model>.create/update/delete` fan out confirmed deltas to subscribers.
 - `useAblo(...)` gives React clients the live row, kept current automatically.
-- `ablo.<model>.claim({ id })` / `claim.state({ id })` / `claim.queue({ id })` let humans and agents coordinate (and observe) active work on a row — and the line waiting behind it — before a write lands.
+- `ablo.<model>.claim({ id })` / `claim.state({ id })` / `claim.queue({ id })` let agents and people coordinate (and observe) active work on a row — and the line waiting behind it — before a write lands.
+
+The bare client is the coordination layer: commit, read, observe, claim. The live
+plane people watch — presence, live queries, the local copy — is the `humans()`
+plugin on top of it, installed by default on a socket client. There is no
+`agents()` plugin, and the absence is the point: an agent is the default caller
+here, not a special one.
 
 Writes go through Ablo. `ablo.<model>.create/update/delete` and the HTTP write
 endpoint enter Ablo's commit chokepoint — where claims, ordering, and idempotency
 are enforced — and Ablo lands the change in your database. It then tails the WAL to
 confirm the row landed and fans the confirmed change out to every connected client.
-One surface for humans, servers, and agents; one place coordination happens.
+One surface for agents, servers, and people; one place coordination happens.
 
 ## HTTP Writes
 
@@ -477,7 +494,7 @@ connects:
 
 | | How Ablo connects to your Postgres | Use when |
 | --- | --- | --- |
-| **`ablo connect`** (primary) | Sets up logical replication and a scoped writer role (`npx ablo connect apply` does it end to end). Ablo writes your rows through the writer role and reads them back over the WAL to confirm — it writes rows but runs no DDL and owns no schema. | Your database can grant a `REPLICATION` role (most can). |
+| **`ablo connect`** (primary) | Sets up logical replication and a scoped writer role (`npx ablo connect apply` does it end to end). Ablo writes your rows through the writer role and reads them back over the WAL to confirm — it writes rows but runs no DDL and owns no schema. The role is non-superuser and cannot bypass RLS, so your own policies govern Ablo's writes. | 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 writes and confirms through it. Needs no replication setup. | Your database **can't** grant a replication role (a locked-down managed DB). |
 
 Your database is the system of record. See

package/dist/BaseSyncedStore.d.ts

@@ -10,7 +10,7 @@
  * 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 type { RecoveryClass } from './transaction/errorCodes.js';
 import { ConnectionManager } from './sync/ConnectionManager.js';
 import { SubscriptionManager } from './sync/SubscriptionManager.js';
 import { type ParticipantScope } from './sync/participants.js';
@@ -18,22 +18,23 @@ import type { SyncClient } from './SyncClient.js';
 import type { Database, BootstrapResult } from './Database.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 { SyncWebSocket, type SyncDelta, type SyncGroupChangePayload, type GroupAddedPayload, type GroupRemovedPayload, type BootstrapHint, type BootstrapDataEvent, type PresenceUpdate, type EventMap, type DefaultCollaborationEvents, type SyncWebSocketEventMap } from './sync/SyncWebSocket.js';
 import { QueryProcessor } from './core/QueryProcessor.js';
 import { Model } from './Model.js';
 import { ModelScope } from './InstanceCache.js';
-import type { Schema } from './schema/schema.js';
+import type { Schema } from './transaction/schema/schema.js';
 import type { SyncStatus, LocalMutation } from './core/storeContract.js';
-import type { AuthCredentialSource } from './auth/credentialSource.js';
-import type { ModelData } from './types/modelData.js';
+import type { AuthCredentialSource } from './transaction/auth/credentialSource.js';
+import type { ModelData } from './transaction/types/modelData.js';
 import type { EnrichmentPlanEntry, ForeignKeyIndexSpec } from './sync/syncPlan.js';
 import { type CredentialRefresher } from './sync/credentialLifecycle.js';
 import type { RehydrationStats } from './sync/bootstrapApply.js';
+import type { ParticipantKind } from './transaction/types/participant.js';
 /** Constructor type for Model subclasses (accepts abstract classes) */
 export type ModelConstructor<T extends Model> = abstract new (...args: never[]) => T;
 /** Concrete constructor type for instantiation */
 export type ConcreteModelConstructor<T extends Model> = new (data?: any) => T;
-export type { ModelData } from './types/modelData.js';
+export type { ModelData } from './transaction/types/modelData.js';
 /** Query result interface */
 export interface QueryResult<T extends Model> {
     data: T[];
@@ -47,6 +48,16 @@ export interface SyncedStoreConfig {
     enableOffline?: boolean;
     enableCache?: boolean;
     enableTelemetry?: boolean;
+    /**
+     * Wire message types to surface as collaboration events, e.g.
+     * `['document:selection', 'document:cursor']`.
+     *
+     * The vocabulary belongs to the application, not the SDK — these name the
+     * application's own concepts, and a schema with no documents should never see
+     * them. Defaults to none, so an application opts in by naming the events it
+     * actually broadcasts.
+     */
+    collaborationEvents?: readonly string[];
     /**
      * Declarative enrichment plan consumed by `enrichRelations`. Replaces
      * the subclass override of `enrichRelations` for per-model parent
@@ -75,7 +86,7 @@ export interface UserContext {
      *  sessions; 'agent' for headless bots / worker processes. The
      *  store routes this to SyncWebSocket so the WS URL carries
      *  `kind=agent` and the server applies capability-token auth. */
-    kind?: 'user' | 'agent' | 'system';
+    kind?: ParticipantKind;
     /** Restricted (`rk_`) API key for `kind: 'agent'` — the agent's
      *  bearer credential. Sent in the `ablo.bearer.<token>` WebSocket
      *  subprotocol, never in the URL. */
@@ -107,14 +118,20 @@ export interface SmartSyncOptions {
     maxBatchSize?: number;
 }
 export type { RehydrationStats } from './sync/bootstrapApply.js';
-/** Bootstrap timeout configuration */
+/**
+ * Bootstrap retry configuration.
+ *
+ * There is deliberately no overall timeout here. How long one attempt may run
+ * is not a policy this layer gets to invent — it is a property of the fetcher's
+ * watchdogs, read from `BootstrapFetcher.budgetMs`. A second number kept here
+ * would only be able to disagree with them, which is exactly what it used to do.
+ */
 export declare const BOOTSTRAP_CONFIG: {
-    readonly OVERALL_TIMEOUT_MS: 15000;
     readonly MAX_RETRY_ATTEMPTS: 3;
     readonly RETRY_DELAY_MS: 500;
 };
 export { ModelScope };
-export type { SyncDelta, SyncGroupChangePayload, GroupAddedPayload, GroupRemovedPayload, BootstrapHint, BootstrapDataEvent, PresenceUpdateEvent, };
+export type { SyncDelta, SyncGroupChangePayload, GroupAddedPayload, GroupRemovedPayload, BootstrapHint, BootstrapDataEvent, PresenceUpdate, };
 export { deriveSyncPlanFromSchema } from './sync/syncPlan.js';
 /**
  * The abstract base class that application-specific sync stores extend. It
@@ -133,13 +150,13 @@ export { deriveSyncPlanFromSchema } from './sync/syncPlan.js';
  * the underlying SyncWebSocket without casts:
  *
  * @example
- *   interface AbloEvents {
- *     'sheet:selection': [SheetSelectionEvent];
- *     'slide:cursor':    [SlideCursorEvent];
+ *   interface EditorEvents {
+ *     'document:selection': [SelectionEvent];
+ *     'document:cursor':    [CursorEvent];
  *   }
- *   class SyncedStore extends BaseSyncedStore<AbloEvents> {
- *     subscribeToSlideCursor(handler: (e: SlideCursorEvent) => void) {
- *       return this.syncWebSocket?.subscribe('slide:cursor', handler);
+ *   class EditorStore extends BaseSyncedStore<EditorEvents> {
+ *     subscribeToCursor(handler: (e: CursorEvent) => void) {
+ *       return this.syncWebSocket.subscribe('document:cursor', handler);
  *     }
  *   }
  */
@@ -155,15 +172,20 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * `create(key, data)` factory and model self-healing.
      */
     protected readonly schema?: TSchema;
-    protected syncWebSocket: SyncWebSocket<TCollaboration> | null;
+    /**
+     * The connection, owned by whoever built this store (ADR 0016 follow-up
+     * 3b): the host constructs it and hands it in, the store seeds its late
+     * values during `initialize()` and owns the lifecycle from there. One
+     * instance for the store's whole lifetime — reconnects replace the socket
+     * inside it, never the object.
+     */
+    protected readonly syncWebSocket: SyncWebSocket<TCollaboration>;
     /**
      * 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`.
+     * groups. Constructed with the connection; the permanent base scopes are
+     * seeded in `setupWebSocketSync` once identity resolves.
      */
-    protected areaOfInterest: SubscriptionManager | null;
+    protected readonly areaOfInterest: SubscriptionManager;
     /** 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;
@@ -171,15 +193,32 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      *  enters of the same scope so they share one fetch. */
     private readonly hydratingGroups;
     private _syncServerUrl?;
+    /** Application-declared collaboration event types; empty unless configured. */
+    private _collaborationEvents;
     /**
      * Public accessor for the underlying SyncWebSocket. Used by the
      * factory in `createSyncEngine` to wire the default mutation
      * executor — the executor needs the WS handle to send commit
      * frames, and the factory can't reach `protected` state through
-     * normal typing. Returns null until WS is initialized during
-     * `initialize()`.
+     * normal typing.
+     */
+    getSyncWebSocket(): SyncWebSocket<TCollaboration>;
+    /**
+     * Subscribe to pushed frames — deltas, presence updates, claim grants and
+     * losses, connection changes, and this store's collaboration events.
+     * Durable by construction: the connection object exists for the store's
+     * whole lifetime (reconnects replace only the socket inside it), so a
+     * subscription made before the first connect starts delivering when the
+     * socket opens and keeps delivering across every reconnect. Returns the
+     * unsubscribe function.
      */
-    getSyncWebSocket(): SyncWebSocket<TCollaboration> | null;
+    subscribe<K extends keyof SyncWebSocketEventMap<TCollaboration>>(event: K, handler: (...args: SyncWebSocketEventMap<TCollaboration>[K]) => void): () => void;
+    /**
+     * Send a collaboration event (an app-specific real-time message from this
+     * store's `TCollaboration` map). A no-op while the connection is down —
+     * presence-grade traffic is not queued.
+     */
+    sendCollaborationEvent<K extends string & keyof TCollaboration>(messageType: K, payload: TCollaboration[K] extends [infer P] ? Omit<P & Record<string, unknown>, 'timestamp'> : never): void;
     private scopeToGroups;
     /**
      * Bring a scope into view and subscribe to its sync groups. With
@@ -230,13 +269,15 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     protected pendingDeltas: SyncDelta[];
     protected batchTimer: ReturnType<typeof setTimeout> | null;
     protected syncPromise: Promise<void> | null;
-    /** Resume/ack cursor — delegates to the shared SyncPosition (see
-     *  sync/syncPosition.ts). Advances only after IDB persistence. */
+    /** Resume/ack cursor — delegates to the shared LogPosition (see
+     *  logPosition.ts). Advances only after IDB persistence. */
     protected get lastAckedId(): number;
-    /** Pool-applied cursor — delegates to the shared SyncPosition. */
+    /** Pool-applied cursor — delegates to the shared LogPosition. */
     protected get highestProcessedSyncId(): number;
     protected bootstrapDeltaQueue: SyncDelta[] | null;
     protected activeBootstrapCount: number;
+    /** The live deadline for the bootstrap attempt in flight, if any. */
+    private bootstrapDeadlineTimer;
     protected pendingDeletes: Set<string>;
     protected modelTypesHydrated: Set<string>;
     protected modelTypeHydrationInFlight: Map<string, Promise<void>>;
@@ -245,6 +286,15 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
         database: Database;
         objectPool: InstanceCache;
         modelRegistry: ModelRegistry;
+        /**
+         * The connection, built by the host. When omitted, the store constructs
+         * its own from `url` and the collaboration-event config — the
+         * self-contained path subclasses and tests use. Either way the store
+         * owns the lifecycle from here: it seeds the late values (identity,
+         * read scope, resume cursor) during `initialize()` and releases the
+         * first connect.
+         */
+        syncWebSocket?: SyncWebSocket<TCollaboration>;
         /**
          * Optional schema. When provided, {@link deriveSyncPlanFromSchema} walks
          * the schema's models and relations to auto-populate foreign-key indexes
@@ -331,7 +381,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     subscribeSessionError(listener: (error: Error) => void): () => void;
     /**
      * Subscribe to per-mutation failure payloads. Forwarded from the
-     * underlying `SyncClient.transactionQueue` so consumers (toast layer,
+     * underlying `SyncClient.mutationQueue` so consumers (toast layer,
      * route-level reverted boundaries, telemetry) can react without
      * reaching across the store. Returns an unsubscribe function.
      *
@@ -342,10 +392,17 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * same shape, same lifecycle.
      */
     subscribeMutationFailure(listener: (payload: {
-        transaction: import('./transactions/TransactionQueue.js').Transaction;
+        transaction: import('./transactions/mutations/MutationQueue.js').QueuedMutation;
         error: Error;
         permanent?: boolean;
     }) => void): () => void;
+    /**
+     * Subscribe to commit round-trip latency. Forwarded from the underlying
+     * `SyncClient` for the same reason as `subscribeMutationFailure` — the
+     * React provider binds against this surface, so the engine's wiring stays
+     * private while the SDK keeps one hook to expose.
+     */
+    subscribeCommitLatency(listener: (sample: import('./transactions/mutations/commitLatency.js').CommitLatencySample) => void): () => void;
     /**
      * Wait for the in-flight transaction for (modelName, modelId) to be
      * confirmed by the server. See `SyncClient.waitForConfirmation` for the
@@ -355,7 +412,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     /**
      * Observe the LOCAL mutation stream for undo recording (see
      * {@link import('./core/storeContract.js').LocalMutation}). Taps the
-     * TransactionQueue's `transaction:created` event — fired once per local
+     * MutationQueue's `transaction:created` event — fired once per local
      * create/update/delete/archive with `previousData` already captured.
      * Remote/collaborator deltas apply via `applyDeltaBatchToPool` and never
      * emit here, so undo is naturally local-only (you can't undo a teammate).
@@ -366,8 +423,29 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * Prevents the common issue where bootstrap hangs on startup.
      */
     protected executeBootstrapWithTimeout<T>(bootstrapFn: () => Promise<T>, _context: UserContext, signal?: AbortSignal): Promise<T>;
-    /** Create a timeout promise for bootstrap attempts */
+    /**
+     * The outer deadline for one bootstrap attempt.
+     *
+     * The length is DERIVED from the fetcher's own watchdog budget, not chosen. A
+     * chosen number is what broke this: the previous fixed 15s was shorter than a
+     * single model chunk's allowance — 20s waiting for response headers plus 15s
+     * of stall grace — so on any workspace with one slow model the deadline fired
+     * before the watchdogs it was meant to backstop, and every attempt timed out
+     * by construction. The watchdogs below are progress-based and already
+     * guarantee termination; this deadline exists only for a hang somewhere other
+     * than the network, so it must sit above them, and it can only do that
+     * reliably by asking them how long they take.
+     *
+     * Reaching it aborts the work in flight. `Promise.race` merely stops waiting:
+     * without the abort the losing bootstrap keeps running, keeps its sockets, and
+     * races the retry that replaced it — which is how one page load turned into
+     * dozens of overlapping requests.
+     */
     protected createBootstrapTimeout(attempt: number): Promise<never>;
+    /** Disarm the deadline once its attempt has settled. Load-bearing now that
+     *  firing it aborts real work: a leftover timer would cancel a later,
+     *  unrelated bootstrap. */
+    private clearBootstrapDeadline;
     /** Reset bootstrap-related state for a clean retry */
     protected resetBootstrapState(): void;
     /** Perform reconnect: bootstrap + WS reconnect. Returns outcome for state machine. */
@@ -495,8 +573,15 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * driven session" vs "is this a server agent". The latter never has
      * a tab to lose focus or a network adapter to wake up.
      */
-    protected createConnectionManager(kind?: 'user' | 'agent' | 'system'): ConnectionManager | null;
-    /** Disconnect and clean up all resources */
+    protected createConnectionManager(kind?: ParticipantKind): ConnectionManager | null;
+    /**
+     * Disconnect and clean up all resources. Terminal: this means "the client
+     * is finished", not "close and reopen later" — the connection object stays
+     * assigned but closed, the event wiring is torn down, and nothing
+     * re-initializes a disconnected store. (Mid-session closes during recovery
+     * go through the connection FSM's `onDisconnectWebSocket`, which closes
+     * the transport without touching the store.)
+     */
     disconnect(): Promise<void>;
     /**
      * Destroy every IndexedDB database owned by the sync engine.
@@ -535,7 +620,30 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * mutation attempt surface a clearer error.
      */
     protected waitForWebSocketConnected(timeoutMs: number): Promise<boolean>;
+    /**
+     * Seed the connection's late values and open it. The socket itself exists
+     * from construction; what identity resolution supplies — the participant
+     * kind, the credential, the read scope, and the resume cursor — is seeded
+     * here, and only then is the held first connect released. A retried
+     * `initialize()` after a failed `ready()` re-runs this against the same
+     * connection object: the reconnect counter is reset for a clean slate,
+     * while the session-error latch deliberately survives (only the
+     * credential-expiry recovery clears it).
+     */
     protected setupWebSocketSync(context: UserContext, lastSyncId: number): void;
+    /**
+     * Wire the store's handlers onto the connection. Runs once, at
+     * construction — the connection object is stable for the store's
+     * lifetime, so the wiring is too.
+     */
+    protected wireSocketEvents(): void;
+    /**
+     * Build and start the connection FSM. The `onConnectionEvent` hook is the
+     * bridge — WS events fire the hook, the hook forwards into the FSM. Called
+     * from `setupWebSocketSync` because the FSM's shape depends on the resolved
+     * participant kind (agents get none — see {@link createConnectionManager}).
+     */
+    private startConnectionManager;
     /** Memoized pipeline context — `enqueueDelta` runs once per delta, so the
      *  accessor object is built once and reused (the get/set accessors always
      *  read the live host fields). */
@@ -590,7 +698,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * schema build time) to find children. The previous implementation did
      * `getByType(ctor).filter(e => e.toJSON()[foreignKey] === parentId)` —
      * a full pool scan per child model + a `toJSON()` allocation per
-     * candidate. For a deck delete with 10K layers in the pool, that was
+     * candidate. For a report delete with 10K blocks in the pool, that was
      * 10K toJSON allocations per cascade level. The FK-indexed lookup
      * skips both the scan AND the allocation.
      */
@@ -605,7 +713,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * Save a model (create or update).
      *
      * Accepts any entity shape with `{ id: string }` so consumers can pass the
-     * Zod-inferred model types from `InferModel<Schema, K>` without knowing
+     * Zod-inferred model types from `Model<Schema, K>` without knowing
      * about the internal `Model` base class. At runtime, every entity reaching
      * this method came through the object pool (via `store.create`, a query
      * accessor, or an optimistic insert) and IS a `Model` instance — the one
@@ -618,7 +726,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     }>(entity: T, options?: {
         skipValidation?: boolean;
     }): Promise<void>;
-    /** Save with an atomic server mutation (e.g., createSlideWithLayers) */
+    /** Save with an atomic server mutation (e.g., createSectionWithBlocks) */
     saveWithAtomicMutation(model: Model, mutation: (gql: unknown) => Promise<unknown>): Promise<void>;
     /** Delete a model. Accepts schema-inferred entity shapes (see `save`). */
     delete<T extends {
@@ -648,17 +756,17 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * Create a model instance locally, typed via the schema.
      *
      * ```ts
-     * const sheet = store.create('spreadsheetSheets', { name, spreadsheetId });
-     * // sheet: SpreadsheetSheet | null — no cast needed
+     * const ledger = store.create('ledgers', { name, reportId });
+     * // ledger: Ledger | null — no cast needed
      * ```
      *
      * The `typename` arg is the schema key (camelCase plural, e.g.
-     * `'spreadsheetSheets'`); the returned instance has the
-     * `InferModel<Schema, K>` shape including computeds + relation accessors.
+     * `'ledgers'`); the returned instance has the
+     * `Model<Schema, K>` shape including computeds + relation accessors.
      * Wraps `pool.create(...)` — the underlying runtime is unchanged, just
      * type-narrowed.
      */
-    create<K extends keyof TSchema['models'] & string>(typename: K, data: Record<string, unknown>): import('./schema/schema.js').InferModel<TSchema, K> | null;
+    create<K extends keyof TSchema['models'] & string>(typename: K, data: Record<string, unknown>): import('./transaction/schema/schema.js').Model<TSchema, K> | null;
     /**
      * Query entry point for callers that hold a {@link Model} constructor and an
      * options object. It filters, orders, and paginates the matching models from
@@ -676,7 +784,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     /**
      * Get all models of a type. Returns Model[] honestly — callers that need
      * narrow types should use `useAblo((ablo) => ablo.<model>.list(...))`
-     * which does proper inference via `InferModel<S, K>`.
+     * which does proper inference via `Model<S, K>`.
      */
     allModelsOfType(modelClass: ModelConstructor<Model>, scope?: ModelScope): Model[];
     /** Error handler for fire-and-forget flushPendingDeltas calls */
@@ -688,7 +796,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     /** Handle bootstrap_data event. Override in subclass. */
     protected handleBootstrapData(_data: BootstrapDataEvent): void;
     /** Handle presence_update event. Override in subclass. */
-    protected handlePresenceUpdate(_data: PresenceUpdateEvent): void;
+    protected handlePresenceUpdate(_data: PresenceUpdate): void;
     protected incrementPendingChanges(): void;
     protected decrementPendingChanges(): void;
     protected updateSyncStatus(updates: Partial<SyncStatus>): void;