@abloatai/ablo 0.35.0 → 0.37.0

package/dist/sync/SubscriptionManager.d.ts

@@ -1,159 +0,0 @@
-/**
- * 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/sync/SubscriptionManager.js

@@ -1,243 +0,0 @@
-/**
- * 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/sync/SyncWebSocket.d.ts

@@ -1,173 +0,0 @@
-/**
- * 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 '../transaction/wire/delta.js';
-import { WsTransport, type WsTransportOptions, type EventMap, type DefaultCollaborationEvents } from '../transaction/transport/wsTransport.js';
-export type { CommitAck } from './commitFrames.js';
-export type { SyncCapabilities, BootstrapHint, BootstrapDataEvent, PresenceUpdate, CoreSyncEventMap, DefaultCollaborationEvents, EventMap, SyncWebSocketEventMap, } from '../transaction/transport/wsTransport.js';
-/**
- * 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;
-}