@abloatai/ablo 0.56.0 → 0.58.0

package/docs/operating-on-your-database.md

@@ -39,6 +39,13 @@ Ablo prevents a non-holder from writing through another participant's claim by
 default. It does not infer that every plain update is a read-modify-write
 operation; use the guarded forms when lost-update protection matters.
 
+Direct SQL remains outside that enforcement path. If an existing application
+service writes the same row directly, keep its database constraints and locks
+as the final integrity boundary and route every participating caller through
+one named operation. Ablo can select one worker before expensive work begins;
+the existing service must still re-read, validate, and commit authoritatively.
+See [Coordinate an existing database operation](./coordination.md#coordinate-an-existing-database-operation).
+
 ## Three kinds of action
 
 Sort any action you're about to take into one of these, and the right move

package/docs/quickstart.md

@@ -10,10 +10,11 @@ confirms it by tailing your write-ahead log (WAL). Your rows live in your databa
 which stays the system of record. Ablo writes rows but **runs no DDL and owns no
 schema** — your migration tool stays in charge of the shape of your database.
 
-> No database yet? Pass an `apiKey` only and Ablo keeps your rows in its own log,
-> so you can build the whole app today. Point it at a
-> separate or local Postgres for a development branch, or at your production
-> database when you're ready.
+> **Which database?** A branch needs one connected before a schema will push, so
+> start on a throwaway rather than your production Postgres. `ablo dev` gives
+> each Git branch its own isolated plane: point a development branch at a local
+> or separate database, and connect your production one when you're ready for it
+> to be the system of record.
 
 ## 1. Install and initialize
 
@@ -26,14 +27,16 @@ npx ablo init
 by signing you in — one browser click, and a project-scoped `mk_` management
 credential is saved locally. Later, `npx ablo dev` (step 4) prepares an isolated branch and writes
 its temporary `ABLO_API_KEY` into `.env.local`, so the SDK follows your Git
-branch with no manual copy-paste. `npx ablo login` also exists standalone. In
-CI, set project management access explicitly:
+branch with no manual copy-paste. `npx ablo login` also exists standalone.
+Headless CI uses the same credential input as every other Ablo process; during branch
+preparation it contains an `mk_` credential:
 
 ```bash
-export ABLO_MANAGEMENT_KEY=mk_...
+export ABLO_API_KEY=mk_...
 ```
 
-Every runtime call needs a branch-bound API key. `ablo dev` exchanges the
+Do not pass that value to application code. Every runtime call needs a
+branch-bound API key. `ablo dev` exchanges the
 stored management credential for
 an expiring `sk_*` key bound to the current development branch.
 Production runtimes use `sk_*`. In production a key points at the database
@@ -67,9 +70,12 @@ export const schema = defineSchema({
 });
 ```
 
-**Reserved fields** — `id`, `createdAt`, `updatedAt`, `organizationId`, and
-`createdBy` are provided by the SDK automatically. Don't declare them in your
-`model(...)` fields; declare only your own.
+**`id` is the only automatic field.** Every row carries one, so leave it out of
+`model(...)`. Everything else is yours, audit fields included: declare
+`createdAt`, `updatedAt` or `createdBy` and `ablo migrate` gives each a column,
+which your write or a database default then fills. Ablo does not write them for
+you. A model that omits them still reads and writes, it just orders and
+attributes its history less precisely.
 
 The schema is registered once (init scaffolds `ablo/register.ts` for you), and
 every type is one parameter away — no `typeof schema` re-stating, anywhere:
@@ -229,12 +235,12 @@ const updated = await ablo.weatherReports.update({
 console.log({ id: updated.id, status: updated.status }); // { id: '...', status: 'ready' }
 ```
 
-Read a single row back with `get({ id })`. It resolves to the row, or to
+Read a single row back with `read({ id })`. It resolves to the row, or to
 `undefined` when no row has that id — so narrow it once, then the fields are
 fully typed:
 
 ```ts
-const report = await ablo.weatherReports.get({ id: created.id });
+const report = await ablo.weatherReports.read({ id: created.id });
 if (!report) throw new Error(`weatherReports ${created.id} not found`);
 
 console.log(report.status); // 'ready'

package/docs/react.md

@@ -25,7 +25,7 @@ as props. Construct the client once, then pass that instance to the provider.
 
 ```ts
 // lib/ablo.ts
-import Ablo from '@abloatai/ablo';
+import { Ablo } from '@abloatai/ablo/react';
 import { createAbloReact } from '@abloatai/ablo/react';
 import { schema } from '@/ablo/schema';
 
@@ -140,12 +140,12 @@ const reports = useAblo((ablo) =>
 ## Server Load
 
 ```tsx
-const report = await ablo.weatherReports.get({ id });
+const report = await ablo.weatherReports.read({ id });
 ```
 
 Use `get` in Server Components when the row may not be in the local pool
 yet — it hydrates from the local store and the server, and returns a Promise, so
-`await` it. (Server reads come in two shapes: `get({ id })` for one row and
+`await` it. (Server reads come in two shapes: `read({ id })` for one row and
 `list({ where })` for many; both are async. The synchronous local reads are
 the `local` reads, used in render below.)
 
@@ -156,12 +156,12 @@ For Server Actions and route handlers, call the SDK directly:
 ```ts
 import { ablo } from '@/lib/ablo';
 
-const snap = ablo.snapshot({ weatherReports: id });
+const report = await ablo.weatherReports.read({ id });
+if (!report) throw new Error('report not found');
 await ablo.weatherReports.update({
   id,
   data: patch,
-  readAt: snap.stamp,
-  onStale: 'reject',
+  reads: [report],
 });
 ```
 
@@ -173,12 +173,12 @@ const ablo = useAblo();
 
 async function markReady() {
   if (!ablo) return;
-  const snap = ablo.snapshot({ weatherReports: id });
+  const report = await ablo.weatherReports.read({ id });
+  if (!report) return;
   await ablo.weatherReports.update({
     id,
     data: { status: 'ready' },
-    readAt: snap.stamp,
-    onStale: 'reject',
+    reads: [report],
   });
 }
 ```

package/docs/schema-contract.md

@@ -51,26 +51,27 @@ The model key (`weatherReports`) becomes the client namespace
 contract. You should not create a parallel string-keyed write path for the same
 data.
 
-### Reserved fields
+### The one field you don't declare
 
-The SDK provides these on every row automatically — do **not** declare them in
-your `model(...)` fields:
+`id` is supplied on every row, so leave it out of your `model(...)` fields. That
+is the whole list.
 
-- `id`
-- `createdAt`
-- `updatedAt`
-- `organizationId`
-- `createdBy`
+Two things look like framework territory and are not. **Audit fields are yours to
+declare and yours to fill.** Add `createdAt`, `updatedAt` or `createdBy` and
+`ablo migrate` gives each a column, which your own write or a database default
+then populates; Ablo records who changed what in its transaction log and does not
+write these columns for you. Omit them and no column is created at all; the model
+still reads and writes, it just orders and attributes its history less precisely.
 
-Declare only your own fields; the reserved ones are still present on the row and
-readable, you just don't author them.
+**The tenancy column** (`organizationId` by default) comes from the model's
+`policy` rather than its field list, so you neither declare it nor lose it.
 
 ## Reads and writes
 
 Use async reads when the row may not be local:
 
 ```ts
-const report = await ablo.weatherReports.get({ id: reportId });
+const report = await ablo.weatherReports.read({ id: reportId });
 const ready = await ablo.weatherReports.list({ where: { status: 'ready' } });
 ```
 
@@ -123,8 +124,8 @@ session route, never a raw API key.
 - Keep direct database writes out of the coordinated path unless they are reported
   back through Data Source events.
 - Use `claim` for slow read -> think -> write spans.
-- Use `readAt` + `onStale: 'reject'` when a write must fail if the row changed
-  after it was read.
+- Use `read` and pass its exact row in `reads` when a write must fail if the row
+  changed after it was read.
 
 For the shortest runnable path, start with [Quickstart](./quickstart.md). For a
 production app, continue with [Integration Guide](./integration-guide.md).

package/docs/session-settings.md

@@ -50,6 +50,7 @@ context, whether or not you map anything:
 | `app.current_participant_id` | The participant making the write |
 | `app.current_participant_kind` | Whether that participant is a person, an agent, or the system |
 | `app.current_user_id` | The person on whose behalf the write is made |
+| `app.current_subject_groups` | The subject groups the caller belongs to, as a JSON array of `group:value` strings |
 
 If your policies read these names directly, you need no mapping at all — this
 page is for the case where they read different ones.
@@ -62,6 +63,14 @@ from `app.current_org_id` can be useful as defense in depth, but it is not a
 substitute for the tenant policy and you should never loosen RLS to make an
 Ablo write pass.
 
+`app.current_subject_groups` is the one a model with a `subject` rule reads. A
+subject rule names a field and a group — `subject: { field: 'teamId', group:
+'team' }` — and Ablo provisions a policy asking whether the array contains
+`team:` followed by that row's value. The setting is always present, and it is
+`[]` when the caller belongs to no group, so a policy on a pooled connection
+reads an empty membership as an empty membership rather than inheriting what the
+previous transaction left behind.
+
 `app.current_user_id` is worth reading twice, because it has three states rather
 than two. It carries a person's id when a person is behind the write. It carries
 `*` when a backend credential is acting as the organization itself, which is the

package/docs/sessions.md

@@ -74,7 +74,7 @@ plumbing:
 ```tsx
 'use client';
 
-import Ablo from '@abloatai/ablo';
+import { Ablo } from '@abloatai/ablo/react';
 import { AbloProvider } from '@abloatai/ablo/react';
 import { schema } from '@/ablo.schema';
 

package/examples/README.md

@@ -30,8 +30,8 @@ For read-reason-write work, pass the exact returned rows that informed the
 decision. Their watermarks stay opaque:
 
 ```ts
-const record = await ablo.records.get({ id: recordId });
-const policy = await ablo.policies.get({ id: policyId });
+const record = await ablo.records.read({ id: recordId });
+const policy = await ablo.policies.read({ id: policyId });
 const result = await model({ record, policy });
 await ablo.records.update({
   id: record.id,

package/examples/agent-turn.ts

@@ -21,7 +21,7 @@ if (!recordId) throw new Error('RECORD_ID is required');
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 try {
   await ablo.ready();
-  const record = await ablo.records.get({ id: recordId });
+  const record = await ablo.records.read({ id: recordId });
   if (!record) throw new Error(`Record ${recordId} was not found`);
   const commitId = `record:${recordId}:cheap`;
   await ablo.records.update({

package/examples/data-source/customer-server.ts

@@ -114,10 +114,14 @@ export const handleAbloSource = dataSource({
     // own transaction. The example uses a synchronous in-memory
     // update; the surrounding `apply` helper shows where you would
     // open `db.transaction(async (tx) => { ... })`.
-    commit({ operations, clientTxId }) {
+    commit({ operations, clientTxId, context }) {
+      // The routes an outbox event carries come from the trusted scope Ablo
+      // signed into the request, never from the row itself. Ablo adds the
+      // organization group on its side; these are the finer ones.
+      const syncGroups = context.scope?.syncGroups ?? [];
       const rows: RecordRow[] = [];
       for (const op of operations) {
-        const row = applyOperation(op, clientTxId);
+        const row = applyOperation(op, clientTxId, syncGroups);
         if (row) rows.push(row);
       }
       return { rows };
@@ -145,6 +149,7 @@ export const handleAbloSource = dataSource({
 function applyOperation(
   op: SourceOperation,
   clientTxId: string | undefined,
+  syncGroups: readonly string[],
 ): RecordRow | null {
   if (op.model !== 'records') return null;
   const id = op.id ?? `record_${Math.random().toString(36).slice(2, 10)}`;
@@ -160,7 +165,7 @@ function applyOperation(
         : {}),
     };
     recordStore.set(id, row);
-    appendOutbox({ operation: op, entityId: id, data: row, clientTxId });
+    appendOutbox({ operation: op, entityId: id, data: row, clientTxId, syncGroups });
     return row;
   }
 
@@ -169,7 +174,7 @@ function applyOperation(
     if (!existing) return null;
     const next: RecordRow = { ...existing, ...(op.input as Partial<RecordRow>) };
     recordStore.set(id, next);
-    appendOutbox({ operation: op, entityId: id, data: next, clientTxId });
+    appendOutbox({ operation: op, entityId: id, data: next, clientTxId, syncGroups });
     return next;
   }
 
@@ -177,7 +182,7 @@ function applyOperation(
     const existing = recordStore.get(id);
     if (!existing) return null;
     recordStore.delete(id);
-    appendOutbox({ operation: op, entityId: id, data: null, clientTxId });
+    appendOutbox({ operation: op, entityId: id, data: null, clientTxId, syncGroups });
     return existing;
   }
 
@@ -189,6 +194,7 @@ function appendOutbox(input: {
   entityId: string;
   data: RecordRow | null;
   clientTxId: string | undefined;
+  syncGroups: readonly string[];
 }): void {
   outboxSequence += 1;
   outbox.push(
@@ -197,6 +203,7 @@ function appendOutbox(input: {
       operation: input.operation,
       entityId: input.entityId,
       data: input.data,
+      syncGroups: input.syncGroups,
       ...(input.clientTxId ? { clientTxId: input.clientTxId } : {}),
     }),
   );

package/examples/expensive-agent-turn.ts

@@ -49,7 +49,7 @@ try {
   if (!durable) throw new Error(`Commit ${commitId} was not retained`);
   console.log({
     identity: ablo.identity,
-    readSet: durable.readSet,
+    reads: durable.reads,
     attempts: durable.attempts,
     claims: durable.claims,
     authority: durable.authority,

package/llms.txt

@@ -6,6 +6,62 @@ Here is the problem it solves. Two agents reach for `report_stockholm` at once.
 
 Use AI SDK for the agent loop. Use Ablo when agent reads and writes must persist, coordinate with concurrent work, and leave an audit trail.
 
+## When to use Ablo
+
+Reach for Ablo when MORE THAN ONE writer changes the same rows and the second one must not clobber the first. That is the whole judgement. If a single process owns the data, an ORM against your database is simpler and you should use it.
+
+These are the jobs it is right for:
+
+- **Two or more agents on one workload.** A planner and three workers editing the same records; a swarm assigned overlapping tickets; a retry that restarts while the first attempt is still running. Each takes `claim({ id })` before its slow step, so the second waits and is handed the row as the first left it instead of overwriting.
+- **A read → LLM call → write gap.** The row can change during the seconds your model is thinking. Pass the `readAt` stamp from your read back into the write and a stale write is refused (`AbloStaleContextError`) rather than silently applied on top of someone else's.
+- **A human and an agent in the same record.** A person editing in your app is just another holder of the claim. The agent queues behind them; nobody's edit is lost, and neither side needs to know the other exists.
+- **Work that must survive the process.** Commits are durable and receipts are idempotent, so a crashed or re-scheduled agent replays its write with the same `idempotencyKey` and gets the original result instead of a duplicate.
+- **Anything you will later have to explain.** Every accepted change lands in an append-only log with who wrote it, when, and against which read. `logs` answers "what did the agents actually do" without you having instrumented for the question in advance.
+- **Data you are not allowed to move.** Ablo runs on the customer's own Postgres. It tails the replication stream and writes back through a scoped role; your rows never live in Ablo. If a data-residency or procurement rule forbids a vendor holding the records, this is the shape that passes.
+
+These are the jobs it is WRONG for, and saying so saves you a wasted integration:
+
+- **One writer, no concurrency.** Use Prisma, Drizzle, or SQL. Ablo's coordination costs a round trip and buys you nothing here.
+- **Chat history, traces, or evals.** Append-only telemetry has no contention to resolve. Write it wherever you write logs.
+- **A cache, a queue, or a pub/sub bus.** Ablo is a commit chokepoint over a system of record, not a message broker. Emit your events as usual and use Ablo for the state they are about.
+- **Vector search, embeddings, or retrieval.** Different problem. Ablo coordinates the rows; your vector store indexes them.
+- **A file, blob, or artifact store.** Coordinate the ROW that points at the object; put the bytes in object storage.
+
+How to call it, shortest path first: install `@abloatai/ablo`, run `npx ablo init --yes --framework <nextjs|vite|remix|vanilla>`, and construct `Ablo({ schema, apiKey: process.env.ABLO_API_KEY })`. Use `ablo.<model>.get({ id })` to observe a row. Use `const input = await ablo.<model>.read({ id })`, then pass `reads: [input]` to the create/update/delete whose decision used it; if the row moved, that mutation does not land. `list({ where })` is observational. Wrap anything slow and exclusive in `await using claim = await ablo.<model>.claim({ id })`. The sections below cover the rest; "Start here" is the first thing to run.
+
+## Machine-readable surfaces
+
+Everything below is public, needs no credential, and is served from `https://www.abloatai.com`:
+
+- `/llms.txt` — this file.
+- `/llms-full.txt` — the entire published documentation corpus in one fetch.
+- `/developers` — every developer surface named on one page: the SDK, the API reference, the OpenAPI document, the MCP server, the CLI.
+- `/openapi.json` — the REST contract as OpenAPI 3.1: every route, a stable `operationId` and description on each, typed responses, and the `ErrorEnvelope` every 4xx and 5xx decodes through. Generate a client from it when no SDK exists for your runtime.
+- `/mcp` — the integration-helper MCP server over Streamable HTTP. POST your JSON-RPC here; a GET returns a descriptor rather than the protocol.
+- `/.well-known/mcp` — the same Streamable HTTP server at its direct discovery endpoint, with no page/transport negotiation.
+- `/.well-known/mcp.json` — that server's manifest, in the MCP registry's `server.json` format.
+- `/api/docs/<page>` — any documentation page as plain Markdown, for a client that fetches URLs rather than speaking MCP.
+- `/sitemap.xml` — every indexable page on the domain.
+
+Pricing and plan limits are public at [Ablo pricing](https://docs.abloatai.com/pricing). Do not
+infer prices or follow a dashboard billing link: the documentation page is the canonical rate
+card and needs no sign-in.
+
+Every page on that host serves a Markdown representation from its own URL: send
+`Accept: text/markdown` (q-values are honoured), or append `.md` to the path if
+your client cannot set the header. Responses carry `Vary: Accept`, a client that
+will accept neither `text/html` nor `text/markdown` gets a `406` listing what is
+available, and a path that does not exist answers a real `404` — never a `200`
+carrying a sign-in page.
+
+## Versioning and deprecation
+
+Every route lives under `/v1`, and that segment is part of the address you call. A change that would break you arrives as a new segment beside it, never as a change to this one. Additive changes do land in `/v1` — a new response field, a new optional parameter, a new error code — so ignore what you do not recognize.
+
+Every response carries `Ablo-Version`, a date stamp for the contract being served. A route being withdrawn says so on itself for at least 180 days first: `Deprecation` (RFC 9745) carries when the deprecation took effect and the route keeps answering; `Sunset` (RFC 8594) carries when it stops. The same operations are marked `deprecated: true` in `/openapi.json`.
+
+Responses also carry `RateLimit-Policy` (the standing allowance, e.g. `"secret";q=600;w=12`) and, once your request is attributed to a key, `RateLimit` (what is left and when it refills). A 429 adds `Retry-After` in whole seconds. Pace against these rather than retrying blind.
+
 ## Surfaces: pick by who is calling
 
 Every surface reaches the same coordinated state. They are not interchangeable.
@@ -14,6 +70,7 @@ Every surface reaches the same coordinated state. They are not interchangeable.
 - Coordination MCP, `@abloatai/mcp` — an agent living inside an MCP host (Claude, Cursor). Two jobs: MANAGING your Ablo the way the CLI does (`get_schema`, `list_projects`, `create_project`, `tail_logs`, `get_usage`), and claim/commit as tools over your rows. Call `get_schema` first — it is the only way to learn the model names every data tool needs. `init`, `push`, `pull`, `generate` have no tools (they touch your repo); run those in a shell.
 - `humans()` with `@abloatai/humans/react` — the interfaces a person watches agent work arrive in. The bare client is the coordination layer (commit, read, observe, claim); `humans()` is the plugin that adds the local watchable copy, live queries, and presence. It `requires: { duplex: true }`, so a `transport: 'http'` agent is rejected at construction rather than left holding a subscription that never delivers. It remains the compatibility default for omitted `plugins`; new code should install it explicitly from `@abloatai/humans`. There is no `agents()` plugin — agents are the default caller, not a special one. A browser NEVER receives the secret key; mint a session token.
 - CLI, `ablo` — scaffolding, schema push, connecting a database. Terminals and CI. Agents must run it non-interactively (see the CLI section below).
+- CLI package, [`@abloatai/cli`](https://www.npmjs.com/package/@abloatai/cli) — the official npm package that installs the `ablo` binary.
 - REST, `/api/v1` — runtimes with no SDK.
 - Integration-helper MCP, hosted `/api/mcp` — teaching a coding assistant the SDK WHILE BUILDING an integration. Docs, schema lint, and scaffolds only; it has NO per-model data tools and cannot touch application rows.
 
@@ -52,7 +109,7 @@ const schema = defineSchema({
 
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
-const report = await ablo.weatherReports.get({ id: 'report_stockholm' });
+const report = await ablo.weatherReports.read({ id: 'report_stockholm' });
 if (!report) throw new Error('Row not found');
 
 // Claim the row (waits if someone else holds it), read the fresh copy off
@@ -64,7 +121,7 @@ const updated = await ablo.weatherReports.update({
 });
 ```
 
-That is the normal app path: declare models in a schema, then use `ablo.<model>.get({ id })`, `ablo.<model>.create(...)`, `ablo.<model>.update(...)`, and `ablo.<model>.delete(...)`. Every verb takes a single options object.
+That is the normal app path: declare models in a schema, then use `ablo.<model>.read({ id })`, `ablo.<model>.create(...)`, `ablo.<model>.update(...)`, and `ablo.<model>.delete(...)`. Every verb takes a single options object.
 
 Treat the schema as the integration contract. It drives typed model clients,
 React selectors, server and agent writes, Data Source request/response shape,
@@ -75,12 +132,12 @@ For full integrations, use `integration-guide` as the canonical doc. It covers
 the same model API across your own Data Source-backed app databases,
 React selectors, multiplayer, and future agent workers.
 
-Reads come in two flavors, and you pick by whether you can wait. `get({ id })`
-(one row) and `list({ where })` (many) are async — they answer from the local
-graph and fall back to the server, so await them. `local.get(id)`,
+Server reads separate observation from decision input. `get({ id })` and
+`list({ where })` return current data without creating stale evidence.
+`read({ id })` returns the same row with private `{ model, id, readAt }` evidence
+for a specific mutation's `reads` array. `local.get(id)`,
 `local.list({ where })`, and `local.count({ where })` are the same reads narrowed
-to what has already synced: nothing to await, reactive in render. There is no
-second verb to learn — `local.` is the only difference. The query reads accept
+to what has already synced: nothing to await, reactive in render. The collection queries accept
 `where`, `filter`, `orderBy`, `limit`, `offset`,
 and `state`; state defaults to `'live'`, with `'archived'` and `'all'` to include
 retired rows.
@@ -117,7 +174,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 block routes to `block:` + `document:` + `workspace:`), so everyone watching the workspace 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: 'workspace: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: 'workspace: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.
+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 block routes to `block:` + `document:` + `workspace:`), so everyone watching the workspace 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, pass rows returned by `ablo.<model>.read({ id })` in the mutation's `reads` array. Ablo records compact model/id/readAt evidence, not row contents. At commit the server checks whether anything moved past the read watermark; if so, the mutation does not land. Use `get` when no such relationship exists. 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. No transitive auto-recompute, no convergence guarantee for cycles.
 
 ## Nouns
 
@@ -129,7 +186,7 @@ A change to one row reaches other rows three ways. ROUTING: a write fans out to
 ## Claimed Behavior
 
 Reads never silently block. Schema reads stay open while a row is claimed.
-Typed reads through `ablo.<model>.get({ id })` return the row by default,
+Typed reads through `ablo.<model>.read({ id })` return the row by default,
 even while it is claimed. Pass `ifClaimed: 'fail'` to throw
 `AbloClaimedError`, and inspect active coordination separately through
 `ablo.<model>.claim.state({ id })`.
@@ -147,7 +204,7 @@ frees. Use `ifClaimed: 'fail'` when you'd rather refuse to read a claimed row.
 
 ## Guarantees
 
-Schema model writes update local state optimistically, while their returned promise always waits for authoritative confirmation. Server rejection rolls back local state. To prevent lost updates, read with `snapshot(...)` to capture a `readAt`, then write with `onStale: 'reject'` — the server rejects your update if someone else changed the row after that `readAt`.
+Schema model writes update local state optimistically, while their returned promise always waits for authoritative confirmation. Server rejection rolls back local state. To prevent lost updates, fetch the decision input with `read({ id })` and pass that exact row in the mutation's `reads` array. If it changed, the mutation does not land.
 
 Claims coordinate writers; they do not block readers. Most users should stay on
 schema-backed reads/writes and `claim(...)`; manual protocol bookkeeping is not
@@ -231,6 +288,11 @@ Import from these public paths only:
 
 Do not teach `/api`, `/agent`, `/core`, `/realtime`, or internal subpaths. (`/source` and `/ai-sdk` are public.)
 
+`onChange` is WebSocket-only. It exists on the reactive client because that
+client holds an open socket and a local graph. The stateless HTTP client does
+not expose it at the type or runtime level; HTTP agents re-read or inspect
+durable logs instead.
+
 ## CLI: agents run it NON-INTERACTIVELY
 
 `ablo init` and other prompts need a TTY; an agent/CI run has none and will HANG. Always:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.56.0",
+  "version": "0.58.0",
   "description": "The public Ablo SDK for coordinated reads, commits, claims, observation, and reactive applications.",
   "license": "Apache-2.0",
   "type": "module",
@@ -81,9 +81,9 @@
       "default": "./dist/ai-sdk.js"
     },
     "./context": {
-      "types": "./dist/context.d.ts",
-      "import": "./dist/context.js",
-      "default": "./dist/context.js"
+      "types": "./dist/context/index.d.ts",
+      "import": "./dist/context/index.js",
+      "default": "./dist/context/index.js"
     },
     "./wire": {
       "types": "./dist/wire.d.ts",
@@ -139,8 +139,8 @@
     "directory": "packages/ablo"
   },
   "dependencies": {
-    "@abloatai/humans": "^0.56.0",
-    "@abloatai/transaction": "^0.56.0",
+    "@abloatai/humans": "^0.58.0",
+    "@abloatai/transaction": "^0.58.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {

package/dist/context/sources.d.ts

@@ -1,21 +0,0 @@
-import { z } from 'zod';
-import type { ContextEvidenceSlice } from './evidence.js';
-export declare const contextSourceSchema: z.ZodReadonly<z.ZodDiscriminatedUnion<[z.ZodObject<{
-    key: z.ZodString;
-    kind: z.ZodLiteral<"ablo">;
-    guarantee: z.ZodLiteral<"guardable">;
-    cursor: z.ZodNumber;
-}, z.core.$strip>, z.ZodObject<{
-    key: z.ZodString;
-    kind: z.ZodLiteral<"value">;
-    guarantee: z.ZodLiteral<"informational">;
-    cursor: z.ZodNull;
-}, z.core.$strip>, z.ZodObject<{
-    key: z.ZodString;
-    kind: z.ZodLiteral<"mixed">;
-    guarantee: z.ZodLiteral<"partial">;
-    cursor: z.ZodNumber;
-}, z.core.$strip>], "kind">>;
-export type ContextSource = z.infer<typeof contextSourceSchema>;
-export declare function sourceFor(key: string, evidence: ContextEvidenceSlice): ContextSource;
-//# sourceMappingURL=sources.d.ts.map

package/dist/context/sources.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../../src/context/sources.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE1D,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;4BAmBnB,CAAC;AAEd,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,wBAAgB,SAAS,CACvB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,oBAAoB,GAC7B,aAAa,CAaf"}

package/dist/context/sources.js

@@ -1,36 +0,0 @@
-import { z } from 'zod';
-export const contextSourceSchema = z.discriminatedUnion('kind', [
-    z.object({
-        key: z.string(),
-        kind: z.literal('ablo'),
-        guarantee: z.literal('guardable'),
-        cursor: z.number().int().nonnegative(),
-    }),
-    z.object({
-        key: z.string(),
-        kind: z.literal('value'),
-        guarantee: z.literal('informational'),
-        cursor: z.null(),
-    }),
-    z.object({
-        key: z.string(),
-        kind: z.literal('mixed'),
-        guarantee: z.literal('partial'),
-        cursor: z.number().int().nonnegative(),
-    }),
-]).readonly();
-export function sourceFor(key, evidence) {
-    if (evidence.reads.length === 0) {
-        return contextSourceSchema.parse({
-            key,
-            kind: 'value',
-            guarantee: 'informational',
-            cursor: null,
-        });
-    }
-    const cursor = Math.max(...evidence.reads.map((item) => item.entry.watermark));
-    return evidence.includesInformational
-        ? contextSourceSchema.parse({ key, kind: 'mixed', guarantee: 'partial', cursor })
-        : contextSourceSchema.parse({ key, kind: 'ablo', guarantee: 'guardable', cursor });
-}
-//# sourceMappingURL=sources.js.map

package/dist/context/sources.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"sources.js","sourceRoot":"","sources":["../../src/context/sources.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IAC9D,CAAC,CAAC,MAAM,CAAC;QACP,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;QACf,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;QACvB,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;QACjC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;KACvC,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;QACf,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;QACxB,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC;QACrC,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE;KACjB,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;QACf,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;QACxB,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;QAC/B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;KACvC,CAAC;CACH,CAAC,CAAC,QAAQ,EAAE,CAAC;AAId,MAAM,UAAU,SAAS,CACvB,GAAW,EACX,QAA8B;IAE9B,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChC,OAAO,mBAAmB,CAAC,KAAK,CAAC;YAC/B,GAAG;YACH,IAAI,EAAE,OAAO;YACb,SAAS,EAAE,eAAe;YAC1B,MAAM,EAAE,IAAI;SACb,CAAC,CAAC;IACL,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IAC/E,OAAO,QAAQ,CAAC,qBAAqB;QACnC,CAAC,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;QACjF,CAAC,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC;AACvF,CAAC"}

package/dist/context.d.ts

@@ -1,22 +0,0 @@
-import type { CapturedRow } from '@abloatai/transaction';
-import { type AwaitedDeep } from './context/await.js';
-import { type ContextSource } from './context/sources.js';
-export { contextSourceSchema, type ContextSource } from './context/sources.js';
-export type { AwaitedDeep } from './context/await.js';
-export interface ContextOptions<TData extends Readonly<Record<string, unknown>>> {
-    /** The client whose read evidence may guard a later write. */
-    readonly ablo: object;
-    /** Values selected by the application. Nested promises are accepted. */
-    readonly data: TData;
-}
-export interface ContextResult<TData extends Readonly<Record<string, unknown>>> {
-    readonly data: AwaitedDeep<TData>;
-    /** Exact returned Ablo rows, ready to pass to a write's `reads` option. */
-    readonly reads: readonly CapturedRow[];
-    /** The greatest watermark among included authoritative reads. */
-    readonly cursor: number | null;
-    readonly sources: readonly ContextSource[];
-}
-/** Assemble selected application values and the Ablo evidence they retain. */
-export declare function context<const TData extends Readonly<Record<string, unknown>>>(options: ContextOptions<TData>): Promise<ContextResult<TData>>;
-//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjE,OAAO,EAAa,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErE,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC/E,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAItD,MAAM,WAAW,cAAc,CAAC,KAAK,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7E,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;CACtB;AAED,MAAM,WAAW,aAAa,CAAC,KAAK,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5E,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;CAC5C;AAED,8EAA8E;AAC9E,wBAAsB,OAAO,CAAC,KAAK,CAAC,KAAK,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACjF,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC,GAC7B,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAsB/B"}