@abloatai/ablo 0.32.0 → 0.34.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # 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
+
+The declarative seam introduced in 0.32.0 for carrying tenant identity into your row-level-security policies has a clearer name and a simpler shape. `tenantContext` is now `sessionSettings`, and instead of a list of `{ guc, from }` pairs it is a plain map from the Postgres session setting your policies read to the Ablo identity that fills it:
+
+```ts
+defineSchema({
+  models: { document: { /* … */ } },
+  sessionSettings: { 'app.current_org': 'orgId' },
+})
+```
+
+The setting name is the key, so a setting takes exactly one source and a duplicate is unrepresentable rather than something to validate away. If you adopted `tenantContext` in 0.32.0, rename it to `sessionSettings` and turn each `{ guc: 'app.current_org', from: 'orgId' }` into `'app.current_org': 'orgId'`; the exported names followed the rename — `TenantContextMapping` and `TenantContextSource` became `SessionSettings` and `SessionSettingSource`, and `RESERVED_TENANT_CONTEXT_GUCS` became `RESERVED_SESSION_SETTINGS`. The meaning is unchanged: Ablo fills only settings it resolves from your authenticated identity, never from client-supplied data, so a mapping can forward the tenant Ablo already trusts but can never widen a writer's scope, and settings the engine reserves for itself — `row_security`, the timeouts — are still refused at definition time. Schemas pushed before the rename keep parsing.
+
+Claims gain a fairness backstop, off by default. Claims coordinate long work by waiting rather than locking: when another participant holds a row, your `claim` joins a fair FIFO line behind it, and the holder keeps its lease alive for as long as the work runs by beating on a cadence. Nothing bounded a hold, so a holder that kept beating — and never read the `queueDepth` pressure signal each beat returns, the cue to checkpoint and release when others are waiting — could keep a contended row indefinitely, and the line behind it had no recourse but that holder's goodwill. A deployment can now configure, per model, how long a single holding may last while contenders are actually queued; a holder that runs past that fair share is preempted at the server on its next beat, which arrives as the `claim_lost` you already handle — abandon or re-claim, exactly as when a lease lapses. The guarantee is deliberately narrow: a holder with no one waiting is never preempted however long it runs, so open-ended solo work is untouched, and preemption is a fairness decision, never a correctness one — a preempted holder's next write is still checked at commit against the row's version and fencing token, so the worst it can cause is a clean re-read, never a lost update.
+
+### Patch Changes
+
+Connecting a database a second time now behaves the way you'd expect. `ablo connect --apply` publishes exactly the tables you name with `--tables`, and until now it assumed that publication didn't exist yet — so on a database that had already been connected, the step to publish your tables quietly did nothing, and the writer role ended up granted on one set of tables while Ablo was still reading a different, older set. Registration then refused the writer as "not ready," which was correct but baffling: the two halves disagreed and nothing said so. Apply now reconciles the publication to match your `--tables` on every run — adding what's newly named, dropping what's no longer there, the same declarative model a CDC tool like Debezium uses — and prints what it's about to add or drop before it touches anything, so narrowing the set is a decision you see rather than a surprise.
+
+When a readiness check does fail, the reason is finally visible. The direct-write preflight has always returned a precise checklist — which privilege is missing, on which table, and the exact grant to fix it — but the CLI was reading it from the wrong place in the error and rendered a blank message that sent you in circles. The checklist now prints under the failure, one line per unmet requirement, with the fix.
+
 ## 0.32.0
 
 ### Minor Changes

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <strong>Let people and AI agents work on the same data without overwriting each other.</strong>
+  <strong>The coordination infrastructure for fleets of AI agents.</strong>
 </p>
 
 <p align="center">
@@ -23,17 +23,28 @@
 
 ---
 
-When an agent and a person change the same thing at once, work gets lost: one
-edit silently clobbers another, or the agent acts on data that already moved.
-Ablo gives them one shared, typed write path so people, server actions, and
-agents can all work on the same rows without working blind.
+Development stopped being the bottleneck; coordination is. The moment a *fleet*
+of agents — not one, and not just people — edits the same rows, work gets lost:
+one agent clobbers another, or acts on data that already moved. Ablo is the
+infrastructure that lets the fleet work as one — the load-bearing coordination
+layer the way operational-transform and presence sit invisibly under a shared
+document. You build the agents; Ablo is the substrate that lets them run together
+on shared state without stepping on each other, with the people and server
+actions alongside them on the exact same path.
 
 The core idea is a **claim**. An agent's work is rarely one instant write; it
-reads something, thinks, calls an LLM or tool, then writes back. While that is
-happening, the row can change underneath it. So before slow work starts, the
-agent claims the row. If someone else is already working on it, `claim` waits,
-re-reads the fresh row, then hands it over. No stale overwrite, no separate
-agent mutation path.
+reads something, thinks, calls an LLM or a tool, then writes back — and in that
+gap the row can move under it. So before the slow work starts, the agent claims
+the row. If another agent is already on it, `claim` waits its turn in a fair
+line, re-reads the fresh row, then hands it over. No stale overwrite, no separate
+agent mutation path. People are exempt by policy: a human edit is never made to
+queue behind an agent, and by declared conflict rules always wins.
+
+When the row moves anyway — say a record an agent generated against gets bumped
+the moment before it commits — the commit is rejected and the agent is handed
+back exactly the records that changed, so it re-reads only those, not the world.
+The pattern we kept measuring: with real agents contending on shared state, the
+win comes from the coordination layer, not a bigger model. Org beats intelligence.
 
 Under the hood, you define your data once with a Zod schema and get the same
 typed model client for every actor — people, server actions, and agents:
@@ -63,8 +74,9 @@ yet? A **sandbox** `sk_test` key holds throwaway **test data** — like Stripe t
 mode — so you can explore before pointing it at your Postgres. Test-mode only; in
 production every row lives in your database.)
 
-**Built for** collaborative editors, AI agent workflows, background workers on
-your own infrastructure, and internal tools — anywhere people and agents change
+**Built for** fleets of agents working a shared backlog, AI agent workflows on
+your own infrastructure, collaborative editors where agents and people co-edit,
+and internal tools — anywhere agents (and the people alongside them) change
 shared state and everyone has to see it live.
 
 ## Set up

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",
@@ -5431,6 +5442,55 @@ BEGIN
 END $$;`
   ];
 }
+function reconcilePublicationPlan(current, desiredTables) {
+  const pub = quoteIdent(ABLO_PUBLICATION);
+  const desiredAll = desiredTables.length === 0;
+  const target = desiredAll ? "FOR ALL TABLES" : `FOR TABLE ${desiredTables.map(quoteIdent).join(", ")}`;
+  if (!current.exists) {
+    return {
+      sql: [`CREATE PUBLICATION ${pub} ${target};`],
+      added: desiredAll ? [] : [...desiredTables],
+      removed: [],
+      recreated: false
+    };
+  }
+  if (current.allTables !== desiredAll) {
+    return {
+      sql: [`DROP PUBLICATION IF EXISTS ${pub};`, `CREATE PUBLICATION ${pub} ${target};`],
+      added: desiredAll ? [] : desiredTables.filter((t) => !current.tables.includes(t)),
+      removed: current.allTables ? [] : current.tables.filter((t) => !desiredTables.includes(t)),
+      recreated: true
+    };
+  }
+  if (desiredAll) {
+    return { sql: [], added: [], removed: [], recreated: false };
+  }
+  const added = desiredTables.filter((t) => !current.tables.includes(t));
+  const removed = current.tables.filter((t) => !desiredTables.includes(t));
+  if (added.length === 0 && removed.length === 0) {
+    return { sql: [], added: [], removed: [], recreated: false };
+  }
+  return {
+    sql: [`ALTER PUBLICATION ${pub} SET TABLE ${desiredTables.map(quoteIdent).join(", ")};`],
+    added,
+    removed,
+    recreated: false
+  };
+}
+async function readPublicationState(sql) {
+  const pubRows = await sql.unsafe(
+    `SELECT puballtables FROM pg_publication WHERE pubname = $1`,
+    [ABLO_PUBLICATION]
+  );
+  const pubRow = pubRows[0];
+  if (!pubRow) return { exists: false, allTables: false, tables: [] };
+  if (pubRow.puballtables) return { exists: true, allTables: true, tables: [] };
+  const tableRows = await sql.unsafe(
+    `SELECT tablename FROM pg_publication_tables WHERE pubname = $1 AND schemaname = 'public' ORDER BY tablename`,
+    [ABLO_PUBLICATION]
+  );
+  return { exists: true, allTables: false, tables: tableRows.map((r2) => r2.tablename) };
+}
 async function probeReadiness(sql, opts = {}) {
   const publication = opts.publication ?? ABLO_PUBLICATION;
   const items = [];
@@ -5568,7 +5628,7 @@ async function registerDirectDataSource(opts) {
       )
     );
   } else if (code === "database_not_replication_ready" || code === "data_source_blocked") {
-    for (const f of body.details?.failures ?? []) {
+    for (const f of body.failures ?? body.details?.failures ?? []) {
       console.error(
         `  ${import_picocolors6.default.red("\u2717")} ${import_picocolors6.default.bold(f.item ?? "item")}${f.actual ? import_picocolors6.default.dim(` (${f.actual})`) : ""}`
       );
@@ -5580,7 +5640,8 @@ async function registerDirectDataSource(opts) {
   Apply the fixes, verify with ${import_picocolors6.default.bold("ablo connect check")}, then re-run.`)
     );
   } else if (code === "database_unreachable" || code === "source_unreachable") {
-    if (body.details?.reason) console.error(import_picocolors6.default.dim(`  ${body.details.reason}`));
+    const reason = body.reason ?? body.details?.reason;
+    if (reason) console.error(import_picocolors6.default.dim(`  ${reason}`));
     console.error(
       import_picocolors6.default.dim(
         `  Ablo's servers must be able to reach this database \u2014 a localhost or private-network
@@ -5592,7 +5653,7 @@ async function registerDirectDataSource(opts) {
   console.error();
   return false;
 }
-var import_picocolors6, import_zod6, ABLO_PUBLICATION, ABLO_REPLICATION_ROLE, ABLO_WRITE_ROLE, DIRECT_DATA_SOURCE_ROUTES, DataSourceRegisterSuccess, DataSourceRegisterError;
+var import_picocolors6, import_zod6, ABLO_PUBLICATION, ABLO_REPLICATION_ROLE, ABLO_WRITE_ROLE, DIRECT_DATA_SOURCE_ROUTES, DataSourceRegisterSuccess, ReadinessFailure, DataSourceRegisterError;
 var init_connectSetup = __esm({
   "src/cli/connectSetup.ts"() {
     "use strict";
@@ -5614,17 +5675,20 @@ var init_connectSetup = __esm({
       host: import_zod6.z.string().optional(),
       status: import_zod6.z.string().optional()
     });
+    ReadinessFailure = import_zod6.z.object({
+      item: import_zod6.z.string().optional(),
+      actual: import_zod6.z.string().optional(),
+      fix: import_zod6.z.string().optional()
+    });
     DataSourceRegisterError = import_zod6.z.object({
       code: import_zod6.z.string().optional(),
       message: import_zod6.z.string().optional(),
+      // Canonical: top-level, spread from the engine's `details`.
+      failures: import_zod6.z.array(ReadinessFailure).optional(),
+      reason: import_zod6.z.string().optional(),
+      // Fallback: a wrapping proxy or older engine that nested the same payload.
       details: import_zod6.z.object({
-        failures: import_zod6.z.array(
-          import_zod6.z.object({
-            item: import_zod6.z.string().optional(),
-            actual: import_zod6.z.string().optional(),
-            fix: import_zod6.z.string().optional()
-          })
-        ).optional(),
+        failures: import_zod6.z.array(ReadinessFailure).optional(),
         reason: import_zod6.z.string().optional()
       }).optional(),
       error: import_zod6.z.object({ code: import_zod6.z.string().optional(), message: import_zod6.z.string().optional() }).optional()
@@ -5785,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 };
@@ -5829,18 +5894,21 @@ function connectApplyPlan(input) {
       sql: []
     }
   ];
+  const reconcile2 = input.existingPublication ? reconcilePublicationPlan(input.existingPublication, tables) : null;
+  const publicationSql = reconcile2 ? reconcile2.sql : [
+    `DO $$ BEGIN
+  CREATE PUBLICATION ${quoteIdent(ABLO_PUBLICATION)} ${publicationTarget};
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;`
+  ];
+  const publicationDetail = reconcile2?.sql.length === 0 ? "already publishing exactly these tables \u2014 nothing to change" : tables.length > 0 ? `a read stream of the ${tables.length} table${tables.length === 1 ? "" : "s"} you chose` : "a read stream of your tables";
   return [
     ...walStep,
     {
       key: "publication",
       title: "Publish your tables to Ablo",
-      detail: tables.length > 0 ? `a read stream of the ${tables.length} table${tables.length === 1 ? "" : "s"} you chose` : "a read stream of your tables",
-      sql: [
-        `DO $$ BEGIN
-  CREATE PUBLICATION ${quoteIdent(ABLO_PUBLICATION)} ${publicationTarget};
-EXCEPTION WHEN duplicate_object THEN NULL;
-END $$;`
-      ]
+      detail: publicationDetail,
+      sql: publicationSql
     },
     {
       key: "replication-role",
@@ -5915,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";
@@ -6040,12 +6129,38 @@ 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);
   }
   const provider = detectProvider(target);
   const walReady = await currentWalLevel(admin) === "logical";
+  const existingPublication = await readPublicationState(admin).catch(
+    () => ({ exists: false, allTables: false, tables: [] })
+  );
+  const pubReconcile = reconcilePublicationPlan(existingPublication, args.tables);
   const replicationPassword = generateRolePassword();
   const writePassword = generateRolePassword();
   const buildPlan = (mode2) => connectApplyPlan({
@@ -6057,9 +6172,21 @@ async function runConnectApply(args) {
       writeClause: passwordClause(writePassword, mode2)
     },
     walAlreadyLogical: walReady,
-    provider
+    provider,
+    existingPublication
   });
   const steps = buildPlan("scram-verifier");
+  if (pubReconcile.removed.length > 0 || pubReconcile.recreated) {
+    console.log(
+      `  ${import_picocolors8.default.yellow("!")} ${import_picocolors8.default.bold(ABLO_PUBLICATION)} already publishes a different set; reconciling to your ${import_picocolors8.default.bold("--tables")}:`
+    );
+    for (const t of pubReconcile.added) console.log(`      ${import_picocolors8.default.green("+")} ${t}`);
+    for (const t of pubReconcile.removed)
+      console.log(`      ${import_picocolors8.default.red("-")} ${t} ${import_picocolors8.default.dim("(stops replicating to Ablo)")}`);
+    if (pubReconcile.recreated && existingPublication.allTables)
+      console.log(`      ${import_picocolors8.default.red("-")} ${import_picocolors8.default.dim("every other table (was FOR ALL TABLES)")}`);
+    console.log();
+  }
   printPlan2(steps, args.showSql);
   if (!args.yes) {
     if (!process.stdout.isTTY) {

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