@abloatai/ablo 0.26.0 → 0.27.0

package/dist/sync/groupChange.js

@@ -1,24 +1,26 @@
 /**
- * groupChange — sync-group change / shrinkage handling.
+ * Handles the delta types that change which sync groups a session can see. A
+ * sync group is a fan-out scope the server uses to decide which entities a
+ * client receives. When a session's membership changes, these handlers update
+ * the client's subscription list; when access is revoked, they clear cached
+ * data and trigger a full re-bootstrap so revoked rows cannot linger on the
+ * device.
  *
- * Extracted from BaseSyncedStore.ts as a cohesive leaf: the 'G'/'S' delta
- * handlers (incremental group-added, legacy group-diff, group-removed), the
- * group-set math, the force-re-bootstrap trigger, and the security-critical
- * shrinkage check. The store keeps thin protected delegates with unchanged
- * signatures — subclass override points stay overridable, and the leaf
- * routes every cross-handler call back through the minimal
- * {@link GroupChangeContext} so dynamic dispatch is preserved.
+ * Every handler takes a {@link GroupChangeContext}, the narrow facade through
+ * which it reaches the client's local storage and connection lifecycle hooks.
  */
 import { getContext } from '../context.js';
-/** Sentinel for a 'G'/'S' payload that could not be parsed (vs a valid
- *  `null`/absent payload, which the handlers already tolerate). */
+/**
+ * Marker returned when a group-change payload cannot be parsed, kept distinct
+ * from a valid null or absent payload, which the handlers accept normally.
+ */
 const MALFORMED_PAYLOAD = Symbol('malformed-group-change-payload');
 /**
- * Parse a group-change delta payload without ever throwing. The server
- * serializes these as JSON strings; a corrupt frame used to escape the
- * whole delta pipeline as an unhandled rejection AFTER the watermark had
- * advanced — the delta is never re-delivered, so the security clear it
- * carried was permanently lost.
+ * Parses a group-change delta payload without ever throwing. The server sends
+ * these as JSON strings. If a frame is corrupt, this returns
+ * {@link MALFORMED_PAYLOAD} rather than raising, because an error escaping here
+ * would leave the delta pipeline after the watermark has already advanced. The
+ * delta is never re-delivered, so the security clear it carried would be lost.
  */
 function parseGroupChangePayload(delta) {
     if (typeof delta.data !== 'string')
@@ -36,41 +38,38 @@ function parseGroupChangePayload(delta) {
     }
 }
 /**
- * The legacy-clear fallback for an unparseable group-change delta: we know
- * access changed but not how, so treat it as a revocation — clear cached
- * data (IDB + pool) and force a full re-bootstrap with server truth.
+ * Fallback for a group-change delta that could not be read. Because we know
+ * access changed but not how, this treats it as a revocation: it clears cached
+ * data from both local storage and the in-memory pool, then forces a full
+ * re-bootstrap from the server.
  */
 async function clearForUnknownGroupChange(ctx, delta, kind) {
     getContext().logger.debug(`[BaseSyncedStore] Unreadable ${kind} payload — clearing cached data and re-bootstrapping`, { syncId: delta.id });
-    // SECURITY: same rationale as the legacy removedGroups path — revoked data
-    // must not persist if the device goes offline before the re-bootstrap.
+    // Revoked data must not persist if the device goes offline before the
+    // re-bootstrap, the same reasoning as the explicit removed-groups path.
     await ctx.database.clear();
     ctx.objectPool.clear();
     ctx.forceFullRebootstrap();
 }
 /**
- * Handle an actionType 'G' delta.
- *
- * The server emits 'G' via two distinct pathways, distinguished by payload
- * shape:
+ * Handles a 'G' (group-change) delta. The server sends two shapes of this
+ * delta, told apart by the payload:
  *
- *   Incremental (EmitGroupAdded):   { group, userId }
- *     - The recipient was added to a single sync group.
- *     - Subsequent 'C' (Covering) deltas deliver each newly-visible entity.
- *     - No re-bootstrap — entities arrive via the normal insert path.
+ *   Incremental — `{ group, userId }`: the recipient was added to a single
+ *   sync group. No re-bootstrap follows; the newly visible entities arrive as
+ *   ordinary 'C' (covering) deltas through the normal insert path.
  *
- *   Legacy (EmitGroupChange):       { addedGroups, removedGroups }
- *     - Single delta carrying the full group membership diff.
- *     - Forces a full re-bootstrap (disconnect + reconnect + fetch all).
- *     - Deprecated on the server; kept here for wire-level backward compat.
+ *   Full diff — `{ addedGroups, removedGroups }`: one delta carrying the whole
+ *   membership change. This forces a full re-bootstrap (disconnect, reconnect,
+ *   and refetch), clearing cached data first if any group was removed.
  */
 export async function handleSyncGroupChange(ctx, delta) {
     const raw = parseGroupChangePayload(delta);
     if (raw === MALFORMED_PAYLOAD) {
-        // Malformed payload — we can't know WHICH groups changed, and this
-        // delta will never be re-delivered (the watermark already advanced).
-        // Degrade to the legacy security path: assume a removal, clear cached
-        // data, and rebuild from server truth. Never throw out of the pipeline.
+        // The payload is unreadable, so we cannot tell which groups changed, and
+        // this delta will never be re-delivered because the watermark has already
+        // advanced. Fall back to the safe direction: assume a revocation, clear
+        // cached data, and rebuild from the server rather than throwing.
         await clearForUnknownGroupChange(ctx, delta, 'sync-group change');
         return;
     }
@@ -84,7 +83,7 @@ export async function handleSyncGroupChange(ctx, delta) {
         await ctx.handleGroupAdded(incremental, delta.id);
         return;
     }
-    // Legacy payload: { addedGroups, removedGroups }
+    // Full-diff payload: { addedGroups, removedGroups }
     const payload = {
         removedGroups: rawObj.removedGroups ?? [],
         addedGroups: rawObj.addedGroups ?? [],
@@ -94,9 +93,9 @@ export async function handleSyncGroupChange(ctx, delta) {
         addedGroups: payload.addedGroups,
         syncId: delta.id,
     });
-    // SECURITY: If groups were removed, clear cached data immediately.
-    // This prevents revoked data from persisting if the device goes offline
-    // before the full re-bootstrap completes.
+    // If any groups were removed, clear cached data immediately so revoked data
+    // cannot persist should the device go offline before the re-bootstrap
+    // completes.
     if (payload.removedGroups.length > 0) {
         await ctx.database.clear();
         ctx.objectPool.clear();
@@ -109,11 +108,10 @@ export async function handleSyncGroupChange(ctx, delta) {
     ctx.forceFullRebootstrap();
 }
 /**
- * Handle an incremental GroupAdded delta.
- *
- * Adds the new group to the subscription metadata without triggering a
- * re-bootstrap. The server will follow up with 'C' (Covering) deltas for
- * each newly-visible entity, which flow through the normal insert path.
+ * Handles an incremental group-added delta. It records the new sync group in
+ * the subscription metadata without forcing a re-bootstrap; the server then
+ * sends a 'C' (covering) delta for each newly visible entity, which flows
+ * through the normal insert path.
  */
 export async function handleGroupAdded(ctx, payload, syncId) {
     getContext().logger.info('[BaseSyncedStore] Group added (incremental)', {
@@ -123,26 +121,20 @@ export async function handleGroupAdded(ctx, payload, syncId) {
     const current = new Set(ctx.getSubscribedSyncGroups());
     current.add(payload.group);
     await ctx.database.updateWorkspaceMetadata({ subscribedSyncGroups: Array.from(current) });
-    // Note: no forceFullRebootstrap() — covering deltas will bring the entities.
+    // No forceFullRebootstrap() here; the covering deltas will bring the entities.
 }
 /**
- * Handle an actionType 'S' (GroupRemoved) delta.
- *
- * Signals that the recipient has lost access to a sync group. Because
- * the client does not track per-entity group membership, we can't
- * selectively purge entities belonging to that group. The safe fallback
- * is the legacy behavior: clear local state and force a re-bootstrap
- * with the updated group list.
- *
- * Future optimization: track group membership in the ObjectPool so 'S'
- * can do a targeted purge instead of a full re-bootstrap.
+ * Handles an 'S' (group-removed) delta, which signals the recipient has lost
+ * access to a sync group. The client does not track which entities belong to
+ * which group, so it cannot purge only the affected rows; instead it clears
+ * local state and forces a re-bootstrap with the updated group list.
  */
 export async function handleGroupRemoved(ctx, delta) {
     const raw = parseGroupChangePayload(delta);
     if (raw === MALFORMED_PAYLOAD) {
-        // Malformed 'S' payload — access WAS revoked but we can't tell which
-        // group. Degrade to the legacy clear (the safe direction for a
-        // security delta) instead of throwing out of the pipeline.
+        // The payload is unreadable: access was revoked but we cannot tell which
+        // group. Fall back to a full clear, the safe direction for an
+        // access-revocation delta, rather than throwing.
         await clearForUnknownGroupChange(ctx, delta, 'group-removed');
         return;
     }
@@ -158,9 +150,9 @@ export async function handleGroupRemoved(ctx, delta) {
         group: groupKey,
         syncId: delta.id,
     });
-    // SECURITY: Clear cached data before re-bootstrap. This prevents
-    // revoked-group data from persisting if the device goes offline
-    // between receiving 'S' and completing the re-bootstrap.
+    // Clear cached data before the re-bootstrap so revoked-group data cannot
+    // persist if the device goes offline between receiving this delta and
+    // completing the re-bootstrap.
     await ctx.database.clear();
     ctx.objectPool.clear();
     // Update subscription metadata so the re-bootstrap fetches the
@@ -170,7 +162,7 @@ export async function handleGroupRemoved(ctx, delta) {
     await ctx.database.updateWorkspaceMetadata({ subscribedSyncGroups: Array.from(current) });
     ctx.forceFullRebootstrap();
 }
-/** Compute new sync groups after applying additions and removals */
+/** Computes the new sync-group set after applying the additions and removals in a diff. */
 export function computeUpdatedSyncGroups(ctx, payload) {
     const current = new Set(ctx.getSubscribedSyncGroups());
     for (const g of payload.removedGroups)
@@ -179,12 +171,12 @@ export function computeUpdatedSyncGroups(ctx, payload) {
         current.add(g);
     return Array.from(current);
 }
-/** Force a full re-bootstrap via connection lifecycle event.
- *
- * No-op for `bootstrapMode: 'none'` participants — they never pull
- * baseline state, so a "force re-bootstrap" trigger (sync-group
- * shrink, scope revocation) instead just flushes the local pool and
- * relies on covering deltas to repopulate the data they actually
+/**
+ * Forces a full re-bootstrap by marking local storage as needing one,
+ * disconnecting, and emitting a connection lifecycle event that the reconnect
+ * path acts on. Does nothing for participants whose bootstrap mode is 'none':
+ * they never pull a baseline, so after a trigger such as a sync-group shrink or
+ * an access revocation they rely on covering deltas to repopulate the data they
  * subscribe to.
  */
 export function forceFullRebootstrap(ctx) {
@@ -197,12 +189,12 @@ export function forceFullRebootstrap(ctx) {
     ctx.emitConnectionEvent('WS_DISCONNECTED');
 }
 /**
- * Single source of truth for the sync-group list this session is
- * subscribed to. Server-issued (`context.syncGroups`) is authoritative.
- * When absent, the SDK subscribes to no explicit groups. Both
- * `checkSyncGroupShrinkage` and `setupWebSocketSync` resolve through
- * here so the WS subscription and the security-critical shrinkage
- * check can never disagree.
+ * Resolves the sync-group list this session subscribes to, and is the single
+ * place that decision is made. The server-issued `context.syncGroups` is
+ * authoritative; when it is absent, the session subscribes to no explicit
+ * groups. {@link checkSyncGroupShrinkage} and connection setup both read
+ * through here, so the live subscription and the access-revocation check can
+ * never disagree.
  */
 export function resolveSyncGroups(context) {
     if (context.syncGroups && context.syncGroups.length > 0) {
@@ -210,7 +202,11 @@ export function resolveSyncGroups(context) {
     }
     return [];
 }
-/** Check if sync groups shrank since last session — force full bootstrap if so */
+/**
+ * Compares the session's current sync groups against the set stored from the
+ * last session. If any group is now missing, access has narrowed, so this
+ * clears cached data and forces a full bootstrap before recording the new set.
+ */
 export async function checkSyncGroupShrinkage(ctx) {
     const currentSyncGroups = ctx.getCurrentSyncGroups();
     if (!currentSyncGroups)
@@ -228,8 +224,8 @@ export async function checkSyncGroupShrinkage(ctx) {
                 storedCount: stored.length,
                 currentCount: currentGroups.size,
             });
-            // SECURITY: Clear cached data before re-bootstrap to prevent
-            // revoked-group data from persisting if device goes offline
+            // Clear cached data before the re-bootstrap so revoked-group data cannot
+            // persist if the device goes offline first.
             await ctx.database.clear();
             ctx.objectPool.clear();
             ctx.database.markRequiresFullBootstrap();

package/dist/sync/heartbeat.d.ts

@@ -1,55 +1,56 @@
 /**
  * Application-level heartbeat for the sync WebSocket.
  *
- * 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.
+ * The browser WebSocket API hides RFC 6455 protocol-level ping and pong frames
+ * from JavaScript, so the server's keepalive cannot be observed by client
+ * code. That leaves the client unable to tell a healthy idle connection apart
+ * from a "zombie" socket whose underlying TCP connection has silently broken
+ * (laptop sleep, NAT timeout, mobile handoff). To close the gap, the client
+ * sends an application-level `{ type: 'ping' }` every 30 seconds and
+ * force-closes the socket if no inbound traffic arrives within 10 seconds. Any
+ * inbound message counts as proof the connection is alive; the explicit `pong`
+ * merely guarantees that something arrives even on an otherwise idle stream.
  */
 /**
- * One cadence for both sides: the SDK's application-level ping runs at the
- * same `PING_INTERVAL_MS` as the server's RFC 6455 keepalive (and the claim
- * lease window is derived from it — see `wire/protocol.ts`).
+ * The interval between application-level pings, shared with both sides of the
+ * connection: the client pings at the same {@link PING_INTERVAL_MS} the server
+ * uses for its own keepalive, and the claim lease window is derived from the
+ * same constant.
  */
 export declare const HEARTBEAT_INTERVAL_MS = 30000;
 export declare const HEARTBEAT_TIMEOUT_MS = 10000;
 /**
- * The slice of the socket the heartbeat needs — kept minimal so this
- * leaf never depends on the SyncWebSocket class itself.
+ * The narrow slice of the socket the heartbeat depends on. Keeping it small
+ * lets the {@link HeartbeatController} work without depending on the full
+ * WebSocket transport.
  */
 export interface HeartbeatTransport {
-    /** True only while the underlying socket is `OPEN`. */
+    /** True only while the underlying socket is open. */
     isSocketOpen(): boolean;
-    /** Send the `{ type: 'ping' }` frame; throws when the socket is already dead. */
+    /** Sends the `{ type: 'ping' }` frame; throws when the socket is already dead. */
     sendPing(): void;
     /**
-     * Force-close the socket from the client side (private 4xxx code) so
-     * `onclose` fires and runs the owner's reconnect / handshake-failed
-     * dispatch.
+     * Closes the socket from the client side with a private 4xxx code, so the
+     * socket's close event fires and the owner's reconnect or handshake-failure
+     * handling runs.
      */
     forceClose(reason: string): void;
 }
 /**
- * Every `HEARTBEAT_INTERVAL_MS` while `OPEN`, send `{ type: 'ping' }`
- * and arm a `HEARTBEAT_TIMEOUT_MS` watchdog. Any inbound frame (the
- * owner's `onmessage` calls {@link clearHeartbeatTimeout}) clears the
- * watchdog. If the watchdog fires, we treat the connection as zombie
- * and force-close it — `onclose` then triggers the existing reconnect
- * path.
+ * Runs the application-level heartbeat for one socket. While the socket is
+ * open, it sends a `{ type: 'ping' }` frame every {@link HEARTBEAT_INTERVAL_MS}
+ * and arms a {@link HEARTBEAT_TIMEOUT_MS} watchdog. Any inbound frame clears
+ * the watchdog — the owner calls {@link HeartbeatController.clearHeartbeatTimeout}
+ * from its message handler. If the watchdog fires first, the connection is
+ * treated as a zombie and force-closed, which lets the owner's reconnect path
+ * run.
  *
- * 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.
+ * The heartbeat exists because the client cannot see the protocol-level
+ * keepalive: browsers answer the server's pings automatically but never expose
+ * those frames to JavaScript. On a half-open connection (laptop wake, NAT
+ * timeout, mobile handoff) the socket can report itself open for minutes
+ * before the operating system surfaces the break, so observable application
+ * traffic is the only reliable signal.
  */
 export declare class HeartbeatController {
     private readonly transport;

package/dist/sync/heartbeat.js

@@ -1,41 +1,41 @@
 /**
  * Application-level heartbeat for the sync WebSocket.
  *
- * 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.
+ * The browser WebSocket API hides RFC 6455 protocol-level ping and pong frames
+ * from JavaScript, so the server's keepalive cannot be observed by client
+ * code. That leaves the client unable to tell a healthy idle connection apart
+ * from a "zombie" socket whose underlying TCP connection has silently broken
+ * (laptop sleep, NAT timeout, mobile handoff). To close the gap, the client
+ * sends an application-level `{ type: 'ping' }` every 30 seconds and
+ * force-closes the socket if no inbound traffic arrives within 10 seconds. Any
+ * inbound message counts as proof the connection is alive; the explicit `pong`
+ * merely guarantees that something arrives even on an otherwise idle stream.
  */
 import { getContext } from '../context.js';
 import { PING_INTERVAL_MS } from '../wire/protocol.js';
 /**
- * One cadence for both sides: the SDK's application-level ping runs at the
- * same `PING_INTERVAL_MS` as the server's RFC 6455 keepalive (and the claim
- * lease window is derived from it — see `wire/protocol.ts`).
+ * The interval between application-level pings, shared with both sides of the
+ * connection: the client pings at the same {@link PING_INTERVAL_MS} the server
+ * uses for its own keepalive, and the claim lease window is derived from the
+ * same constant.
  */
 export const HEARTBEAT_INTERVAL_MS = PING_INTERVAL_MS;
 export const HEARTBEAT_TIMEOUT_MS = 10_000;
 /**
- * Every `HEARTBEAT_INTERVAL_MS` while `OPEN`, send `{ type: 'ping' }`
- * and arm a `HEARTBEAT_TIMEOUT_MS` watchdog. Any inbound frame (the
- * owner's `onmessage` calls {@link clearHeartbeatTimeout}) clears the
- * watchdog. If the watchdog fires, we treat the connection as zombie
- * and force-close it — `onclose` then triggers the existing reconnect
- * path.
+ * Runs the application-level heartbeat for one socket. While the socket is
+ * open, it sends a `{ type: 'ping' }` frame every {@link HEARTBEAT_INTERVAL_MS}
+ * and arms a {@link HEARTBEAT_TIMEOUT_MS} watchdog. Any inbound frame clears
+ * the watchdog — the owner calls {@link HeartbeatController.clearHeartbeatTimeout}
+ * from its message handler. If the watchdog fires first, the connection is
+ * treated as a zombie and force-closed, which lets the owner's reconnect path
+ * run.
  *
- * 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.
+ * The heartbeat exists because the client cannot see the protocol-level
+ * keepalive: browsers answer the server's pings automatically but never expose
+ * those frames to JavaScript. On a half-open connection (laptop wake, NAT
+ * timeout, mobile handoff) the socket can report itself open for minutes
+ * before the operating system surfaces the break, so observable application
+ * traffic is the only reliable signal.
  */
 export class HeartbeatController {
     transport;
@@ -49,8 +49,8 @@ export class HeartbeatController {
         this.heartbeatTimer = setInterval(() => {
             if (!this.transport.isSocketOpen())
                 return;
-            // Send the ping. If `send` throws, the socket is already dead —
-            // force-close so onclose triggers the reconnect cycle.
+            // Send the ping. If it throws, the socket is already dead, so
+            // force-close it to let the close event drive the reconnect cycle.
             try {
                 this.transport.sendPing();
             }
@@ -62,9 +62,9 @@ export class HeartbeatController {
                 this.transport.forceClose('heartbeat-send-failed');
                 return;
             }
-            // Arm the timeout. ANY inbound message clears it (see the owner's
-            // onmessage). We don't require an explicit `pong` — a delta or any
-            // other frame is equally good proof-of-life.
+            // Arm the timeout. Any inbound message clears it; an explicit `pong` is
+            // not required, since a delta or any other frame is equally good proof
+            // that the connection is alive.
             if (this.heartbeatTimeoutTimer)
                 clearTimeout(this.heartbeatTimeoutTimer);
             this.heartbeatTimeoutTimer = setTimeout(() => {

package/dist/sync/participants.d.ts

@@ -3,9 +3,9 @@ import type { Schema } from '../schema/schema.js';
 import type { Claim, Activity, ClaimTarget, ClaimStream, Peer, PresenceStream, PresenceTarget } from '../types/streams.js';
 import type { AttachableClaimStream } from './createClaimStream.js';
 /**
- * Scope accepted by participant APIs. The normal SDK shape is an
- * entity target (`{ type, id }`). Raw sync-group strings remain an
- * advanced transport escape hatch.
+ * The scope a participant can be joined to. The usual form is an entity target
+ * (`{ type, id }`); raw sync-group strings are an advanced escape hatch for
+ * addressing a transport scope directly.
  */
 export type ParticipantScope = ClaimTarget | readonly ClaimTarget[] | string | readonly string[] | {
     readonly syncGroup: string;
@@ -19,26 +19,27 @@ export interface EngineParticipant {
 }
 export interface ParticipantJoinOptions {
     /**
-     * Initial focus target: customer schema vocabulary, optionally
-     * narrowed to a path, field, or range. When `scope` is omitted,
-     * this also becomes the routing scope.
+     * The initial focus target, named in your schema's vocabulary and optionally
+     * narrowed to a path, field, or range. When `scope` is omitted, this target
+     * also becomes the routing scope.
      */
     readonly target?: PresenceTarget;
     /** Alias for `target` when the participant is joined to a broader scope. */
     readonly focus?: PresenceTarget;
     /**
-     * Routing scope. Can be one entity, many entities, or a raw
-     * sync-group escape hatch. Use this for "joined to folder, focused
-     * on file" shapes.
+     * The routing scope: one entity, many entities, or a raw sync-group escape
+     * hatch. Use it for "joined to the folder, focused on one file" shapes,
+     * where the participant listens more broadly than its focus target.
      */
     readonly scope?: ParticipantScope;
     /** Present a narrower capability for this logical participant. */
     readonly capabilityToken?: string;
-    /** Claim TTL, in seconds or a compact duration string (`30s`, `5m`). */
+    /** How long the claim lives, in seconds or a compact duration string (`30s`, `5m`). */
     readonly ttlSeconds?: number | string | null;
     /**
-     * Activity to announce immediately after the claim acks. Defaults to
-     * `reading` when `target` is present. Pass false to join silently.
+     * The activity to announce as soon as the claim is acknowledged. Defaults to
+     * `reading` when a `target` is present. Pass `false` to join without
+     * announcing anything.
      */
     readonly activity?: 'reading' | 'viewing' | 'editing' | false;
     readonly detail?: string;
@@ -63,17 +64,16 @@ export interface ScopedClaimOptions {
     /** Free-form reason. Defaults to `'editing'`. Common: `'editing'`,
      *  `'writing'`, `'reviewing'`, app-specific phases. */
     readonly reason?: string;
-    /** TTL — server auto-expires the claim after this. */
+    /** How long the claim lives; the server expires it automatically after this. */
     readonly ttl?: import('../types/streams.js').Duration;
 }
 export interface ScopedClaims {
     readonly focus: ClaimTarget | null;
     readonly others: readonly Claim[];
     /**
-     * Claim an exclusive claim on the participant's focus target (or
-     * an explicit override via `opts.target`). Single verb — the old
-     * `editing / writing / announce / claim(reason, opts)` overloads
-     * collapsed into this one method.
+     * Takes an exclusive claim on the participant's focus target, or on an
+     * explicit target passed via `opts.target`. While the claim is held, other
+     * participants that request an overlapping target are rejected.
      */
     claim(opts?: ScopedClaimOptions): Claim;
     onRejected(listener: Parameters<ClaimStream['onRejected']>[0]): () => void;
@@ -84,10 +84,10 @@ export interface ParticipantFocusOptions {
     readonly detail?: string;
 }
 export interface JoinedParticipant {
-    /** Current exact thing this participant is reading/editing. */
+    /** The exact entity this participant is currently reading or editing. */
     readonly target: ClaimTarget | null;
     readonly focusTarget: ClaimTarget | null;
-    /** Transport scopes this participant is joined to for visibility/fan-out. */
+    /** The transport scopes this participant is joined to, which govern what it sees and receives. */
     readonly syncGroups: readonly string[];
     readonly presence: ScopedPresence;
     readonly claims: ScopedClaims;

package/dist/sync/schemas.d.ts

@@ -74,7 +74,8 @@ export declare const BootstrapResponseSchema: z.ZodObject<{
 }, z.core.$loose>;
 export type ValidatedBootstrapResponse = z.infer<typeof BootstrapResponseSchema>;
 /**
- * Validate a raw bootstrap response from the server.
- * Logs validation failures via SyncObservability and throws a descriptive error.
+ * Validates a raw bootstrap response from the server and returns the typed
+ * result. On failure it records a diagnostic breadcrumb and throws an
+ * {@link AbloValidationError} describing which fields were invalid.
  */
 export declare function parseBootstrapResponse(raw: unknown): ValidatedBootstrapResponse;

package/dist/sync/schemas.js

@@ -8,7 +8,8 @@ import { z } from 'zod';
 import { getContext } from "../context.js";
 import { AbloValidationError } from "../errors.js";
 // ─── Sync Action Types ───────────────────────────────────────────────────────
-// Mirror of SyncActionType from sync-engine/types.ts
+// The action codes a server delta can carry, matching the wire protocol's
+// action-type set.
 const SYNC_ACTION_VALUES = ['I', 'U', 'D', 'A', 'C', 'G', 'S', 'V'];
 // ─── Server Delta Schema ─────────────────────────────────────────────────────
 export const ServerDeltaSchema = z
@@ -23,11 +24,12 @@ export const ServerDeltaSchema = z
 })
     .passthrough();
 // ─── Model Value Schema ─────────────────────────────────────────────────────
-// Server model values arrive in multiple shapes depending on Go serialization:
-//   - Array: already-parsed JSON array (most common)
-//   - String: double-encoded JSON string from json.RawMessage
-//   - null: from PostgreSQL jsonb_agg with no matching rows
-// This schema normalizes all variants into unknown[] before downstream use.
+// A model's values can arrive in more than one shape depending on how the
+// server serialized them:
+//   - Array: an already-parsed JSON array (the common case)
+//   - String: a JSON array still encoded as a string, which must be parsed
+//   - null: no matching rows
+// This schema normalizes every variant into an array before downstream use.
 const ModelValueSchema = z
     .union([z.array(z.unknown()), z.string(), z.null()])
     .transform((val) => {
@@ -54,15 +56,17 @@ export const BootstrapResponseSchema = z
     deltaCount: z.number().optional(),
     failedModels: z.array(z.string()).optional(),
     timestamp: z.number().default(() => Date.now()),
-    // Server's active schema hash (drift detection). Optional: absent from
-    // older servers / tenants that have never pushed a schema.
+    // The server's active schema hash, used to detect schema drift. Optional:
+    // absent when the server predates this field or the tenant has never
+    // pushed a schema.
     schemaHash: z.string().optional(),
 })
     .passthrough();
 // ─── Parse Helpers ───────────────────────────────────────────────────────────
 /**
- * Validate a raw bootstrap response from the server.
- * Logs validation failures via SyncObservability and throws a descriptive error.
+ * Validates a raw bootstrap response from the server and returns the typed
+ * result. On failure it records a diagnostic breadcrumb and throws an
+ * {@link AbloValidationError} describing which fields were invalid.
  */
 export function parseBootstrapResponse(raw) {
     const result = BootstrapResponseSchema.safeParse(raw);