@abloatai/ablo 0.24.0 → 0.26.0

package/dist/sync/SyncWebSocket.d.ts

@@ -9,17 +9,10 @@
  */
 import { EventEmitter } from 'events';
 import type { MutationOperation } from '../interfaces/index.js';
-import type { ClientSyncDelta } from '../schema/sync-delta-wire.js';
+import { type ClientSyncDelta } from '../schema/sync-delta-wire.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
@@ -57,18 +50,6 @@ 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 +64,6 @@ export interface SyncWebSocketOptions {
     organizationId: string;
     lastSyncId?: number;
     syncGroups?: string[];
-    versions?: VersionVector;
     capabilities?: SyncCapabilities;
     reconnectDelay?: number;
     maxReconnectDelay?: number;
@@ -181,7 +161,7 @@ export interface PresenceUpdateEvent {
     /** 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<{
+    activeClaims?: {
         claimId: string;
         entityType: string;
         entityId: string;
@@ -205,7 +185,7 @@ export interface PresenceUpdateEvent {
          */
         status?: 'active' | 'committed' | 'expired' | 'canceled';
         error?: ClaimError;
-    }>;
+    }[];
     localTime?: string;
     type?: string;
     timezone?: string;
@@ -335,20 +315,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 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.
+     */
+    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 +348,23 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
     private lastCloseReason;
     private lastForceCloseReason;
     private sessionErrorAt;
-    private lastSyncId;
-    private versionVector;
-    private syncCursor;
+    /**
+     * 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`.
+     */
+    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.
+     */
+    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
@@ -410,6 +394,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,26 +411,39 @@ 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.
+     * 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.
+     *
+     * 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.
+     *
+     * 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.
      */
     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
+     * 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
@@ -455,16 +460,6 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * Send message to server
      */
     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
@@ -484,22 +479,7 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * 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}.
-     */
-    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,7 +488,7 @@ 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
@@ -526,7 +506,7 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * `apps/sync-server/docs/PARTICIPANT_CLAIMS.md` for the migration
      * framing (Phase A.1).
      */
-    sendClaim(claimId: string, syncGroups: ReadonlyArray<string>, options?: {
+    sendClaim(claimId: string, syncGroups: readonly string[], options?: {
         capabilityToken?: string;
         ttlSeconds?: number;
         timeoutMs?: number;
@@ -562,7 +542,7 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * the read side and carries no capability token of its own; it's bounded
      * by the connection credential's grant.
      */
-    updateSubscription(syncGroups: ReadonlyArray<string>, options?: {
+    updateSubscription(syncGroups: readonly string[], options?: {
         timeoutMs?: number;
     }): Promise<{
         syncGroups: string[];
@@ -584,15 +564,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 +608,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 +657,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)
      */
@@ -730,7 +678,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;
     /**