@abloatai/ablo 0.25.0 → 0.27.0

package/dist/sync/SyncWebSocket.d.ts

@@ -1,74 +1,53 @@
 /**
- * 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';
-/**
- * Resolution value of a commit ack. `notifications` is present only when a
- * guarded write (`onStale: 'notify') hit a concurrent change — the
- * advisory self-heal signal, surfaced both here and via `conflict:notified`.
- */
-export interface CommitAck {
-    lastSyncId: number;
-    notifications?: StaleNotification[];
-}
+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;
     userId: string;
 }
-export interface VersionVector {
-    tasks: number;
-    projects: number;
-    users: number;
-    events: number;
-    inboxitems: number;
-    teams: number;
-    assignments: number;
-    comments: number;
-    threads: number;
-    [entityType: string]: number;
-}
 export interface SyncCapabilities {
     partialBootstrap?: boolean;
     compressedDeltas?: boolean;
@@ -83,7 +62,6 @@ export interface SyncWebSocketOptions {
     organizationId: string;
     lastSyncId?: number;
     syncGroups?: string[];
-    versions?: VersionVector;
     capabilities?: SyncCapabilities;
     reconnectDelay?: number;
     maxReconnectDelay?: number;
@@ -93,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;
@@ -136,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,
@@ -171,17 +144,16 @@ 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`. */
-    activeClaims?: Array<{
+    /** 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;
         entityId: string;
@@ -198,14 +170,14 @@ 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;
-    }>;
+    }[];
     localTime?: string;
     type?: string;
     timezone?: string;
@@ -276,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;
@@ -302,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."
@@ -335,20 +312,12 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
     /** Periodic catchup interval — polls for missed deltas every 30s while connected */
     private catchupInterval;
     /**
-     * Application-level heartbeat. The browser WebSocket API hides RFC 6455
-     * protocol-level ping/pong from JavaScript, so the server's `ws.ping()`
-     * keepalive can't be observed by client code — meaning the client cannot
-     * tell a healthy idle connection apart from a "zombie" socket where TCP
-     * silently broke (laptop sleep, NAT timeout, mobile handoff). We send an
-     * application-level `{ type: 'ping' }` every 30s and force-close the
-     * socket if no inbound traffic arrives within 10s. ANY inbound message
-     * counts as proof-of-life — the explicit `pong` is just a guarantee that
-     * something will arrive even on an idle stream.
-     */
-    private heartbeatTimer;
-    private heartbeatTimeoutTimer;
-    private static readonly HEARTBEAT_INTERVAL_MS;
-    private static readonly HEARTBEAT_TIMEOUT_MS;
+     * 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;
     private isManualClose;
     /** When true, a session error has been detected (from any path — WS close or HTTP bootstrap).
@@ -376,11 +345,22 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
     private lastCloseReason;
     private lastForceCloseReason;
     private sessionErrorAt;
-    private lastSyncId;
-    private versionVector;
-    private syncCursor;
+    /**
+     * 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;
+    /**
+     * 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;
     /**
      * In-flight `commit` mutation requests keyed by clientTxId. Resolved when
      * a matching `mutation_result` frame arrives from the server, or rejected on
@@ -389,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;
     /**
@@ -410,6 +390,14 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * Suppresses further reconnection attempts and Sentry error capture.
      */
     setSessionErrorDetected(): void;
+    /**
+     * Clear the session-error latch so `connect()` / `scheduleReconnect()`
+     * work again. Called by the store's access-credential recovery path when
+     * the close was a re-mintable `ek_`/`rk_` expiry (`4001 credential_expired`),
+     * not a login loss — see `isAccessCredentialExpiryCloseReason`. Genuine
+     * session losses never clear the latch; re-auth builds a fresh client.
+     */
+    clearSessionError(): void;
     /**
      * Connect to the sync engine WebSocket
      */
@@ -419,32 +407,40 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      */
     private setupEventHandlers;
     /**
-     * Normalize a wire delta at the receive boundary. The contract
-     * (`syncDeltaWireCoreSchema`) says `id: 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
-     * `>=` threshold comparisons in TransactionQueue) silently breaks on
-     * strings: acks are withheld, the resume cursor never advances, and
-     * every reconnect replays from 0 (or force-bootstraps once the gap
-     * exceeds maxDeltaGapForPartial). Coerce ONCE here so the rest of the
-     * client can trust the declared type — and old servers stay compatible.
+     * 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 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 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;
     /**
-     * Handle incoming sync delta
+     * Handle incoming sync delta (untrusted wire input — validated and
+     * normalized by {@link normalizeWireDelta}; malformed deltas are dropped).
      */
     private handleDelta;
     /**
-     * Send acknowledgment for received delta with version vector.
-     *
-     * This is the SOLE forward-mover of `this.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;
     /**
@@ -456,50 +452,17 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      */
     send(message: any): void;
     /**
-     * Project the SDK's `MutationOperation[]` onto the canonical wire
-     * `CommitMessage`. This is the single serialize boundary between the SDK op
-     * type (loose `type: string`, plus an SDK-internal `options` the server never
-     * reads) and the strict wire contract. The per-field map gives compile-time
-     * drift detection (a `CommitOperation` shape change breaks here) and the lone
-     * `as` narrows the validated op `type` to the wire union — the only
-     * loosening, localized to this boundary.
-     */
-    private buildCommitFrame;
-    /**
-     * 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).
+     * 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 } }`.
      *
-     * 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.
-     *
-     * 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.
-     */
-    /**
-     * Defensively validate the optional `notifications` array off a commit ack.
-     * Untrusted wire data — a malformed entry is dropped rather than throwing,
-     * so a bad notification never sinks an otherwise-successful commit.
-     */
-    private parseNotifications;
-    /**
-     * Single instrumentation point for claim events. Every `claim_*` frame routes
-     * through here so a developer debugging a collision gets one consistent trace
-     * — a console line AND a structured capture — without each dispatch case
-     * re-deriving the row/holder shape. The wire payload is loosely typed
-     * (`Record<string, unknown>`), so this is the one place that narrows it into
-     * a {@link ClaimEvent}.
+     * 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.
      */
-    private recordClaim;
-    sendCommit(operations: ReadonlyArray<MutationOperation>, clientTxId: string, timeoutMs?: number, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null): Promise<CommitAck>;
+    sendCommit(operations: readonly MutationOperation[], clientTxId: string, timeoutMs?: number, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null): Promise<CommitAck>;
     /**
      * Send a commit frame without waiting for `mutation_result`.
      *
@@ -508,25 +471,18 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * eventual `mutation_result` frame is intentionally ignored by this
      * instance because no pending resolver is registered.
      */
-    sendCommitQueued(operations: ReadonlyArray<MutationOperation>, clientTxId: string, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null): void;
+    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: ReadonlyArray<string>, options?: {
+    sendClaim(claimId: string, syncGroups: readonly string[], options?: {
         capabilityToken?: string;
         ttlSeconds?: number;
         timeoutMs?: number;
@@ -545,32 +501,31 @@ 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: ReadonlyArray<string>, options?: {
+    updateSubscription(syncGroups: readonly string[], options?: {
         timeoutMs?: number;
     }): Promise<{
         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;
@@ -584,15 +539,15 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
     /**
      * Send spreadsheet selection presence
      */
-    sendSheetSelection(sheetId: string, selectedCells: Array<{
+    sendSheetSelection(sheetId: string, selectedCells: {
         ref: string;
-    }>): void;
+    }[]): void;
     /**
      * Send slide layer selection presence
      */
-    sendSlideSelection(deckId: string, slideId: string, selectedLayers: Array<{
+    sendSlideSelection(deckId: string, slideId: string, selectedLayers: {
         layerId: string;
-    }>): void;
+    }[]): void;
     /**
      * Send slide cursor position for real-time collaboration
      * Note: Throttling should be handled by the caller (e.g., useSlideCursorBroadcast hook)
@@ -628,26 +583,6 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * Disconnect from WebSocket
      */
     disconnect(): void;
-    /**
-     * Application-level heartbeat. Every `HEARTBEAT_INTERVAL_MS` while
-     * `OPEN`, send `{ type: 'ping' }` and arm a `HEARTBEAT_TIMEOUT_MS`
-     * watchdog. Any inbound frame (handled in `onmessage`) clears the
-     * watchdog. If the watchdog fires, we treat the connection as
-     * zombie and force-close it — `onclose` then triggers the existing
-     * reconnect path.
-     *
-     * Why both sides need this:
-     *  - The server sends RFC 6455 protocol pings via `ws.ping()` every
-     *    30s. Browsers auto-respond with a pong but DO NOT expose either
-     *    frame to JavaScript, so the client is blind to its own keepalive.
-     *  - On a half-open TCP (laptop wake, NAT timeout, mobile handoff)
-     *    the browser may keep `readyState === OPEN` for minutes before
-     *    the OS surfaces the broken connection. App-level traffic is
-     *    the only signal we can observe.
-     */
-    private startHeartbeat;
-    private stopHeartbeat;
-    private clearHeartbeatTimeout;
     /**
      * Force-close the socket from the client side using a private 4xxx
      * code. Callers expect `onclose` to fire; that handler runs the
@@ -697,18 +632,6 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * Update last sync ID (for persistence)
      */
     setLastSyncId(syncId: number): void;
-    /**
-     * Get current version vector
-     */
-    getVersionVector(): VersionVector;
-    /**
-     * Update version vector for specific entity type
-     */
-    updateVersionVector(entityType: string, version: number): void;
-    /**
-     * Set version vector (for initialization)
-     */
-    setVersionVector(versions: VersionVector): void;
     /**
      * Update sync cursor (for incremental sync)
      */
@@ -722,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>;
     /**
@@ -730,7 +653,10 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      */
     requestBootstrap(entities?: string[]): Promise<void>;
     /**
-     * Handle sync response from server
+     * Handle sync response from server. Untrusted wire input — the envelope
+     * fields are narrowed defensively and every delta is validated through
+     * {@link normalizeWireDelta} (exactly once each; malformed ones drop out
+     * of the batch).
      */
     private handleSyncResponse;
     /**
@@ -738,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 } }
      */