@abloatai/ablo 0.26.0 → 0.27.0

package/dist/sync/createClaimStream.js

@@ -1,34 +1,42 @@
 /**
- * Transport-driven ClaimStream factory.
+ * Creates a {@link ClaimStream} over a live sync connection. A claim is a
+ * short-lived, advisory lease a participant takes on an entity (or a field of
+ * one) to signal "I'm working on this"; the stream lets you take claims, see
+ * everyone else's, and watch the wait queue when a claim is contended.
  *
- * Mirrors `createPresenceStream` — built directly on `SyncWebSocket`,
- * no SyncAgent wrapper. Claims derive their `others` view from the
- * same `presence_update` frames the presence stream consumes (the
- * Hub piggybacks `activeClaims` on every presence frame). Outbound
- * announce/revoke ride the same socket via `claim_begin` /
+ * The stream is built directly on the sync WebSocket and shares that one
+ * connection. It learns about other participants' claims from the same
+ * `presence_update` frames the {@link createPresenceStream} presence stream
+ * consumes — the server piggybacks each participant's `activeClaims` on every
+ * presence frame — and sends its own claims as `claim_begin` and
  * `claim_abandon` frames.
  *
- * Wire contract (apps/sync-server/src/hub/types.ts):
- *   • Outbound: `{ type: 'claim_begin', payload: { claimId,
- *       entityType, entityId, reason, field?, estimatedMs? } }`
- *   • Outbound: `{ type: 'claim_abandon', payload: { claimId,
- *       entityType?, entityId? } }`
- *   • Inbound (via presence): `event.activeClaims: Claim[]`
- *     stamped with `declaredAt`, `expiresAt`.
- *   • Inbound: `claim_rejected` event with conflict metadata.
- *
- * After the dual-engine collapse (step #36), this is the only
- * ClaimStream factory in the SDK; the older compatibility path
- * deletes.
+ * Wire frames:
+ *   • Outbound `claim_begin` — announce a claim: `{ claimId, entityType,
+ *       entityId, reason, field?, estimatedMs? }`.
+ *   • Outbound `claim_abandon` — release it: `{ claimId, entityType?,
+ *       entityId? }`.
+ *   • Inbound, via presence — `event.activeClaims`, each stamped with
+ *       `declaredAt` and `expiresAt`.
+ *   • Inbound `claim_rejected` — the server refused the claim, with conflict
+ *       metadata.
  */
 import { asyncIteratorFrom } from '../utils/asyncIterator.js';
 import { toMs } from '../utils/duration.js';
-import { descriptionFromMeta, participantKindFromWire, } from '../coordination/schema.js';
+import { claimHeartbeatAckPayloadSchema, descriptionFromMeta, participantKindFromWire, } from '../coordination/schema.js';
+import { AbloClaimedError, AbloConnectionError } from '../errors.js';
+import { resolveHeartbeatOptions } from '../client/claimHeartbeatLoop.js';
 import { getContext } from '../context.js';
 /** Readable target for the coordination trace: `documents:abc` / `documents:abc.title`. */
 function claimLabel(type, id, field) {
     return field ? `${type}:${id}.${field}` : `${type}:${id}`;
 }
+/**
+ * How long a heartbeat waits for its `claim_heartbeat_ack` before giving up
+ * as transient (the auto-heartbeat loop's next tick retries). Comfortably
+ * above a round trip, comfortably below the ttl/3 beat cadence.
+ */
+const HEARTBEAT_ACK_TIMEOUT_MS = 10_000;
 export function createClaimStream(config, transport = null) {
     const { participantId } = config;
     // ── State: others' open claims, keyed by claimId ───────────────
@@ -49,6 +57,16 @@ export function createClaimStream(config, transport = null) {
     const listeners = new Set();
     const rejectionListeners = new Set();
     const lostListeners = new Set();
+    // ── State: in-flight heartbeats awaiting their ack, keyed by claimId ──
+    const pendingHeartbeats = new Map();
+    const settleHeartbeat = (claimId, settle) => {
+        const pending = pendingHeartbeats.get(claimId);
+        if (!pending)
+            return;
+        pendingHeartbeats.delete(claimId);
+        clearTimeout(pending.timer);
+        settle(pending);
+    };
     const notifyListeners = () => {
         claimsSnapshot = Object.freeze(Array.from(activeByClaimId.values()));
         for (const l of listeners) {
@@ -151,8 +169,9 @@ export function createClaimStream(config, transport = null) {
                 }
             }
         }));
-        // (2a) Server-side LOSS frames — you held it, then lost it (preempted /
-        //      expired). Distinct from a rejection (a claim the server refused).
+        // (2a) Server-side loss frames — you held the claim, then lost it
+        //      (preempted or expired). Distinct from a rejection, which is a claim
+        //      the server refused.
         unsubs.push(t.subscribe('claim_lost', (payload) => {
             const lost = payload;
             if (!lost.claimId)
@@ -186,7 +205,7 @@ export function createClaimStream(config, transport = null) {
                 queueByEntity.delete(key);
             else
                 queueByEntity.set(key, Object.freeze([...line]));
-            // If WE are in this line, trace our position (the "agent queued behind a
+            // If we are in this line, trace our position (the "agent queued behind a
             // claim" moment) — once per position change, so advancing is visible.
             const ourIndex = line.findIndex((c) => ownClaims.has(c.id));
             const ourClaim = ourIndex >= 0 ? line[ourIndex] : undefined;
@@ -199,6 +218,30 @@ export function createClaimStream(config, transport = null) {
             }
             notifyListeners();
         }));
+        // (2c) Heartbeat replies — correlate back to the awaiting beat by
+        //      claimId. `held` resolves with the extended expiry; `queued` and
+        //      `lost` reject with a typed claimed error, because a heartbeat on
+        //      a handle we thought we held coming back as anything but `held`
+        //      means the lease is no longer ours.
+        unsubs.push(t.subscribe('claim_heartbeat_ack', (payload) => {
+            const parsed = claimHeartbeatAckPayloadSchema.safeParse(payload);
+            if (!parsed.success)
+                return;
+            const ack = parsed.data;
+            settleHeartbeat(ack.claimId, ({ resolve, reject }) => {
+                if (ack.status === 'held' && ack.expiresAt !== undefined) {
+                    resolve({
+                        expiresAt: ack.expiresAt,
+                        ...(ack.queueDepth !== undefined
+                            ? { queueDepth: ack.queueDepth }
+                            : {}),
+                    });
+                    return;
+                }
+                const c = ownClaims.get(ack.claimId);
+                reject(new AbloClaimedError(`The lease behind ${c ? claimLabel(c.entityType, c.entityId, c.field) : `claim ${ack.claimId}`} is no longer held — it expired or was granted onward while this participant was working. Re-acquire the claim and retry; a write attempted under the old lease is rejected by its \`readAt\` guard.`, { code: 'claim_lost' }));
+            });
+        }));
         // (3) On reconnect, re-announce every open self-claim — the
         //     server's claim state is in-memory and is lost across
         //     restarts. Without this, peers would see our claims vanish
@@ -245,6 +288,39 @@ export function createClaimStream(config, transport = null) {
             },
         });
     }
+    /**
+     * Send one heartbeat and await its ack. Rejects with
+     * {@link AbloConnectionError} (transient — the auto-heartbeat loop retries
+     * on its next tick) when the socket is down or the ack times out, and with
+     * {@link AbloClaimedError} (definitive) when the server answers that the
+     * lease is no longer ours.
+     */
+    function sendHeartbeat(claimId, claim, options) {
+        if (!attached?.isConnected()) {
+            return Promise.reject(new AbloConnectionError(`The heartbeat for ${claimLabel(claim.entityType, claim.entityId, claim.field)} was skipped because the connection is down. The keepalive renews held leases automatically on reconnect; the next beat retries.`));
+        }
+        return new Promise((resolve, reject) => {
+            settleHeartbeat(claimId, ({ reject: rejectPrior }) => {
+                rejectPrior(new AbloConnectionError('A newer heartbeat for this claim superseded the one still awaiting its reply.'));
+            });
+            const timer = setTimeout(() => {
+                settleHeartbeat(claimId, ({ reject: rejectTimeout }) => {
+                    rejectTimeout(new AbloConnectionError(`No reply to the heartbeat for ${claimLabel(claim.entityType, claim.entityId, claim.field)} arrived within ${HEARTBEAT_ACK_TIMEOUT_MS / 1000}s. The next beat retries.`));
+                });
+            }, HEARTBEAT_ACK_TIMEOUT_MS);
+            pendingHeartbeats.set(claimId, { resolve, reject, timer });
+            attached?.send({
+                type: 'claim_heartbeat',
+                payload: {
+                    claimId,
+                    entityType: claim.entityType,
+                    entityId: claim.entityId,
+                    ...(options.ttl !== undefined ? { ttlMs: toMs(options.ttl) } : {}),
+                    ...(options.details !== undefined ? { details: options.details } : {}),
+                },
+            });
+        });
+    }
     function sendAbandon(claimId, claim) {
         if (!attached?.isConnected())
             return;
@@ -281,7 +357,7 @@ export function createClaimStream(config, transport = null) {
         };
         ownClaims.set(claimId, claim);
         sendBegin(claimId, claim);
-        // Coordination trace (info): the creator can SEE their human/agent claims.
+        // Coordination trace (info): the creator can see their human/agent claims.
         getContext().logger.info(`claim: requesting ${claimLabel(claim.entityType, claim.entityId, claim.field)} for "${claim.reason}"` +
             (claim.queue ? ' (will queue if contended)' : ''), { claimId });
         let revoked = false;
@@ -310,6 +386,7 @@ export function createClaimStream(config, transport = null) {
                 revoke();
             },
             revoke,
+            heartbeat: (options) => sendHeartbeat(claimId, claim, resolveHeartbeatOptions(options)),
             [Symbol.asyncDispose]: async () => {
                 revoke();
             },
@@ -377,6 +454,11 @@ export function createClaimStream(config, transport = null) {
             for (const off of unsubs)
                 off();
             unsubs.length = 0;
+            for (const claimId of [...pendingHeartbeats.keys()]) {
+                settleHeartbeat(claimId, ({ reject }) => {
+                    reject(new AbloConnectionError('The claim stream was disposed while this heartbeat was awaiting its reply.'));
+                });
+            }
             listeners.clear();
             rejectionListeners.clear();
             lostListeners.clear();

package/dist/sync/createPresenceStream.d.ts

@@ -1,25 +1,26 @@
 /**
- * Transport-driven PresenceStream factory.
+ * Creates a {@link PresenceStream} over a live sync connection. Presence is the
+ * lightweight, ephemeral "who's here and what are they doing" view: each
+ * participant broadcasts a status and an activity, and sees everyone else's.
+ * The stream is built directly on the sync WebSocket and adds no second
+ * connection. It is the sibling of {@link createClaimStream}, which reuses the
+ * same presence frames.
  *
- * This is the engine's home for presence — built directly on
- * `SyncWebSocket`, no SyncAgent wrapper, no second connection. The
- * older compatibility path predates this and will be deleted when
- * the dual-engine collapse completes.
+ * There are two ways to construct it:
  *
- * Two construction modes:
+ *   1. Direct — pass an already-open `transport`, for example an agent worker
+ *      or a test.
+ *   2. Deferred — construct without a transport and call `attach(transport)`
+ *      once the connection is ready. The returned stream object is stable from
+ *      construction, so callers can hold the reference and let attachment
+ *      happen later.
  *
- *   1. Direct — pass `transport: SyncWebSocket` when it's already
- *      open (agent worker, tests).
- *   2. Deferred — pass `attachLater: true` and call `.attach(transport)`
- *      once the engine's WS lifecycle has produced one. The returned
- *      stream object is stable from construction; attachment can
- *      happen later without callers having to re-grab the reference.
- *
- * Wire contract (apps/sync-server/src/hub/types.ts):
- *   • Outbound: `{ type: 'presence_update', payload: { status, activity? } }`
- *     — server stamps `userId`, `kind`, `timestamp`, `isAgent` and
- *       broadcasts to other clients on the same sync groups.
- *   • Inbound:  same frame, with `kind: 'enter' | 'update' | 'leave'`.
+ * Wire frames:
+ *   • Outbound `presence_update` — `{ status, activity? }`. The server stamps
+ *       `userId`, `kind`, `timestamp`, and `isAgent`, then broadcasts to the
+ *       other participants on the same sync groups.
+ *   • Inbound — the same frame, with `kind` one of `enter`, `update`, or
+ *       `leave`.
  */
 import type { SyncWebSocket } from './SyncWebSocket.js';
 import type { PresenceStream } from '../types/streams.js';

package/dist/sync/createPresenceStream.js

@@ -1,25 +1,26 @@
 /**
- * Transport-driven PresenceStream factory.
+ * Creates a {@link PresenceStream} over a live sync connection. Presence is the
+ * lightweight, ephemeral "who's here and what are they doing" view: each
+ * participant broadcasts a status and an activity, and sees everyone else's.
+ * The stream is built directly on the sync WebSocket and adds no second
+ * connection. It is the sibling of {@link createClaimStream}, which reuses the
+ * same presence frames.
  *
- * This is the engine's home for presence — built directly on
- * `SyncWebSocket`, no SyncAgent wrapper, no second connection. The
- * older compatibility path predates this and will be deleted when
- * the dual-engine collapse completes.
+ * There are two ways to construct it:
  *
- * Two construction modes:
+ *   1. Direct — pass an already-open `transport`, for example an agent worker
+ *      or a test.
+ *   2. Deferred — construct without a transport and call `attach(transport)`
+ *      once the connection is ready. The returned stream object is stable from
+ *      construction, so callers can hold the reference and let attachment
+ *      happen later.
  *
- *   1. Direct — pass `transport: SyncWebSocket` when it's already
- *      open (agent worker, tests).
- *   2. Deferred — pass `attachLater: true` and call `.attach(transport)`
- *      once the engine's WS lifecycle has produced one. The returned
- *      stream object is stable from construction; attachment can
- *      happen later without callers having to re-grab the reference.
- *
- * Wire contract (apps/sync-server/src/hub/types.ts):
- *   • Outbound: `{ type: 'presence_update', payload: { status, activity? } }`
- *     — server stamps `userId`, `kind`, `timestamp`, `isAgent` and
- *       broadcasts to other clients on the same sync groups.
- *   • Inbound:  same frame, with `kind: 'enter' | 'update' | 'leave'`.
+ * Wire frames:
+ *   • Outbound `presence_update` — `{ status, activity? }`. The server stamps
+ *       `userId`, `kind`, `timestamp`, and `isAgent`, then broadcasts to the
+ *       other participants on the same sync groups.
+ *   • Inbound — the same frame, with `kind` one of `enter`, `update`, or
+ *       `leave`.
  */
 import { asyncIteratorFrom } from '../utils/asyncIterator.js';
 import { participantKindFromWire } from '../coordination/schema.js';
@@ -67,10 +68,9 @@ export function createPresenceStream(config, transport = null) {
             if (self.activity.entityId)
                 sendUpdate(self.activity);
         }));
-        // Inbound presence frames — translate the legacy wire vocabulary
-        // (userId / isAgent / timestamp) into the engine shape
-        // (participantId / participantKind / lastActive). When the server
-        // adopts the engine names this block collapses to a pass-through.
+        // Inbound presence frames arrive in the wire vocabulary
+        // (userId / isAgent / timestamp); translate them into the shape this
+        // stream exposes (participantId / participantKind / lastActive).
         unsubs.push(t.subscribe('presence_update', (event) => {
             if (event.userId === participantId)
                 return; // own echo
@@ -117,10 +117,9 @@ export function createPresenceStream(config, transport = null) {
     if (transport)
         attach(transport);
     // ── Outbound ────────────────────────────────────────────────────
-    // Note: do NOT include `isAgent` in the payload. Server derives it
-    // authoritatively from the connection's identity prefix; clients
-    // self-declaring `isAgent` caused human sessions to broadcast as
-    // agents to peers (real bug we caught earlier).
+    // Do not include `isAgent` in the payload. The server derives it
+    // authoritatively from the connection's identity, and letting a client
+    // self-declare it once caused human sessions to broadcast as agents to peers.
     function sendUpdate(activity) {
         if (!attached?.isConnected())
             return; // no-op until connected

package/dist/sync/createSnapshot.d.ts

@@ -1,24 +1,22 @@
 /**
- * Engine-attached snapshot factory.
+ * Captures a {@link Snapshot} of a chosen set of entities, along with a
+ * watermark, so a caller can detect when that state has gone stale. This is
+ * what an LLM caller threads into a prompt: `stamp` flows into later writes as
+ * `readAt`, so the server rejects a mutation premised on data that has since
+ * changed; `signal` is an `AbortSignal` that fires as soon as any captured
+ * entity receives a delta, so a mid-generation invalidation can abort the token
+ * stream instead of producing output against stale context.
  *
- * Captures the engine's current entity state + watermark for context-
- * staleness detection. The returned Snapshot is what an LLM caller
- * threads into a prompt: `stamp` flows into writes as `readAt` so the
- * server rejects mutations against now-stale data; `signal` fires on
- * any captured-entity delta so mid-generation invalidations abort
- * the token stream rather than producing output against dead context.
- *
- * Reads from the engine's MobX-reactive ObjectPool, picks up the
- * engine's `lastSyncId`, and subscribes to delta frames on the
- * engine's transport. Same socket as entity sync — no second
- * connection.
+ * It reads the current entity state from the in-memory pool, reads the engine's
+ * current `lastSyncId` as the watermark, and subscribes to delta frames on the
+ * existing sync connection — no second connection.
  */
-import type { ObjectPool } from '../ObjectPool.js';
+import type { InstanceCache } from '../InstanceCache.js';
 import type { Schema } from '../schema/schema.js';
 import type { SyncWebSocket } from './SyncWebSocket.js';
 import type { Snapshot } from '../types/streams.js';
 export interface CreateSnapshotArgs<TSchema extends Schema = Schema, K extends keyof TSchema['models'] & string = keyof TSchema['models'] & string> {
-    pool: ObjectPool;
+    pool: InstanceCache;
     /** Live transport for delta subscriptions. May be null if the engine
      *  hasn't connected yet — the snapshot still resolves with current
      *  pool state, but `signal` won't fire until reconnect. */

package/dist/sync/createSnapshot.js

@@ -1,24 +1,22 @@
 /**
- * Engine-attached snapshot factory.
+ * Captures a {@link Snapshot} of a chosen set of entities, along with a
+ * watermark, so a caller can detect when that state has gone stale. This is
+ * what an LLM caller threads into a prompt: `stamp` flows into later writes as
+ * `readAt`, so the server rejects a mutation premised on data that has since
+ * changed; `signal` is an `AbortSignal` that fires as soon as any captured
+ * entity receives a delta, so a mid-generation invalidation can abort the token
+ * stream instead of producing output against stale context.
  *
- * Captures the engine's current entity state + watermark for context-
- * staleness detection. The returned Snapshot is what an LLM caller
- * threads into a prompt: `stamp` flows into writes as `readAt` so the
- * server rejects mutations against now-stale data; `signal` fires on
- * any captured-entity delta so mid-generation invalidations abort
- * the token stream rather than producing output against dead context.
- *
- * Reads from the engine's MobX-reactive ObjectPool, picks up the
- * engine's `lastSyncId`, and subscribes to delta frames on the
- * engine's transport. Same socket as entity sync — no second
- * connection.
+ * It reads the current entity state from the in-memory pool, reads the engine's
+ * current `lastSyncId` as the watermark, and subscribes to delta frames on the
+ * existing sync connection — no second connection.
  */
 import { AbloValidationError } from '../errors.js';
 import { Model, modelAsRow } from '../Model.js';
 /**
- * Three top-level keys that conflict with the per-model buckets if a
- * customer's schema declares a model named `stamp` / `signal` /
- * `onChange`. Throw at snapshot time so the collision is loud.
+ * The snapshot result exposes `stamp`, `signal`, and `onChange` at its top
+ * level, alongside one bucket per model. If a schema declares a model with one
+ * of these names, the two would collide, so snapshot creation throws instead.
  */
 const RESERVED_SNAPSHOT_KEYS = new Set([
     'stamp',
@@ -80,9 +78,7 @@ export function createSnapshot(args) {
             const key = `${delta.modelName}:${delta.modelId}`;
             if (!watched.has(key))
                 return;
-            // The snapshot API treats every delta as 'semantic' severity.
-            // Future: distinguish metadata-only deltas (e.g., updatedAt
-            // bumps) from content changes — that's a separate scope.
+            // Every delta to a captured entity is reported as 'semantic' severity.
             fireChange({
                 model: delta.modelName,
                 id: delta.modelId,
@@ -96,16 +92,14 @@ export function createSnapshot(args) {
         signal: controller.signal,
         onChange: (listener) => {
             listeners.add(listener);
-            // Caller is responsible for unsubscribing when they're done.
-            // The delta subscription itself stays for the snapshot's life;
-            // there's no public dispose because snapshots are short-lived
-            // (one LLM call's worth) and the transport-level subscription
-            // is cheap. If a long-lived consumer needs explicit teardown,
-            // we can add `.dispose()` in a follow-up.
+            // The caller unsubscribes its own listener via the returned function.
+            // The underlying delta subscription lives for the snapshot's lifetime;
+            // there is no explicit dispose because a snapshot is short-lived (one
+            // LLM call's worth) and the subscription is cheap.
             return () => {
                 listeners.delete(listener);
-                // If the last listener AND the abort fired, drop the delta
-                // subscription too — no one's listening anymore.
+                // Once the last listener is gone and the abort has fired, drop the
+                // delta subscription too — nothing is listening anymore.
                 if (listeners.size === 0 && controller.signal.aborted && unsubDelta) {
                     unsubDelta();
                     unsubDelta = null;