@abloatai/ablo 0.33.0 → 0.34.1

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

@@ -542,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

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/index.md

@@ -50,6 +50,7 @@ Three things stay true no matter how you use Ablo:
 - [Client Behavior](./client-behavior.md) — Options, errors, retries, timeouts, and imports.
 - [Debugging & Logs](./debugging.md) — Turn on the `[Ablo]` coordination trace (`debug` / `logLevel`) to watch claims, queueing, and grants while you build — or read the same activity in code via `ClaimLog` to render an activity feed.
 - [Connect Your Database](./data-sources.md) — Keep canonical rows in your app database without giving Ablo database credentials.
+- [Operating on Your Database](./operating-on-your-database.md) — Which actions run freely, which to verify first, and which belong to a human — and how to tell.
 - [React](./react.md) — Provider, hooks, and reactive reads for React apps.
 - [API Keys](./api-keys.md) — Bearer tokens for the public API.
 
@@ -77,6 +78,7 @@ Three things stay true no matter how you use Ablo:
 - [Guarantees](./guarantees.md) — Confirmed writes, optimistic state, stale-write protection, and agent lifecycle.
 - [Coordination](./coordination.md) — `claim`, `claim.state`, and `claim.queue` for active work.
 - [Connect Your Database](./data-sources.md) — Where data lands when your app database is canonical.
+- [Operating on Your Database](./operating-on-your-database.md) — The safety model for working on a live database: reversible model writes vs. human-gated DDL, and the read-only checks that resolve the doubt.
 - [Receipt](./api.md#receipt) — Confirm what landed.
 - [Usage](./api.md#usage) — Metering and audit dimensions.
 - [Audit Log](./audit.md) — Trace any confirmed write back to the human behind it.

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/operating-on-your-database.md

@@ -0,0 +1,109 @@
+# Operating on Your Database
+
+Ablo sits over your database as a coordination layer, not an owner. It reads
+your Postgres replication stream and routes each write through a claim-checked
+commit that lands in your own tables. It never runs DDL, never migrates, never
+drops. That single boundary is why almost everything you do through Ablo is
+either read-only or reversible — and why the few actions that aren't are easy to
+name. This page is how to tell them apart, so you can work on a real database
+without guessing which move is the dangerous one.
+
+The habit that makes it easy is to look before you act. One command shows you
+the real shape of your database measured against your schema, and changes
+nothing:
+
+```bash
+npx ablo check   # read-only — reports which columns fit your models and which don't
+```
+
+When a question is about the live database — does this column exist, is it
+nullable, will this write fit — you can usually answer it by observing rather
+than reasoning in the dark.
+
+## The floor: what Ablo never does
+
+These hold on every database Ablo connects to, and they are what bound the blast
+radius of anything you do through the model API:
+
+- It **never runs DDL or migrations** on your database, and never drops a table
+  or column. Schema changes to your own tables are always your application's
+  action, run with your admin credential — never Ablo's.
+- It **never owns your rows.** Canonical data stays in your tables; Ablo hosts
+  only the transaction log and the coordination state.
+- Every model write is **claim-checked and recorded.** A write based on a row
+  that moved under you is rejected rather than applied, and the prior value is
+  retained in the log, so a confirmed change is attributable and
+  reconstructable.
+
+So a normal `ablo.<model>.update(...)` cannot silently corrupt your database:
+the worst case is a clean rejection and a re-read, not a lost row.
+
+## Three kinds of action
+
+Sort any action you're about to take into one of these, and the right move
+follows.
+
+**Run freely — read-only or reversible.**
+Reads (`retrieve`, `list`, `get`), `ablo check`, and `ablo pull` observe and
+never change anything. Previews — `--show-sql`, `--dry-run` — print the exact
+SQL a command would run without executing it. Model writes through
+`ablo.<model>.create` / `update` are claim-checked, optimistic, rolled back if
+the server rejects them, and recorded in the log with the prior value. All of
+these are safe to run on your own initiative.
+
+**Verify first — needs one look at the live database.**
+Routing an existing table's writes through a model requires the model to match
+the table's real columns. Run `ablo check`: it names the columns that fit and
+the ones that don't, so a `NOT NULL` column your model doesn't set shows up as a
+line in the report rather than a surprise at commit time. Decide the model shape
+from what `check` tells you, then proceed. Nothing here is risky — it just reads
+better after you've seen the ground truth.
+
+**Hand to a human — irreversible, outside the log's protection.**
+Raw DDL on the live database — `ALTER TABLE … OWNER TO`, adding or dropping a
+column, changing a constraint — changes the database itself and is not covered
+by the reversible log, so it belongs to a person with their hand on it. So does
+a `connect` cutover run with its confirmation skipped (`--yes`): the prompt
+exists because the step provisions real roles and reconciles publication on a
+live database, and on a shared or production database that confirmation is the
+human's to give. Removing a model from your schema belongs here too — for the
+reason below.
+
+## The one action that isn't what it looks like
+
+Deleting a model from `ablo/schema.ts` reads like a code cleanup, but it is a
+schema change. Your schema is a desired-state declaration: `ablo push` diffs it
+against the server's copy, and a model that has vanished from the schema can be
+read as a table that should no longer exist. "Nothing imports it" answers a
+code question. The question that governs safety is *does removing this drop a
+real table on the next push* — and that one is answered against the database,
+not the codebase. Before removing a model that maps a live table, confirm the
+table is gone or empty and that your push path is additive; otherwise keep the
+model until the data is dealt with. A `load: 'manual'` mapping is often present
+precisely to hold a table in place, so treat its comment as load-bearing.
+
+## The verification loop
+
+Most of the uncertainty in working on a live database dissolves into a few
+read-only checks:
+
+- `ablo check` — does the live database match the schema? Reports the exact
+  column-by-column fit. Read-only.
+- `ablo pull` — what is actually in the database, expressed as a schema.
+  Read-only, like `prisma db pull`.
+- `--show-sql` / `--dry-run` on `connect` and `migrate` — the exact statements,
+  printed and unexecuted, so you approve the SQL before it runs.
+- Read the row and its claim state before you write — `retrieve` / `list`, and
+  `ablo.<model>.claim.state({ id })` for who is already working on it.
+
+The pattern underneath all of it is steady: reads and model writes flow freely
+because the boundary and the log make them safe, DDL and cutovers pause for a
+human because they change the database itself, and the space between the two is
+one `ablo check` away from certain.
+
+## See also
+
+- [Connect Your Database](./data-sources.md) — the one path a database joins Ablo.
+- [Guarantees](./guarantees.md) — what a confirmed write, a stale check, and a claim promise.
+- [CLI & Migrations](./cli.md) — `check`, `pull`, `migrate`, and their read-only / preview flags.
+- [Schema Contract](./schema-contract.md) — how the schema drives push, and why it is a desired-state declaration.

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.33.0",
+  "version": "0.34.1",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",