@abloatai/ablo 0.26.0 → 0.27.0

package/dist/sync/wsFrameHandlers.d.ts

@@ -1,13 +1,10 @@
 /**
- * Inbound frame dispatch for the sync WebSocket.
- *
- * Replaces the monolithic frame `switch` that used to live inside
- * `SyncWebSocket.setupEventHandlers` with a frame-type → handler table of
- * functions over a minimal {@link WsSession} interface — only the members
- * the handlers actually touch, never the transport class itself (no
- * import cycle). The host's `onmessage` stays responsible for JSON
- * parsing, heartbeat proof-of-life, and the outer try/catch; everything
- * after that funnels through {@link dispatchWsFrame}.
+ * Routes each inbound frame from the sync WebSocket to the handler for its
+ * type. Handlers work against a minimal {@link WsSession} interface — only
+ * the members they actually touch, rather than the transport object itself,
+ * which keeps this module free of an import cycle. Reading a message off the
+ * socket, parsing its JSON, and tracking heartbeats all happen before this
+ * point; every parsed frame then passes through {@link dispatchWsFrame}.
  */
 import { type CommitAck } from './commitFrames.js';
 /**
@@ -33,9 +30,10 @@ export interface PendingClaim {
     timeout: ReturnType<typeof setTimeout>;
 }
 /**
- * In-flight `update_subscription` record awaiting `subscription_ack`.
- * FIFO-matched (no correlation id on the wire) — see the session field
- * doc on SyncWebSocket.pendingSubscriptions.
+ * An in-flight `update_subscription` request awaiting its
+ * `subscription_ack`. The wire carries no correlation id, so requests are
+ * matched to their acknowledgements in first-in, first-out order, the same
+ * order the server applies them.
  */
 export interface PendingSubscription {
     resolve: (value: {
@@ -45,14 +43,14 @@ export interface PendingSubscription {
     timeout: ReturnType<typeof setTimeout>;
 }
 /**
- * Parsed inbound wire frame (the raw `JSON.parse` result). Untrusted
- * data — every payload is loose and each handler narrows defensively,
- * the same posture the inline switch had.
+ * A parsed inbound wire frame, straight from `JSON.parse`. The data is
+ * untrusted: every payload is loosely typed, and each handler narrows it
+ * defensively before use.
  */
 export interface WsInboundFrame {
     type?: string;
     payload?: unknown;
-    /** Legacy bare-delta frames carry delta fields at the top level. */
+    /** Some delta frames carry their delta fields at the top level rather than under `payload`. */
     actionType?: unknown;
     modelName?: unknown;
     [key: string]: unknown;
@@ -60,17 +58,18 @@ export interface WsInboundFrame {
 /** Narrow arbitrary wire data to a plain string-keyed record. */
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
 /**
- * Envelope guard for the raw `JSON.parse` result of an inbound WS message.
- * A frame is any plain object whose `type`, when present, is a string —
- * payload-level validation stays with each handler (deltas go through the
- * canonical `clientSyncDeltaSchema` at the `normalizeWireDelta` seam).
+ * A type guard for the parsed result of an inbound message. A frame is any
+ * plain object whose `type`, when present, is a string. Validating the
+ * payload itself is left to each handler; delta payloads, for example, are
+ * checked against the canonical delta schema before they are applied.
  */
 export declare function isWsInboundFrame(value: unknown): value is WsInboundFrame;
 /**
- * The slice of SyncWebSocket the frame handlers operate on. The host
- * builds one adapter object over its private state; closures read live
- * fields so host-side reassignment (e.g. the pendingSubscriptions reset
- * on close) can't strand the handlers on stale references.
+ * The subset of the sync WebSocket that the frame handlers need. The
+ * transport builds a single object exposing these members over its own
+ * private state. Handlers read the fields live rather than capturing them,
+ * so resetting a field elsewhere — such as clearing pending subscriptions
+ * on close — never leaves a handler holding a stale value.
  */
 export interface WsSession {
     /** EventEmitter surface — handlers emit the typed transport events. */
@@ -79,7 +78,7 @@ export interface WsSession {
     pendingMutations: Map<string, PendingCommit>;
     /** In-flight claim acks keyed by claimId. */
     pendingClaims: Map<string, PendingClaim>;
-    /** FIFO pop of the oldest in-flight `update_subscription` request. */
+    /** Removes and returns the oldest in-flight `update_subscription` request. */
     shiftPendingSubscription(): PendingSubscription | undefined;
     /** Connection options subset the handlers write back (acked sync groups). */
     options: {
@@ -88,10 +87,9 @@ export interface WsSession {
     /** Registered collaboration event keys (colon format). */
     collaborationEventTypes: ReadonlySet<string>;
     /**
-     * Receive-boundary delta processing. Takes UNTRUSTED wire data — the
-     * host validates against the canonical `clientSyncDeltaSchema` (and
-     * drops malformed deltas) at its `normalizeWireDelta` seam, so the
-     * handlers here never need to cast.
+     * Processes one inbound delta. The argument is untrusted wire data; the
+     * transport validates it against the canonical delta schema and drops
+     * anything malformed, so handlers here never cast.
      */
     handleDelta(delta: unknown): void;
     handleSyncResponse(payload: unknown): void;
@@ -103,15 +101,16 @@ export interface WsSession {
 }
 export type WsFrameHandler = (session: WsSession, message: WsInboundFrame) => void;
 /**
- * Frame-type → handler table. Every named server frame the SDK
- * understands dispatches through here; anything else falls to the
- * collaboration-event / unknown-type path in {@link dispatchWsFrame}.
+ * Maps each frame type to its handler. Every named server frame this
+ * package understands is dispatched from this table; anything else falls
+ * through to the collaboration-event and unknown-type path in
+ * {@link dispatchWsFrame}.
  */
 export declare const wsFrameHandlers: Record<string, WsFrameHandler>;
 /**
- * Route one parsed inbound frame to its handler. Mirrors the original
- * inline switch exactly: keepalives are ignored, a missing `type` is
- * the legacy bare-delta form, unknown types fall through to the
- * collaboration-event map (underscore wire format → colon event key).
+ * Routes one parsed inbound frame to its handler. Keepalive frames are
+ * ignored, a missing `type` is treated as a bare delta, and any unknown
+ * type falls through to the collaboration-event map, whose wire names use
+ * underscores and whose event keys use colons.
  */
 export declare function dispatchWsFrame(session: WsSession, message: WsInboundFrame): void;

package/dist/sync/wsFrameHandlers.js

@@ -1,13 +1,10 @@
 /**
- * Inbound frame dispatch for the sync WebSocket.
- *
- * Replaces the monolithic frame `switch` that used to live inside
- * `SyncWebSocket.setupEventHandlers` with a frame-type → handler table of
- * functions over a minimal {@link WsSession} interface — only the members
- * the handlers actually touch, never the transport class itself (no
- * import cycle). The host's `onmessage` stays responsible for JSON
- * parsing, heartbeat proof-of-life, and the outer try/catch; everything
- * after that funnels through {@link dispatchWsFrame}.
+ * Routes each inbound frame from the sync WebSocket to the handler for its
+ * type. Handlers work against a minimal {@link WsSession} interface — only
+ * the members they actually touch, rather than the transport object itself,
+ * which keeps this module free of an import cycle. Reading a message off the
+ * socket, parsing its JSON, and tracking heartbeats all happen before this
+ * point; every parsed frame then passes through {@link dispatchWsFrame}.
  */
 import { getContext } from '../context.js';
 import { CapabilityError, errorFromWire, } from '../errors.js';
@@ -19,10 +16,10 @@ export function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 /**
- * Envelope guard for the raw `JSON.parse` result of an inbound WS message.
- * A frame is any plain object whose `type`, when present, is a string —
- * payload-level validation stays with each handler (deltas go through the
- * canonical `clientSyncDeltaSchema` at the `normalizeWireDelta` seam).
+ * A type guard for the parsed result of an inbound message. A frame is any
+ * plain object whose `type`, when present, is a string. Validating the
+ * payload itself is left to each handler; delta payloads, for example, are
+ * checked against the canonical delta schema before they are applied.
  */
 export function isWsInboundFrame(value) {
     if (!isRecord(value))
@@ -31,10 +28,10 @@ export function isWsInboundFrame(value) {
     return type === undefined || typeof type === 'string';
 }
 /**
- * Ack for a prior `commit` we sent. Canonical shape is
- * `MutationResultMessage` in `@abloatai/ablo/wire`. This stays a
- * DEFENSIVE parse (not a typed cast) because the payload is
- * untrusted wire data that may be malformed or from an older server.
+ * Handles the acknowledgement of a `commit` request. The canonical wire
+ * shape is `MutationResultMessage`. The payload is parsed defensively
+ * rather than cast, since it is untrusted and may be malformed or sent by
+ * an older server.
  */
 const handleMutationResult = (session, message) => {
     const p = (message.payload ?? message);
@@ -54,9 +51,9 @@ const handleMutationResult = (session, message) => {
         // Coerce defensively — bigint columns serialize as strings
         // from older servers (see normalizeWireDelta).
         const ackedSyncId = Number(lastSyncId);
-        // Notify-instead-of-abort: a guarded write's premise moved. Emit
-        // the advisory signal so an agent loop can self-heal, AND resolve
-        // the receipt with it (the commit still succeeded).
+        // The write succeeded, but a guarded premise shifted underneath it.
+        // Emit the advisory signal so a caller can react, and still resolve
+        // the receipt, since the commit itself went through.
         if (notifications && notifications.length > 0) {
             const txId = typeof clientTxId === 'string' ? clientTxId : '';
             const event = {
@@ -86,13 +83,10 @@ const handleMutationResult = (session, message) => {
         });
     }
     else {
-        // Capture the FULL server error so the user can see what
-        // actually rejected the mutation. Without this, every
-        // rejection becomes the generic "mutation failed on
-        // server" — useless when debugging chart batches that
-        // tank 40+ ops at once. We stringify object errors so
-        // structured server payloads (e.g., Zod issues, schema
-        // violations) survive the trip through `new Error(...)`.
+        // Capture the full server error so the caller can see what actually
+        // rejected the mutation, rather than a generic "mutation failed on
+        // server". Object errors are stringified so structured server payloads,
+        // such as validation issues, survive being wrapped in an Error.
         let errorMessage;
         let errorCode;
         let requiredCapability;
@@ -123,14 +117,12 @@ const handleMutationResult = (session, message) => {
         else {
             errorMessage = 'mutation failed on server';
         }
-        // Coordination collision: a stale-context rejection (the write's
-        // readAt premise moved underneath) or a foreign-claim conflict is
-        // exactly the collision ClaimLog exists to surface. The notify
-        // path (success + notifications) emits captureConflict above; a
-        // HARD rejection must too — otherwise observability.collisions()
-        // silently misses every rejected write. The conflicted rows ride
-        // along on the typed error's `conflicts` detail (see
-        // AbloStaleContextError.toJSON / errorEnvelope).
+        // A stale-context rejection (the write read state that has since
+        // changed) or a foreign-claim conflict is a coordination collision.
+        // The success-with-notifications path above records the conflict, and a
+        // hard rejection must record it too, or the collision count would miss
+        // every rejected write. The conflicting rows ride along on the typed
+        // error's `conflicts` detail.
         if (errorCode === 'stale_context' ||
             errorCode === 'claim_conflict' ||
             errorCode === 'entity_claimed' ||
@@ -169,11 +161,9 @@ const handleMutationResult = (session, message) => {
     }
 };
 /**
- * Ack for a prior `claim` we sent. Wire format mirrors
- * apps/sync-server/src/hub/types.ts ClaimAckMessage:
- *   { type: 'claim_ack',
- *     payload: { claimId, success, syncGroups?,
- *                ttlSeconds?, error? } }
+ * Handles the acknowledgement of a `claim` request. The frame has the shape
+ * `{ type: 'claim_ack', payload: { claimId, success, syncGroups?,
+ * ttlSeconds?, error? } }`.
  */
 const handleClaimAck = (session, message) => {
     const p = (message.payload ?? {});
@@ -223,11 +213,11 @@ const handleClaimAck = (session, message) => {
     }
 };
 /**
- * Ack for a prior `update_subscription`. The wire carries no
- * correlation id, so FIFO-match against the oldest pending
- * request — the server applies and acks subscription updates
- * in receive order. Validated through the canonical zod schema
- * (mirrors how the Hub validates inbound frames).
+ * Handles the acknowledgement of an `update_subscription` request. The wire
+ * carries no correlation id, so the ack is matched to the oldest pending
+ * request in first-in, first-out order, since the server applies and
+ * acknowledges subscription updates in the order it receives them. The
+ * payload is validated against its canonical schema before use.
  */
 const handleSubscriptionAck = (session, message) => {
     const pending = session.shiftPendingSubscription();
@@ -255,10 +245,10 @@ const handleSubscriptionAck = (session, message) => {
     }
 };
 /**
- * `delta` frames carry either a single delta or a `{ deltas: [...] }` batch.
- * Only DISCRIMINATES the two shapes here — each delta is validated exactly
- * once downstream (the host's `normalizeWireDelta` seam), so batch elements
- * are handed over raw rather than pre-parsed.
+ * Handles a `delta` frame, which carries either a single delta or a
+ * `{ deltas: [...] }` batch. This only tells the two shapes apart; each
+ * delta is validated once downstream, so batch elements are passed along
+ * raw rather than parsed here.
  */
 const handleDeltaFrame = (session, message) => {
     const p = message.payload;
@@ -271,14 +261,15 @@ const handleDeltaFrame = (session, message) => {
         for (const d of p.deltas) {
             session.handleDelta(d);
         }
-        // `p.newVersions` from pre-cutover servers is ignored — the version
-        // vector was removed in W4a (sync_id is the causality token).
+        // `p.newVersions` from older servers is ignored; `sync_id` is the
+        // causality token.
     }
 };
 /**
- * Frame-type → handler table. Every named server frame the SDK
- * understands dispatches through here; anything else falls to the
- * collaboration-event / unknown-type path in {@link dispatchWsFrame}.
+ * Maps each frame type to its handler. Every named server frame this
+ * package understands is dispatched from this table; anything else falls
+ * through to the collaboration-event and unknown-type path in
+ * {@link dispatchWsFrame}.
  */
 export const wsFrameHandlers = {
     sync_response: (session, message) => { session.handleSyncResponse(message.payload); },
@@ -299,10 +290,9 @@ export const wsFrameHandlers = {
         }
     },
     claim_rejected: (session, message) => {
-        // Server denied an `claim_begin` because the target is
-        // already claimed by another participant. Forward the
-        // payload as-is — the ClaimStream consumer interprets
-        // the conflict shape (peerId, target, etc.).
+        // The server denied a claim because the target is already held by
+        // another participant. The payload is forwarded as-is for the claim
+        // stream consumer to interpret (peerId, target, and so on).
         recordClaim('rejected', (message.payload ?? {}));
         session.emit('claim_rejected', message.payload ?? {});
     },
@@ -334,13 +324,20 @@ export const wsFrameHandlers = {
         recordClaim('lost', (message.payload ?? {}));
         session.emit('claim_lost', message.payload ?? {});
     },
+    claim_heartbeat_ack: (session, message) => {
+        // Reply to our `claim_heartbeat` — the claim stream correlates it back
+        // to the awaiting caller by claimId. Not logged per-frame: heartbeats
+        // are a cadence, and the interesting transitions (lost) surface through
+        // the caller's error path.
+        session.emit('claim_heartbeat_ack', message.payload ?? {});
+    },
     delta: handleDeltaFrame,
 };
 /**
- * Route one parsed inbound frame to its handler. Mirrors the original
- * inline switch exactly: keepalives are ignored, a missing `type` is
- * the legacy bare-delta form, unknown types fall through to the
- * collaboration-event map (underscore wire format → colon event key).
+ * Routes one parsed inbound frame to its handler. Keepalive frames are
+ * ignored, a missing `type` is treated as a bare delta, and any unknown
+ * type falls through to the collaboration-event map, whose wire names use
+ * underscores and whose event keys use colons.
  */
 export function dispatchWsFrame(session, message) {
     if (message.type === 'pong' || message.type === 'ping') {
@@ -349,16 +346,15 @@ export function dispatchWsFrame(session, message) {
         return;
     }
     if (message.type === undefined) {
-        // Legacy support: bare delta (validated at the host's
-        // normalizeWireDelta seam like every other delta).
+        // A bare delta, validated downstream like every other delta.
         if (message.actionType || message.modelName) {
             session.handleDelta(message);
         }
         return;
     }
-    // Own-property lookup so wire types like 'toString' can never hit
-    // Object.prototype members — those fall through to the unknown-type
-    // path exactly as the switch's `default` did.
+    // Look up own properties only, so a wire type like 'toString' can't match
+    // an inherited Object.prototype member; such types fall through to the
+    // unknown-type path.
     const handler = Object.prototype.hasOwnProperty.call(wsFrameHandlers, message.type)
         ? wsFrameHandlers[message.type]
         : undefined;

package/dist/testing/fixtures/bootstrap.d.ts

@@ -1,7 +1,9 @@
 /**
- * Bootstrap response factories for sync engine tests.
- *
- * Creates well-formed bootstrap responses matching the server API.
+ * Factories that build well-formed bootstrap responses for tests. A
+ * bootstrap response is what the server returns when a client first syncs:
+ * either a full snapshot of the models or a partial batch of deltas since a
+ * known point. These helpers produce the same shapes, so tests can exercise
+ * client sync logic without a live server.
  */
 import type { BootstrapType } from '../../types/index.js';
 export type BootstrapModelData = Record<string, Record<string, unknown>[]>;
@@ -21,15 +23,19 @@ export interface BootstrapResponse {
     timestamp: number;
 }
 /**
- * Create a full bootstrap response (fresh snapshot from server).
+ * Builds a full bootstrap response — a fresh snapshot of the given models,
+ * as the server sends on a client's first sync.
  */
 export declare function createFullBootstrapResponse(models: BootstrapModelData, lastSyncId?: number): BootstrapResponse;
 /**
- * Create a partial bootstrap response (delta batch from lastSyncId).
+ * Builds a partial bootstrap response — a batch of deltas applied on top of
+ * the client's last known sync point, given by `lastSyncId`.
  */
 export declare function createPartialBootstrapResponse(deltas: BootstrapResponse['deltas'], lastSyncId: number): BootstrapResponse;
 /**
- * Create a full bootstrap response with test model data pre-populated.
+ * Builds a full bootstrap response with the common test models
+ * pre-populated. Pass any of the named model arrays to include them in the
+ * snapshot.
  */
 export declare function createTestBootstrapResponse(options?: {
     tasks?: Record<string, unknown>[];

package/dist/testing/fixtures/bootstrap.js

@@ -1,10 +1,13 @@
 /**
- * Bootstrap response factories for sync engine tests.
- *
- * Creates well-formed bootstrap responses matching the server API.
+ * Factories that build well-formed bootstrap responses for tests. A
+ * bootstrap response is what the server returns when a client first syncs:
+ * either a full snapshot of the models or a partial batch of deltas since a
+ * known point. These helpers produce the same shapes, so tests can exercise
+ * client sync logic without a live server.
  */
 /**
- * Create a full bootstrap response (fresh snapshot from server).
+ * Builds a full bootstrap response — a fresh snapshot of the given models,
+ * as the server sends on a client's first sync.
  */
 export function createFullBootstrapResponse(models, lastSyncId = 100) {
     return {
@@ -15,7 +18,8 @@ export function createFullBootstrapResponse(models, lastSyncId = 100) {
     };
 }
 /**
- * Create a partial bootstrap response (delta batch from lastSyncId).
+ * Builds a partial bootstrap response — a batch of deltas applied on top of
+ * the client's last known sync point, given by `lastSyncId`.
  */
 export function createPartialBootstrapResponse(deltas, lastSyncId) {
     return {
@@ -27,7 +31,9 @@ export function createPartialBootstrapResponse(deltas, lastSyncId) {
     };
 }
 /**
- * Create a full bootstrap response with test model data pre-populated.
+ * Builds a full bootstrap response with the common test models
+ * pre-populated. Pass any of the named model arrays to include them in the
+ * snapshot.
  */
 export function createTestBootstrapResponse(options = {}) {
     const models = {};

package/dist/testing/fixtures/deltas.d.ts

@@ -1,7 +1,8 @@
 /**
- * Delta factories for sync engine tests.
- *
- * Creates well-formed SyncAction objects matching the server wire format.
+ * Factories that build well-formed delta objects for tests. A delta, a
+ * {@link SyncAction}, is a single change to one model instance in the wire
+ * format the server sends: an insert, update, delete, archive, and so on.
+ * These helpers let tests construct deltas without a live server.
  */
 import type { SyncActionType, SyncAction } from '../../types/index.js';
 /** Reset the delta counter (call in beforeEach for deterministic IDs) */
@@ -19,68 +20,64 @@ export interface CreateDeltaOptions {
     data?: Record<string, unknown>;
 }
 /**
- * Create a single SyncAction (delta) matching the server wire format.
+ * Builds a single delta ({@link SyncAction}) in the server's wire format.
  */
 export declare function createDelta(options: CreateDeltaOptions): SyncAction;
 /**
- * Create an INSERT delta for a new entity.
+ * Builds an insert delta for a new entity.
  */
 export declare function createInsertDelta(modelName: string, modelId: string, data: Record<string, unknown>, syncId?: number): SyncAction;
 /**
- * Create an UPDATE delta for an existing entity.
+ * Builds an update delta for an existing entity.
  */
 export declare function createUpdateDelta(modelName: string, modelId: string, data: Record<string, unknown>, syncId?: number): SyncAction;
 /**
- * Create a DELETE delta.
+ * Builds a delete delta.
  */
 export declare function createDeleteDelta(modelName: string, modelId: string, syncId?: number): SyncAction;
 /**
- * Create an ARCHIVE delta.
+ * Builds an archive delta, stamping `archivedAt` with the current time.
  */
 export declare function createArchiveDelta(modelName: string, modelId: string, syncId?: number): SyncAction;
 /**
- * Create an UNARCHIVE (reVive) delta.
+ * Builds an unarchive delta, clearing `archivedAt`.
  */
 export declare function createUnarchiveDelta(modelName: string, modelId: string, syncId?: number): SyncAction;
 /**
- * Create a COVERING ('C') delta.
- *
- * Signals that the client has gained permission to see an existing entity.
- * Treated as an insert by the client — the entity is added to the local
- * store as if newly created. Typically follows a GroupAdded delta.
+ * Builds a covering ('C') delta. It signals that the client has gained
+ * permission to see an entity that already exists. The client treats it
+ * like an insert, adding the entity to its local store as if newly created.
+ * A covering delta typically follows a group-added delta.
  */
 export declare function createCoveringDelta(modelName: string, modelId: string, data: Record<string, unknown>, syncId?: number): SyncAction;
 /**
- * Create a GROUP ADDED ('G') delta using the incremental payload shape.
- *
- * Signals that the recipient was added to a single sync group. The client
- * updates its subscription metadata and waits for Covering deltas to
- * deliver the newly-visible entities. Unlike the legacy 'G' payload
- * (addedGroups/removedGroups), this does not trigger a re-bootstrap.
+ * Builds a group-added ('G') delta in the incremental payload shape. It
+ * signals that the recipient was added to a single sync group. The client
+ * updates its subscription state and waits for covering deltas to deliver
+ * the newly visible entities. Unlike the older payload that carries both
+ * added and removed groups, this shape does not trigger a re-bootstrap.
  */
 export declare function createGroupAddedDelta(userId: string, group: string, syncId?: number): SyncAction;
 /**
- * Create a legacy GROUP CHANGE ('G') delta with the old payload shape.
- *
- * Carries both added and removed groups in one delta and forces a full
- * re-bootstrap on the client. Use for testing backward compatibility with
- * the deprecated EmitGroupChange path.
+ * Builds a group-change ('G') delta in the older payload shape, which
+ * carries both added and removed groups in one delta and forces a full
+ * re-bootstrap on the client. Useful for testing backward compatibility
+ * with that older shape.
  */
 export declare function createLegacyGroupChangeDelta(userId: string, added: string[], removed: string[], syncId?: number): SyncAction;
 /**
- * Create a GROUP REMOVED ('S') delta.
- *
- * Signals that the recipient lost access to a sync group. The client
- * purges affected local state and triggers a re-bootstrap with the
- * updated group list.
+ * Builds a group-removed ('S') delta. It signals that the recipient lost
+ * access to a sync group. The client purges the affected local state and
+ * re-bootstraps with the updated group list.
  */
 export declare function createGroupRemovedDelta(userId: string, group: string, syncId?: number): SyncAction;
 /**
- * Create a batch of deltas with sequential sync IDs.
+ * Builds a batch of deltas with sequential sync IDs.
  */
 export declare function createDeltaBatch(deltas: Omit<CreateDeltaOptions, 'id'>[], startingSyncId?: number): SyncAction[];
 /**
- * Create a confirmation delta — used to confirm that a mutation
- * was persisted by the server (TransactionQueue watches for this).
+ * Builds a confirmation delta, which signals that a mutation was persisted
+ * by the server. The client's transaction queue watches for these to
+ * confirm its in-flight writes.
  */
 export declare function createConfirmationDelta(modelName: string, modelId: string, syncId: number, action?: SyncActionType, data?: Record<string, unknown>): SyncAction;