@abloatai/ablo 0.34.1 → 0.35.0

package/dist/wire/index.js

@@ -1,49 +1,8 @@
-/**
- * The wire contract for the sync protocol: the HTTP envelope shapes and the
- * write-path frames, with no dependency on the client runtime. A server — a
- * route handler, an edge function — can import the envelope producers here
- * without pulling in the full sync client.
- *
- * It has two halves, used across every endpoint:
- *   - Error responses — {@link errorEnvelope}, {@link ErrorEnvelope}, and
- *     {@link statusForType} turn any thrown value into the uniform
- *     `{ type, code, param, message, doc_url, request_id }` body.
- *   - List responses — {@link listEnvelope} and {@link ListEnvelope} stamp the
- *     uniform `{ object: 'list', data, has_more, next_cursor }` collection.
- *
- * The {@link AbloError} hierarchy, {@link docUrlForCode}, and the wire-parsing
- * helpers are re-exported too, so a single import lets a route throw the right
- * typed error and serialize it back out.
- */
-export { errorEnvelope, statusForType } from './errorEnvelope.js';
-export { listEnvelope } from './listEnvelope.js';
-export { bootstrapReasonSchema } from './bootstrapReason.js';
-// The write-path frame contract: the message shapes shared by the client and
-// the server. The runtime Zod validators sit beside the interfaces and are
-// pinned to them, and they gate every operation and payload on both commit
-// transports.
-export { commitOperationSchema, commitPayloadSchema, } from './frames.js';
-// Protocol versioning: the single integer the client and server compare to
-// confirm they can speak to each other, plus the WebSocket close code used to
-// reject a mismatch. See protocolVersion.ts for the changelog and deploy rules.
-export { PROTOCOL_VERSION, MIN_SUPPORTED_PROTOCOL_VERSION, DEFAULT_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, WS_CLOSE_PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER, protocolVersionProblem, resolveProtocolVersion, } from './protocolVersion.js';
-// Commit settlement backbone. The transport receipt, server execution cache,
-// and normalized client acknowledgement are different envelopes composed from
-// this one discriminated settlement vocabulary.
-export { COMMIT_CORRELATION_ID_MAX_LENGTH, correlationIdSchema, commitStatusSchema, commitSettlementSchema, commitReceiptSchema, legacyCompatibleCommitReceiptSchema, rejectedCommitReceiptSchema, mutationResultPayloadSchema, mutationResultMessageSchema, commitAckSchema, mutationCommitResultSchema, } from './commit.js';
-// The read-path delta contract: the shape the server broadcasts to clients as the
-// payload of a `delta` or `sync_response` frame, together with the shared
-// participant vocabulary it carries. Both ends derive their delta type from these
-// schemas, so the client and server cannot drift apart.
-export { participantKindSchema, confirmationStateSchema, syncDeltaActionSchema, wireDeltaDataSchema, participantRefSchema, syncDeltaWireCoreSchema, clientSyncDeltaSchema, serverSyncDeltaSchema, } from './delta.js';
-// The error surface a wire consumer needs to throw, classify, and serialize.
-export { AbloError, AbloAuthenticationError, AbloPermissionError, AbloValidationError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, SyncSessionError, docUrlForCode, translateHttpError, errorFromWire, toAbloError, ERROR_CONTRACT_VERSION, 
-// The table mapping each error code to its HTTP status and retryable flag —
-// plain data a server can use to resolve a code's canonical status the same
-// way the client's error serializer does.
-errorCodeSpec, } from '../errors.js';
-// Protocol timing constants — the 30-second ping cadence and the lease window
-// derived from it, shared by the client heartbeat and the server keepalive,
-// claim leasing, and presence expiry (see protocol.ts) — plus the WebSocket
-// subprotocols used during the authenticated handshake.
-export { PING_INTERVAL_MS, LEASE_TTL_MS, WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL, } from './protocol.js';
+// Moved to @ablo/transaction (ADR 0013 — the settlement core extraction).
+// This shim re-exports it at the original path so in-package importers of
+// `wire/index.js` keep working; rewire to `@ablo/transaction/wire`
+// and delete this shim once the core package is fully wired.
+//
+// Line comments on purpose: tsc copies a leading JSDoc block into the
+// published `.d.ts`, and this note names a package npm has never heard of.
+export * from '../transaction/wire/index.js';

package/docs/agent-messaging.md

@@ -1,5 +1,7 @@
 # Agent Messaging
 
+> Durable handoffs between agents, linked to the claim they are about.
+
 Use a normal model when agents or humans need durable communication inside a
 syncGroup. Use claim `description` and `meta` for live coordination context.
 Use a `messages` row when the information must survive reconnects, work over
@@ -32,7 +34,6 @@ export const schema = defineSchema({
       status: z.string(),
       teamId: z.string(),
     },
-    {},
     { entityRoles: [entityRole({ kind: "team", source: "teamId" })] },
   ),
 
@@ -47,7 +48,6 @@ export const schema = defineSchema({
       aboutEntityId: z.string().optional(),
       aboutIntentId: z.string().optional(),
     },
-    {},
     { entityRoles: [entityRole({ kind: "team", source: "teamId" })] },
   ),
 });
@@ -121,7 +121,7 @@ Peers outside that syncGroup do not.
 Live clients read locally and update when deltas arrive:
 
 ```ts
-const rows = ablo.messages.getAll({
+const rows = ablo.messages.local.list({
   where: { teamId },
   orderBy: { createdAt: "asc" },
 });

package/docs/agents.md

@@ -1,14 +1,17 @@
 # Agents
 
+> The stateless participant: wake on a trigger, read, claim, commit, go idle.
+
 An agent is a **reactive** participant: it wakes on something happening, reads
 what it needs, writes a result, and goes idle. That's a request/response
 workload — so agents talk to Ablo over **plain HTTP**, holding no WebSocket. The
 credential *is* the identity; the server resolves the org, scope, and actor from
 the key on every request (the Stripe server-SDK / Liveblocks-node shape).
 
-Humans get the live plane (WebSocket: presence, optimistic, sub-100ms). Agents
-get the stateless plane (HTTP). **Both operate on the same typed, coordinated
-state — and coordinate *with each other*.**
+Agents get the stateless plane (HTTP). People — when you add the `humans()`
+plugin — get the live plane (WebSocket: presence, optimistic, sub-100ms).
+**Both operate on the same typed, coordinated state — and coordinate *with each
+other*.**
 
 <Note>
 Agents transact against your **pushed schema**, same as everyone — `ablo.tasks`
@@ -40,7 +43,7 @@ await ablo.tasks.update({ id: task.id, data: { status: "done" } });
 
 It exposes `retrieve` / `list` / `create` / `update` / `delete`, plus `commits`
 and `claim`. It does **not** expose the stateful-only surface (`get` /
-`getAll` / `getCount` local reads, `onChange` live subscription) — those need a
+`local` reads, `onChange` live subscription) — those need a
 live connection, so with `transport: 'http'` the return type narrows and they
 are a *compile error*, not a runtime surprise.
 
@@ -77,14 +80,18 @@ a message back to the claim it discusses.
 
 See [Agent Messaging](/agent-messaging) for the schema and setup details.
 
-## Humans + agents on one state
+## When a person is in the loop
+
+There's no separate "agent mode" — and no separate human mode either. The bare
+client is the coordination layer; `humans()` is the plugin that adds the live
+plane on top of it. An agent acting over HTTP and a person editing over their
+socket share the same typed state and the same coordination: the agent can claim
+the row that person is holding (and wait in line), and they see the agent's
+committed changes stream in **live** over their own socket, even though the
+agent committed over HTTP.
 
-There's no separate "agent mode." A human editing a record over their WebSocket
-and an agent acting over HTTP share the same typed state and the same coordination
-plane: the agent can claim the row a human is editing (and wait in line), and the
-human sees the agent's committed changes stream in **live** — over the human's
-own socket, even though the agent committed over HTTP. You write the agent once;
-it's a first-class participant, not a bolt-on.
+There is no `agents()` plugin, and the absence is the point — an agent is the
+default caller here, not a bolt-on.
 
 ## How an agent runs
 
@@ -101,7 +108,7 @@ agents costs nothing on the live plane — that capacity stays for humans.
 
 ## What stays on the live (human) plane
 
-`onChange` (live subscriptions) and `get`/`getAll`/`getCount` (local synced-pool
+`onChange` (live subscriptions) and the `local` reads (local synced-pool
 reads) require a WebSocket and a local store — they're for interactive UIs, not
 stateless agents. An agent reacts to an external trigger (a job/queue/webhook),
 then reads with `list`/`retrieve`. See [client behavior](/client-behavior) for

package/docs/api-keys.md

@@ -1,5 +1,7 @@
 # API Keys
 
+> The credential that carries an agent's identity and bounds what it may write.
+
 Authenticate a server-side client — a route handler, worker, or CLI — by passing an API key when you create the client.
 
 ```ts
@@ -97,10 +99,12 @@ Test and live keys are the same shape; the prefix names the environment:
 - `sk_live_…` — a key against your live data.
 
 Every org has a default sandbox, plus any number of additional
-sandboxes you create. **Data is isolated per sandbox; the schema is shared
-across the whole org.** A schema you push from a test key defines the same
-models your live keys see — only the rows differ. This mirrors how Stripe
-separates sandbox and production data while keeping the API shape identical.
+sandboxes you create. **Data is isolated per sandbox; the schema is one
+definition serving both.** A sandbox reads the production schema until it is
+pushed one of its own, so your test and live keys see the same models and only
+the rows differ — how Stripe separates sandbox and production data while keeping
+the API shape identical. A schema change reaches production when you push it
+with a live key ([Deployment](./deployment.md)).
 
 ## Scopes
 

package/docs/api.md

@@ -1,5 +1,7 @@
 # API
 
+> The per-method reference for every model call an agent or an interface can make.
+
 > **Upgrading?** Every breaking change and its migration is on the
 > [Version History & Migration Guide](./migration.md).
 
@@ -11,10 +13,12 @@ row, you can optionally `claim` it so they serialize instead of clobbering
 each other.
 
 Two things to know before the method list. **Reads come in two flavors:**
-`retrieve({ id })` / `list({ where })` are async and hit the server (use them when
-the row may not be local yet); `get(id)` / `getAll({ where })` / `getCount({ where })`
-are synchronous reads off the local graph (use them in render, after data has
-synced). **Claims don't lock.** If another writer holds the row, `claim` waits
+`retrieve({ id })` / `list({ where })` are async — they answer from what is
+already local and fall back to the server. Put `local.` in front of either and
+you get the same read restricted to what is already here, which is why it can
+return a value rather than a promise: `local.retrieve(id)`, `local.list({ where })`,
+`local.count({ where })`. Use those in render, after data has synced.
+**Claims don't lock.** If another writer holds the row, `claim` waits
 for them, re-reads the fresh row, then hands it to you — so two writers
 serialize instead of clobbering.
 
@@ -49,31 +53,31 @@ Each schema model becomes a typed model on the client:
 
 - `ablo.weatherReports.retrieve({ id })` reads one row asynchronously (server read).
 - `ablo.weatherReports.list({ where })` reads a collection asynchronously (server read).
-- `ablo.weatherReports.get(id)` reads one row synchronously from the local graph.
+- `ablo.weatherReports.local.retrieve(id)` reads one row synchronously from the local graph.
 - `ablo.weatherReports.create({ data })` creates a row.
 - `ablo.weatherReports.update({ id, data, ...options })` updates a row.
 - `ablo.weatherReports.delete({ id, ...options })` deletes a row.
 
-`retrieve`/`list` and `get`/`getAll`/`getCount` are not aliases. Use
-`retrieve({ id })` or `list({ where })` when the row may not be local yet — they
-hydrate pool → IndexedDB → network. Use `get(id)` / `getAll({ where })` /
-`getCount({ where })` for a cheap synchronous snapshot of what is already in
-the local graph.
+`local.` narrows a read to what has already synced. `retrieve({ id })` and
+`list({ where })` answer from the local graph and fall back to IndexedDB and
+then the network, so reach for them when the row may not be here yet.
+`local.retrieve(id)` and `local.list({ where })` are the same reads with the
+fallback removed — nothing to await, so they return a value.
 
 | Method | Returns | Use when |
 |---|---|---|
 | `retrieve({ id })` | `Promise<T \| undefined>` | You need one row, hydrating from local store and server. |
 | `list({ where })` | `Promise<T[]>` | You need to hydrate a collection from local store and server. |
-| `get(id)` | `T \| undefined` | You want a synchronous snapshot of one local row. |
-| `getAll(options?)` | `T[]` | You want a synchronous snapshot of a local collection. |
-| `getCount(options?)` | `number` | You want a synchronous count of local rows. |
+| `local.retrieve(id)` | `T \| undefined` | You want a synchronous snapshot of one local row. |
+| `local.list(options?)` | `T[]` | You want a synchronous snapshot of a local collection. |
+| `local.count(options?)` | `number` | You want a synchronous count of local rows. |
 | `create({ data, ...options })` | `Promise<T>` | You want to create through the schema model. |
 | `update({ id, data, ...options })` | `Promise<T>` | You want to update through the schema model. |
 | `delete({ id, ...options })` | `Promise<void>` | You want to delete through the schema model. |
 
 `retrieve`, `list`, `create`, `update`, and `delete` are the main path — they go
-through the server. `get` / `getAll` / `getCount` are **synchronous reads**
-off the rows a session has already synced, so a cheap re-read needs no round-trip.
+through the server. The `local` reads work off the rows a session has already
+synced, so a cheap re-read needs no round-trip.
 
 ## Protected Writes
 
@@ -103,7 +107,7 @@ Protected write options:
 
 ## Claims
 
-Before anyone writes a row, they can claim it so other people and agents see
+Before anyone writes a row, they can claim it so other agents and people see
 who is editing it in real time. Claims don't lock. If another writer holds the
 row, `claim` waits for them, re-reads the fresh row, then hands it to you — so
 two writers serialize instead of clobbering. A claim is temporary: it expires
@@ -206,7 +210,7 @@ The SDK is a convenience wrapper over a model-scoped HTTP surface — the same
 noun (`model`) and verbs as `ablo.<model>.…`. Non-JS callers (or curl) use it
 directly. The table below shows the shape with `{model}` as a placeholder; the
 [OpenAPI spec](./openapi.json) expands it into one **typed** path per model
-(`/api/v1/models/task`, `/api/v1/models/deck`, …, generated from your schema) so each
+(`/api/v1/models/task`, `/api/v1/models/workspace`, …, generated from your schema) so each
 endpoint documents that model's real field contract instead of a generic blob.
 
 | SDK call | HTTP |
@@ -232,7 +236,7 @@ error `code` (e.g. `stale_context`, `intent_conflict`) to act on.
 operations across rows/models that must commit together) — the per-model routes
 above are the one-record path. Both run the identical guarded-write engine.
 
-The [coordination MCP server](./mcp.md) (`@ablo/mcp`) is this same surface
+The [coordination MCP server](./mcp.md) (`@abloatai/mcp`) is this same surface
 rendered as agent tools.
 
 ## Errors

package/docs/audit.md

@@ -1,5 +1,7 @@
 # Audit log
 
+> Trace any committed change back to the key that made it, and to the person behind that key.
+
 The audit log records who changed what in your org, and when — including
 changes an AI agent made on a person's behalf. Every change is one row, and the
 rows are chained with a keyed hash (HMAC-SHA256) so you can later prove the

package/docs/cli.md

@@ -1,5 +1,7 @@
 # CLI
 
+> Scaffold a schema, connect a database, push it, and watch it sync.
+
 The `ablo` CLI gets you from an empty project to live-syncing data: scaffold a
 schema, authenticate, push the schema, and watch it sync. Your
 `defineSchema(...)` is the single source of truth: whether you run the CLI
@@ -34,7 +36,7 @@ This mirrors `stripe login`.
 | `ablo login`             | Authorize in the browser; provisions + stores a test and a live key.       |
 | `ablo login --project <slug>` | Same, but scope (and mint) the pair to a project, and make it active. |
 | `ablo logout`            | Remove the stored keys.                                                    |
-| `ablo status`            | Show the active org, mode, both keys (prefix + expiry), and server health. |
+| `ablo status`            | Show the active org, mode, both keys (prefix, what each can do, expiry), and server health. |
 | `ablo mode [sandbox\|production]` | Switch the active environment. With no argument, prompts.                         |
 
 Keys live in `~/.config/ablo/credentials.json` (mode `0600`), keyed by project
@@ -49,8 +51,11 @@ belongs to one of them. Test keys are bound to an isolated sandbox: their reads
 and writes never touch production data. Switch with `ablo mode`; `ablo dev` is always
 the sandbox by design.
 
-The schema, however, is **shared** across the org — pushing a schema (from
-either environment) defines the same models sandbox and production see; only the rows differ.
+The schema is **one definition serving both**: a sandbox reads the production
+schema until it is pushed one of its own, so your test and live keys see the same
+models and only the rows differ. Each plane keeps its own copy once pushed, so a
+schema change reaches production when you push it with a live key — see
+[Deployment](./deployment.md).
 
 ## Projects
 
@@ -100,6 +105,29 @@ profiles entirely: it acts in whatever project it was minted for.
 | `ablo pull`                        | **Direct Postgres** — generate `defineSchema(...)` from your existing tables (read-only, like `prisma db pull`).                              | `--out <path>`, `--app-schema <name>`, `--import <pkg>`, `--force`                                     |
 | `ablo check`                       | **Direct Postgres** — verify your _existing_ tables fit the schema (read-only, no schema changes).                                                       | `--schema <path>`, `--export <name>`, `--app-schema <name>`                                            |
 | `ablo generate`                    | Emit TypeScript types from the schema.                                                                                                        | `--out <path>`, `--schema`, `--export`                                                                 |
+| `ablo docs`                        | Read these pages for the version you installed — offline, no network (see [`ablo docs`](#ablo-docs)).                                          | `--json`                                                                                               |
+
+## `ablo docs`
+
+The documentation for the version in your `node_modules`, not the version on the
+website.
+
+```bash
+npx ablo docs                  # every page, with what it covers
+npx ablo docs coordination     # one page, as markdown
+npx ablo docs --json           # the page list, machine-readable
+```
+
+These pages ship inside the npm package, so they describe the code beside them
+and stay reachable with no network — the sandboxes and CI runners agents work in
+often have none. That matters most when a project is pinned: `get` / `getAll` /
+`getCount` became `retrieve` / `list` in 0.35.0, and a website always describes
+the newest release, so an agent on an earlier version reads the new name and
+writes a call its own package doesn't have.
+
+Pass a slug (`coordination`), a path (`docs/coordination.md`), or a file name
+(`AGENTS.md`). A miss names the closest page. The same pages are served over
+HTTP at `/api/docs/<slug>` and through the docs MCP server.
 
 ## `ablo dev`
 

package/docs/client-behavior.md

@@ -1,6 +1,8 @@
 # Client Behavior
 
-When several writers touch the same data at once — a person in the browser, a Server Action, an agent worker — the SDK decides whose write lands and how the others find out. This page is the reference for that: per-write options like `wait` and `onStale`, claiming a record so your slow work runs uninterrupted, and which errors are safe to retry.
+> Per-write options, claim behavior, and which errors are safe to retry.
+
+When several writers touch the same data at once — an agent worker, a Server Action, a person in the browser — the SDK decides whose write lands and how the others find out. This page is the reference for that: per-write options like `wait` and `onStale`, claiming a record so your slow work runs uninterrupted, and which errors are safe to retry.
 
 Claims don't lock. If another writer holds the row, `claim` waits for them, re-reads the fresh row, then hands it to you — so two writers serialize instead of clobbering.
 
@@ -32,7 +34,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`, `join`) 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 (the `local` reads, `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. |
@@ -52,7 +54,7 @@ Each schema model becomes a typed model:
 await ablo.ready();
 
 const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
-const local = ablo.weatherReports.get('report_stockholm');
+const local = ablo.weatherReports.local.retrieve('report_stockholm');
 
 await ablo.weatherReports.create({ data: { location: 'Stockholm', status: 'pending' } });
 await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' }, wait: 'confirmed' });
@@ -60,11 +62,11 @@ await ablo.weatherReports.delete({ id: 'report_stockholm', wait: 'confirmed' });
 ```
 
 Call `retrieve`/`list` first — they fetch from the server and you `await` them.
-After that, `get`/`getAll`/`getCount` read the already-synced data instantly with
+After that, `local.retrieve`/`local.list`/`local.count` read the already-synced data instantly with
 no `await`, and stay reactive in render. Use the async pair to load, the sync trio
 to read.
 
-`getAll` accepts the same practical read options the React selector path uses:
+`local.list` accepts the same practical read options the React selector path uses:
 `where`, `filter`, `orderBy`, `limit`, `offset`, and `state`. The `state`
 lifecycle filter defaults to `'live'`; pass `'archived'` or `'all'` when you
 intentionally want non-live rows.
@@ -91,7 +93,7 @@ await ablo.weatherReports.update({
 
 Once the server accepts the write, every other connected client gets the new row
 automatically — no polling or manual refresh on your side. React clients that use
-`useAblo((ablo) => ablo.weatherReports.get(id))` receive the new row, and selectors
+`useAblo((ablo) => ablo.weatherReports.local.retrieve(id))` receive the new row, and selectors
 such as `useAblo((ablo) => ablo.weatherReports.claim.state({ id }))`
 receive active claim state. There is
 no extra multiplayer setup beyond routing shared state through Ablo.

package/docs/concurrency-convention.md

@@ -1,5 +1,7 @@
 # Concurrency Convention
 
+> The governing rule for how Ablo resolves concurrent writes to shared state.
+
 > The governing convention for how Ablo resolves concurrent writes to shared
 > state, and the boundaries of that convention. This is the contract; the
 > three-layer mechanics live in [`coordination.md`](./coordination.md).
@@ -35,8 +37,8 @@ notification when you didn't, and the premise moved under you.
 
 ## 2. The dispositions (`onStale`)
 
-Every guarded write (and every read dependency, §4) declares how a stale premise
-should be handled. Three modes, split by whether they **force** an outcome:
+Every guarded write (and every premise declared in §4) says what should happen
+when it goes stale. Three modes, split by whether they **force** an outcome:
 
 | mode | coercive? | what the engine does | who resolves | use when |
 |---|---|---|---|---|
@@ -50,43 +52,44 @@ should be handled. Three modes, split by whether they **force** an outcome:
 
 ---
 
-## 3. What is checked: two footprints
+## 3. What is checked: two premises
 
-A conflict is a **footprint intersection** — your operation's footprint overlaps
-a concurrent delta. Ablo checks two footprints, and they are independent:
+A conflict is a **premise intersection** — what your operation was based on
+overlaps a concurrent delta. Ablo checks two premises, and they are independent.
+They differ only in what declared them:
 
-| footprint | declared by | question | scope |
+| premise | declared by | question | scope |
 |---|---|---|---|
 | **Write-target** | per-op `readAt` | "did a row I'm **writing** change since I read it?" | the rows in `operations[]` |
-| **Read-set** | batch-level `reads[]` | "did anything I **looked at** change since I read it?" | rows/groups in `reads[]`, even if not written |
+| **Batch** | batch-level `reads[]` | "did anything I **looked at** change since I read it?" | rows/groups in `reads[]`, even if not written |
 
 The write-target check alone is the narrow case the canary anomaly defeats: an
 agent reads `deal.stage`, writes `task.status`, and a peer moves `deal.stage` —
-`task` never changed, so a write-target-only check waves it through. The read-set
-closes that gap.
+`task` never changed, so a write-target-only check waves it through. The batch
+premise closes that gap.
 
 ---
 
-## 4. The read-set (`reads[]`)
+## 4. The batch premise (`reads[]`)
 
-A commit may declare, at the batch level, the premises its writes depended on.
+A commit may declare, at the batch level, what its writes were based on.
 Two granularities, developer's choice per entry:
 
 ```ts
 reads: [
-  { model: 'Slide', id: 's-1', readAt: N, fields?: ['title'] }, // ROW premise
-  { group: 'deck:abc', readAt: N, onStale: 'notify' },          // GROUP premise
+  { model: 'Document', id: 's-1', readAt: N, fields?: ['title'] }, // ROW premise
+  { group: 'workspace:abc', readAt: N, onStale: 'notify' },          // GROUP premise
 ]
 ```
 
 - **Row** — did this specific row (optionally these fields) change? The literal
   per-object premise.
 - **Group** — did *anything* in this sync group change? `group` is a sync-group
-  key (`deck:abc`, `slide:s1`, `org:X`) — the same unit a participant **watches
+  key (`workspace:abc`, `document:s1`, `org:X`) — the same unit a participant **watches
   and claims**. This is the more Ablo-native granularity.
 
-**Boundary — a stale read fires over the whole batch.** A read dependency is a
-premise for *all* the writes in the commit, so its disposition governs the batch:
+**Boundary — a stale premise fires over the whole batch.** Each entry covers
+*all* the writes in the commit, so its disposition governs the batch:
 `reject` aborts it, `notify` holds **every** write and notifies, `overwrite`
 lets them land. Per-entry `onStale` defaults to `reject`.
 
@@ -152,7 +155,7 @@ function reconcile(n: StaleNotification) {
 
 The loop **terminates** because each retry advances `readAt` to `observedSyncId`;
 a peer that keeps writing only ever notifies you against a *newer* baseline, never
-the same one twice. A group read-dep reconciles identically, except `group` is set
+the same one twice. A group premise reconciles identically, except `group` is set
 and `currentValues` is empty (re-read the group).
 
 ---
@@ -186,7 +189,7 @@ What the convention **guarantees**, and where it **stops**:
    (back-compat). *Open decision (§7).*
 
 6. **Policy seam.** Custom `ConflictPolicy` functions see **write-target**
-   conflicts (`stale_context` / `claim_held`). **Read-set** conflicts are
+   conflicts (`stale_context` / `claim_held`). **Batch-premise** conflicts are
    currently resolved directly via each entry's `onStale`, not through the policy
    seam. *Open decision (§7).*
 
@@ -205,18 +208,21 @@ These are deliberately left open; they change behavior and are the user's call.
   default to `notify` (philosophy-aligned: surface, don't overwrite) instead of
   `reject` (back-compat)? Trade-off: alignment vs. a behavior change for existing
   agent callers.
-- **Read-deps through the policy seam.** Should read-set conflicts also pass
-  through `ConflictPolicy` (requires a group-aware conflict shape), or stay on
-  the direct `onStale` mapping?
+- **Batch premises through the policy seam.** Should premise conflicts also
+  pass through `ConflictPolicy` (requires a group-aware conflict shape), or stay
+  on the direct `onStale` mapping?
 
 ---
 
 ## 8. Out of scope
 
 - Irreversible external side-effects (§6.4) — not gated by this convention.
-- Cross-object *serializability proof*. The read-set is a sound premise check,
-  not a full precedence-graph guarantee; it needs declared reads to catch a
-  premise, and a caller that declares none gets only write-target checking.
+- Cross-object *serializability proof*. A batch premise is a sound check, not
+  a full precedence-graph guarantee; it catches only what the caller declared.
+  A caller that declares nothing gets **no check at all** — not write-target
+  checking, which needs a `readAt` to check against. A plain write is
+  last-writer-wins, as §6.5 says. The floor is zero, and closing that gap is the
+  subject of ADR 0018.
 - Identity → participant-kind mapping. `writtenBy.kind` reports whatever
   authenticated (an `sk_` key resolves to `system`, not `agent`); how identities
   map to kinds is a separate concern.