@abloatai/ablo 0.32.0 → 0.34.0

package/dist/sync/SyncWebSocket.d.ts

@@ -10,7 +10,7 @@ import { EventEmitter } from 'events';
 import type { MutationOperation } from '../interfaces/index.js';
 import { type ClientSyncDelta } from '../wire/delta.js';
 import type { BootstrapReason } from '../wire/bootstrapReason.js';
-import type { ClaimRejection, StaleNotification, ReadDependency, WireClaim } from '../coordination/schema.js';
+import type { ClaimRejection, StaleNotification, ReadDependency, TrackDependency, WireClaim } from '../coordination/schema.js';
 import { type CommitAck } from './commitFrames.js';
 export type { CommitAck } from './commitFrames.js';
 import { type AuthTokenGetter } from '../auth/credentialSource.js';
@@ -441,7 +441,7 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * not auto-retry — the caller's transaction queue owns retry and offline
      * replay, and the SDK does not duplicate that logic.
      */
-    sendCommit(operations: readonly MutationOperation[], clientTxId: string, timeoutMs?: number, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null): Promise<CommitAck>;
+    sendCommit(operations: readonly MutationOperation[], clientTxId: string, timeoutMs?: number, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null, track?: readonly TrackDependency[] | null): Promise<CommitAck>;
     /**
      * Send a commit frame without waiting for `mutation_result`.
      *
@@ -450,7 +450,7 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * eventual `mutation_result` frame is intentionally ignored by this
      * instance because no pending resolver is registered.
      */
-    sendCommitQueued(operations: readonly MutationOperation[], clientTxId: string, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null): void;
+    sendCommitQueued(operations: readonly MutationOperation[], clientTxId: string, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null, track?: readonly TrackDependency[] | null): void;
     /**
      * Activates a participant claim on this connection. One connection can hold
      * several concurrent claims at once, each scoped to a different set of sync

package/dist/sync/SyncWebSocket.js

@@ -689,7 +689,7 @@ export class SyncWebSocket extends EventEmitter {
      * not auto-retry — the caller's transaction queue owns retry and offline
      * replay, and the SDK does not duplicate that logic.
      */
-    sendCommit(operations, clientTxId, timeoutMs = 15_000, causedByTaskId, reads) {
+    sendCommit(operations, clientTxId, timeoutMs = 15_000, causedByTaskId, reads, track) {
         if (this.ws?.readyState !== WebSocket.OPEN) {
             return Promise.reject(this.notConnectedError('commit'));
         }
@@ -704,7 +704,7 @@ export class SyncWebSocket extends EventEmitter {
                 // an open turn — keeps the wire shape stable for sessions
                 // that don't use turns. Servers that don't know the field
                 // ignore it; newer servers stamp it onto every delta.
-                const frame = buildCommitFrame(operations, clientTxId, causedByTaskId, reads);
+                const frame = buildCommitFrame(operations, clientTxId, causedByTaskId, reads, track);
                 this.ws.send(JSON.stringify(frame));
             }
             catch (error) {
@@ -722,11 +722,11 @@ export class SyncWebSocket extends EventEmitter {
      * eventual `mutation_result` frame is intentionally ignored by this
      * instance because no pending resolver is registered.
      */
-    sendCommitQueued(operations, clientTxId, causedByTaskId, reads) {
+    sendCommitQueued(operations, clientTxId, causedByTaskId, reads, track) {
         if (this.ws?.readyState !== WebSocket.OPEN) {
             throw this.notConnectedError('commit');
         }
-        const frame = buildCommitFrame(operations, clientTxId, causedByTaskId, reads);
+        const frame = buildCommitFrame(operations, clientTxId, causedByTaskId, reads, track);
         this.ws.send(JSON.stringify(frame));
     }
     /**

package/dist/sync/commitFrames.d.ts

@@ -7,7 +7,7 @@
 import type { CommitMessage } from '../wire/index.js';
 import type { CommitAck as CanonicalCommitAck } from '../wire/commit.js';
 import type { MutationOperation, ClaimEvent } from '../interfaces/index.js';
-import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
+import type { StaleNotification, ReadDependency, TrackDependency } from '../coordination/schema.js';
 /**
  * The value a commit acknowledgement resolves to. `notifications` is present
  * only when a guarded write (`onStale: 'notify'`) met a concurrent change; it
@@ -24,7 +24,7 @@ export type CommitAck = CanonicalCommitAck;
  * here; the single `as` cast narrows the validated `type` to the wire union and
  * is the only place that loosening happens.
  */
-export declare function buildCommitFrame(operations: readonly MutationOperation[], clientTxId: string, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null): CommitMessage;
+export declare function buildCommitFrame(operations: readonly MutationOperation[], clientTxId: string, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null, track?: readonly TrackDependency[] | null): CommitMessage;
 /**
  * Defensively validate the optional `notifications` array off a commit ack.
  * Untrusted wire data — a malformed entry is dropped rather than throwing,

package/dist/sync/commitFrames.js

@@ -16,7 +16,7 @@ import { formatClaim } from '../coordination/trace.js';
  * here; the single `as` cast narrows the validated `type` to the wire union and
  * is the only place that loosening happens.
  */
-export function buildCommitFrame(operations, clientTxId, causedByTaskId, reads) {
+export function buildCommitFrame(operations, clientTxId, causedByTaskId, reads, track) {
     const payload = {
         operations: operations.map((op) => ({
             type: op.type,
@@ -35,6 +35,10 @@ export function buildCommitFrame(operations, clientTxId, causedByTaskId, reads)
     // The read set the batch was premised on: the rows or groups the writer read before committing.
     if (reads && reads.length > 0)
         payload.reads = [...reads];
+    // Durable read-dependencies the writer is registering: the rows or groups it
+    // wants to keep hearing about after this commit, delivered on a future receipt.
+    if (track && track.length > 0)
+        payload.track = [...track];
     return { type: 'commit', payload };
 }
 /**

package/dist/transactions/TransactionQueue.d.ts

@@ -16,7 +16,7 @@ import type { Database } from '../Database.js';
 import { Model } from '../Model.js';
 import { SyncPosition } from '../sync/syncPosition.js';
 import type { WriteOptions } from '../interfaces/index.js';
-import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
+import type { StaleNotification, ReadDependency, TrackDependency } from '../coordination/schema.js';
 import { type MutationInput, type Transaction, type UserContext } from './commitPayload.js';
 import { type DurableCommitEnvelope, type DurableCommitOperation, type CommitOutboxScope } from './commitEnvelope.js';
 import type { DurableWriteStore } from './durableWriteStore.js';
@@ -45,6 +45,8 @@ interface CommitTransaction {
     causedByTaskId?: string | null;
     /** Read dependencies for the whole batch, forwarded to the executor so the server can detect stale-context writes. */
     reads?: ReadDependency[] | null;
+    /** Durable read-dependencies (`track`) to register for the batch's participant, forwarded to the executor. */
+    track?: TrackDependency[] | null;
     status: 'pending' | 'executing' | 'awaiting_delta' | 'completed' | 'failed';
     createdAt: number;
     attempts: number;
@@ -410,6 +412,7 @@ export declare class TransactionQueue extends EventEmitter {
     enqueueCommit(clientTxId: string, operations: CommitTransaction['operations'], options?: {
         causedByTaskId?: string | null;
         reads?: ReadDependency[] | null;
+        track?: TrackDependency[] | null;
     }): Promise<void>;
     /**
      * Drains the pending commit-lane envelopes one at a time. A transient

package/dist/transactions/TransactionQueue.js

@@ -400,6 +400,13 @@ export class TransactionQueue extends EventEmitter {
                             : [...input.commitOptions.reads],
                     }
                     : {}),
+                ...(input.commitOptions?.track !== undefined
+                    ? {
+                        track: input.commitOptions.track === null
+                            ? null
+                            : [...input.commitOptions.track],
+                    }
+                    : {}),
             },
             ...(this.commitOutboxScope ? { scope: this.commitOutboxScope } : {}),
             createdAt: input.createdAt,
@@ -1829,11 +1836,13 @@ export class TransactionQueue extends EventEmitter {
                 operations: existing.operations,
                 causedByTaskId: existing.causedByTaskId ?? null,
                 reads: existing.reads ?? null,
+                track: existing.track ?? null,
             });
             const incomingIntent = stableStringify({
                 operations,
                 causedByTaskId: options.causedByTaskId ?? null,
                 reads: options.reads ?? null,
+                track: options.track ?? null,
             });
             if (existingIntent !== incomingIntent) {
                 throw new AbloIdempotencyError('Idempotency key reused with a different atomic commit request', { code: 'idempotency_conflict' });
@@ -1864,6 +1873,7 @@ export class TransactionQueue extends EventEmitter {
             operations: [...operations],
             causedByTaskId: options.causedByTaskId ?? null,
             ...(options.reads ? { reads: options.reads } : {}),
+            ...(options.track ? { track: options.track } : {}),
             status: 'pending',
             createdAt: Date.now(),
             attempts: 0,
@@ -1878,6 +1888,7 @@ export class TransactionQueue extends EventEmitter {
             commitOptions: {
                 causedByTaskId: tx.causedByTaskId ?? null,
                 ...(tx.reads ? { reads: tx.reads } : {}),
+                ...(tx.track ? { track: tx.track } : {}),
             },
             createdAt: tx.createdAt,
             sealedAt: tx.sealedAt,
@@ -1941,6 +1952,7 @@ export class TransactionQueue extends EventEmitter {
                             commitOptions: {
                                 causedByTaskId: tx.causedByTaskId ?? null,
                                 ...(tx.reads ? { reads: tx.reads } : {}),
+                                ...(tx.track ? { track: tx.track } : {}),
                             },
                             createdAt: tx.createdAt,
                             sealedAt: tx.sealedAt,
@@ -1955,6 +1967,9 @@ export class TransactionQueue extends EventEmitter {
                         ...(durableEnvelope.commitOptions.reads
                             ? { reads: durableEnvelope.commitOptions.reads }
                             : {}),
+                        ...(durableEnvelope.commitOptions.track
+                            ? { track: durableEnvelope.commitOptions.track }
+                            : {}),
                     }));
                     tx.durableEnvelope = await this.persistDurableCommitAcceptance(durableEnvelope, result);
                     tx.lastSyncId = result.lastSyncId;
@@ -2446,6 +2461,9 @@ export class TransactionQueue extends EventEmitter {
                     ...(envelope.commitOptions.reads
                         ? { reads: [...envelope.commitOptions.reads] }
                         : {}),
+                    ...(envelope.commitOptions.track
+                        ? { track: [...envelope.commitOptions.track] }
+                        : {}),
                     status: 'pending',
                     createdAt: envelope.createdAt,
                     sealedAt: envelope.sealedAt,

package/dist/transactions/commitEnvelope.d.ts

@@ -111,6 +111,14 @@ export declare const durableCommitEnvelopeSchema: z.ZodObject<{
                 notify: "notify";
             }>>;
         }, z.core.$strip>]>>>>;
+        track: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            model: z.ZodString;
+            id: z.ZodString;
+            readAt: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            group: z.ZodString;
+            readAt: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>]>>>>;
     }, z.core.$strict>>;
     scope: z.ZodOptional<z.ZodObject<{
         organizationId: z.ZodString;

package/dist/transactions/commitEnvelope.js

@@ -7,7 +7,7 @@
  * operations, and the source mutations it supersedes.
  */
 import { z } from 'zod';
-import { readDependencySchema } from '../coordination/schema.js';
+import { readDependencySchema, trackDependencySchema } from '../coordination/schema.js';
 import { commitOperationSchema } from '../wire/frames.js';
 import { correlationIdSchema } from '../wire/commit.js';
 import { idempotencyKeySchema } from './idempotencyKey.js';
@@ -50,6 +50,7 @@ export const durableCommitOperationSchema = commitOperationSchema
 const durableCommitOptionsSchema = z.strictObject({
     causedByTaskId: z.string().min(1).nullable().optional(),
     reads: z.array(readDependencySchema).nullable().optional(),
+    track: z.array(trackDependencySchema).nullable().optional(),
 });
 export const commitOutboxScopeSchema = z.strictObject({
     organizationId: z.string().min(1),

package/dist/transactions/durableWriteStore.d.ts

@@ -62,6 +62,14 @@ export declare const pendingWriteSchema: z.ZodUnion<readonly [z.ZodObject<{
                 notify: "notify";
             }>>;
         }, z.core.$strip>]>>>>;
+        track: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            model: z.ZodString;
+            id: z.ZodString;
+            readAt: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            group: z.ZodString;
+            readAt: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>]>>>>;
     }, z.core.$strict>>;
     scope: z.ZodOptional<z.ZodObject<{
         organizationId: z.ZodString;

package/dist/wire/frames.d.ts

@@ -13,7 +13,7 @@
  * server to update together.
  */
 import { z } from 'zod';
-import type { OnStaleMode, ReadDependency } from '../coordination/index.js';
+import type { OnStaleMode, ReadDependency, TrackDependency } from '../coordination/index.js';
 import type { MutationResultMessageWire } from './commit.js';
 /**
  * A single operation within a {@link CommitMessage} batch. Each operation is
@@ -121,6 +121,14 @@ export interface CommitMessage {
          * being written are checked for staleness.
          */
         reads?: ReadDependency[] | null;
+        /**
+         * Durable read-dependencies to register for this batch's participant. Each
+         * entry — a row (`{ model, id }`) or a sync group (`{ group }`) — is persisted
+         * and re-checked against every future delta; a later match surfaces a
+         * `StaleNotification` on the participant's next commit. Distinct from `reads`,
+         * which is checked once here and discarded.
+         */
+        track?: TrackDependency[] | null;
     };
 }
 /**
@@ -172,6 +180,14 @@ export declare const commitPayloadSchema: z.ZodObject<{
             notify: "notify";
         }>>;
     }, z.core.$strip>]>>>>;
+    track: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        model: z.ZodString;
+        id: z.ZodString;
+        readAt: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        group: z.ZodString;
+        readAt: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>]>>>>;
 }, z.core.$strip>;
 /**
  * The server's acknowledgement of a {@link CommitMessage}. Runtime shape and

package/dist/wire/frames.js

@@ -15,7 +15,7 @@
 import { z } from 'zod';
 // The runtime schema primitives are imported straight from the coordination
 // schema module to keep this file's runtime dependencies limited to Zod.
-import { commitOperationSchema as coordinationCommitOperationSchema, readDependencySchema, } from '../coordination/schema.js';
+import { commitOperationSchema as coordinationCommitOperationSchema, readDependencySchema, trackDependencySchema, } from '../coordination/schema.js';
 /**
  * Runtime validator for {@link CommitOperation}. Both commit transports — the
  * WebSocket `commit` frame and the HTTP `/v1/commits` endpoint — run this check
@@ -42,6 +42,7 @@ export const commitPayloadSchema = z.object({
     clientTxId: z.string(),
     causedByTaskId: z.string().nullish(),
     reads: z.array(readDependencySchema).nullish(),
+    track: z.array(trackDependencySchema).nullish(),
 });
 // Pins the schema to the payload type: fails to compile if either side drifts.
 const _commitPayloadContract = true;

package/docs/client-behavior.md

@@ -32,7 +32,7 @@ Common options:
 | `baseURL` | Override the hosted sync endpoint for staging or private deployments. |
 | `persistence` | `memory` by default. Use `indexeddb` for a durable browser cache that survives reloads. |
 | `durableWrites` | Optional crash recovery for unacknowledged agent/worker writes. Independent of the default memory cache; accepts `{ store, namespace? }`. |
-| `transport` | `'websocket'` (default) is the live, stateful client — a persistent socket, a local synced pool, and `onChange` subscriptions. `'http'` returns the **stateless** client for server-side actors (agents, workers, serverless): the same `ablo.<model>` read/write/claim surface, but each call is one HTTP round-trip with no socket. Under `'http'` the return type narrows to `AbloHttpClient`, so stateful-only methods (`get`/`getAll`, `onChange`, `watch`) are compile errors rather than runtime gaps. |
+| `transport` | `'websocket'` (default) is the live, stateful client — a persistent socket, a local synced pool, and `onChange` subscriptions. `'http'` returns the **stateless** client for server-side actors (agents, workers, serverless): the same `ablo.<model>` read/write/claim surface, but each call is one HTTP round-trip with no socket. Under `'http'` the return type narrows to `AbloHttpClient`, so stateful-only methods (`get`/`getAll`, `onChange`, `join`) are compile errors rather than runtime gaps. |
 | `fetch` | Custom fetch implementation for tests or non-standard runtimes. |
 | `defaultHeaders` | Extra headers attached to every HTTP request. |
 | `defaultQuery` | Extra query parameters attached to every HTTP request. |

package/docs/coordination.md

@@ -473,6 +473,18 @@ Each beat's answer carries two more things:
   the lease. Durable progress belongs in the data itself — write a row, and
   every subscriber already sees it.
 
+Cooperative yield has a server-side backstop your deployment can turn on: a
+**cumulative-hold ceiling**. Left unset — the default — a holder that keeps
+beating holds the row as long as it likes, and the line behind it depends on
+that holder reading `queueDepth` and releasing of its own accord. With a ceiling
+configured for a model, a holder that runs past its fair share *while contenders
+are queued* is preempted at the server: its next beat comes back `claim_lost`
+(reason `preempted`) — the same loss you already handle, so abandon or re-claim,
+and any write attempted under the old lease is fenced regardless. A holder with
+no one waiting is never preempted, however long it runs. It is the same idea as
+an SQS message that cannot stay invisible past a hard cap however often its lock
+is refreshed, narrowed here to bite only under real contention.
+
 Works identically on both transports: the realtime client sends a
 `claim_heartbeat` frame; the HTTP client posts
 `POST /api/v1/models/{model}/{id}/claim/heartbeat` (`{ ttl?, claimId?, details? }`).
@@ -530,23 +542,23 @@ snapshot.
 | still has a second live connection | survives — release fires only on the last connection |
 | loses the server to a restart | rides the TTL in the coordination store; re-announced on reconnect |
 
-### `watch` — presence for a set of rows
+### `join` — presence for a set of rows
 
 Reading or claiming a row auto-enrolls you in its sync group, which is enough for
 `claim.state`/`claim.queue` to observe co-participants. When you want to *hold*
 presence on a known set of rows — a deck's slides, a board's cards — and react to
-who joins or leaves, use `watch`:
+who joins or leaves, use `join`:
 
 ```ts
-await using room = await ablo.slides.watch(slideIds, { ttl: '5m' });
+await using room = await ablo.slides.join(slideIds, { ttl: '5m' });
 room.peers; // who else is here, live
 ```
 
-`watch(ids, { ttl? })` opens a model-scoped presence/claim subscription and returns
+`join(ids, { ttl? })` opens a model-scoped presence/claim subscription and returns
 a participant handle (`.peers`, the scoped claim stream, `.leave()` / `await using`
 disposal). It is the model-scoped successor to the old top-level
 `ablo.participants.join({ scope })`. **WebSocket only** — presence needs a live
-socket, so `watch` is absent on the HTTP client (`Ablo({ transport: 'http' })`) and
+socket, so `join` is absent on the HTTP client (`Ablo({ transport: 'http' })`) and
 throws on any non-ws construction.
 
 ### Writing under a claim
@@ -603,7 +615,7 @@ inspect the `code`.
 
 | error | `code` | thrown when | carries |
 |---|---|---|---|
-| `AbloClaimedError` | `claim_lost` | A held/queued claim was taken away — the holder disconnected (reaped on the keepalive cycle), went silent past its TTL, or was revoked — while you were holding or waiting. | `claims?` |
+| `AbloClaimedError` | `claim_lost` | A held/queued claim was taken away — the holder disconnected (reaped on the keepalive cycle), went silent past its TTL, was revoked, or was preempted (a privileged reorder, or a configured cumulative-hold ceiling reached while contenders waited) — while you were holding or waiting. | `claims?` |
 | `AbloClaimedError` | `claim_queued` | **HTTP transport only.** A contended `claim` (default `queue: true`) could not block-wait for the lease (no socket), so it rejected immediately instead of queueing. Retryable — re-attempt the claim. | `claims?` |
 | `AbloClaimedError` | `grant_timeout` | The optional `timeoutMs` elapsed while you were still queued for a grant. | `claims?` |
 | `AbloClaimedError` | `queue_too_deep` | `claim` was passed `maxQueueDepth` and the wait line was already that deep when you tried to join — fail-fast instead of waiting. | `claims?` |

package/docs/groups.md

@@ -135,6 +135,56 @@ the same row don't collide.
 
 ---
 
+## Staying subscribed across commits: `track`
+
+A read premise guards a single commit: you state what you read, the engine
+checks it, the premise is gone. That fits an actor that reads and writes in one
+breath. It does not fit a long-running one — an agent that reads a row now,
+works for a few minutes, and writes much later. By the time it commits, the
+premise it would have declared is stale, and there was no commit in between on
+which to hear that the ground had shifted.
+
+`track` is the durable half of the same idea. Register what you are watching and
+it persists on the server; the next time you commit anything, a change that
+landed on the tracked target since you registered rides back on your receipt —
+the same `StaleNotification` an `onStale: 'notify'` premise would have handed
+you, arriving on the write you were going to make anyway.
+
+```ts
+// Register interest and walk away — no write required.
+await ablo.slides.track({ id: 's-1' });
+
+// …minutes of other work later, on your next commit…
+const res = await ablo.layers.update({ id: 'layer-C', data: { text: revised } });
+res.notifications; // populated if s-1 moved under you in the meantime
+```
+
+The target is a row (`{ id }` on the model verb) or a sync group (as a write
+option, below). A track is an idempotent registration: calling it again refreshes
+the same subscription rather than stacking duplicates, and once a change fires the
+track re-baselines, so the same change notifies once. Your own writes to a target
+you track never notify you — the signal is about what *others* did.
+
+You can also register a track as part of a write you are already making, the
+persisted companion to `reads`:
+
+```ts
+await ablo.slides.update({
+  id: 's-1',
+  data: { title: revised },
+  reads: [{ group: 'deck:abc', readAt: N, onStale: 'notify' }], // guards THIS commit
+  track: [{ group: 'deck:abc' }],                               // and keeps watching after it
+});
+```
+
+So `reads` is the premise for the commit in hand; `track` is a standing
+subscription that outlives it. Both speak the same notification vocabulary, and
+both leave the resolution to you — the engine reports that the target moved and
+lets the actor decide what that means. Delivery is on your next commit's receipt;
+a track does not yet push out of band between commits.
+
+---
+
 ## Sizing groups
 
 A group is the unit of both delivery and staleness, so its size is a real

package/docs/identity.md

@@ -519,8 +519,8 @@ an agent pointed at the entities it's working on. You **never hand-write**
    (**read-interest**), and `claim`-ing it pins a **write-intent** subscription.
    So an agent's reachable set **accretes** as it works — no extra subscribe call.
 
-3. **Explicitly, for presence — `watch`.** To hold presence on a known set of rows
-   and react to peers, use the WebSocket-only `ablo.<model>.watch(ids, { ttl })`
+3. **Explicitly, for presence — `join`.** To hold presence on a known set of rows
+   and react to peers, use the WebSocket-only `ablo.<model>.join(ids, { ttl })`
    (it returns a participant handle with `.peers`). See
    [Coordination](./coordination.md).
 

package/docs/migration.md

@@ -11,8 +11,9 @@ change when you upgrade.
 
 | Version | What changed | What to do |
 |---|---|---|
-| **0.28.0** | Removed React placeholders that had no working runtime | `usePresence` → `usePeers` or `useWatch`; `useClaim` → `ablo.<model>.claim`; `SyncGroupProvider` / `useSyncGroup` → `useWatch({ scope })` |
-| **0.11.0** | Historical `intent` → `claim` rename | The hook renamed in that release was later removed in 0.28.0. Current code uses `ablo.<model>.claim` or `useWatch` |
+| **0.34.0** | Presence verb renamed `watch` → `join` | `ablo.<model>.watch(ids)` → `ablo.<model>.join(ids)`; `useWatch` → `useJoin`; the `WatchOptions` / `UseWatchOptions` / `UseWatchReturn` types → `JoinOptions` / `UseJoinOptions` / `UseJoinReturn`; error code `model_watch_not_configured` → `model_join_not_configured` |
+| **0.28.0** | Removed React placeholders that had no working runtime | `usePresence` → `usePeers` or `useJoin`; `useClaim` → `ablo.<model>.claim`; `SyncGroupProvider` / `useSyncGroup` → `useJoin({ scope })` |
+| **0.11.0** | Historical `intent` → `claim` rename | The hook renamed in that release was later removed in 0.28.0. Current code uses `ablo.<model>.claim` or `useJoin` |
 | **0.10.0** | Environment enum renamed `test`/`live` → `sandbox`/`production` | Update code that branches on the environment (e.g. source `mode`): `'test'`→`'sandbox'`, `'live'`→`'production'`. Key prefixes `sk_test_`/`sk_live_` are unchanged |
 | **0.9.2** | `turn` primitive + agent-work `tasks` resource removed | Coordinate with `claim`; mint a scoped session instead of `agent().run()` |
 | **0.9.2** | `intents` deprecated in favor of `claim` | Use `ablo.<model>.claim`; `ablo.intents` is now `@internal` |
@@ -26,17 +27,40 @@ change when you upgrade.
 
 ---
 
+## 0.34.0 — presence verb renamed `watch` → `join`
+
+The model-level presence verb read like a data subscription but delivered
+presence — who else is on a row and what they hold — so it now says what it
+does. `ablo.<model>.join(ids, { ttl })` opens the participant handle
+(`.peers`, `.claims`, `await using` disposal); the returned `status` was
+already `'joined'`, and the layer beneath always called itself `join`, so the
+verb now matches. `onChange` remains the way to hear row *values* change, and
+`track` remains the durable read-dependency for actors.
+
+```ts
+// before
+await using room = await ablo.slides.watch(slideIds, { ttl: '5m' });
+// after
+await using room = await ablo.slides.join(slideIds, { ttl: '5m' });
+```
+
+The React hook follows: `useWatch({ scope })` → `useJoin({ scope })`. There is
+no compatibility alias — rename the call sites and the `WatchOptions` /
+`UseWatchOptions` / `UseWatchReturn` type imports.
+
+---
+
 ## 0.28.0 — dead React multiplayer placeholders removed
 
 Four React exports looked usable but had no live implementation:
 
 - `usePresence` returned no provider-backed presence value. Use `usePeers` for
-  read-only presence or `useWatch` to join a scoped participant.
+  read-only presence or `useJoin` to join a scoped participant.
 - `useClaim` depended on a callback the provider never supplied and always
   threw. Use `ablo.<model>.claim({ id, ... })` for row claims or
-  `useWatch({ scope, claim: true })` for a scoped participant claim.
+  `useJoin({ scope, claim: true })` for a scoped participant claim.
 - `SyncGroupProvider` and `useSyncGroup` had no repository consumers. Pass the
-  scope directly to `useWatch({ scope })`.
+  scope directly to `useJoin({ scope })`.
 
 There is no compatibility alias: the replacement APIs were already the only
 working paths.

package/docs/react.md

@@ -178,9 +178,9 @@ imperative work after an event or effect.
 
 See [API reference](/docs/api) for the full options surface.
 
-## useWatch — scoped presence + read interest
+## useJoin — scoped presence + read interest
 
-`useWatch` is the React form of `ablo.<model>.watch`. It joins multiplayer for a
+`useJoin` is the React form of `ablo.<model>.join`. It joins multiplayer for a
 scope on the engine's existing socket (one TCP connection, N logical
 sub-syncgroup participants) and returns the reactive participant facade. Use it
 when a mount should both *see* who else is on an entity and, optionally, declare
@@ -189,10 +189,10 @@ write interest in it.
 ```tsx
 'use client';
 
-import { useWatch } from '@abloatai/ablo/react';
+import { useJoin } from '@abloatai/ablo/react';
 
 export function DeckPresence({ deckId }: { deckId: string }) {
-  const { peers, claims, status } = useWatch({
+  const { peers, claims, status } = useJoin({
     scope: { slideDecks: deckId },
     claim: true,   // I intend to write — pin the scope + let peers observe the claim
     hydrate: true, // backfill the deck's current rows if not already loaded
@@ -203,7 +203,7 @@ export function DeckPresence({ deckId }: { deckId: string }) {
 }
 ```
 
-Options (`UseWatchOptions`):
+Options (`UseJoinOptions`):
 
 | Option | Default | Effect |
 | --- | --- | --- |
@@ -213,7 +213,7 @@ Options (`UseWatchOptions`):
 | `ttlSeconds` | — | Lease TTL for the scope claim. |
 | `paused` | `false` | Tear down and don't re-join while true. |
 
-Returns (`UseWatchReturn`): `{ participant, peers, claims, status, error }`.
+Returns (`UseJoinReturn`): `{ participant, peers, claims, status, error }`.
 `peers` is everyone else on the scope's sync groups; `claims` is their active
 write-claims; `status` is the join lifecycle. Auto-cleans up on unmount or when
 `paused` flips true.
@@ -221,7 +221,7 @@ write-claims; `status` is the join lifecycle. Auto-cleans up on unmount or when
 ## usePeers — read-only presence
 
 `usePeers` is a *pure reader* of the presence stream already flowing on the
-connection. Unlike `useWatch`, it does **not** enter/leave a scope (no
+connection. Unlike `useJoin`, it does **not** enter/leave a scope (no
 `update_subscription`, no warm-TTL churn) — so reading it never changes what the
 connection is subscribed to.
 
@@ -242,9 +242,9 @@ engine's groups. Returns `ReadonlyArray<Peer>`, where each `Peer` carries
 `participantKind` (`'user' | 'agent' | 'system'`), `participantId`, optional
 `label`, `syncGroups`, `activity`, `lastActive`, and optional `activeClaims`.
 
-Reach for `usePeers` (not a second `useWatch`) when some **other** mount already
+Reach for `usePeers` (not a second `useJoin`) when some **other** mount already
 owns the scope's read interest — scope `leave` is not reference-counted, so a
-second `useWatch` on the same scope would warm-drop the owner's subscription on
+second `useJoin` on the same scope would warm-drop the owner's subscription on
 unmount.
 
 ## Next.js

package/llms.txt

@@ -90,7 +90,7 @@ coordination until the app reports it through Data Source events.
 
 ## Change propagation
 
-A change to one row reaches other rows three ways. ROUTING: a write fans out to every sync group the row belongs to, INCLUDING its ancestors' groups (editing a layer routes to `layer:` + `slide:` + `deck:`), so everyone watching the deck sees it — delivery, not recomputation. DELETE CASCADE: deleting a parent emits explicit tombstone deltas for its descendants, so open clients never silently hold rows that are gone. VALUE: derived values are NOT recomputed server-side — Ablo surfaces that the source moved and the actor decides. To keep dependent work fresh, declare what you read as a batch premise: `reads: [{ group: 'deck:abc', readAt: N, onStale: 'notify' }]`. At commit the server checks whether anything in that group moved past `readAt`; `notify` holds the write and returns a `StaleNotification` (re-read the group and regenerate), `reject` aborts. To chain A→B→C, put A+B in one group and B+C in another: A's change reaches B, and C hears it only once B ITSELF writes — the engine wires the edges and signals each hop, the actor walks them. No transitive auto-recompute, no convergence guarantee for cycles.
+A change to one row reaches other rows three ways. ROUTING: a write fans out to every sync group the row belongs to, INCLUDING its ancestors' groups (editing a layer routes to `layer:` + `slide:` + `deck:`), so everyone watching the deck sees it — delivery, not recomputation. DELETE CASCADE: deleting a parent emits explicit tombstone deltas for its descendants, so open clients never silently hold rows that are gone. VALUE: derived values are NOT recomputed server-side — Ablo surfaces that the source moved and the actor decides. To keep dependent work fresh, declare what you read as a batch premise: `reads: [{ group: 'deck:abc', readAt: N, onStale: 'notify' }]`. At commit the server checks whether anything in that group moved past `readAt`; `notify` holds the write and returns a `StaleNotification` (re-read the group and regenerate), `reject` aborts. To chain A→B→C, put A+B in one group and B+C in another: A's change reaches B, and C hears it only once B ITSELF writes — the engine wires the edges and signals each hop, the actor walks them. No transitive auto-recompute, no convergence guarantee for cycles. `reads` guards ONE commit; for a long-running actor that reads now and writes much later, register a DURABLE premise with `track`: `ablo.<model>.track({ id })` for a row, or the `track:` write option (`track: [{ group: 'deck:abc' }]`) alongside a write. A track persists server-side; the next time you commit anything, a change that landed on the tracked target rides back on your receipt's `notifications` (same `StaleNotification` shape as `onStale: 'notify'`). It is an idempotent registration, re-baselines so a change fires once, and never notifies you of your own writes. Delivery is on your next commit — a track does not yet push out of band between commits.
 
 ## Nouns
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",