@abloatai/ablo 0.10.0 → 0.11.0

package/dist/sync/AreaOfInterestManager.js

@@ -0,0 +1,233 @@
+/**
+ * AreaOfInterestManager — client-side hysteresis + prominence policy over
+ * the `update_subscription` read primitive.
+ *
+ * Game netcode never thrashes its area-of-interest on a boundary: a cell
+ * you walk out of stays subscribed for a margin before it's dropped
+ * (hysteresis), and "important" entities stay relevant from farther away
+ * (prominence). This manager applies both to Ablo sync groups:
+ *
+ *   - `enter(group)` / `leave(group)` move read interest as the user opens
+ *     and closes entities (decks, sheets, docs). A `leave` does NOT
+ *     immediately unsubscribe — the group goes WARM with a TTL and stays
+ *     in the effective set. Re-entering within the window is a no-op
+ *     (already subscribed → no bootstrap), and only when the warm TTL
+ *     lapses does the group actually drop. This is the boundary hysteresis
+ *     that turns deck-tab flipping from a re-bootstrap storm into a
+ *     cache hit.
+ *
+ *   - `pin(group)` / `unpin(group)` express prominence: a group that holds
+ *     an active claim (write-claim) is pinned and never goes warm or
+ *     expires while pinned. The claim machinery is the prominence oracle —
+ *     the row two agents are fighting over stays subscribed regardless of
+ *     navigation.
+ *
+ *   - `baseGroups` are permanent infrastructure scopes (e.g. `org:<id>`,
+ *     `user:<id>`) that are always in the effective set.
+ *
+ * The effective set is recomputed and diffed against what was last sent;
+ * the transport's `update_subscription` is only called when it actually
+ * changes, so hysteresis genuinely suppresses network churn rather than
+ * just deferring it.
+ *
+ * Transport-agnostic: it depends only on {@link SubscriptionTransport},
+ * which `SyncWebSocket` satisfies structurally. `now` and the sweep timer
+ * are injectable so the policy is deterministic under test.
+ */
+function setsEqual(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const v of a)
+        if (!b.has(v))
+            return false;
+    return true;
+}
+export class AreaOfInterestManager {
+    transport;
+    baseGroups;
+    warmTtlMs;
+    maxWarm;
+    now;
+    /** Groups currently in view (open entities). */
+    active = new Set();
+    /** Claim-pinned groups — prominence; never warm/expire while pinned. */
+    pinned = new Set();
+    /** Left-but-warm groups → epoch-ms at which they drop. */
+    warm = new Map();
+    /** Last set the transport confirmed — the diff baseline. */
+    lastSent = new Set();
+    /** Coalescing state so concurrent mutations collapse into one in-flight call. */
+    inFlight = null;
+    dirty = false;
+    cancelSweep;
+    constructor(options) {
+        this.transport = options.transport;
+        this.baseGroups = new Set(options.baseGroups ?? []);
+        this.warmTtlMs = options.warmTtlMs ?? 30_000;
+        this.maxWarm = options.maxWarm ?? 16;
+        this.now = options.now ?? (() => Date.now());
+        const sweepInterval = options.sweepIntervalMs ?? this.warmTtlMs;
+        if (sweepInterval > 0) {
+            const schedule = options.scheduler ??
+                ((fn, ms) => {
+                    const handle = setInterval(fn, ms);
+                    return () => clearInterval(handle);
+                });
+            this.cancelSweep = schedule(() => {
+                void this.sweep();
+            }, sweepInterval);
+        }
+        else {
+            this.cancelSweep = null;
+        }
+    }
+    /**
+     * Move a group into the warm set with a fresh TTL, maintaining LRU order
+     * and the `maxWarm` cap. JS `Map` preserves insertion order, so deleting
+     * then re-setting moves the group to the most-recently-warmed position;
+     * eviction then drops from the front (oldest). Base/pinned groups never
+     * warm — callers guard before calling this.
+     */
+    warmGroup(group) {
+        this.warm.delete(group);
+        this.warm.set(group, this.now() + this.warmTtlMs);
+        while (this.warm.size > this.maxWarm) {
+            const oldest = this.warm.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.warm.delete(oldest);
+        }
+    }
+    /** The effective read set: base ∪ active ∪ pinned ∪ (warm not yet expired). */
+    desiredGroups() {
+        const now = this.now();
+        const desired = new Set(this.baseGroups);
+        for (const g of this.active)
+            desired.add(g);
+        for (const g of this.pinned)
+            desired.add(g);
+        for (const [g, expiry] of this.warm) {
+            if (expiry > now)
+                desired.add(g);
+        }
+        return desired;
+    }
+    /** Bring a group into view. Cancels any warm timer for it. Idempotent. */
+    enter(group) {
+        this.warm.delete(group);
+        this.active.add(group);
+        return this.reconcile();
+    }
+    /**
+     * Leave a group. It does not drop immediately — it goes warm for
+     * `warmTtlMs` (unless pinned, in which case it stays via the pin).
+     * Re-entering within the window is free.
+     */
+    leave(group) {
+        this.active.delete(group);
+        if (!this.pinned.has(group) && !this.baseGroups.has(group)) {
+            this.warmGroup(group);
+        }
+        return this.reconcile();
+    }
+    /** Pin a group (active claim / prominence). Never warm or expires while pinned. */
+    pin(group) {
+        this.warm.delete(group);
+        this.pinned.add(group);
+        return this.reconcile();
+    }
+    /**
+     * Unpin a group. If it's not currently in view, it transitions to warm
+     * (so dropping a claim gets the same hysteresis as closing a tab) rather
+     * than dropping instantly.
+     */
+    unpin(group) {
+        this.pinned.delete(group);
+        if (!this.active.has(group) && !this.baseGroups.has(group)) {
+            this.warmGroup(group);
+        }
+        return this.reconcile();
+    }
+    /**
+     * Drop warm groups whose TTL has lapsed and reconcile. Auto-invoked on
+     * the sweep timer; call manually (with an injected `now`) in tests.
+     */
+    sweep() {
+        const now = this.now();
+        for (const [g, expiry] of this.warm) {
+            if (expiry <= now)
+                this.warm.delete(g);
+        }
+        return this.reconcile();
+    }
+    /** The set the manager believes is subscribed (post-confirmation). */
+    effectiveGroups() {
+        return [...this.lastSent];
+    }
+    /**
+     * Re-assert the full desired set against the transport, forgetting what
+     * was previously confirmed. Call after a reconnect: a fresh
+     * `SyncWebSocket` instance starts from the connect-time URL groups, so
+     * the manager's `lastSent` diff baseline is stale. Clearing it forces
+     * one `update_subscription` that re-establishes the live interest on the
+     * new socket.
+     *
+     * Resetting `lastSent` makes the next reconcile unconditionally re-push
+     * the current desired set (one `update_subscription` frame) so the fresh
+     * socket's server-side index matches local interest, even if warm/pinned
+     * groups drifted across the disconnect window. The connect-time URL
+     * already carries the last-acked set, so this is a correction frame, not
+     * the primary mechanism.
+     */
+    resync() {
+        this.lastSent = new Set();
+        return this.reconcile();
+    }
+    /** Stop the sweep timer. The connection is unaffected. */
+    dispose() {
+        this.cancelSweep?.();
+    }
+    /**
+     * Push the desired set to the transport iff it differs from the last
+     * confirmed set. Coalesces concurrent mutations: if a call is already in
+     * flight, mark dirty and let the in-flight loop pick up the newest state
+     * — so a burst of enter/leave collapses into the minimum number of
+     * `update_subscription` round-trips.
+     */
+    reconcile() {
+        if (this.inFlight) {
+            this.dirty = true;
+            return this.inFlight;
+        }
+        if (setsEqual(this.desiredGroups(), this.lastSent)) {
+            return Promise.resolve();
+        }
+        this.inFlight = (async () => {
+            try {
+                do {
+                    this.dirty = false;
+                    const target = this.desiredGroups();
+                    if (setsEqual(target, this.lastSent))
+                        break;
+                    try {
+                        const result = await this.transport.updateSubscription([...target]);
+                        this.lastSent = new Set(result.syncGroups);
+                    }
+                    catch {
+                        // Transport unavailable (offline / socket not open) or the
+                        // server rejected the set. Interest is SOFT state — never throw
+                        // out of enter/leave/sweep for an expected transient. Leave
+                        // `lastSent` unchanged so the diff persists; `resync()` on the
+                        // next `connected` re-pushes the then-current desired set,
+                        // which is what recovers "interest changed while offline."
+                        break;
+                    }
+                } while (this.dirty);
+            }
+            finally {
+                this.inFlight = null;
+            }
+        })();
+        return this.inFlight;
+    }
+}

package/dist/sync/BootstrapHelper.d.ts

@@ -100,7 +100,15 @@ export declare class BootstrapHelper {
      * @param lastSyncId - Optional: client's current lastSyncId for partial bootstrap
      * @returns Bootstrap data (either full snapshot or delta batch)
      */
-    fetchBootstrap(lastSyncId?: number): Promise<BootstrapData>;
+    fetchBootstrap(lastSyncId?: number, 
+    /**
+     * Per-call sync-group override for SCOPED hydrate-on-enter. When provided,
+     * the request uses THESE groups instead of `this.options.syncGroups`,
+     * WITHOUT mutating the shared options (so a concurrent full bootstrap is
+     * unaffected). Also bypasses the offline full-snapshot cache below, which
+     * holds the connection's full bootstrap and would be wrong for a subset.
+     */
+    syncGroupsOverride?: readonly string[]): Promise<BootstrapData>;
     /**
      * Fetch bootstrap with ETag, returning 304 hints
      */

package/dist/sync/BootstrapHelper.js

@@ -83,7 +83,15 @@ export class BootstrapHelper {
      * @param lastSyncId - Optional: client's current lastSyncId for partial bootstrap
      * @returns Bootstrap data (either full snapshot or delta batch)
      */
-    async fetchBootstrap(lastSyncId) {
+    async fetchBootstrap(lastSyncId, 
+    /**
+     * Per-call sync-group override for SCOPED hydrate-on-enter. When provided,
+     * the request uses THESE groups instead of `this.options.syncGroups`,
+     * WITHOUT mutating the shared options (so a concurrent full bootstrap is
+     * unaffected). Also bypasses the offline full-snapshot cache below, which
+     * holds the connection's full bootstrap and would be wrong for a subset.
+     */
+    syncGroupsOverride) {
         // organizationId omitted — server reads it from auth identity.
         // See `fetchBootstrapWithETag` for the full rationale.
         const params = new URLSearchParams();
@@ -91,8 +99,8 @@ export class BootstrapHelper {
         if (lastSyncId !== undefined && lastSyncId > 0) {
             params.append('lastSyncId', lastSyncId.toString());
         }
-        // Add sync groups
-        this.options.syncGroups.forEach((group) => {
+        // Add sync groups (per-call override wins over the configured set).
+        (syncGroupsOverride ?? this.options.syncGroups).forEach((group) => {
             params.append('syncGroups', group);
         });
         // Selective bootstrap: only request instant-strategy models.
@@ -102,8 +110,10 @@ export class BootstrapHelper {
             params.append('models', this.options.instantModels.join(','));
         }
         const url = `${this.options.baseUrl}/sync/bootstrap?${params.toString()}`;
-        // If offline, try cached bootstrap
-        if (typeof navigator !== 'undefined' && navigator && navigator.onLine === false) {
+        // If offline, try cached bootstrap. Skipped for a scoped override — the
+        // cache holds the FULL snapshot, which is not a valid answer to a subset
+        // request; a scoped hydrate just soft-fails offline and retries on re-enter.
+        if (!syncGroupsOverride && typeof navigator !== 'undefined' && navigator && navigator.onLine === false) {
             const cached = this.options.cacheScope
                 ? this.loadCachedBootstrap(this.options.cacheScope)
                 : null;

package/dist/sync/NetworkProbe.d.ts

@@ -29,7 +29,7 @@ import { type AuthTokenGetter } from '../auth/credentialSource.js';
 /**
  * The closed set of probe outcomes — one value carrying both reachability and
  * credential disposition, so the {@link ConnectionManager} branches on a single
- * exhaustive discriminant instead of reconstructing intent from a trio of
+ * exhaustive discriminant instead of reconstructing claim from a trio of
  * booleans. Mirrors the {@link RecoveryClass} taxonomy at the connectivity tier.
  */
 export declare const PROBE_OUTCOMES: readonly ["reachable", "unreachable", "session_expired", "credential_stale", "auth_blocked"];

package/dist/sync/NetworkProbe.js

@@ -31,7 +31,7 @@ import { withAuthHeaders } from '../auth/credentialSource.js';
 /**
  * The closed set of probe outcomes — one value carrying both reachability and
  * credential disposition, so the {@link ConnectionManager} branches on a single
- * exhaustive discriminant instead of reconstructing intent from a trio of
+ * exhaustive discriminant instead of reconstructing claim from a trio of
  * booleans. Mirrors the {@link RecoveryClass} taxonomy at the connectivity tier.
  */
 export const PROBE_OUTCOMES = [

package/dist/sync/SyncWebSocket.d.ts

@@ -10,6 +10,7 @@
 import { EventEmitter } from 'events';
 import type { MutationOperation } from '../interfaces/index.js';
 import type { ClientSyncDelta } from '../schema/sync-delta-wire.js';
+import type { ClaimError, ClaimRejection } from '../coordination/schema.js';
 import { type AuthTokenGetter } from '../auth/credentialSource.js';
 /**
  * The wire delta the client receives. Derived from the canonical
@@ -160,12 +161,19 @@ export interface PresenceUpdateEvent {
     /** Server-derived from the connection's userId prefix. Clients must
      *  not self-declare — server is the source of truth. */
     isAgent?: boolean;
+    /**
+     * Server-stamped canonical kind (`'user' | 'agent' | 'system'`). Additive:
+     * older servers omit it and readers fall back to the lossy `isAgent`
+     * boolean (which cannot express `'system'`). Typed `string` because it is
+     * raw wire input — normalize via `participantKindFromWire`.
+     */
+    participantKind?: string;
     timestamp?: number;
     /** Server stamps every presence frame with this participant's open
-     *  intent claims so peers see them without a separate channel. Wire
-     *  shape mirrors `apps/sync-server/src/hub/types.ts IntentClaim`. */
-    activeIntents?: Array<{
-        intentId: string;
+     *  claim claims so peers see them without a separate channel. Wire
+     *  shape mirrors `apps/sync-server/src/hub/types.ts Claim`. */
+    activeClaims?: Array<{
+        claimId: string;
         entityType: string;
         entityId: string;
         path?: string;
@@ -187,13 +195,7 @@ export interface PresenceUpdateEvent {
          * learn *how* it resolved before it drops from the active set.
          */
         status?: 'active' | 'committed' | 'expired' | 'canceled';
-        error?: {
-            code: string;
-            message?: string;
-            heldBy?: string;
-            heldByIntentId?: string;
-            heldByExpiresAt?: number;
-        };
+        error?: ClaimError;
     }>;
     localTime?: string;
     type?: string;
@@ -240,30 +242,30 @@ export interface CoreSyncEventMap {
         claimId: string;
     }];
     /**
-     * Server rejected an `intent_begin` because another participant
+     * Server rejected an `claim_begin` because another participant
      * already holds an open claim on the same target (cooperative
      * mutex enforced server-side). Surfaces to the participant-level
-     * IntentStream so the caller knows their announce was denied.
+     * ClaimStream so the caller knows their announce was denied.
      * Payload mirrors the wire frame's `payload`.
      */
-    intent_rejected: [Record<string, unknown>];
+    claim_rejected: [ClaimRejection];
     /**
-     * Fair-queue frames (opt-in `queue: true` on `intent_begin`). `intent_acquired`
-     * means the target was free and the lease is ours immediately; `intent_queued`
-     * means the claim is waiting in line (carries `position`); `intent_granted`
-     * means it reached the head and the lease is now ours; `intent_lost` means a
+     * Fair-queue frames (opt-in `queue: true` on `claim_begin`). `claim_acquired`
+     * means the target was free and the lease is ours immediately; `claim_queued`
+     * means the claim is waiting in line (carries `position`); `claim_granted`
+     * means it reached the head and the lease is now ours; `claim_lost` means a
      * held/granted claim was taken away (TTL lapse on disconnect, revoke).
      */
     /**
-     * Per-entity wait-queue snapshot: `{ target, queue: Intent[] }` with each
+     * Per-entity wait-queue snapshot: `{ target, queue: Claim[] }` with each
      * entry `status: 'queued'` + `position`. Broadcast to entity peers on every
      * queue mutation — powers the reactive `ablo.<model>.claim.queue({ id })` read.
      */
-    intent_queue: [Record<string, unknown>];
-    intent_acquired: [Record<string, unknown>];
-    intent_queued: [Record<string, unknown>];
-    intent_granted: [Record<string, unknown>];
-    intent_lost: [Record<string, unknown>];
+    claim_queue: [Record<string, unknown>];
+    claim_acquired: [Record<string, unknown>];
+    claim_queued: [Record<string, unknown>];
+    claim_granted: [Record<string, unknown>];
+    claim_lost: [Record<string, unknown>];
 }
 /**
  * Collaboration event — app-specific real-time events (selection, cursors, etc.)
@@ -370,6 +372,15 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * over a multiplexed connection.
      */
     private pendingClaims;
+    /**
+     * 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.)
+     */
+    private pendingSubscriptions;
     constructor(options: SyncWebSocketOptions);
     /**
      * Mark that a session error has been detected (e.g. 401 from HTTP bootstrap).
@@ -497,6 +508,29 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * we reject it locally — the user explicitly chose to release.
      */
     sendRelease(claimId: string): void;
+    /**
+     * 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: ReadonlyArray<string>, options?: {
+        timeoutMs?: number;
+    }): Promise<{
+        syncGroups: string[];
+    }>;
     /**
      * Compatibility setter for direct SyncWebSocket users. The SDK-owned
      * `Ablo()` path passes `getAuthToken`, so reconnect URL auth reads the
@@ -676,7 +710,7 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      *
      * 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 } }
      */
     private handlePresenceUpdate;
 }