@abloatai/ablo 0.26.0 → 0.28.0

package/dist/sync/syncPosition.js

@@ -1,61 +1,61 @@
 /**
- * THE sync-position structure — one typed object for "where is this client
- * in the global delta order", replacing five scattered private counters
- * (`lastSeenSyncId` on the queue, `highestProcessedSyncId` + `lastAckedId`
- * on the store, ad-hoc acked watermarks, `max()` calls at snapshot sites).
+ * Records where this client stands in the global delta order. It is a single
+ * typed object holding three related but distinct positions, each with its own
+ * rule for when it may advance. Keeping them separate is deliberate: collapsing
+ * them into one counter is a classic source of sync bugs.
  *
- * Three facts with DIFFERENT advance disciplines — flattening them was the
- * historical bug source, so the structure models them explicitly:
+ *   - `persisted` — the resume cursor. It advances only after deltas have
+ *     committed to durable local storage. This is the value reconnect catch-up
+ *     sends to the server, so it must never run ahead of what actually landed
+ *     on disk; otherwise the server would skip deltas the client never stored.
  *
- *   - `persisted` — the resume/ack cursor. Advances ONLY after deltas have
- *     committed to IndexedDB (the Replicache "lastMutationID read in the
- *     same transaction as the client view" rule — see SyncWebSocket.sendAck).
- *     This is what reconnect catch-up sends; it must never run ahead of
- *     durable state or the server skips deltas that never landed.
+ *   - `applied` — the in-memory cursor: the last delta applied to the object
+ *     pool. It drives the guards that deduplicate and reject replayed deltas.
+ *     It may run ahead of `persisted`, because the pool is updated before the
+ *     flush to disk, and behind what has merely been received, because
+ *     bootstrap-queued deltas arrive before they are applied.
  *
- *   - `applied` — the in-memory cursor: the last delta APPLIED to the
- *     object pool. Drives delta dedup/replay guards. May run ahead of
- *     `persisted` (pool applies before the IDB flush) and behind receipt
- *     (bootstrap-queued deltas are received but not yet applied).
+ *   - `acked` — the highest server position acknowledged for this client's own
+ *     commits. An acknowledgement at N means the server applied our write at N;
+ *     the optimistic pool already reflects it, so for the entities we wrote we
+ *     have effectively read through N even before the echo returns on the
+ *     stream.
  *
- *   - `acked` — the highest server watermark ACKED to this client's OWN
- *     commits. An ack at N means the server applied our write at N; the
- *     optimistic pool already reflects it, so for entities we wrote we have
- *     logically read through N even before the stream echo arrives.
+ * One value is derived: `readFloor` is the greater of `applied` and `acked`,
+ * and is the only position a snapshot or claim should stamp as its read point.
+ * Using the raw stream cursor alone would make a claim taken right after a
+ * confirmed write look stale against that write's own delta; using the raw
+ * acknowledgement alone would be wrong for read-only clients. The maximum is
+ * correct per entity, because a competing change to an entity we just wrote
+ * necessarily lands above our acknowledgement and still rejects as stale.
  *
- * One derived read: `readFloor` = max(applied, acked) — the ONLY value
- * snapshots/claims may stamp as `readAt`. The bare stream cursor made a
- * claim taken right after an ack-confirmed write stale against that write's
- * own delta; the bare ack would be wrong for read-only clients. Per-entity
- * correct: a foreign change to an entity we just wrote necessarily lands
- * ABOVE our ack and still stale-rejects.
- *
- * The Zod schema IS the state shape — the class holds exactly one
- * `SyncPositionSnapshot` and applies monotonic merges to it, so
- * snapshot/restore are identity-shaped and the schema is the single gate
- * for anything loaded from disk (`parseSyncPosition`; a corrupted stored
- * cursor "ahead of reality" is an existing, known failure mode).
+ * The validation schema is the state shape: the class holds exactly one
+ * {@link SyncPositionSnapshot} and merges monotonically into it, so snapshot
+ * and restore share that shape and {@link parseSyncPosition} is the single gate
+ * for anything loaded from disk — a corrupted cursor stored "ahead of reality"
+ * being a known failure mode.
  */
 import { z } from 'zod';
 export const syncPositionSchema = z.object({
-    /** Resume/ack cursor — advances only after IDB persistence. */
+    /** The resume cursor; advances only after deltas persist to durable local storage. */
     persisted: z.number().int().nonnegative(),
-    /** In-memory cursor — last delta applied to the pool. */
+    /** The in-memory cursor: the last delta applied to the object pool. */
     applied: z.number().int().nonnegative(),
-    /** Highest server watermark acked to this client's own commits. */
+    /** The highest server position acknowledged for this client's own commits. */
     acked: z.number().int().nonnegative(),
 });
 /**
- * PERSISTENCE DESIGN: only the `persisted` cursor is stored durably (as
- * `WorkspaceMetadata.lastSyncId`, written by Database after each IDB delta
- * commit and gated on load through `syncPositionSchema.shape.persisted` in
- * `Database.requiredBootstrap`). Persisting `applied`/`acked` would be
- * meaningless: on resume the pool is rebuilt FROM the persisted state, so
- * the correct restore is exactly `advancePersisted(storedCursor)` — which
- * implies `applied`, while `acked` starts at 0 (a dead session's acks carry
- * no read authority; the offline queue re-acks its own replays).
+ * Only the `persisted` cursor is stored durably; `applied` and `acked` are
+ * not. On resume the object pool is rebuilt from the persisted state, so the
+ * correct restore is simply to advance `persisted` to the stored value, which
+ * also implies `applied`. `acked` starts at zero, because a past session's
+ * acknowledgements carry no read authority and the offline queue
+ * re-acknowledges its own replays.
+ */
+/**
+ * Validates an untrusted value, such as one loaded from disk, into a position
+ * snapshot, or returns null when it does not match the schema.
  */
-/** Validate a persisted/foreign value into a position snapshot. */
 export function parseSyncPosition(value) {
     const result = syncPositionSchema.safeParse(value);
     return result.success ? result.data : null;
@@ -69,11 +69,13 @@ function advance(state, next) {
         acked: Math.max(state.acked, next.acked ?? 0),
     };
 }
-/** The live position. One instance per client (owned by SyncClient); the
- *  three producers advance their own fact, consumers read. */
+/**
+ * The live sync position: one instance per client. Three producers each
+ * advance their own cursor, and consumers read the result.
+ */
 export class SyncPosition {
     #state = ZERO;
-    /** Current state — the schema shape, frozen-by-copy. */
+    /** Returns a copy of the current state in the schema's shape. */
     snapshot() {
         return { ...this.#state };
     }
@@ -86,25 +88,28 @@ export class SyncPosition {
     get acked() {
         return this.#state.acked;
     }
-    /** THE value snapshots/claims stamp as `readAt`. */
+    /** The position a snapshot or claim stamps as its read point: the greater of `applied` and `acked`. */
     get readFloor() {
         return Math.max(this.#state.applied, this.#state.acked);
     }
-    /** Deltas through `syncId` have COMMITTED to IndexedDB. Persisting
-     *  implies applied — the flush path applies before/with persisting. */
+    /**
+     * Records that deltas through `syncId` have committed to durable local
+     * storage. This also advances `applied`, since the flush applies each delta
+     * before or as it persists.
+     */
     advancePersisted(syncId) {
         this.#state = advance(this.#state, { persisted: syncId, applied: syncId });
     }
-    /** A delta was APPLIED to the in-memory pool. */
+    /** Records that a delta was applied to the in-memory object pool. */
     advanceApplied(syncId) {
         this.#state = advance(this.#state, { applied: syncId });
     }
-    /** The server acked one of OUR commits at this watermark. */
+    /** Records that the server acknowledged one of this client's commits at the given position. */
     noteAck(lastSyncId) {
         if (lastSyncId !== undefined)
             this.#state = advance(this.#state, { acked: lastSyncId });
     }
-    /** Restore from a VALIDATED snapshot (e.g. IDB resume). Monotonic. */
+    /** Restores from an already-validated snapshot, for example on resume from disk. The merge is monotonic. */
     restore(snapshot) {
         this.#state = advance(this.#state, snapshot);
     }

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 = {};