@abloatai/ablo 0.26.0 → 0.27.0

package/dist/sync/{AreaOfInterestManager.js → SubscriptionManager.js}

@@ -1,38 +1,28 @@
 /**
- * AreaOfInterestManager — client-side hysteresis + prominence policy over
- * the `update_subscription` read primitive.
+ * Decides which sync groups a connection subscribes to as the user navigates,
+ * and pushes each change through the {@link SubscriptionTransport}'s
+ * `update_subscription` call. It smooths two kinds of churn so that opening and
+ * closing entities does not turn into a storm of subscription changes.
  *
- * Game netcode never thrashes its area-of-interest on a boundary: a cell
- * you walk out of stays subscribed for a margin before it's dropped
- * (hysteresis), and "important" entities stay relevant from farther away
- * (prominence). This manager applies both to Ablo sync groups:
+ * The first is hysteresis. Calling {@link SubscriptionManager.leave | leave}
+ * on a group does not unsubscribe it right away; the group stays subscribed for
+ * a grace period — its warm window — and drops only once that window lapses.
+ * Re-entering within the window costs nothing, since the group was never
+ * dropped, so rapid back-and-forth navigation becomes a cache hit rather than a
+ * repeated bootstrap.
  *
- *   - `enter(group)` / `leave(group)` move read interest as the user opens
- *     and closes entities (decks, sheets, docs). A `leave` does NOT
- *     immediately unsubscribe — the group goes WARM with a TTL and stays
- *     in the effective set. Re-entering within the window is a no-op
- *     (already subscribed → no bootstrap), and only when the warm TTL
- *     lapses does the group actually drop. This is the boundary hysteresis
- *     that turns deck-tab flipping from a re-bootstrap storm into a
- *     cache hit.
+ * The second is prominence. A group that holds an active write claim is pinned
+ * (see {@link SubscriptionManager.pin | pin}) and stays subscribed regardless
+ * of navigation, so a row someone is actively editing never loses its live
+ * updates. The `baseGroups` are permanent scopes that are always subscribed.
  *
- *   - `pin(group)` / `unpin(group)` express prominence: a group that holds
- *     an active claim (write-claim) is pinned and never goes warm or
- *     expires while pinned. The claim machinery is the prominence oracle —
- *     the row two agents are fighting over stays subscribed regardless of
- *     navigation.
- *
- *   - `baseGroups` are permanent infrastructure scopes (e.g. `org:<id>`,
- *     `user:<id>`) that are always in the effective set.
- *
- * The effective set is recomputed and diffed against what was last sent;
- * the transport's `update_subscription` is only called when it actually
- * changes, so hysteresis genuinely suppresses network churn rather than
- * just deferring it.
- *
- * Transport-agnostic: it depends only on {@link SubscriptionTransport},
- * which `SyncWebSocket` satisfies structurally. `now` and the sweep timer
- * are injectable so the policy is deterministic under test.
+ * The manager recomputes the full desired set on every change, diffs it against
+ * the set the transport last confirmed, and calls `update_subscription` only
+ * when the set actually changes — so the smoothing suppresses network traffic
+ * rather than merely deferring it. It depends only on
+ * {@link SubscriptionTransport}, which {@link SyncWebSocket} satisfies. The
+ * clock and the sweep timer are injectable so the policy is deterministic under
+ * test.
  */
 function setsEqual(a, b) {
     if (a.size !== b.size)
@@ -42,7 +32,7 @@ function setsEqual(a, b) {
             return false;
     return true;
 }
-export class AreaOfInterestManager {
+export class SubscriptionManager {
     transport;
     baseGroups;
     warmTtlMs;
@@ -165,19 +155,15 @@ export class AreaOfInterestManager {
         return [...this.lastSent];
     }
     /**
-     * Re-assert the full desired set against the transport, forgetting what
-     * was previously confirmed. Call after a reconnect: a fresh
-     * `SyncWebSocket` instance starts from the connect-time URL groups, so
-     * the manager's `lastSent` diff baseline is stale. Clearing it forces
-     * one `update_subscription` that re-establishes the live interest on the
-     * new socket.
-     *
-     * Resetting `lastSent` makes the next reconcile unconditionally re-push
-     * the current desired set (one `update_subscription` frame) so the fresh
-     * socket's server-side index matches local interest, even if warm/pinned
-     * groups drifted across the disconnect window. The connect-time URL
-     * already carries the last-acked set, so this is a correction frame, not
-     * the primary mechanism.
+     * Re-asserts the full desired set against the transport, forgetting what was
+     * previously confirmed. Call this after a reconnect: a fresh
+     * {@link SyncWebSocket} starts from the sync groups named in the connect-time
+     * URL, so the manager's diff baseline no longer reflects the new socket.
+     * Clearing that baseline makes the next reconcile push one
+     * `update_subscription` frame that re-establishes the current interest —
+     * including any warm or pinned groups that drifted while the connection was
+     * down. The connect-time URL already carries the last-acknowledged set, so
+     * this is a correction, not the primary mechanism.
      */
     resync() {
         this.lastSent = new Set();
@@ -214,14 +200,20 @@ export class AreaOfInterestManager {
                         this.lastSent = new Set(result.syncGroups);
                     }
                     catch {
-                        // Transport unavailable (offline / socket not open) or the
-                        // server rejected the set. Interest is SOFT state — never throw
-                        // out of enter/leave/sweep for an expected transient. Leave
-                        // `lastSent` unchanged so the diff persists; `resync()` on the
-                        // next `connected` re-pushes the then-current desired set,
-                        // which is what recovers "interest changed while offline."
+                        // Transport unavailable (offline, or socket not open) or the
+                        // server rejected the set. Read interest is soft state, so enter,
+                        // leave, and sweep never throw for an expected transient failure.
+                        // Leaving `lastSent` unchanged keeps the pending diff; `resync()`
+                        // on the next successful connect re-pushes the then-current desired
+                        // set, which recovers any interest that changed while offline.
                         break;
                     }
+                    // A concurrent reconcile() arriving during the await above sets
+                    // `this.dirty` back to true (the coalescing path near line 245).
+                    // TypeScript's intra-closure flow analysis can't see that cross-
+                    // invocation mutation and reads this as always-false, but the loop
+                    // is genuinely reentrant.
+                    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
                 } while (this.dirty);
             }
             finally {

package/dist/sync/SyncWebSocket.d.ts

@@ -1,50 +1,48 @@
 /**
- * SyncWebSocket - Manages WebSocket connection to Go sync engine
- *
- * Handles:
- * - WebSocket lifecycle (connect, reconnect, disconnect)
- * - Delta reception and processing
- * - Multi-tab support
- * - Automatic reconnection with exponential backoff
+ * Manages the WebSocket connection to the sync server. It owns the socket
+ * lifecycle (connect, reconnect, disconnect), receives and validates the
+ * incoming delta stream, sends commits and claims over the same socket, and
+ * reconnects automatically with exponential backoff. Consumers subscribe to its
+ * typed events (see {@link CoreSyncEventMap}) to react to deltas, presence, and
+ * connection changes.
  */
 import { EventEmitter } from 'events';
 import type { MutationOperation } from '../interfaces/index.js';
-import { type ClientSyncDelta } from '../schema/sync-delta-wire.js';
+import { type ClientSyncDelta } from '../wire/delta.js';
 import type { ClaimError, ClaimRejection, StaleNotification, ReadDependency } from '../coordination/schema.js';
 import { type CommitAck } from './commitFrames.js';
 export type { CommitAck } from './commitFrames.js';
 import { type AuthTokenGetter } from '../auth/credentialSource.js';
 /**
- * The wire delta the client receives. Derived from the canonical
- * `clientSyncDeltaSchema` (`@abloatai/ablo/schema`) via `z.infer` so the
- * SDK and the sync-server share ONE contract instead of two hand-maintained
- * interfaces. The action vocabulary (`I`/`U`/`D`/`A`/`V`/`C`/`G`/`S`) and the
- * client-only extras (`metadata`, `clientMutationId`, deprecated flat
- * `createdBy`) live in that schema; see its doc for the full field reference.
+ * The wire delta the client receives. It is inferred from the canonical
+ * `clientSyncDeltaSchema` so the client and server share one contract rather
+ * than two hand-maintained definitions. The action vocabulary
+ * (`I`/`U`/`D`/`A`/`V`/`C`/`G`/`S`) and the client-only extras (`metadata`,
+ * `clientMutationId`, and the deprecated flat `createdBy`) live in that schema;
+ * see its own documentation for the full field reference.
  */
 export type SyncDelta = ClientSyncDelta;
 /**
- * Payload for legacy actionType 'G' deltas emitted by EmitGroupChange.
- * Carries both added and removed groups in one delta, forces full re-bootstrap.
+ * Payload for an older actionType `'G'` delta. It carries both the added and
+ * removed sync groups in one delta and forces a full re-bootstrap.
  */
 export interface SyncGroupChangePayload {
     removedGroups: string[];
     addedGroups: string[];
 }
 /**
- * Payload for incremental actionType 'G' deltas emitted by EmitGroupAdded.
- * Signals that the recipient has joined a single sync group; subsequent
- * 'C' (Covering) deltas will deliver the newly-visible entities. No
- * re-bootstrap required.
+ * Payload for an incremental actionType `'G'` delta. It signals that the
+ * recipient has joined a single sync group; the following `'C'` (covering)
+ * deltas deliver the newly visible entities. No re-bootstrap is required.
  */
 export interface GroupAddedPayload {
     group: string;
     userId: string;
 }
 /**
- * Payload for actionType 'S' deltas emitted by EmitGroupRemoved.
- * Signals that the recipient has lost access to a sync group. The client
- * purges affected local entities and updates its subscription metadata.
+ * Payload for an actionType `'S'` delta. It signals that the recipient has lost
+ * access to a sync group; the client purges the affected local entities and
+ * updates its subscription metadata.
  */
 export interface GroupRemovedPayload {
     group: string;
@@ -73,27 +71,25 @@ export interface SyncWebSocketOptions {
      */
     collaborationEvents?: string[];
     /**
-     * Participant kind to declare on the WS upgrade. Defaults to `'user'`
-     * (session-auth, web app). Agent runtimes (Node workers) pass
-     * `'agent'` so the server's `agentTokenProvider`
-     * routes them through capability-token verification instead of
-     * session auth. The server reads this as the `kind` query param.
+     * The participant kind declared on the WebSocket upgrade. Defaults to
+     * `'user'` (session auth, the web app). Agent runtimes pass `'agent'` so the
+     * server verifies them by capability token instead of session auth. The
+     * server reads this as the `kind` query parameter.
      */
     kind?: 'user' | 'agent' | 'system';
     /**
-     * The agent's bearer credential — a restricted (`rk_`) API key. When
-     * set, sent in the `ablo.bearer.<token>` WebSocket subprotocol so the
-     * credential stays out of URLs and proxy logs. Required for `kind: 'agent'`;
-     * ignored for `kind: 'user'`. (Field name predates the Biscuit→opaque-key
-     * migration.)
+     * The agent's bearer credential — a restricted (`rk_`) API key. When set, it
+     * is sent in the `ablo.bearer.<token>` WebSocket subprotocol so the credential
+     * stays out of URLs and proxy logs. Required for `kind: 'agent'` and ignored
+     * for `kind: 'user'`.
      */
     capabilityToken?: string;
     /**
-     * Shared credential getter. When provided, WebSocket URL auth reads this
-     * instead of a copied `capabilityToken`, so reconnects use refreshed tokens
-     * from the SDK's single auth source.
+     * Getter for the current credential. When provided, the WebSocket upgrade
+     * reads it instead of a copied `capabilityToken`, so reconnects always use
+     * the freshest token from the SDK's single credential source. Preferred over
+     * `getCapabilityToken`.
      */
-    /** Shared SDK auth getter. Preferred internal name. */
     getAuthToken?: AuthTokenGetter;
     /** @deprecated Use `getAuthToken`. Kept for direct low-level callers. */
     getCapabilityToken?: AuthTokenGetter;
@@ -116,14 +112,11 @@ export interface BootstrapDataEvent {
     cursor?: string;
 }
 /**
- * Presence update event payload — mirrors the wire frame's `payload`
- * field (apps/sync-server/src/hub/types.ts PresenceUpdateMessage).
- *
- * Every consumer (web entity-presence cache, PresenceStream,
- * agent-runtime presence reducer) reads its own subset; this type is
- * the union of what the server actually sends. Stripping fields at
- * this layer (the prior bug) silently broke rich-presence consumers
- * that needed `kind`, `activity`, `isAgent` to dispatch correctly.
+ * Payload of a presence-update event, mirroring the `payload` field of the wire
+ * frame. This type is the union of everything the server may send; each
+ * consumer reads its own subset. Forwarding the full shape, rather than
+ * stripping fields here, is deliberate — presence consumers rely on `kind`,
+ * `activity`, and `isAgent` to dispatch correctly.
  */
 export interface PresenceUpdateEvent {
     /** Server-stamped transition: 'enter' on join + roster snapshot,
@@ -151,16 +144,15 @@ export interface PresenceUpdateEvent {
      *  not self-declare — server is the source of truth. */
     isAgent?: boolean;
     /**
-     * Server-stamped canonical kind (`'user' | 'agent' | 'system'`). Additive:
-     * older servers omit it and readers fall back to the lossy `isAgent`
-     * boolean (which cannot express `'system'`). Typed `string` because it is
-     * raw wire input — normalize via `participantKindFromWire`.
+     * The canonical participant kind (`'user' | 'agent' | 'system'`), stamped by
+     * the server. Some servers omit it, in which case readers fall back to the
+     * lossy `isAgent` boolean, which cannot express `'system'`. Typed as `string`
+     * because it is raw wire input — normalize it via `participantKindFromWire`.
      */
     participantKind?: string;
     timestamp?: number;
-    /** Server stamps every presence frame with this participant's open
-     *  claims so peers see them without a separate channel. Wire
-     *  shape mirrors `apps/sync-server/src/hub/types.ts Claim`. */
+    /** Every presence frame carries this participant's open claims, stamped by
+     *  the server, so peers see them without a separate channel. */
     activeClaims?: {
         claimId: string;
         entityType: string;
@@ -178,10 +170,10 @@ export interface PresenceUpdateEvent {
         declaredAt: number;
         expiresAt: number;
         /**
-         * Lifecycle state. Additive — older servers omit it and the reader
-         * treats absence as `'active'`. Terminal states (`committed` /
-         * `expired` / `canceled`) ride one frame as the claim ends so peers
-         * learn *how* it resolved before it drops from the active set.
+         * The claim's lifecycle state. When absent, the reader treats it as
+         * `'active'`. A terminal state (`committed`, `expired`, or `canceled`) rides
+         * one final frame as the claim ends, so peers learn how it resolved before
+         * it drops from the active set.
          */
         status?: 'active' | 'committed' | 'expired' | 'canceled';
         error?: ClaimError;
@@ -256,14 +248,19 @@ export interface CoreSyncEventMap {
     claim_granted: [Record<string, unknown>];
     claim_lost: [Record<string, unknown>];
     /**
-     * Notify-instead-of-abort (non-coercion). A committed write guarded with
-     * `onStale: 'notify' collided with a concurrent change; rather than
-     * forcing an outcome, the engine returned the conflicting field's current
-     * value so the actor can solve it. The resolver is the intelligent actor —
-     * an agent reasoning over the change, or a human watching the row. The commit
-     * SUCCEEDED; held ops ('notify') weren't written and the actor re-issues once
-     * it has reconciled. (The claim is the prospective form of the same
-     * non-coercion; this is the in-flight form.)
+     * Reply to an outbound `claim_heartbeat` — the lease's fate: `held` with
+     * the extended `expiresAt`, `queued` with the current `position`, or
+     * `lost`. Correlated back to the awaiting caller by `claimId` in the
+     * claim stream.
+     */
+    claim_heartbeat_ack: [Record<string, unknown>];
+    /**
+     * A committed write guarded with `onStale: 'notify'` collided with a
+     * concurrent change. Rather than forcing an outcome, the engine returns the
+     * conflicting field's current value so the actor — an agent reasoning over the
+     * change, or a person watching the row — can reconcile it. The commit itself
+     * succeeded; the held operations were not written, and the actor re-issues
+     * them once it has reconciled.
      */
     'conflict:notified': [{
         clientTxId: string;
@@ -282,7 +279,7 @@ export type DefaultCollaborationEvents = Record<string, never>;
  * `Record<string, ...>` requires an implicit string index signature, which
  * TypeScript interfaces don't have. So a closed interface like Ablo's
  * `AbloCollaborationEvents` would fail to satisfy `Record<string, unknown[]>`,
- * even though every one of its values IS a tuple. This mapped form iterates
+ * even though every one of its values is a tuple. This mapped form iterates
  * over `keyof T` instead of demanding a string index, so it accepts both
  * closed interfaces and open Record types — while still enforcing
  * "every value is an array."
@@ -315,10 +312,10 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
     /** Periodic catchup interval — polls for missed deltas every 30s while connected */
     private catchupInterval;
     /**
-     * Application-level heartbeat — ping every 30s, force-close on a 10s
-     * silent watchdog. The full zombie-socket rationale lives with the
-     * timers in `sync/heartbeat.ts`; the transport closures below are the
-     * only socket access the controller gets.
+     * Application-level heartbeat: ping every 30 seconds and force-close after a
+     * 10-second silence. The {@link HeartbeatController} holds the timing and the
+     * zombie-socket rationale; the closures below are the only socket access it
+     * gets.
      */
     private readonly heartbeat;
     private isConnecting;
@@ -349,20 +346,19 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
     private lastForceCloseReason;
     private sessionErrorAt;
     /**
-     * Sync-position state (lastSyncId watermark, version vector, server
-     * cursor). The advance discipline stays documented at `sendAck` /
-     * `handleDelta`; the state itself lives in `sync/syncCursor.ts`.
+     * Sync-position state: the lastSyncId watermark, version vector, and server
+     * cursor. The advance discipline is documented at `sendAck` and `handleDelta`;
+     * the state itself lives in {@link SyncCursor}.
      */
     private readonly cursor;
     /** Registered collaboration event keys (colon format) for dispatch in onmessage */
     private collaborationEventTypes;
     /**
-     * Minimal session adapter handed to the frame dispatch table
-     * (`sync/wsFrameHandlers.ts`). Exposes ONLY the members the handlers
-     * touch; the closure members read live state so host-side reassignment
-     * (e.g. the `pendingSubscriptions` reset on close) can't strand the
-     * handlers on a stale reference. Built in the constructor, after the
-     * state it captures exists.
+     * A minimal session adapter handed to the inbound frame dispatch table
+     * ({@link dispatchWsFrame}). It exposes only the members the handlers touch;
+     * the closure members read live state so a reassignment here (for example the
+     * `pendingSubscriptions` reset on close) cannot strand a handler on a stale
+     * reference. Built in the constructor, after the state it captures exists.
      */
     private readonly frameSession;
     /**
@@ -373,10 +369,10 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      */
     private pendingMutations;
     /**
-     * In-flight `claim` requests keyed by claimId. Resolved when the
-     * matching `claim_ack` arrives, or rejected on timeout/disconnect.
-     * Same shape as pendingMutations — Phoenix-style request/response
-     * over a multiplexed connection.
+     * In-flight `claim` requests keyed by claimId. Resolved when the matching
+     * `claim_ack` arrives, or rejected on timeout or disconnect — the same
+     * request/response pattern as `pendingMutations`, multiplexed over the one
+     * connection.
      */
     private pendingClaims;
     /**
@@ -411,28 +407,25 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      */
     private setupEventHandlers;
     /**
-     * Validate + normalize a wire delta at the receive boundary — the ONE
-     * seam every inbound delta (`delta` frame, batch element, `sync_response`
-     * replay, legacy bare frame) passes through before it is emitted,
-     * persisted to IDB, or allowed to advance any watermark.
+     * Validates and normalizes a wire delta at the receive boundary — the single
+     * seam every inbound delta (a `delta` frame, a batch element, a `sync_response`
+     * replay, or the older bare frame) passes through before it is emitted,
+     * persisted, or allowed to advance any watermark.
      *
-     * Normalization (older/deployed servers stay compatible):
-     *  - `id`: the contract says `number`, but deployed servers have sent the
-     *    raw Postgres BIGINT serialization — a STRING — and every downstream
-     *    watermark gate (`typeof syncId === 'number'` in
-     *    `Database.processDeltaBatch`, the metadata-cursor update, numeric
-     *    `>=` thresholds in TransactionQueue) silently breaks on strings:
-     *    acks are withheld, the resume cursor never advances, and every
-     *    reconnect replays from 0. Coerce ONCE here.
-     *  - `transactionId` / `createdBy`: the SERVER projection sends these as
-     *    nullable (and `createdBy` as a nested ParticipantRef); the client
-     *    contract types them as optional strings and never reads them.
-     *    Normalize to absent instead of rejecting every real server delta.
+     * Normalization keeps already-deployed servers compatible:
+     *  - `id`: the contract says `number`, but some servers have sent the raw
+     *    Postgres BIGINT serialization — a string — and every downstream watermark
+     *    gate treats a string as invalid, so acks are withheld, the resume cursor
+     *    never advances, and every reconnect replays from zero. Coerce it once here.
+     *  - `transactionId` / `createdBy`: the server projection sends these as
+     *    nullable (and `createdBy` as a nested reference); the client contract
+     *    types them as optional strings and never reads them, so normalize them to
+     *    absent rather than reject every real server delta.
      *
-     * Validation: `clientSyncDeltaSchema.safeParse` — the canonical Zod wire
-     * contract. A frame that fails is DROPPED (returns `null`) with a
-     * debug-level log + observability breadcrumb; it is never applied. One
-     * parse per delta — callers must not re-parse.
+     * Validation runs `clientSyncDeltaSchema.safeParse`, the canonical wire
+     * contract. A frame that fails is dropped (returns `null`) with a debug log
+     * and an observability breadcrumb; it is never applied. There is one parse per
+     * delta — callers must not re-parse.
      */
     private normalizeWireDelta;
     /**
@@ -441,15 +434,13 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      */
     private handleDelta;
     /**
-     * Send acknowledgment for received delta with version vector.
-     *
-     * This is the SOLE forward-mover of `this.cursor.lastSyncId` for live
-     * deltas. Called by `BaseSyncedStore.flushPendingDeltas` with the
-     * `persistedSyncId` watermark — i.e. only after the deltas have
-     * actually committed to IDB. Keeping the cursor advance here (rather
-     * than at receipt in `handleDelta`/`handleSyncResponse`) means the
-     * cursor never gets ahead of the persisted view, so reconnect/
-     * catch-up requests can't accidentally skip un-persisted deltas.
+     * Acknowledges received deltas up to the given syncId. This is the only place
+     * `this.cursor.lastSyncId` moves forward for live deltas. The store calls it
+     * with its persisted-syncId watermark — that is, only after the deltas have
+     * committed to local storage. Advancing the cursor here, rather than at
+     * receipt in `handleDelta` or `handleSyncResponse`, keeps the cursor from
+     * getting ahead of the persisted view, so reconnect and catch-up requests
+     * cannot skip un-persisted deltas.
      */
     private sendAck;
     /**
@@ -461,23 +452,15 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      */
     send(message: any): void;
     /**
-     * Send a `commit` mutation request over the existing WebSocket and
-     * resolve when the server's `mutation_result` frame comes back with
-     * the same `clientTxId`. The wire-level frame is `{ type: 'commit',
-     * payload: { operations, clientTxId } }` — matching the
-     * `handleCommit` path on `apps/sync-server/src/hub/Hub.ts` (see the
-     * dispatch at Hub.ts:737).
-     *
-     * Historical naming note: this was originally `sendBatchAck` back when
-     * the Go sync-engine used a GraphQL `batchAck` mutation. The TS
-     * sync-server uses `type: 'commit'` over WebSocket exclusively. The
-     * method name now matches the wire protocol so the ack/commit naming
-     * confusion stops here.
+     * Sends a `commit` mutation request over the existing WebSocket and resolves
+     * when the server's `mutation_result` frame comes back with the same
+     * `clientTxId`. The wire frame is `{ type: 'commit', payload: { operations,
+     * clientTxId } }`.
      *
-     * Times out after 15s of silence from the server. The socket may close
-     * during an in-flight mutation (network flap, server restart); we do
-     * NOT auto-retry here — the caller's TransactionQueue owns retry +
-     * offline replay semantics and the SDK shouldn't duplicate that logic.
+     * Times out after 15 seconds of silence from the server. The socket may close
+     * during an in-flight mutation (a network flap, a server restart); this does
+     * not auto-retry — the caller's transaction queue owns retry and offline
+     * replay, and the SDK does not duplicate that logic.
      */
     sendCommit(operations: readonly MutationOperation[], clientTxId: string, timeoutMs?: number, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null): Promise<CommitAck>;
     /**
@@ -490,21 +473,14 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      */
     sendCommitQueued(operations: readonly MutationOperation[], clientTxId: string, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null): void;
     /**
-     * Activate a participant claim on this connection. Multiplexed
-     * subscription pattern (Phoenix Channels / Pusher) — the same
-     * connection can hold N concurrent claims, each scoped to a
-     * different set of sync groups.
-     *
-     * Returns a promise that resolves with the server-canonicalized
-     * `syncGroups` and effective `ttlSeconds` once `claim_ack` arrives,
-     * or rejects with a typed error on `success: false` ack /
-     * timeout / disconnect.
+     * Activates a participant claim on this connection. One connection can hold
+     * several concurrent claims at once, each scoped to a different set of sync
+     * groups, so the SDK reuses the existing connection instead of opening a
+     * separate socket per scope.
      *
-     * Why this exists: the old scoped-participant path opened a separate
-     * WS per scope. With claims, the SDK reuses the existing session/agent
-     * connection — one TCP, N logical participants. See
-     * `apps/sync-server/docs/PARTICIPANT_CLAIMS.md` for the migration
-     * framing (Phase A.1).
+     * Returns a promise that resolves with the server-canonicalized `syncGroups`
+     * and effective `ttlSeconds` once `claim_ack` arrives, or rejects with a typed
+     * error on a failed ack, a timeout, or a disconnect.
      */
     sendClaim(claimId: string, syncGroups: readonly string[], options?: {
         capabilityToken?: string;
@@ -525,22 +501,21 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      */
     sendRelease(claimId: string): void;
     /**
-     * Move this connection's READ interest — replace the connection-level
-     * sync groups mid-session as the user opens/closes entities. This is the
-     * area-of-interest (AOI) navigation primitive: the server fans out
-     * deltas only for groups currently in view, instead of the frozen set
-     * chosen at connect.
+     * Moves this connection's read interest — replaces the connection-level sync
+     * groups mid-session as the user opens and closes entities. This is the
+     * area-of-interest navigation primitive: the server fans out deltas only for
+     * the groups currently in view, rather than the fixed set chosen at connect.
      *
-     * Full-set replace semantics — pass the complete new group list, not a
-     * delta. Resolves with the server's effective set once `subscription_ack`
-     * arrives; rejects (typed) on a scope denial (a restricted `rk_` key
-     * requesting a group outside its allowlist), timeout, or disconnect. On
-     * success the new set is recorded as `options.syncGroups` so a later
-     * reconnect re-subscribes to current interest, not the connect-time set.
+     * This is a full-set replace: pass the complete new group list, not a delta.
+     * Resolves with the server's effective set once `subscription_ack` arrives;
+     * rejects (with a typed error) on a scope denial (a restricted `rk_` key
+     * requesting a group outside its allowlist), a timeout, or a disconnect. On
+     * success the new set is recorded as `options.syncGroups`, so a later reconnect
+     * re-subscribes to the current interest rather than the connect-time set.
      *
-     * Distinct from {@link sendClaim} (write-claim, per-op, TTL'd) — this is
-     * the read side and carries no capability token of its own; it's bounded
-     * by the connection credential's grant.
+     * Distinct from {@link sendClaim} (a write claim, per operation, with a TTL):
+     * this is the read side, carries no capability token of its own, and is
+     * bounded by the connection credential's grant.
      */
     updateSubscription(syncGroups: readonly string[], options?: {
         timeoutMs?: number;
@@ -548,9 +523,9 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
         syncGroups: string[];
     }>;
     /**
-     * Compatibility setter for direct SyncWebSocket users. The SDK-owned
-     * `Ablo()` path passes `getAuthToken`, so reconnect URL auth reads the
-     * shared credential source instead of this copied value.
+     * Sets a fixed credential for callers that construct the socket directly. The
+     * SDK instead supplies `getAuthToken`, so reconnects read the shared
+     * credential source rather than this copied value.
      */
     setCapabilityToken(token: string): void;
     getAuthToken(): string | undefined;
@@ -670,7 +645,7 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      */
     getLastSyncId(): number;
     /**
-     * Linear-style incremental sync request
+     * Requests an incremental sync from the server, starting at the current cursor.
      */
     requestIncrementalSync(): Promise<void>;
     /**
@@ -689,13 +664,12 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      */
     private handleBootstrapResponse;
     /**
-     * Handle presence update from server. The wire frame's payload is
-     * forwarded as-is so every consumer (web entity cache,
-     * PresenceStream, agent runtime) reads from the same shape.
-     * Stripping fields here was a prior bug — it silently dropped
-     * `kind`, `activity`, `syncGroups`, `isAgent` for rich consumers.
+     * Handles a presence update from the server. The wire frame's payload is
+     * forwarded as-is, so every consumer reads the same shape; stripping fields
+     * here would drop `kind`, `activity`, `syncGroups`, and `isAgent` for
+     * consumers that need them.
      *
-     * Wire frame (apps/sync-server/src/hub/types.ts PresenceUpdateMessage):
+     * The wire frame is:
      *   { type: 'presence_update', payload: { kind, userId, status,
      *     syncGroups, activity, isAgent, timestamp, activeClaims } }
      */