@abloatai/humans 0.37.0

package/dist/local/sync/SubscriptionManager.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Decides which sync groups a connection subscribes to as the user navigates,
+ * and pushes each change through the {@link SubscriptionTransport}'s
+ * `update_subscription` call. It smooths two kinds of churn so that opening and
+ * closing entities does not turn into a storm of subscription changes.
+ *
+ * The first is hysteresis. Calling {@link SubscriptionManager.leave | leave}
+ * on a group does not unsubscribe it right away; the group stays subscribed for
+ * a grace period — its warm window — and drops only once that window lapses.
+ * Re-entering within the window costs nothing, since the group was never
+ * dropped, so rapid back-and-forth navigation becomes a cache hit rather than a
+ * repeated bootstrap.
+ *
+ * The second is prominence. A group that holds an active write claim is pinned
+ * (see {@link SubscriptionManager.pin | pin}) and stays subscribed regardless
+ * of navigation, so a row someone is actively editing never loses its live
+ * updates. The `baseGroups` are permanent scopes that are always subscribed.
+ *
+ * The manager recomputes the full desired set on every change, diffs it against
+ * the set the transport last confirmed, and calls `update_subscription` only
+ * when the set actually changes — so the smoothing suppresses network traffic
+ * rather than merely deferring it. It depends only on
+ * {@link SubscriptionTransport}, which {@link SyncWebSocket} satisfies. The
+ * clock and the sweep timer are injectable so the policy is deterministic under
+ * test.
+ */
+/** The single capability this manager needs from the connection. */
+export interface SubscriptionTransport {
+    /**
+     * Replaces the connection's read interest with the complete group set. This
+     * is a full replace, not an incremental add or remove. Resolves with the
+     * effective set the server applied, which the manager treats as authoritative
+     * for its next diff.
+     */
+    updateSubscription(syncGroups: readonly string[]): Promise<{
+        syncGroups: string[];
+    }>;
+}
+export interface SubscriptionManagerOptions {
+    /** Connection to drive. `SyncWebSocket` satisfies this structurally. */
+    transport: SubscriptionTransport;
+    /**
+     * Groups always present in the effective set (e.g. `org:<id>`,
+     * `user:<id>`). Never warm, never expired.
+     */
+    baseGroups?: readonly string[];
+    /**
+     * How long a `leave`-ed group stays subscribed before it actually drops.
+     * This is the hysteresis margin. Default 30s.
+     */
+    warmTtlMs?: number;
+    /**
+     * The maximum number of warm (left but still subscribed) groups. Under heavy
+     * navigation, warm groups would otherwise pile up until each one's window
+     * lapses, inflating the connection's subscription set. When the cap is
+     * exceeded, the least-recently-warmed group is dropped immediately instead of
+     * waiting for its window. Default 16.
+     */
+    maxWarm?: number;
+    /**
+     * Auto-run the warm-expiry sweep on this cadence. Set `0` to disable and
+     * drive {@link SubscriptionManager.sweep} yourself (tests do this).
+     * Default = `warmTtlMs` (checks about once per margin).
+     */
+    sweepIntervalMs?: number;
+    /** Clock injection point for deterministic tests. Default `Date.now`. */
+    now?: () => number;
+    /**
+     * Schedule a periodic callback. Default wraps `setInterval`/
+     * `clearInterval`. Injected so tests avoid real timers.
+     */
+    scheduler?: (fn: () => void, intervalMs: number) => () => void;
+}
+export declare class SubscriptionManager {
+    private readonly transport;
+    private baseGroups;
+    private readonly warmTtlMs;
+    private readonly maxWarm;
+    private readonly now;
+    /** Groups currently in view (open entities). */
+    private readonly active;
+    /** Claim-pinned groups — prominence; never warm/expire while pinned. */
+    private readonly pinned;
+    /** Left-but-warm groups → epoch-ms at which they drop. */
+    private readonly warm;
+    /** Last set the transport confirmed — the diff baseline. */
+    private lastSent;
+    /** Coalescing state so concurrent mutations collapse into one in-flight call. */
+    private inFlight;
+    private dirty;
+    /** Arms the sweep timer; `null` when sweeping is disabled. The timer is
+     *  armed lazily, on the first warm entry — sweeping exists only to expire
+     *  warm groups, so a manager that never warms one holds no timer (and a
+     *  client that is constructed but never navigates holds none either). */
+    private readonly armSweep;
+    private cancelSweep;
+    constructor(options: SubscriptionManagerOptions);
+    /**
+     * Seeds the permanent scopes once the host resolves identity. The manager
+     * can exist from client construction — before the connection's read scope
+     * is known — so the base set is seeded rather than fixed at construction.
+     */
+    setBaseGroups(groups: readonly string[]): void;
+    /**
+     * 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.
+     */
+    private warmGroup;
+    /** The effective read set: base ∪ active ∪ pinned ∪ (warm not yet expired). */
+    private desiredGroups;
+    /** Bring a group into view. Cancels any warm timer for it. Idempotent. */
+    enter(group: string): Promise<void>;
+    /**
+     * 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: string): Promise<void>;
+    /** Pin a group (active claim / prominence). Never warm or expires while pinned. */
+    pin(group: string): Promise<void>;
+    /**
+     * 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: string): Promise<void>;
+    /**
+     * Drop warm groups whose TTL has lapsed and reconcile. Auto-invoked on
+     * the sweep timer; call manually (with an injected `now`) in tests.
+     */
+    sweep(): Promise<void>;
+    /** The set the manager believes is subscribed (post-confirmation). */
+    effectiveGroups(): string[];
+    /**
+     * Re-asserts the full desired set against the transport, forgetting what was
+     * previously confirmed. Call this after a reconnect: a fresh
+     * {@link SyncWebSocket} starts from the sync groups named in the connect-time
+     * URL, so the manager's diff baseline no longer reflects the new socket.
+     * Clearing that baseline makes the next reconcile push one
+     * `update_subscription` frame that re-establishes the current interest —
+     * including any warm or pinned groups that drifted while the connection was
+     * down. The connect-time URL already carries the last-acknowledged set, so
+     * this is a correction, not the primary mechanism.
+     */
+    resync(): Promise<void>;
+    /** Stop the sweep timer. The connection is unaffected. */
+    dispose(): void;
+    /**
+     * 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.
+     */
+    private reconcile;
+}

package/dist/local/sync/SubscriptionManager.js

@@ -0,0 +1,243 @@
+/**
+ * Decides which sync groups a connection subscribes to as the user navigates,
+ * and pushes each change through the {@link SubscriptionTransport}'s
+ * `update_subscription` call. It smooths two kinds of churn so that opening and
+ * closing entities does not turn into a storm of subscription changes.
+ *
+ * The first is hysteresis. Calling {@link SubscriptionManager.leave | leave}
+ * on a group does not unsubscribe it right away; the group stays subscribed for
+ * a grace period — its warm window — and drops only once that window lapses.
+ * Re-entering within the window costs nothing, since the group was never
+ * dropped, so rapid back-and-forth navigation becomes a cache hit rather than a
+ * repeated bootstrap.
+ *
+ * The second is prominence. A group that holds an active write claim is pinned
+ * (see {@link SubscriptionManager.pin | pin}) and stays subscribed regardless
+ * of navigation, so a row someone is actively editing never loses its live
+ * updates. The `baseGroups` are permanent scopes that are always subscribed.
+ *
+ * The manager recomputes the full desired set on every change, diffs it against
+ * the set the transport last confirmed, and calls `update_subscription` only
+ * when the set actually changes — so the smoothing suppresses network traffic
+ * rather than merely deferring it. It depends only on
+ * {@link SubscriptionTransport}, which {@link SyncWebSocket} satisfies. The
+ * clock 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 SubscriptionManager {
+    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;
+    /** Arms the sweep timer; `null` when sweeping is disabled. The timer is
+     *  armed lazily, on the first warm entry — sweeping exists only to expire
+     *  warm groups, so a manager that never warms one holds no timer (and a
+     *  client that is constructed but never navigates holds none either). */
+    armSweep;
+    cancelSweep = null;
+    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.armSweep = () => {
+                this.cancelSweep = schedule(() => {
+                    void this.sweep();
+                }, sweepInterval);
+            };
+        }
+        else {
+            this.armSweep = null;
+        }
+    }
+    /**
+     * Seeds the permanent scopes once the host resolves identity. The manager
+     * can exist from client construction — before the connection's read scope
+     * is known — so the base set is seeded rather than fixed at construction.
+     */
+    setBaseGroups(groups) {
+        this.baseGroups = new Set(groups);
+    }
+    /**
+     * 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) {
+        if (this.armSweep && !this.cancelSweep)
+            this.armSweep();
+        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-asserts the full desired set against the transport, forgetting what was
+     * previously confirmed. Call this after a reconnect: a fresh
+     * {@link SyncWebSocket} starts from the sync groups named in the connect-time
+     * URL, so the manager's diff baseline no longer reflects the new socket.
+     * Clearing that baseline makes the next reconcile push one
+     * `update_subscription` frame that re-establishes the current interest —
+     * including any warm or pinned groups that drifted while the connection was
+     * down. The connect-time URL already carries the last-acknowledged set, so
+     * this is a correction, not the primary mechanism.
+     */
+    resync() {
+        this.lastSent = new Set();
+        return this.reconcile();
+    }
+    /** Stop the sweep timer. The connection is unaffected. */
+    dispose() {
+        this.cancelSweep?.();
+        this.cancelSweep = null;
+    }
+    /**
+     * 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, or socket not open) or the
+                        // server rejected the set. Read interest is soft state, so enter,
+                        // leave, and sweep never throw for an expected transient failure.
+                        // Leaving `lastSent` unchanged keeps the pending diff; `resync()`
+                        // on the next successful connect re-pushes the then-current desired
+                        // set, which recovers any interest that changed while offline.
+                        break;
+                    }
+                    // A concurrent reconcile() arriving during the await above sets
+                    // `this.dirty` back to true (the coalescing path near line 245).
+                    // TypeScript's intra-closure flow analysis can't see that cross-
+                    // invocation mutation and reads this as always-false, but the loop
+                    // is genuinely reentrant.
+                    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                } while (this.dirty);
+            }
+            finally {
+                this.inFlight = null;
+            }
+        })();
+        return this.inFlight;
+    }
+}

package/dist/local/sync/SyncWebSocket.d.ts

@@ -0,0 +1,173 @@
+/**
+ * The reactive engine's connection to the sync server: the settlement core's
+ * duplex transport ({@link WsTransport}, ADR 0016) plus everything that turns
+ * the stream into a local, watchable copy — wire-delta validation, the resume
+ * cursor and its persistence-gated ack discipline, incremental sync and
+ * bootstrap requests, the catch-up poll, and presence. The socket lifecycle,
+ * reconnect backoff, heartbeat, and the commit/claim/release/subscription
+ * frames all live in the transport; this subclass overrides its frame hooks
+ * and open/close hooks with the materialisation the transport deliberately
+ * does not do.
+ */
+import { type ClientSyncDelta } from '@abloatai/transaction/wire/delta';
+import { WsTransport, type WsTransportOptions, type EventMap, type DefaultCollaborationEvents } from '@abloatai/transaction/transport/wsTransport';
+export type { CommitAck } from './commitFrames.js';
+export type { SyncCapabilities, BootstrapHint, BootstrapDataEvent, PresenceUpdate, CoreSyncEventMap, DefaultCollaborationEvents, EventMap, SyncWebSocketEventMap, } from '@abloatai/transaction/transport/wsTransport';
+/**
+ * The wire delta the client receives. It is inferred from the canonical
+ * `clientSyncDeltaSchema` so the client and server share one contract rather
+ * than two hand-maintained definitions. The action vocabulary
+ * (`I`/`U`/`D`/`A`/`V`/`C`/`G`/`S`) and the client-only extras (`metadata`,
+ * `clientMutationId`, and the deprecated flat `createdBy`) live in that schema;
+ * see its own documentation for the full field reference.
+ */
+export type SyncDelta = ClientSyncDelta;
+/**
+ * Payload for an older actionType `'G'` delta. It carries both the added and
+ * removed sync groups in one delta and forces a full re-bootstrap.
+ */
+export interface SyncGroupChangePayload {
+    removedGroups: string[];
+    addedGroups: string[];
+}
+/**
+ * Payload for an incremental actionType `'G'` delta. It signals that the
+ * recipient has joined a single sync group; the following `'C'` (covering)
+ * deltas deliver the newly visible entities. No re-bootstrap is required.
+ */
+export interface GroupAddedPayload {
+    group: string;
+    userId: string;
+}
+/**
+ * Payload for an actionType `'S'` delta. It signals that the recipient has lost
+ * access to a sync group; the client purges the affected local entities and
+ * updates its subscription metadata.
+ */
+export interface GroupRemovedPayload {
+    group: string;
+    userId: string;
+}
+/**
+ * The reactive engine's connection options — the transport's options under
+ * the name consumers have always imported.
+ */
+export type SyncWebSocketOptions = WsTransportOptions;
+export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboration> = DefaultCollaborationEvents> extends WsTransport<TCollaboration> {
+    /** Periodic catchup interval — polls for missed deltas every 30s while connected */
+    private catchupInterval;
+    /**
+     * Sync-position state: the lastSyncId watermark, version vector, and server
+     * cursor. The advance discipline is documented at `sendAck` and `handleDelta`;
+     * the state itself lives in {@link SyncCursor}.
+     */
+    private readonly cursor;
+    constructor(options: SyncWebSocketOptions);
+    /** The persisted resume position, sent on the upgrade URL. */
+    protected resumeCursor(): string;
+    /**
+     * The open ritual, run by the transport between its `connected` emit and the
+     * heartbeat start: announce presence, tell the server where we left off,
+     * request the deltas we missed, and start the catch-up poll.
+     */
+    protected onOpened(): void;
+    /** The transport clears its socket reference before this runs. */
+    protected onClosed(): void;
+    /**
+     * Validates and normalizes a wire delta at the receive boundary — the single
+     * seam every inbound delta (a `delta` frame, a batch element, a `sync_response`
+     * replay, or the older bare frame) passes through before it is emitted,
+     * persisted, or allowed to advance any watermark.
+     *
+     * Normalization keeps already-deployed servers compatible:
+     *  - `id`: the contract says `number`, but some servers have sent the raw
+     *    Postgres BIGINT serialization — a string — and every downstream watermark
+     *    gate treats a string as invalid, so acks are withheld, the resume cursor
+     *    never advances, and every reconnect replays from zero. Coerce it once here.
+     *  - `transactionId` / `createdBy`: the server projection sends these as
+     *    nullable (and `createdBy` as a nested reference); the client contract
+     *    types them as optional strings and never reads them, so normalize them to
+     *    absent rather than reject every real server delta.
+     *
+     * Validation runs `clientSyncDeltaSchema.safeParse`, the canonical wire
+     * contract. A frame that fails is dropped (returns `null`) with a debug log
+     * and an observability breadcrumb; it is never applied. There is one parse per
+     * delta — callers must not re-parse.
+     */
+    private normalizeWireDelta;
+    /**
+     * Handle incoming sync delta (untrusted wire input — validated and
+     * normalized by {@link normalizeWireDelta}; malformed deltas are dropped).
+     */
+    protected handleDelta(rawDelta: unknown): void;
+    /**
+     * Acknowledges received deltas up to the given syncId. This is the only place
+     * `this.cursor.lastSyncId` moves forward for live deltas. The store calls it
+     * with its persisted-syncId watermark — that is, only after the deltas have
+     * committed to local storage. Advancing the cursor here, rather than at
+     * receipt in `handleDelta` or `handleSyncResponse`, keeps the cursor from
+     * getting ahead of the persisted view, so reconnect and catch-up requests
+     * cannot skip un-persisted deltas.
+     */
+    private sendAck;
+    /**
+     * Public wrapper for sending ack from outside the class
+     */
+    acknowledge(syncId: number): void;
+    /**
+     * Send presence update to server.
+     * Use this for:
+     * - Updating timezone (improves localTime accuracy shown to other users)
+     * - Manual status changes (away, custom status)
+     *
+     * Note: "online" status is automatically set by server on WebSocket connect,
+     * and "offline" is set on disconnect. You don't need to call this for basic online/offline.
+     *
+     * @param status - "online", "away", or custom status string
+     * @param customStatus - Optional custom status message
+     */
+    sendPresenceUpdate(status?: 'online' | 'away' | 'offline', customStatus?: string): void;
+    /**
+     * Stop the periodic catchup interval
+     */
+    private stopCatchupInterval;
+    /**
+     * Disconnect from WebSocket
+     */
+    disconnect(): void;
+    /**
+     * Update last sync ID (for persistence)
+     */
+    setLastSyncId(syncId: number): void;
+    /**
+     * Update sync cursor (for incremental sync)
+     */
+    setSyncCursor(cursor: string | null): void;
+    /**
+     * Get current sync cursor
+     */
+    getSyncCursor(): string | null;
+    /**
+     * Get the highest syncId seen this session (for persistence on clean shutdown)
+     */
+    getLastSyncId(): number;
+    /**
+     * Requests an incremental sync from the server, starting at the current cursor.
+     */
+    requestIncrementalSync(): Promise<void>;
+    /**
+     * Request bootstrap for specific entities
+     */
+    requestBootstrap(entities?: string[]): Promise<void>;
+    /**
+     * Handle sync response from server. Untrusted wire input — the envelope
+     * fields are narrowed defensively and every delta is validated through
+     * {@link normalizeWireDelta} (exactly once each; malformed ones drop out
+     * of the batch).
+     */
+    protected handleSyncResponse(rawPayload: unknown): void;
+    /**
+     * Handle bootstrap response from server
+     */
+    protected handleBootstrapResponse(payload: unknown): void;
+}