@abloatai/ablo 0.33.0 → 0.34.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.34.0
+
+### Minor Changes
+
+A long-running actor has a stale-context problem the per-commit read gate never reaches. The `reads` guard is a premise for the commit in hand: you declare what you looked at, the server checks it at commit, and the premise is gone. That fits an actor that reads and writes in one breath, not one that reads a row, works for minutes — an LLM call, a fetch, a human's turn — and only then writes. By the time it commits, the premise it would have declared is already old, and there was no commit in between on which to hear that the ground had shifted. This release adds `track`, the durable half of the same idea. `ablo.<model>.track({ id })` registers a read-dependency that persists on the server; the next time you commit anything, a change that landed on the tracked row since you registered rides back on the receipt's `notifications` — the same `StaleNotification` an `onStale: 'notify'` premise hands you, arriving on the write you were going to make anyway. You can also register one as part of a write, `track: [{ group: 'deck:abc' }]` alongside the batch, the standing-subscription companion to the single-commit `reads`. A track is idempotent — registering the same target again refreshes the one subscription rather than stacking duplicates — it re-baselines after it fires so a given change notifies once, and it never notifies you of your own writes, since the signal is about what others did. Delivery is on your next commit's receipt; a track does not yet push out of band between commits, so it sharpens the write-time freshness check rather than replacing a live subscription.
+
+The model-level presence verb is renamed from `watch` to `join`. It read like a data subscription but delivered presence — who else is on a set of rows and what they hold — so it now says what it does. `ablo.<model>.join(ids, { ttl })` opens the participant handle, with `.peers`, the scoped claim stream, and `await using` disposal unchanged; the handle's `status` was already `'joined'` and the layer beneath always called itself join, so the verb now matches the thing it returns. `onChange` remains the way to hear a row's *values* change, and `track` is the durable read-dependency for actors — three distinct jobs that the one overloaded `watch` used to blur. The React hook follows: `useWatch` becomes `useJoin`, the `WatchOptions` / `UseWatchOptions` / `UseWatchReturn` types become `JoinOptions` / `UseJoinOptions` / `UseJoinReturn`, and the error code `model_watch_not_configured` is now `model_join_not_configured`. There is no compatibility alias — rename the call sites and the type imports. The migration guide carries the mechanical diff.
+
+### Patch Changes
+
+`ablo connect --apply` now checks, before it runs any grants, that you can actually grant on the tables you're publishing — and stops with the one-line fix if you can't, instead of failing partway through. The setup grants the writer role access to each published table, an operation Postgres reserves for the table's owner, so a table left owned by an earlier integration's role used to abort the run midway with a bare `must be owner of table …` and no guidance. Apply now names the offending tables and their owner up front and prints the exact `ALTER TABLE … OWNER TO` to reassign them to your admin — metadata only, your rows and row-level-security policies untouched. The check understands inherited role membership, so an admin that inherits the owning role — the ordinary managed-Postgres case — is left to proceed rather than stopped needlessly; only a membership that can't act as the owner is flagged.
+
 ## 0.33.0
 
 ### Minor Changes

package/dist/cli.cjs

@@ -909,7 +909,7 @@ var init_errorCodes = __esm({
       model_claimed: wire("claim", 409, false, "Another participant holds a claim on this row. Read `claim.state` to see who holds it, or queue behind them with a claim of your own."),
       model_claimed_timeout: wire("claim", 409, false, "Another participant held a claim on this row and did not release it in time. Retry, or read `claim.state` to see who holds it."),
       model_claim_not_configured: client("claim", "Claiming requires the collaboration runtime, which the standard Ablo({ schema, apiKey }) client wires up for every model automatically \u2014 there is no per-model claim configuration to add. This appears only when a model proxy is constructed directly without that runtime (an internal/advanced path)."),
-      model_watch_not_configured: client("claim", "watch() opens a presence/claim subscription and needs a live WebSocket, so it is unavailable on the HTTP transport and on model proxies built without a socket. Use the standard Ablo({ schema, apiKey }) client (default WebSocket transport)."),
+      model_join_not_configured: client("claim", "join() opens a presence/claim subscription and needs a live WebSocket, so it is unavailable on the HTTP transport and on model proxies built without a socket. Use the standard Ablo({ schema, apiKey }) client (default WebSocket transport)."),
       // ── stale context / idempotency (409) ──────────────────────────────
       // Not retryable at the transport: the rejected request carries its frozen
       // `readAt`, so resending the identical payload can never succeed. Recovery
@@ -1199,7 +1199,7 @@ var init_roles = __esm({
 });
 
 // src/coordination/schema.ts
-var import_zod3, targetRangeSchema, participantKindSchema, wireParticipantKindSchema, targetRefSchema, onStaleModeSchema, writeGuardSchema, staleNotificationSchema, readDependencySchema, claimStatusSchema, grantStampFields, wireClaimBaseSchema, wireClaimSummarySchema, claimErrorSchema, wireClaimSchema, claimRejectionSchema, claimLostSchema, modelTargetSchema, modelClaimSchema, claimBeginPayloadSchema, claimAbandonPayloadSchema, claimReorderPayloadSchema, claimHeartbeatFieldsSchema, claimHeartbeatPayloadSchema, claimHeartbeatAckPayloadSchema, claimHeartbeatBatchPayloadSchema, claimHeartbeatBatchAckPayloadSchema, updateSubscriptionPayloadSchema, subscriptionAckPayloadSchema, commitOperationTypeSchema, commitOperationSchema, presenceKindSchema, presenceActivitySchema, presenceUpdateFrameSchema;
+var import_zod3, targetRangeSchema, participantKindSchema, wireParticipantKindSchema, targetRefSchema, onStaleModeSchema, writeGuardSchema, staleNotificationSchema, readDependencySchema, trackDependencySchema, claimStatusSchema, grantStampFields, wireClaimBaseSchema, wireClaimSummarySchema, claimErrorSchema, wireClaimSchema, claimRejectionSchema, claimLostSchema, modelTargetSchema, modelClaimSchema, claimBeginPayloadSchema, claimAbandonPayloadSchema, claimReorderPayloadSchema, claimHeartbeatFieldsSchema, claimHeartbeatPayloadSchema, claimHeartbeatAckPayloadSchema, claimHeartbeatBatchPayloadSchema, claimHeartbeatBatchAckPayloadSchema, updateSubscriptionPayloadSchema, subscriptionAckPayloadSchema, commitOperationTypeSchema, commitOperationSchema, presenceKindSchema, presenceActivitySchema, presenceUpdateFrameSchema;
 var init_schema = __esm({
   "src/coordination/schema.ts"() {
     "use strict";
@@ -1284,6 +1284,17 @@ var init_schema = __esm({
         onStale: onStaleModeSchema.optional()
       })
     ]);
+    trackDependencySchema = import_zod3.z.union([
+      import_zod3.z.object({
+        model: import_zod3.z.string(),
+        id: import_zod3.z.string(),
+        readAt: import_zod3.z.number().optional()
+      }),
+      import_zod3.z.object({
+        group: import_zod3.z.string(),
+        readAt: import_zod3.z.number().optional()
+      })
+    ]);
     claimStatusSchema = import_zod3.z.enum([
       "active",
       "committed",
@@ -5838,7 +5849,8 @@ __export(connectApply_exports, {
   logicalReplicationGuidance: () => logicalReplicationGuidance,
   passwordClause: () => passwordClause,
   postRegistrationOutcome: () => postRegistrationOutcome,
-  runConnectApply: () => runConnectApply
+  runConnectApply: () => runConnectApply,
+  tableOwnershipBlockers: () => tableOwnershipBlockers
 });
 function postRegistrationOutcome(input) {
   if (input.registered) return { exitCode: 0, notice: null };
@@ -5971,6 +5983,27 @@ async function unmanageableLedgerOwner(sql) {
   );
   return ledgerBlockedBy(rows[0]);
 }
+function tableOwnershipBlockers(rows) {
+  return rows.filter((row) => !row.can_manage && !row.is_superuser).map((row) => ({ relation: row.relation, owner: row.owner }));
+}
+async function unmanageablePublishedTableOwners(sql, tables) {
+  const scoped = tables.length > 0;
+  const rows = await sql.unsafe(
+    `SELECT format('%I.%I', n.nspname, c.relname) AS relation,
+            pg_get_userbyid(c.relowner) AS owner,
+            pg_has_role(current_user, c.relowner, 'USAGE') AS can_manage,
+            r.rolsuper AS is_superuser
+       FROM pg_class c
+       JOIN pg_namespace n ON n.oid = c.relnamespace
+       JOIN pg_roles r ON r.rolname = current_user
+      WHERE c.relkind = 'r'
+        AND n.nspname = 'public'
+        AND c.relname <> 'ablo_idempotency'
+        ${scoped ? "AND c.relname = ANY($1)" : ""}`,
+    scoped ? [tables] : []
+  );
+  return tableOwnershipBlockers(rows);
+}
 function detectProvider(hostOrTarget) {
   const host = hostOrTarget.toLowerCase();
   if (host.includes("neon.tech")) return "neon";
@@ -6096,6 +6129,28 @@ async function runConnectApply(args) {
   or drop the existing ledger so Ablo recreates it under this admin \u2014 it holds only
   idempotency replay records, safe to drop when no commit is in flight:
       ${import_picocolors8.default.cyan("DROP TABLE ablo_idempotency;")}
+`
+    );
+    process.exit(1);
+  }
+  const foreignTables = await unmanageablePublishedTableOwners(admin, args.tables).catch(() => []);
+  if (foreignTables.length > 0) {
+    await admin.end({ timeout: 2 });
+    const list = foreignTables.map((t) => `${t.relation} (owned by ${t.owner})`).join("\n      ");
+    const alters = foreignTables.map((t) => `ALTER TABLE ${t.relation} OWNER TO ${quoteIdent(capability.rolname)};`).join(" ");
+    const plural = foreignTables.length === 1;
+    console.error(
+      import_picocolors8.default.red(
+        `
+  ${import_picocolors8.default.bold(String(foreignTables.length))} published table${plural ? "" : "s"} ${plural ? "is" : "are"} owned by another role, but you connected as ${import_picocolors8.default.bold(capability.rolname)}:`
+      ) + `
+      ${list}
+
+  Ablo grants the writer role access to your published tables, and Postgres reserves that
+  for the table's owner. Reassign them to your admin \u2014 metadata only, your rows and RLS
+  policies are untouched, and it works when your admin is a member of the owning role:
+      ${import_picocolors8.default.cyan(alters)}
+  Or re-run pointing ${import_picocolors8.default.bold("--url")} at the owning role's connection.
 `
     );
     process.exit(1);

package/dist/client/Ablo.js

@@ -715,10 +715,10 @@ export function Ablo(options) {
             // reconcile errors so read interest never makes a read reject or stall.
             enterScope: (scope) => store.enterScope(scope),
             pinScope: (scope) => store.pinScope(scope),
-            // `ablo.<model>.watch(ids, { ttl })` performs a scoped participant join
+            // `ablo.<model>.join(ids, { ttl })` performs a scoped participant join
             // on this model's sync group(s). WebSocket only — `join` throws
             // `AbloConnectionError` if the socket isn't ready.
-            createWatch: (modelKey, ids, options) => participantManager.join({
+            createJoin: (modelKey, ids, options) => participantManager.join({
                 scope: { [modelKey]: ids },
                 ...(options?.ttl !== undefined ? { ttlSeconds: options.ttl } : {}),
             }),
@@ -758,6 +758,7 @@ export function Ablo(options) {
             const queue = syncClient.getTransactionQueue();
             await queue.enqueueCommit(clientTxId, operations, {
                 ...(commitOptions.reads ? { reads: [...commitOptions.reads] } : {}),
+                ...(commitOptions.track ? { track: [...commitOptions.track] } : {}),
             });
             if (wait === 'queued') {
                 return { id: clientTxId, status: 'queued' };

package/dist/client/createModelProxy.d.ts

@@ -6,13 +6,14 @@
  * `retrieve` and `list`, the synchronous local-graph snapshots `get`, `getAll`,
  * and `getCount`, the writes `create`, `update`, and `delete`, the coordination
  * namespace `claim` (callable as `claim({ id })`, plus `claim.state`,
- * `claim.queue`, `claim.release`, and `claim.reorder`), `watch`, and `onChange`.
+ * `claim.queue`, `claim.release`, and `claim.reorder`), `join`, and `onChange`.
  * The factory returns a plain object; the client assembles the `ablo.<model>`
  * lookup table from one of these per model.
  */
 import { AbloClaimedError } from '../errors.js';
 import { type ModelUpdater, type ContentionOptions } from './functionalUpdate.js';
 import type { MutationOptions } from '../interfaces/index.js';
+import type { StaleNotification } from '../coordination/schema.js';
 import type { ModelRegistry } from '../ModelRegistry.js';
 import type { InstanceCache } from '../InstanceCache.js';
 import type { SyncClient } from '../SyncClient.js';
@@ -27,6 +28,27 @@ export interface ModelClientMeta {
 }
 export declare function getModelClientMeta(modelClient: unknown): ModelClientMeta | undefined;
 export type ModelListScope = ModelScope | 'live' | 'archived' | 'all';
+/** Options for `track({ id })` — register a durable read-dependency on a row. */
+export interface ModelTrackParams {
+    /** The row to keep hearing about, by id. */
+    id: string;
+    /**
+     * The sync watermark this track is premised on. Omit to baseline at the
+     * current head — "tell me about anything from here on". Pass a known
+     * `lastSyncId` (e.g. the one you read the row at) to also catch a change that
+     * already landed between that read and this call.
+     */
+    readAt?: number;
+}
+/** The result of `track({ id })`. */
+export interface ModelTrackResult {
+    /**
+     * Tracks that had ALREADY fired at registration time — a change matching an
+     * open track that landed before this call. Present only when something was
+     * already stale; the ongoing signal arrives on the receipts of later commits.
+     */
+    notifications?: StaleNotification[];
+}
 /** Options for the synchronous local-pool reads `get`, `getAll`, and
  *  `onChange` — a JavaScript `filter`, an equality `where`, and a lifecycle
  *  `state`. This is the local, reactive axis; contrast {@link ServerReadOptions},
@@ -172,11 +194,11 @@ export interface ModelCollaboration<T> {
     pinScope?(scope: Record<string, string>): void | Promise<void>;
     /**
      * Opens a presence and claim subscription on this model's sync group(s) and
-     * returns the live participant handle. Backs `ablo.<model>.watch(ids)`.
+     * returns the live participant handle. Backs `ablo.<model>.join(ids)`.
      * WebSocket only, since presence needs a live socket; it is absent on other
      * client constructions, where the proxy throws a clear error.
      */
-    createWatch?(modelKey: string, ids: string | readonly string[], options?: WatchOptions): Promise<JoinedParticipant>;
+    createJoin?(modelKey: string, ids: string | readonly string[], options?: JoinOptions): Promise<JoinedParticipant>;
 }
 export interface ClaimTargetOptions<T = Record<string, unknown>> {
     /** Peer-visible description of the work being performed — the sentence a
@@ -369,8 +391,8 @@ export interface ModelDeleteParams<T> extends MutationOptions {
     readonly id: string;
     readonly claim?: Claim<T> | ClaimTargetOptions<T> | null;
 }
-/** Options for the WebSocket-only `ablo.<model>.watch(ids, options?)`. */
-export interface WatchOptions {
+/** Options for the WebSocket-only `ablo.<model>.join(ids, options?)`. */
+export interface JoinOptions {
     /**
      * Lease TTL for the underlying presence claim — the participant
      * auto-releases after this if the holder dies. Compact duration string
@@ -461,19 +483,40 @@ export interface ModelOperations<T, CreateInput> {
      */
     claim: ClaimApi<T>;
     /**
-     * Subscribes this client to the sync group(s) for one or more rows of this
-     * model and returns a live participant handle — presence (`.peers`), the
-     * scoped claim stream (`.claims`), and `.leave()` / `await using` disposal.
+     * Register a durable read-dependency on a row of this model — keep hearing
+     * about it after this call returns. Where the per-write `reads` gate lives for
+     * exactly one commit, a track persists on the server: any change that lands on
+     * the tracked row rides back on the `notifications` of your next commit, so a
+     * long-running actor learns its context went stale without re-reading. A track
+     * you already have is refreshed, not duplicated (it is an idempotent upsert).
+     *
+     * ```ts
+     * await ablo.tasks.track({ id: 'task_42' });
+     * // …minutes of other work later, on your next write…
+     * const res = await ablo.tasks.update({ id: 'task_42', data: { done: true } });
+     * res.notifications; // populated if task_42 changed under you in the meantime
+     * ```
+     *
+     * The returned `notifications` are only the tracks that had ALREADY fired at
+     * registration time; the ongoing signal arrives on later receipts.
+     */
+    track(params: ModelTrackParams): Promise<ModelTrackResult>;
+    /**
+     * Joins the sync group(s) for one or more rows of this model and returns a
+     * live participant handle — presence (`.peers`), the scoped claim stream
+     * (`.claims`), and `.leave()` / `await using` disposal. This is a presence
+     * subscription: it reports who else is here and what they hold, not row
+     * values changing — for the latter, use `onChange`.
      *
      * WebSocket only: presence needs a live socket, so this is absent on HTTP
      * clients and throws on any non-WebSocket construction.
      *
      * ```ts
-     * await using participant = await ablo.slides.watch(slideIds, { ttl: '5m' });
+     * await using participant = await ablo.slides.join(slideIds, { ttl: '5m' });
      * participant.peers; // who else is here
      * ```
      */
-    watch(ids: string | readonly string[], options?: WatchOptions): Promise<JoinedParticipant>;
+    join(ids: string | readonly string[], options?: JoinOptions): Promise<JoinedParticipant>;
     /** Subscribe to changes; the callback runs on every change. */
     onChange(callback: (entities: T[]) => void, options?: LocalReadOptions<T>): () => void;
 }

package/dist/client/createModelProxy.js

@@ -6,7 +6,7 @@
  * `retrieve` and `list`, the synchronous local-graph snapshots `get`, `getAll`,
  * and `getCount`, the writes `create`, `update`, and `delete`, the coordination
  * namespace `claim` (callable as `claim({ id })`, plus `claim.state`,
- * `claim.queue`, `claim.release`, and `claim.reorder`), `watch`, and `onChange`.
+ * `claim.queue`, `claim.release`, and `claim.reorder`), `join`, and `onChange`.
  * The factory returns a plain object; the client assembles the `ablo.<model>`
  * lookup table from one of these per model.
  */
@@ -750,11 +750,30 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         // `claim` is a callable namespace (take a claim) carrying the coordination
         // readers (`claim.state` / `claim.queue` / `claim.release` / `claim.reorder`).
         claim: claimApi,
-        watch: guard((ids, options) => {
-            if (!collaboration?.createWatch) {
-                throw new AbloValidationError(`Model "${schemaKey}" was built without a WebSocket runtime, so watch() is unavailable here. Presence needs a live socket — use the standard Ablo({ schema, apiKey }) client (not the HTTP transport).`, { code: 'model_watch_not_configured' });
+        track: guard(async (params) => {
+            const dep = {
+                model: wireModel,
+                id: params.id,
+                ...(params.readAt !== undefined ? { readAt: params.readAt } : {}),
+            };
+            // A track carries no write, so it rides the commit lane as a zero-operation
+            // commit: the queue tolerates disconnects and de-dupes replays, and the
+            // server's track-only path registers the dependency and reports anything
+            // that already fired. Reuse the same lane the batch `commits.create` door
+            // uses rather than opening a bespoke transport.
+            const clientTxId = typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+                ? crypto.randomUUID()
+                : `tx_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+            const queue = syncClient.getTransactionQueue();
+            await queue.enqueueCommit(clientTxId, [], { track: [dep] });
+            const { notifications } = await queue.waitForCommitReceipt(clientTxId);
+            return notifications && notifications.length > 0 ? { notifications } : {};
+        }),
+        join: guard((ids, options) => {
+            if (!collaboration?.createJoin) {
+                throw new AbloValidationError(`Model "${schemaKey}" was built without a WebSocket runtime, so join() is unavailable here. Presence needs a live socket — use the standard Ablo({ schema, apiKey }) client (not the HTTP transport).`, { code: 'model_join_not_configured' });
             }
-            return collaboration.createWatch(schemaKey, ids, options);
+            return collaboration.createJoin(schemaKey, ids, options);
         }),
         onChange(callback, options) {
             return autorun(() => {

package/dist/client/httpTransport.js

@@ -738,6 +738,7 @@ export function createHttpTransport(options) {
             const requestBody = {
                 operations,
                 reads: commitOptions.reads,
+                track: commitOptions.track,
             };
             const wait = commitOptions.wait ?? 'confirmed';
             let body;

package/dist/client/resourceTypes.d.ts

@@ -4,7 +4,7 @@
  * {@link HttpClaimApi} derivation. This module holds only types and has no runtime
  * imports.
  */
-import type { ReadDependency } from '../coordination/schema.js';
+import type { ReadDependency, TrackDependency } from '../coordination/schema.js';
 import type { ClientCommitReceipt, CommitStatus } from '../wire/commit.js';
 import type { ModelTarget, ModelClaim } from '../coordination/schema.js';
 export type { ModelTarget, ModelClaim };
@@ -96,6 +96,15 @@ export interface CommitCreateOptions {
      * you read, not what you write.
      */
     readonly reads?: readonly ReadDependency[] | null;
+    /**
+     * Durable read-dependencies to register as part of this batch — the persisted
+     * sibling of `reads`. Where `reads` guards only this commit, a `track` entry
+     * (`{ model, id, readAt? }` for a row or `{ group, readAt? }` for a sync group)
+     * lives on past it: a later matching change rides back on a future receipt's
+     * `notifications`. A track-only batch (just `track`, an empty `operations`) is
+     * the batch form of `ablo.<model>.track()`.
+     */
+    readonly track?: readonly TrackDependency[] | null;
 }
 /** Public projection inferred from the canonical runtime schema. */
 export type CommitReceipt = ClientCommitReceipt;

package/dist/client/wsMutationExecutor.d.ts

@@ -4,7 +4,7 @@
  * commit time because it does not exist yet when the executor is created. A
  * client wires this up automatically unless you supply your own executor.
  */
-import type { ReadDependency } from '../coordination/schema.js';
+import type { ReadDependency, TrackDependency } from '../coordination/schema.js';
 import type { MutationExecutor, MutationOperation } from '../interfaces/index.js';
 import type { CommitAck } from '../sync/commitFrames.js';
 /**
@@ -23,5 +23,5 @@ import type { CommitAck } from '../sync/commitFrames.js';
  * generation below exists only for direct, one-shot executor consumers.
  */
 export declare function createDefaultMutationExecutor(getWs: () => {
-    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>;
 } | null): MutationExecutor;

package/dist/client/wsMutationExecutor.js

@@ -34,7 +34,7 @@ export function createDefaultMutationExecutor(getWs) {
                 : `tx_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`);
         try {
             return await ws.sendCommit(operations, clientTxId, undefined, // use sendCommit's built-in 15s default; no per-call override
-            options?.causedByTaskId, options?.reads);
+            options?.causedByTaskId, options?.reads, options?.track);
         }
         catch (err) {
             // Wrap transport-level failures as connection errors so the transaction

package/dist/coordination/index.d.ts

@@ -9,7 +9,7 @@
  * Exports are listed by name rather than re-exported wholesale, so every symbol
  * that becomes part of this package's public API is a deliberate choice.
  */
-export { targetRangeSchema, participantKindSchema, wireParticipantKindSchema, participantKindFromWire, descriptionFromMeta, targetRefSchema, onStaleModeSchema, writeGuardSchema, staleNotificationSchema, readDependencySchema, claimStatusSchema, wireClaimSummarySchema, claimErrorSchema, wireClaimSchema, claimRejectionSchema, modelTargetSchema, modelClaimSchema, claimBeginPayloadSchema, claimAbandonPayloadSchema, claimReorderPayloadSchema, claimHeartbeatPayloadSchema, claimHeartbeatAckPayloadSchema, claimHeartbeatBatchPayloadSchema, claimHeartbeatBatchAckPayloadSchema, updateSubscriptionPayloadSchema, subscriptionAckPayloadSchema, commitOperationTypeSchema, commitOperationSchema, presenceKindSchema, presenceActivitySchema, presenceUpdateFrameSchema, } from './schema.js';
+export { targetRangeSchema, participantKindSchema, wireParticipantKindSchema, participantKindFromWire, descriptionFromMeta, targetRefSchema, onStaleModeSchema, writeGuardSchema, staleNotificationSchema, readDependencySchema, trackDependencySchema, claimStatusSchema, wireClaimSummarySchema, claimErrorSchema, wireClaimSchema, claimRejectionSchema, modelTargetSchema, modelClaimSchema, claimBeginPayloadSchema, claimAbandonPayloadSchema, claimReorderPayloadSchema, claimHeartbeatPayloadSchema, claimHeartbeatAckPayloadSchema, claimHeartbeatBatchPayloadSchema, claimHeartbeatBatchAckPayloadSchema, updateSubscriptionPayloadSchema, subscriptionAckPayloadSchema, commitOperationTypeSchema, commitOperationSchema, presenceKindSchema, presenceActivitySchema, presenceUpdateFrameSchema, } from './schema.js';
 export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '../policy/types.js';
 export type { Conflict, ConflictAxis, ConflictDecision, ConflictKind, ConflictOperation, ConflictPolicy, StaleContextConflict, ClaimHeldConflict, } from '../policy/types.js';
-export type { TargetRange, ParticipantKind, TargetRef, OnStaleMode, WriteGuard, StaleNotification, ReadDependency, ClaimStatus, WireClaimSummary, ClaimError, WireClaim, ClaimRejection, ModelTarget, ModelClaim, ClaimBeginPayload, ClaimAbandonPayload, ClaimReorderPayload, ClaimHeartbeatPayload, ClaimHeartbeatAckPayload, ClaimHeartbeatBatchPayload, ClaimHeartbeatBatchAckPayload, UpdateSubscriptionPayload, SubscriptionAckPayload, CommitOperationType, CommitOperation, AnyCommitOperation, PresenceKind, PresenceActivity, PresenceUpdateFrame, } from './schema.js';
+export type { TargetRange, ParticipantKind, TargetRef, OnStaleMode, WriteGuard, StaleNotification, ReadDependency, TrackDependency, ClaimStatus, WireClaimSummary, ClaimError, WireClaim, ClaimRejection, ModelTarget, ModelClaim, ClaimBeginPayload, ClaimAbandonPayload, ClaimReorderPayload, ClaimHeartbeatPayload, ClaimHeartbeatAckPayload, ClaimHeartbeatBatchPayload, ClaimHeartbeatBatchAckPayload, UpdateSubscriptionPayload, SubscriptionAckPayload, CommitOperationType, CommitOperation, AnyCommitOperation, PresenceKind, PresenceActivity, PresenceUpdateFrame, } from './schema.js';

package/dist/coordination/index.js

@@ -14,7 +14,7 @@ export {
 // Shared primitives
 targetRangeSchema, participantKindSchema, wireParticipantKindSchema, participantKindFromWire, descriptionFromMeta, targetRefSchema, 
 // Layer 3 — optimistic stale-context
-onStaleModeSchema, writeGuardSchema, staleNotificationSchema, readDependencySchema, 
+onStaleModeSchema, writeGuardSchema, staleNotificationSchema, readDependencySchema, trackDependencySchema, 
 // Layer 2 — pessimistic claim / claim-lease
 claimStatusSchema, wireClaimSummarySchema, claimErrorSchema, wireClaimSchema, claimRejectionSchema, modelTargetSchema, modelClaimSchema, claimBeginPayloadSchema, claimAbandonPayloadSchema, claimReorderPayloadSchema, claimHeartbeatPayloadSchema, claimHeartbeatAckPayloadSchema, claimHeartbeatBatchPayloadSchema, claimHeartbeatBatchAckPayloadSchema, 
 // Read interest — area-of-interest navigation

package/dist/coordination/schema.d.ts

@@ -181,6 +181,26 @@ export declare const readDependencySchema: z.ZodUnion<readonly [z.ZodObject<{
     }>>;
 }, z.core.$strip>]>;
 export type ReadDependency = z.infer<typeof readDependencySchema>;
+/**
+ * A durable read-dependency — what a participant is watching so that a later
+ * change to it opens a {@link StaleNotification}. It is the persisted sibling of
+ * a {@link ReadDependency}: the same reference shape, minus the disposition (a
+ * track always notifies — that is what tracking is), with an optional `readAt`
+ * that defaults to the watermark of the commit that registered it. The row form
+ * watches one object; the group form watches a whole sync group ("anything in
+ * `deck:abc`"). Where a `ReadDependency` is checked once at commit and discarded,
+ * a `TrackDependency` is kept and re-checked against every future delta. See
+ * `packages/sync-engine/docs/groups.md` for how it drives change propagation.
+ */
+export declare const trackDependencySchema: 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>]>;
+export type TrackDependency = z.infer<typeof trackDependencySchema>;
 /**
  * The lifecycle of a claim. When absent on the wire it means `'active'` (an
  * additive back-compat default). The server stamps `'active'` on `claim_begin`

package/dist/coordination/schema.js

@@ -183,6 +183,28 @@ export const readDependencySchema = z.union([
         onStale: onStaleModeSchema.optional(),
     }),
 ]);
+/**
+ * A durable read-dependency — what a participant is watching so that a later
+ * change to it opens a {@link StaleNotification}. It is the persisted sibling of
+ * a {@link ReadDependency}: the same reference shape, minus the disposition (a
+ * track always notifies — that is what tracking is), with an optional `readAt`
+ * that defaults to the watermark of the commit that registered it. The row form
+ * watches one object; the group form watches a whole sync group ("anything in
+ * `deck:abc`"). Where a `ReadDependency` is checked once at commit and discarded,
+ * a `TrackDependency` is kept and re-checked against every future delta. See
+ * `packages/sync-engine/docs/groups.md` for how it drives change propagation.
+ */
+export const trackDependencySchema = z.union([
+    z.object({
+        model: z.string(),
+        id: z.string(),
+        readAt: z.number().optional(),
+    }),
+    z.object({
+        group: z.string(),
+        readAt: z.number().optional(),
+    }),
+]);
 // ─────────────────────────────────────────────────────────────────────────
 //  Layer 2 — pessimistic claims and leases
 // ─────────────────────────────────────────────────────────────────────────

package/dist/errorCodes.d.ts

@@ -161,7 +161,7 @@ export declare const ERROR_CODES: {
     readonly model_claimed: ErrorCodeSpec;
     readonly model_claimed_timeout: ErrorCodeSpec;
     readonly model_claim_not_configured: ErrorCodeSpec;
-    readonly model_watch_not_configured: ErrorCodeSpec;
+    readonly model_join_not_configured: ErrorCodeSpec;
     readonly stale_context: ErrorCodeSpec;
     readonly contention_exhausted: ErrorCodeSpec;
     readonly update_aborted: ErrorCodeSpec;

package/dist/errorCodes.js

@@ -157,7 +157,7 @@ export const ERROR_CODES = {
     model_claimed: wire('claim', 409, false, 'Another participant holds a claim on this row. Read `claim.state` to see who holds it, or queue behind them with a claim of your own.'),
     model_claimed_timeout: wire('claim', 409, false, 'Another participant held a claim on this row and did not release it in time. Retry, or read `claim.state` to see who holds it.'),
     model_claim_not_configured: client('claim', 'Claiming requires the collaboration runtime, which the standard Ablo({ schema, apiKey }) client wires up for every model automatically — there is no per-model claim configuration to add. This appears only when a model proxy is constructed directly without that runtime (an internal/advanced path).'),
-    model_watch_not_configured: client('claim', 'watch() opens a presence/claim subscription and needs a live WebSocket, so it is unavailable on the HTTP transport and on model proxies built without a socket. Use the standard Ablo({ schema, apiKey }) client (default WebSocket transport).'),
+    model_join_not_configured: client('claim', 'join() opens a presence/claim subscription and needs a live WebSocket, so it is unavailable on the HTTP transport and on model proxies built without a socket. Use the standard Ablo({ schema, apiKey }) client (default WebSocket transport).'),
     // ── stale context / idempotency (409) ──────────────────────────────
     // Not retryable at the transport: the rejected request carries its frozen
     // `readAt`, so resending the identical payload can never succeed. Recovery

package/dist/interfaces/index.d.ts

@@ -6,7 +6,7 @@
  * session-error detection, online-status checks, and the transport that carries
  * mutations to your backend. The SDK ships sensible no-op defaults where it can.
  */
-import type { ReadDependency, ParticipantKind } from '../coordination/schema.js';
+import type { ReadDependency, TrackDependency, ParticipantKind } from '../coordination/schema.js';
 import type { CommitStatus, MutationCommitResultInput } from '../wire/commit.js';
 export interface SyncLogger {
     debug(message: string, ...args: unknown[]): void;
@@ -232,6 +232,18 @@ export interface MutationOptions {
      * footprints, §4 the read-set) for the governing convention.
      */
     reads?: ReadDependency[] | null;
+    /**
+     * Durable read-dependencies — what this write (or the record it produces) should
+     * keep watching. Unlike `reads`, which is checked once at commit and discarded,
+     * each `track` entry is persisted and re-checked against every future delta; a
+     * later matching change opens a `StaleNotification` for the tracking participant,
+     * delivered at their next commit or live to a held claim. Each entry is a row
+     * (`{ model, id }`) or a sync group (`{ group }`), optionally pinned to a `readAt`
+     * baseline (defaults to this commit's watermark).
+     *
+     * See `packages/sync-engine/docs/groups.md` for how `track` drives propagation.
+     */
+    track?: TrackDependency[] | null;
 }
 /**
  * The subset of {@link MutationOptions} that travels with each write as it is

package/dist/react/AbloProvider.d.ts

@@ -15,7 +15,7 @@ import { type SyncStoreContract } from './context.js';
  *   - **One component, one import.** Consumers write the provider
  *     once at the root; nothing else needs to plumb the engine.
  *   - **Multiplayer is default.** React consumers are always browsers doing
- *     multiplayer UI, so `useWatch()` / `useAblo()` are always
+ *     multiplayer UI, so `useJoin()` / `useAblo()` are always
  *     available. No opt-in prop.
  *   - **Declarative props for app glue.** `preventUnsavedChanges`,
  *     `onSessionExpired`, `postBootstrap`, `resolveUsers` — each
@@ -110,11 +110,11 @@ export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
 export declare function AbloProvider<R extends SchemaRecord = SchemaRecord>(props: AbloProviderProps<R>): React.ReactElement;
 export type { EngineParticipant, ParticipantScope, ParticipantStatus };
 /**
- * Options for `useWatch`. The hook reuses the engine's single
+ * Options for `useJoin`. The hook reuses the engine's single
  * WebSocket and opens a scoped claim on it when `scope` is provided:
  * one TCP connection, N logical sub-syncgroup participants.
  */
-export interface UseWatchOptions {
+export interface UseJoinOptions {
     readonly scope?: ParticipantScope;
     readonly ttlSeconds?: number | string | null;
     /** Tear down + don't re-join while true. */
@@ -145,7 +145,7 @@ export interface UseWatchOptions {
 }
 /** @deprecated Use `ParticipantStatus`. */
 export type MeshParticipantStatus = ParticipantStatus;
-export interface UseWatchReturn {
+export interface UseJoinReturn {
     readonly participant: EngineParticipant | null;
     /** Everyone else on the engine's sync groups (`participant.presence.others`), bridged to React. */
     readonly peers: readonly Peer[];
@@ -159,7 +159,7 @@ export interface UseWatchReturn {
  * lifecycle status. Auto-cleans up on unmount or when `paused`
  * flips to true.
  *
- * `useWatch` is the React form of `ablo.<model>.watch` — scope-level
+ * `useJoin` is the React form of `ablo.<model>.join` — scope-level
  * read-interest + presence; returns the reactive participant facade
  * (peers/claims/status).
  *
@@ -168,10 +168,10 @@ export interface UseWatchReturn {
  * headless-bot patterns (a separate identity in the same browser
  * tab), construct a second `Ablo({ kind: 'agent', ... })` directly.
  */
-export declare function useWatch(opts: UseWatchOptions): UseWatchReturn;
+export declare function useJoin(opts: UseJoinOptions): UseJoinReturn;
 /**
  * Read-only presence: the OTHER participants currently visible to this
- * connection, bridged to React. Unlike {@link useWatch}, this does
+ * connection, bridged to React. Unlike {@link useJoin}, this does
  * NOT enter/leave a scope (no `update_subscription`, no warm-TTL churn) —
  * it is a pure reader of the engine's already-flowing presence stream.
  *
@@ -184,7 +184,7 @@ export declare function useWatch(opts: UseWatchOptions): UseWatchReturn;
  * Use this to answer "is anyone else here?" — e.g. suppressing live-cursor
  * broadcasts while alone — 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
+ * `useJoin` on the same scope would warm-drop the owner's
  * subscription on unmount).
  *
  * ```ts

package/dist/react/AbloProvider.js

@@ -211,7 +211,7 @@ const EMPTY_INTENTS = Object.freeze([]);
  * lifecycle status. Auto-cleans up on unmount or when `paused`
  * flips to true.
  *
- * `useWatch` is the React form of `ablo.<model>.watch` — scope-level
+ * `useJoin` is the React form of `ablo.<model>.join` — scope-level
  * read-interest + presence; returns the reactive participant facade
  * (peers/claims/status).
  *
@@ -220,7 +220,7 @@ const EMPTY_INTENTS = Object.freeze([]);
  * headless-bot patterns (a separate identity in the same browser
  * tab), construct a second `Ablo({ kind: 'agent', ... })` directly.
  */
-export function useWatch(opts) {
+export function useJoin(opts) {
     const ctx = useContext(AbloInternalContext);
     const engine = ctx?.engine ?? null;
     const { paused = false } = opts;
@@ -353,7 +353,7 @@ export function useWatch(opts) {
 }
 /**
  * Read-only presence: the OTHER participants currently visible to this
- * connection, bridged to React. Unlike {@link useWatch}, this does
+ * connection, bridged to React. Unlike {@link useJoin}, this does
  * NOT enter/leave a scope (no `update_subscription`, no warm-TTL churn) —
  * it is a pure reader of the engine's already-flowing presence stream.
  *
@@ -366,7 +366,7 @@ export function useWatch(opts) {
  * Use this to answer "is anyone else here?" — e.g. suppressing live-cursor
  * broadcasts while alone — 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
+ * `useJoin` on the same scope would warm-drop the owner's
  * subscription on unmount).
  *
  * ```ts
@@ -377,7 +377,7 @@ export function useWatch(opts) {
 export function usePeers(scope) {
     const ctx = useContext(AbloInternalContext);
     const engine = ctx?.engine ?? null;
-    // Resolve scope → groups through the schema (same idiom as useWatch).
+    // Resolve scope → groups through the schema (same idiom as useJoin).
     // The stringified, sorted key is the stable effect dependency.
     const scopeKey = JSON.stringify(resolveParticipantSyncGroups(scope, engine?.schema).sort());
     const groups = useMemo(() => JSON.parse(scopeKey), [scopeKey]);
@@ -394,7 +394,7 @@ export function usePeers(scope) {
         // Plain useState + onChange — presence changes on join/leave/activity
         // only (never on cursor traffic, a separate channel), so this fires
         // rarely; a frame of stale presence is harmless (same rationale as
-        // useWatch's peers bridge).
+        // useJoin's peers bridge).
         setPeers(compute());
         return presence.onChange(() => { setPeers(compute()); });
     }, [engine, scopeKey]);