@abloatai/ablo 0.10.1 → 0.11.1

package/dist/sync/SyncWebSocket.js

@@ -11,6 +11,7 @@ import { EventEmitter } from 'events';
 import { getContext } from '../context.js';
 import { flushOfflineQueueOnce } from './OfflineFlush.js';
 import { AbloConnectionError, AbloError, CapabilityError, SyncSessionError, errorFromWire, toAbloError, } from '../errors.js';
+import { subscriptionAckPayloadSchema } from '../coordination/schema.js';
 import { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL, } from '../auth/credentialSource.js';
 // ---------------------------------------------------------------------------
 // Ablo-specific collaboration events moved to apps/web/src/lib/sync/collaboration-events.ts
@@ -105,6 +106,15 @@ export class SyncWebSocket extends EventEmitter {
      * over a multiplexed connection.
      */
     pendingClaims = new Map();
+    /**
+     * In-flight `update_subscription` frames awaiting `subscription_ack`.
+     * A FIFO queue rather than a keyed Map because the wire ack carries no
+     * correlation id — the server applies subscription updates in receive
+     * order and acks in the same order, so `shift()` on ack matches the
+     * oldest pending request. (Read-interest changes are infrequent and
+     * usually settle before the next one, so depth is ~1 in practice.)
+     */
+    pendingSubscriptions = [];
     constructor(options) {
         super();
         // Construct WebSocket URL from base Go server URL
@@ -430,6 +440,37 @@ export class SyncWebSocket extends EventEmitter {
                         }
                         break;
                     }
+                    case 'subscription_ack': {
+                        // 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).
+                        const pending = this.pendingSubscriptions.shift();
+                        if (!pending)
+                            break;
+                        clearTimeout(pending.timeout);
+                        const parsed = subscriptionAckPayloadSchema.safeParse(message.payload);
+                        if (!parsed.success) {
+                            // Unreadable ack — resolve the pending request as a failure
+                            // rather than hang it until timeout.
+                            pending.reject(errorFromWire('malformed subscription_ack from server', {
+                                code: 'malformed_subscription',
+                            }));
+                            break;
+                        }
+                        const ack = parsed.data;
+                        if (ack.success) {
+                            // Keep the reconnect URL aligned with current interest: a
+                            // reconnect re-subscribes from `this.options.syncGroups`.
+                            this.options.syncGroups = ack.syncGroups;
+                            pending.resolve({ syncGroups: ack.syncGroups });
+                        }
+                        else {
+                            pending.reject(errorFromWire(ack.error?.message ?? 'update_subscription rejected by server', { code: ack.error?.code ?? 'malformed_subscription' }));
+                        }
+                        break;
+                    }
                     case 'claim_expired': {
                         // Server-initiated expiry notification. Emit as a typed
                         // event so consumers can react (re-claim with a fresh
@@ -441,39 +482,39 @@ export class SyncWebSocket extends EventEmitter {
                         }
                         break;
                     }
-                    case 'intent_rejected': {
-                        // Server denied an `intent_begin` because the target is
+                    case 'claim_rejected': {
+                        // Server denied an `claim_begin` because the target is
                         // already claimed by another participant. Forward the
-                        // payload as-is — the IntentStream consumer interprets
+                        // payload as-is — the ClaimStream consumer interprets
                         // the conflict shape (peerId, target, etc.).
-                        this.emit('intent_rejected', message.payload ?? {});
+                        this.emit('claim_rejected', message.payload ?? {});
                         break;
                     }
-                    case 'intent_acquired': {
+                    case 'claim_acquired': {
                         // Opt-in fair queue: the target was free, so the lease is ours
-                        // immediately (no waiting). Payload carries { intentId, target }.
-                        this.emit('intent_acquired', message.payload ?? {});
+                        // immediately (no waiting). Payload carries { claimId, target }.
+                        this.emit('claim_acquired', message.payload ?? {});
                         break;
                     }
-                    case 'intent_queue': {
+                    case 'claim_queue': {
                         // Per-entity wait-queue snapshot for reactive `queue(id)`.
-                        this.emit('intent_queue', message.payload ?? {});
+                        this.emit('claim_queue', message.payload ?? {});
                         break;
                     }
-                    case 'intent_queued': {
+                    case 'claim_queued': {
                         // Opt-in fair queue: our claim is waiting in line. Payload
-                        // carries { intentId, target, position }.
-                        this.emit('intent_queued', message.payload ?? {});
+                        // carries { claimId, target, position }.
+                        this.emit('claim_queued', message.payload ?? {});
                         break;
                     }
-                    case 'intent_granted': {
+                    case 'claim_granted': {
                         // Our queued claim reached the head — the lease is now ours.
-                        this.emit('intent_granted', message.payload ?? {});
+                        this.emit('claim_granted', message.payload ?? {});
                         break;
                     }
-                    case 'intent_lost': {
+                    case 'claim_lost': {
                         // A held/granted claim was taken from us (TTL lapse, revoke).
-                        this.emit('intent_lost', message.payload ?? {});
+                        this.emit('claim_lost', message.payload ?? {});
                         break;
                     }
                     case 'delta': {
@@ -585,6 +626,17 @@ export class SyncWebSocket extends EventEmitter {
                 }
                 this.pendingClaims.clear();
             }
+            // Cancel in-flight subscription updates — the reconnect handshake
+            // re-sends `options.syncGroups` (the last acked interest) in the
+            // upgrade URL, so a pending change that never acked is simply
+            // retried by the caller against the fresh connection.
+            if (this.pendingSubscriptions.length > 0) {
+                for (const pending of this.pendingSubscriptions) {
+                    clearTimeout(pending.timeout);
+                    pending.reject(new AbloConnectionError(`WebSocket closed while update_subscription was in flight (code=${event.code})`));
+                }
+                this.pendingSubscriptions = [];
+            }
             // Check for session-related close codes
             // 1008 = Policy Violation (often auth)
             // 4001 = Unauthorized (custom)
@@ -702,7 +754,6 @@ export class SyncWebSocket extends EventEmitter {
             type: 'ack',
             payload: {
                 lastSyncId: syncId,
-                versions: this.versionVector,
             },
         });
     }
@@ -887,13 +938,13 @@ export class SyncWebSocket extends EventEmitter {
     sendRelease(claimId) {
         // Cancel any in-flight claim that hadn't acked yet — the user
         // changed their mind. Without this the timer would eventually
-        // reject; doing it now matches the user's intent immediately.
+        // reject; doing it now matches the user's claim immediately.
         const pending = this.pendingClaims.get(claimId);
         if (pending) {
             clearTimeout(pending.timeout);
             this.pendingClaims.delete(claimId);
             pending.reject(new AbloError(`claim ${claimId} released before ack`, {
-                code: 'intent_wait_aborted',
+                code: 'claim_wait_aborted',
                 httpStatus: 409,
             }));
         }
@@ -906,6 +957,56 @@ export class SyncWebSocket extends EventEmitter {
             // Idempotent contract — silent failure is acceptable here.
         }
     }
+    /**
+     * Move this connection's READ interest — replace the connection-level
+     * sync groups mid-session as the user opens/closes entities. This is the
+     * area-of-interest (AOI) navigation primitive: the server fans out
+     * deltas only for groups currently in view, instead of the frozen set
+     * chosen at connect.
+     *
+     * Full-set replace semantics — pass the complete new group list, not a
+     * delta. Resolves with the server's effective set once `subscription_ack`
+     * arrives; rejects (typed) on a scope denial (a restricted `rk_` key
+     * requesting a group outside its allowlist), timeout, or disconnect. On
+     * success the new set is recorded as `options.syncGroups` so a later
+     * reconnect re-subscribes to current interest, not the connect-time set.
+     *
+     * Distinct from {@link sendClaim} (write-claim, per-op, TTL'd) — this is
+     * the read side and carries no capability token of its own; it's bounded
+     * by the connection credential's grant.
+     */
+    updateSubscription(syncGroups, options) {
+        if (this.ws?.readyState !== WebSocket.OPEN) {
+            return Promise.reject(this.notConnectedError('update_subscription'));
+        }
+        const timeoutMs = options?.timeoutMs ?? 15_000;
+        return new Promise((resolve, reject) => {
+            const entry = {
+                resolve,
+                reject,
+                timeout: setTimeout(() => {
+                    const idx = this.pendingSubscriptions.indexOf(entry);
+                    if (idx !== -1)
+                        this.pendingSubscriptions.splice(idx, 1);
+                    reject(new AbloConnectionError(`update_subscription timed out after ${timeoutMs}ms`, { code: 'wait_for_timeout' }));
+                }, timeoutMs),
+            };
+            this.pendingSubscriptions.push(entry);
+            try {
+                this.ws.send(JSON.stringify({
+                    type: 'update_subscription',
+                    payload: { syncGroups: [...syncGroups] },
+                }));
+            }
+            catch (error) {
+                clearTimeout(entry.timeout);
+                const idx = this.pendingSubscriptions.indexOf(entry);
+                if (idx !== -1)
+                    this.pendingSubscriptions.splice(idx, 1);
+                reject(toAbloError(error));
+            }
+        });
+    }
     /**
      * Compatibility setter for direct SyncWebSocket users. The SDK-owned
      * `Ablo()` path passes `getAuthToken`, so reconnect URL auth reads the
@@ -1287,9 +1388,7 @@ export class SyncWebSocket extends EventEmitter {
         this.send({
             type: 'sync_request',
             payload: {
-                cursor: this.syncCursor,
-                versions: this.versionVector,
-                // Always send lastSyncId to ensure server uses client's current position
+                cursor: this.syncCursor, // Always send lastSyncId to ensure server uses client's current position
                 lastSyncId: this.lastSyncId,
                 capabilities: capsArr,
             },
@@ -1309,9 +1408,7 @@ export class SyncWebSocket extends EventEmitter {
         this.send({
             type: 'bootstrap_request',
             payload: {
-                entities: entities || [],
-                versions: this.versionVector,
-                capabilities: this.options.capabilities,
+                entities: entities || [], capabilities: this.options.capabilities,
             },
         });
     }
@@ -1416,7 +1513,7 @@ export class SyncWebSocket extends EventEmitter {
      *
      * Wire frame (apps/sync-server/src/hub/types.ts PresenceUpdateMessage):
      *   { type: 'presence_update', payload: { kind, userId, status,
-     *     syncGroups, activity, isAgent, timestamp, activeIntents } }
+     *     syncGroups, activity, isAgent, timestamp, activeClaims } }
      */
     handlePresenceUpdate(message) {
         const event = 

package/dist/sync/awaitClaimGrant.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `awaitClaimGrant` — the client side of the fair-queue handover.
+ *
+ * When a `claim` is contended, the server enqueues it and replies `queued`
+ * (HTTP 202 on `/v1/claims`, or `claim_queued` over WS). The grant is then
+ * PUSHED later over the WS as `claim_granted` when the claim reaches the head.
+ * This resolves once that frame arrives for our `claimId` — so the caller's
+ * `claim` promise stays pending (event-driven; no poll, no race) until it's
+ * actually our turn. Rejects on `claim_lost` (surfaced as `claim_lost`: the claim was taken away — TTL
+ * lapse on disconnect, revoke) or an optional timeout.
+ *
+ * Takes only a minimal `{ subscribe }` transport so it unit-tests against a
+ * fake; `SyncWebSocket` satisfies it structurally.
+ */
+export interface GrantTransport {
+    subscribe(event: 'claim_acquired' | 'claim_granted' | 'claim_lost' | 'claim_queued' | 'claim_rejected', handler: (payload: Record<string, unknown>) => void): () => void;
+}
+export interface ClaimGrantInfo {
+    /**
+     * True when the grant arrived as `claim_granted` — i.e. the target was
+     * HELD when we asked and we waited in the FIFO line behind the holder.
+     * False for the immediate `claim_acquired` (target was free).
+     *
+     * Callers use this to know the row may have changed while we queued:
+     * claim VISIBILITY is entity-scoped (org-wide subscriptions receive no
+     * presence/claim fan-out — see Hub.broadcastPresenceChange), so the
+     * local coordination snapshot cannot be trusted to detect "we waited".
+     * The grant frame itself is the authoritative signal.
+     */
+    readonly waited: boolean;
+}
+export declare function awaitClaimGrant(transport: GrantTransport, claimId: string, options?: {
+    timeoutMs?: number;
+    /**
+     * Backpressure: reject instead of waiting if, when we join the line, the
+     * server reports `position >= maxQueueDepth` (i.e. that many claims are
+     * already ahead of us). Omit to wait however deep the queue is.
+     */
+    maxQueueDepth?: number;
+}): Promise<ClaimGrantInfo>;

package/dist/sync/awaitClaimGrant.js

@@ -0,0 +1,86 @@
+/**
+ * `awaitClaimGrant` — the client side of the fair-queue handover.
+ *
+ * When a `claim` is contended, the server enqueues it and replies `queued`
+ * (HTTP 202 on `/v1/claims`, or `claim_queued` over WS). The grant is then
+ * PUSHED later over the WS as `claim_granted` when the claim reaches the head.
+ * This resolves once that frame arrives for our `claimId` — so the caller's
+ * `claim` promise stays pending (event-driven; no poll, no race) until it's
+ * actually our turn. Rejects on `claim_lost` (surfaced as `claim_lost`: the claim was taken away — TTL
+ * lapse on disconnect, revoke) or an optional timeout.
+ *
+ * Takes only a minimal `{ subscribe }` transport so it unit-tests against a
+ * fake; `SyncWebSocket` satisfies it structurally.
+ */
+import { AbloClaimedError, formatClaimedErrorMessage, claimTargetLabel, } from '../errors.js';
+export function awaitClaimGrant(transport, claimId, options) {
+    return new Promise((resolve, reject) => {
+        const unsubs = [];
+        let timer;
+        const settle = (fn) => {
+            if (timer)
+                clearTimeout(timer);
+            for (const u of unsubs)
+                u();
+            fn();
+        };
+        // The target was free → `claim_acquired` (immediate); it was contended,
+        // we waited in line, and reached the head → `claim_granted`. Either frame
+        // means the lease is now ours; `waited` records which path it was.
+        unsubs.push(transport.subscribe('claim_acquired', (p) => {
+            if (p?.claimId === claimId)
+                settle(() => resolve({ waited: false }));
+        }));
+        unsubs.push(transport.subscribe('claim_granted', (p) => {
+            if (p?.claimId === claimId)
+                settle(() => resolve({ waited: true }));
+        }));
+        if (options?.maxQueueDepth !== undefined) {
+            const max = options.maxQueueDepth;
+            unsubs.push(transport.subscribe('claim_queued', (p) => {
+                if (p?.claimId !== claimId)
+                    return;
+                const position = typeof p.position === 'number' ? p.position : 0;
+                if (position >= max) {
+                    settle(() => reject(new AbloClaimedError(`Claim queue for ${claimId} is ${position} deep (max ${max}).`, { code: 'queue_too_deep' })));
+                }
+            }));
+        }
+        unsubs.push(transport.subscribe('claim_rejected', (p) => {
+            const rejection = p;
+            if (rejection.claimId !== claimId)
+                return;
+            const target = rejection.target
+                ? claimTargetLabel({
+                    model: rejection.target.entityType,
+                    id: rejection.target.entityId,
+                    field: rejection.target.field,
+                })
+                : claimId;
+            settle(() => reject(new AbloClaimedError(formatClaimedErrorMessage({
+                targetLabel: target,
+                heldBy: rejection.heldBy,
+                claim: rejection.heldByClaim,
+                policyReason: rejection.policyReason,
+                fallback: `Claim rejected for ${target}.`,
+            }), {
+                code: rejection.reason === 'conflict'
+                    ? 'claim_conflict'
+                    : 'claim_lease_unavailable',
+                claims: rejection.heldByClaim ? [rejection.heldByClaim] : undefined,
+            })));
+        }));
+        unsubs.push(transport.subscribe('claim_lost', (p) => {
+            if (p?.claimId === claimId) {
+                settle(() => reject(new AbloClaimedError(`Claim lost while queued for ${claimId}.`, {
+                    code: 'claim_lost',
+                })));
+            }
+        }));
+        if (options?.timeoutMs && options.timeoutMs > 0) {
+            timer = setTimeout(() => {
+                settle(() => reject(new AbloClaimedError(`Timed out waiting for the queue grant on claim ${claimId}.`, { code: 'grant_timeout' })));
+            }, options.timeoutMs);
+        }
+    });
+}

package/dist/sync/createClaimStream.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Transport-driven ClaimStream factory.
+ *
+ * Mirrors `createPresenceStream` — built directly on `SyncWebSocket`,
+ * no SyncAgent wrapper. Claims derive their `others` view from the
+ * same `presence_update` frames the presence stream consumes (the
+ * Hub piggybacks `activeClaims` on every presence frame). Outbound
+ * announce/revoke ride the same socket via `claim_begin` /
+ * `claim_abandon` frames.
+ *
+ * Wire contract (apps/sync-server/src/hub/types.ts):
+ *   • Outbound: `{ type: 'claim_begin', payload: { claimId,
+ *       entityType, entityId, action, field?, estimatedMs? } }`
+ *   • Outbound: `{ type: 'claim_abandon', payload: { claimId,
+ *       entityType?, entityId? } }`
+ *   • Inbound (via presence): `event.activeClaims: Claim[]`
+ *     stamped with `declaredAt`, `expiresAt`.
+ *   • Inbound: `claim_rejected` event with conflict metadata.
+ *
+ * After the dual-engine collapse (step #36), this is the only
+ * ClaimStream factory in the SDK; the older compatibility path
+ * deletes.
+ */
+import type { SyncWebSocket } from './SyncWebSocket.js';
+import type { ClaimStream } from '../types/streams.js';
+export interface ClaimStreamConfig {
+    /** Identity used to filter our own active claims out of `others`. */
+    participantId: string;
+}
+export interface AttachableClaimStream extends ClaimStream {
+    attach(transport: SyncWebSocket): void;
+    dispose(): void;
+}
+export declare function createClaimStream(config: ClaimStreamConfig, transport?: SyncWebSocket | null): AttachableClaimStream;