@abloatai/ablo 0.24.0 → 0.26.0

package/dist/sync/heartbeat.js

@@ -0,0 +1,91 @@
+/**
+ * Application-level heartbeat for the sync WebSocket.
+ *
+ * The browser WebSocket API hides RFC 6455 protocol-level ping/pong from
+ * JavaScript, so the server's `ws.ping()` keepalive can't be observed by
+ * client code — meaning the client cannot tell a healthy idle connection
+ * apart from a "zombie" socket where TCP silently broke (laptop sleep,
+ * NAT timeout, mobile handoff). We send an application-level
+ * `{ type: 'ping' }` every 30s and force-close the socket if no inbound
+ * traffic arrives within 10s. ANY inbound message counts as
+ * proof-of-life — the explicit `pong` is just a guarantee that something
+ * will arrive even on an idle stream.
+ */
+import { getContext } from '../context.js';
+import { PING_INTERVAL_MS } from '../wire/protocol.js';
+/**
+ * One cadence for both sides: the SDK's application-level ping runs at the
+ * same `PING_INTERVAL_MS` as the server's RFC 6455 keepalive (and the claim
+ * lease window is derived from it — see `wire/protocol.ts`).
+ */
+export const HEARTBEAT_INTERVAL_MS = PING_INTERVAL_MS;
+export const HEARTBEAT_TIMEOUT_MS = 10_000;
+/**
+ * Every `HEARTBEAT_INTERVAL_MS` while `OPEN`, send `{ type: 'ping' }`
+ * and arm a `HEARTBEAT_TIMEOUT_MS` watchdog. Any inbound frame (the
+ * owner's `onmessage` calls {@link clearHeartbeatTimeout}) clears the
+ * watchdog. If the watchdog fires, we treat the connection as zombie
+ * and force-close it — `onclose` then triggers the existing reconnect
+ * path.
+ *
+ * Why both sides need this:
+ *  - The server sends RFC 6455 protocol pings via `ws.ping()` every
+ *    30s. Browsers auto-respond with a pong but DO NOT expose either
+ *    frame to JavaScript, so the client is blind to its own keepalive.
+ *  - On a half-open TCP (laptop wake, NAT timeout, mobile handoff)
+ *    the browser may keep `readyState === OPEN` for minutes before
+ *    the OS surfaces the broken connection. App-level traffic is
+ *    the only signal we can observe.
+ */
+export class HeartbeatController {
+    transport;
+    heartbeatTimer = null;
+    heartbeatTimeoutTimer = null;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    start() {
+        this.stop();
+        this.heartbeatTimer = setInterval(() => {
+            if (!this.transport.isSocketOpen())
+                return;
+            // Send the ping. If `send` throws, the socket is already dead —
+            // force-close so onclose triggers the reconnect cycle.
+            try {
+                this.transport.sendPing();
+            }
+            catch (err) {
+                getContext().observability.captureWebSocketError({
+                    context: 'heartbeat-send-failed',
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                this.transport.forceClose('heartbeat-send-failed');
+                return;
+            }
+            // Arm the timeout. ANY inbound message clears it (see the owner's
+            // onmessage). We don't require an explicit `pong` — a delta or any
+            // other frame is equally good proof-of-life.
+            if (this.heartbeatTimeoutTimer)
+                clearTimeout(this.heartbeatTimeoutTimer);
+            this.heartbeatTimeoutTimer = setTimeout(() => {
+                getContext().observability.captureWebSocketError({
+                    context: 'heartbeat-timeout',
+                });
+                this.transport.forceClose('heartbeat-timeout');
+            }, HEARTBEAT_TIMEOUT_MS);
+        }, HEARTBEAT_INTERVAL_MS);
+    }
+    stop() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        this.clearHeartbeatTimeout();
+    }
+    clearHeartbeatTimeout() {
+        if (this.heartbeatTimeoutTimer) {
+            clearTimeout(this.heartbeatTimeoutTimer);
+            this.heartbeatTimeoutTimer = null;
+        }
+    }
+}

package/dist/sync/participants.d.ts

@@ -1,5 +1,5 @@
 import type { SyncWebSocket } from './SyncWebSocket.js';
-import type { Schema, SchemaRecord } from '../schema/schema.js';
+import type { Schema } from '../schema/schema.js';
 import type { Claim, Activity, ClaimTarget, ClaimStream, Peer, PresenceStream, PresenceTarget } from '../types/streams.js';
 import type { AttachableClaimStream } from './createClaimStream.js';
 /**
@@ -46,7 +46,7 @@ export interface ParticipantJoinOptions {
 export interface ScopedPresence {
     readonly self: Peer;
     readonly focus: ClaimTarget | null;
-    readonly others: ReadonlyArray<Peer>;
+    readonly others: readonly Peer[];
     update(activity: Activity): void;
     reading(detail?: string): void;
     reading(target: PresenceTarget, detail?: string): void;
@@ -68,7 +68,7 @@ export interface ScopedClaimOptions {
 }
 export interface ScopedClaims {
     readonly focus: ClaimTarget | null;
-    readonly others: ReadonlyArray<Claim>;
+    readonly others: readonly Claim[];
     /**
      * Claim an exclusive claim on the participant's focus target (or
      * an explicit override via `opts.target`). Single verb — the old
@@ -91,8 +91,8 @@ export interface JoinedParticipant {
     readonly syncGroups: readonly string[];
     readonly presence: ScopedPresence;
     readonly claims: ScopedClaims;
-    readonly peers: ReadonlyArray<Peer>;
-    readonly activeClaims: ReadonlyArray<Claim>;
+    readonly peers: readonly Peer[];
+    readonly activeClaims: readonly Claim[];
     focus(target: PresenceTarget, options?: ParticipantFocusOptions): JoinedParticipant;
     leave(): void;
     [Symbol.asyncDispose](): Promise<void>;
@@ -106,10 +106,10 @@ export interface ParticipantManagerConfig {
     readonly getTransport: () => SyncWebSocket | null;
     readonly presence: PresenceStream;
     readonly claims: AttachableClaimStream;
-    readonly schema?: Schema<SchemaRecord>;
+    readonly schema?: Schema;
 }
 export declare function createParticipantManager(config: ParticipantManagerConfig): ParticipantManager;
-export declare function resolveParticipantSyncGroups(scope: ParticipantScope | undefined, schema?: Schema<SchemaRecord>): string[];
-export declare function syncGroupFromEntityRef(ref: ClaimTarget, schema?: Schema<SchemaRecord>): string;
+export declare function resolveParticipantSyncGroups(scope: ParticipantScope | undefined, schema?: Schema): string[];
+export declare function syncGroupFromEntityRef(ref: ClaimTarget, schema?: Schema): string;
 export declare function parseParticipantTtlSeconds(value: number | string | null | undefined): number | undefined;
 export declare function createParticipantClaimId(): string;

package/dist/sync/syncCursor.d.ts

@@ -0,0 +1,44 @@
+/**
+ * SyncCursor — the sync-position state of one SyncWebSocket session.
+ *
+ * Owns the two pieces of resume state the transport carries between
+ * connects: the `lastSyncId` watermark and the opaque server cursor.
+ * Extracted from SyncWebSocket so cursor bookkeeping is one cohesive
+ * leaf instead of fields + accessors spread through the transport
+ * class. The advance DISCIPLINE (only move `lastSyncId` on a
+ * persistence-gated ack) is documented at the call sites in
+ * SyncWebSocket (`sendAck` / `handleDelta`).
+ *
+ * (The per-entity version vector that used to live here was a Go-era
+ * ghost — zero decision reads client- or server-side; one total-ordered
+ * log per plane makes the scalar `sync_id` watermark the causality
+ * token. Removed in W4a.)
+ */
+export declare class SyncCursor {
+    lastSyncId: number;
+    syncCursor: string | null;
+    constructor(lastSyncId: number);
+    /**
+     * Advance the local cursor for an ack — this is what
+     * `requestIncrementalSync` and the connect handshake will send next,
+     * and what `getLastSyncId()` reports for clean-shutdown persistence.
+     * Monotonic: a stale (lower) ack never moves the cursor backward.
+     */
+    ackAdvance(syncId: number): 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;
+}

package/dist/sync/syncCursor.js

@@ -0,0 +1,59 @@
+/**
+ * SyncCursor — the sync-position state of one SyncWebSocket session.
+ *
+ * Owns the two pieces of resume state the transport carries between
+ * connects: the `lastSyncId` watermark and the opaque server cursor.
+ * Extracted from SyncWebSocket so cursor bookkeeping is one cohesive
+ * leaf instead of fields + accessors spread through the transport
+ * class. The advance DISCIPLINE (only move `lastSyncId` on a
+ * persistence-gated ack) is documented at the call sites in
+ * SyncWebSocket (`sendAck` / `handleDelta`).
+ *
+ * (The per-entity version vector that used to live here was a Go-era
+ * ghost — zero decision reads client- or server-side; one total-ordered
+ * log per plane makes the scalar `sync_id` watermark the causality
+ * token. Removed in W4a.)
+ */
+export class SyncCursor {
+    lastSyncId;
+    syncCursor;
+    constructor(lastSyncId) {
+        this.lastSyncId = lastSyncId;
+        this.syncCursor = null;
+    }
+    /**
+     * Advance the local cursor for an ack — this is what
+     * `requestIncrementalSync` and the connect handshake will send next,
+     * and what `getLastSyncId()` reports for clean-shutdown persistence.
+     * Monotonic: a stale (lower) ack never moves the cursor backward.
+     */
+    ackAdvance(syncId) {
+        if (syncId > this.lastSyncId) {
+            this.lastSyncId = syncId;
+        }
+    }
+    /**
+     * Update last sync ID (for persistence)
+     */
+    setLastSyncId(syncId) {
+        this.lastSyncId = syncId;
+    }
+    /**
+     * Update sync cursor (for incremental sync)
+     */
+    setSyncCursor(cursor) {
+        this.syncCursor = cursor;
+    }
+    /**
+     * Get current sync cursor
+     */
+    getSyncCursor() {
+        return this.syncCursor;
+    }
+    /**
+     * Get the highest syncId seen this session (for persistence on clean shutdown)
+     */
+    getLastSyncId() {
+        return this.lastSyncId || 0;
+    }
+}

package/dist/sync/syncPlan.d.ts

@@ -0,0 +1,62 @@
+/**
+ * syncPlan — schema → sync-plan derivation.
+ *
+ * Pure leaf extracted from BaseSyncedStore.ts: walks a `Schema` and derives
+ * the two declarative arrays the store's constructor consumes (FK indexes,
+ * enrichment plan). No class state, no side effects — `BaseSyncedStore`
+ * re-exports everything here so importers are unchanged.
+ */
+import type { Schema } from '../schema/schema.js';
+/** A foreign-key index to register on the ObjectPool at construction time. */
+export interface ForeignKeyIndexSpec {
+    /**
+     * The child model name (where the FK field lives) — this is the type
+     * that will be passed to `pool.registerForeignKey(modelName, fieldName)`
+     * and later to `pool.getByForeignKey(modelName, fieldName, value)`.
+     *
+     * Use the wire `__typename` casing (e.g., `'SlideLayer'`, not
+     * `'slideLayer'`) — that's the value `createFromData` stamps onto
+     * models and the pool indexes by.
+     */
+    readonly modelName: string;
+    /** The FK field name on the child model, e.g. `'slideId'`. */
+    readonly fieldName: string;
+}
+/**
+ * A declarative enrichment rule for the delta-apply path.
+ *
+ * When a delta for `modelName` arrives, after the model is constructed
+ * the base store reads `data[foreignKey]` from the payload, looks up
+ * the matching parent in the ObjectPool, and attaches it as
+ * `data[relationKey]`. Best-effort: if the parent isn't yet in the
+ * pool (e.g., arrived later in the same bootstrap batch), enrichment
+ * silently no-ops.
+ *
+ * Replaces the previous pattern of overriding `enrichRelations` on a
+ * subclass to hardcode per-model enrichment logic.
+ */
+export interface EnrichmentPlanEntry {
+    /** The child model whose incoming deltas should be enriched. */
+    readonly modelName: string;
+    /** The FK field on the child that points at the parent's id. */
+    readonly foreignKey: string;
+    /** The property name under which to attach the parent model. */
+    readonly relationKey: string;
+}
+/**
+ * Walk a schema and derive the two sync-plan arrays consumed by
+ * `BaseSyncedStore`'s constructor: FK indexes to register on the pool,
+ * and the enrichment plan.
+ *
+ * FK indexes and enrichment entries are pulled from each `belongsTo`
+ * relation where `options.index` / `options.enrich` is set. Relations
+ * without those options are skipped — this is an opt-in mechanism so
+ * adding a `belongsTo` never silently changes delta or lookup semantics.
+ *
+ * Pure function: takes a Schema, returns two arrays. No side effects,
+ * no class state. Called once at construction time from `BaseSyncedStore`.
+ */
+export declare function deriveSyncPlanFromSchema(schema: Schema): {
+    enrichmentPlan: EnrichmentPlanEntry[];
+    foreignKeyIndexes: ForeignKeyIndexSpec[];
+};

package/dist/sync/syncPlan.js

@@ -0,0 +1,51 @@
+/**
+ * syncPlan — schema → sync-plan derivation.
+ *
+ * Pure leaf extracted from BaseSyncedStore.ts: walks a `Schema` and derives
+ * the two declarative arrays the store's constructor consumes (FK indexes,
+ * enrichment plan). No class state, no side effects — `BaseSyncedStore`
+ * re-exports everything here so importers are unchanged.
+ */
+/**
+ * Walk a schema and derive the two sync-plan arrays consumed by
+ * `BaseSyncedStore`'s constructor: FK indexes to register on the pool,
+ * and the enrichment plan.
+ *
+ * FK indexes and enrichment entries are pulled from each `belongsTo`
+ * relation where `options.index` / `options.enrich` is set. Relations
+ * without those options are skipped — this is an opt-in mechanism so
+ * adding a `belongsTo` never silently changes delta or lookup semantics.
+ *
+ * Pure function: takes a Schema, returns two arrays. No side effects,
+ * no class state. Called once at construction time from `BaseSyncedStore`.
+ */
+export function deriveSyncPlanFromSchema(schema) {
+    const enrichmentPlan = [];
+    const foreignKeyIndexes = [];
+    for (const [modelName, def] of Object.entries(schema.models)) {
+        const typename = def.typename ?? modelName;
+        for (const [relationKey, rel] of Object.entries(def.relations)) {
+            if (rel.type === 'belongsTo') {
+                if (rel.options?.index) {
+                    foreignKeyIndexes.push({ modelName: typename, fieldName: rel.foreignKey });
+                }
+                if (rel.options?.enrich) {
+                    enrichmentPlan.push({
+                        modelName: typename,
+                        foreignKey: rel.foreignKey,
+                        relationKey,
+                    });
+                }
+            }
+            else if (rel.type === 'hasMany' || rel.type === 'hasOne') {
+                // hasMany/hasOne: the FK lives on the TARGET model, not the current model.
+                // Register the FK index on the target so getByForeignKey works.
+                // Target typename is resolved at registration time from the schema.
+                const targetDef = schema.models[rel.target];
+                const targetTypename = targetDef?.typename ?? rel.target;
+                foreignKeyIndexes.push({ modelName: targetTypename, fieldName: rel.foreignKey });
+            }
+        }
+    }
+    return { enrichmentPlan, foreignKeyIndexes };
+}

package/dist/sync/wsFrameHandlers.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Inbound frame dispatch for the sync WebSocket.
+ *
+ * Replaces the monolithic frame `switch` that used to live inside
+ * `SyncWebSocket.setupEventHandlers` with a frame-type → handler table of
+ * functions over a minimal {@link WsSession} interface — only the members
+ * the handlers actually touch, never the transport class itself (no
+ * import cycle). The host's `onmessage` stays responsible for JSON
+ * parsing, heartbeat proof-of-life, and the outer try/catch; everything
+ * after that funnels through {@link dispatchWsFrame}.
+ */
+import { type CommitAck } from './commitFrames.js';
+/**
+ * In-flight `commit` request record, keyed by clientTxId in the session.
+ * Resolved when a matching `mutation_result` frame arrives from the
+ * server, or rejected on timeout / disconnect.
+ */
+export interface PendingCommit {
+    resolve: (value: CommitAck) => void;
+    reject: (err: Error) => void;
+    timeout: ReturnType<typeof setTimeout>;
+}
+/**
+ * In-flight `claim` request record, keyed by claimId. Resolved when the
+ * matching `claim_ack` arrives, or rejected on timeout/disconnect.
+ */
+export interface PendingClaim {
+    resolve: (value: {
+        syncGroups: string[];
+        ttlSeconds?: number;
+    }) => void;
+    reject: (err: Error) => void;
+    timeout: ReturnType<typeof setTimeout>;
+}
+/**
+ * In-flight `update_subscription` record awaiting `subscription_ack`.
+ * FIFO-matched (no correlation id on the wire) — see the session field
+ * doc on SyncWebSocket.pendingSubscriptions.
+ */
+export interface PendingSubscription {
+    resolve: (value: {
+        syncGroups: string[];
+    }) => void;
+    reject: (err: Error) => void;
+    timeout: ReturnType<typeof setTimeout>;
+}
+/**
+ * Parsed inbound wire frame (the raw `JSON.parse` result). Untrusted
+ * data — every payload is loose and each handler narrows defensively,
+ * the same posture the inline switch had.
+ */
+export interface WsInboundFrame {
+    type?: string;
+    payload?: unknown;
+    /** Legacy bare-delta frames carry delta fields at the top level. */
+    actionType?: unknown;
+    modelName?: unknown;
+    [key: string]: unknown;
+}
+/** Narrow arbitrary wire data to a plain string-keyed record. */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Envelope guard for the raw `JSON.parse` result of an inbound WS message.
+ * A frame is any plain object whose `type`, when present, is a string —
+ * payload-level validation stays with each handler (deltas go through the
+ * canonical `clientSyncDeltaSchema` at the `normalizeWireDelta` seam).
+ */
+export declare function isWsInboundFrame(value: unknown): value is WsInboundFrame;
+/**
+ * The slice of SyncWebSocket the frame handlers operate on. The host
+ * builds one adapter object over its private state; closures read live
+ * fields so host-side reassignment (e.g. the pendingSubscriptions reset
+ * on close) can't strand the handlers on stale references.
+ */
+export interface WsSession {
+    /** EventEmitter surface — handlers emit the typed transport events. */
+    emit(event: string, ...args: unknown[]): boolean;
+    /** In-flight commit acks keyed by clientTxId. */
+    pendingMutations: Map<string, PendingCommit>;
+    /** In-flight claim acks keyed by claimId. */
+    pendingClaims: Map<string, PendingClaim>;
+    /** FIFO pop of the oldest in-flight `update_subscription` request. */
+    shiftPendingSubscription(): PendingSubscription | undefined;
+    /** Connection options subset the handlers write back (acked sync groups). */
+    options: {
+        syncGroups: string[];
+    };
+    /** Registered collaboration event keys (colon format). */
+    collaborationEventTypes: ReadonlySet<string>;
+    /**
+     * Receive-boundary delta processing. Takes UNTRUSTED wire data — the
+     * host validates against the canonical `clientSyncDeltaSchema` (and
+     * drops malformed deltas) at its `normalizeWireDelta` seam, so the
+     * handlers here never need to cast.
+     */
+    handleDelta(delta: unknown): void;
+    handleSyncResponse(payload: unknown): void;
+    handleBootstrapResponse(payload: unknown): void;
+    handlePresenceUpdate(message: {
+        payload?: unknown;
+        [k: string]: unknown;
+    }): void;
+}
+export type WsFrameHandler = (session: WsSession, message: WsInboundFrame) => void;
+/**
+ * Frame-type → handler table. Every named server frame the SDK
+ * understands dispatches through here; anything else falls to the
+ * collaboration-event / unknown-type path in {@link dispatchWsFrame}.
+ */
+export declare const wsFrameHandlers: Record<string, WsFrameHandler>;
+/**
+ * Route one parsed inbound frame to its handler. Mirrors the original
+ * inline switch exactly: keepalives are ignored, a missing `type` is
+ * the legacy bare-delta form, unknown types fall through to the
+ * collaboration-event map (underscore wire format → colon event key).
+ */
+export declare function dispatchWsFrame(session: WsSession, message: WsInboundFrame): void;