@abloatai/ablo 0.56.0 → 0.58.0

package/docs/api.md

@@ -12,9 +12,11 @@ confirmed write streams to everyone watching. When two writers touch the same
 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:**
-`get({ 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
+Three things to know before the method list. **`get` observes; `read` declares.**
+Both fetch one current row, but only the exact object returned by `read({ id })`
+can be carried in a mutation's `reads` array. If it changed, that mutation does
+not land. `get({ id })` and `list({ where })` are ordinary queries with no stale
+guard. **Local reads do not fetch.** Put `local.` in front of a query 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.get(id)`, `local.list({ where })`,
 `local.count({ where })`. Use those in render, after data has synced.
@@ -38,10 +40,14 @@ const schema = defineSchema({
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
 await ablo.ready();
-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');
 
-await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' } });
+await ablo.weatherReports.update({
+  id: 'report_stockholm',
+  data: { status: 'ready' },
+  reads: [report],
+});
 ```
 
 For end-to-end app setup across React, existing backends, Data Source, and
@@ -51,14 +57,17 @@ agents, read the [Integration Guide](./integration-guide.md).
 
 Each schema model becomes a typed model on the client:
 
-- `ablo.weatherReports.get({ id })` reads one row asynchronously (server read).
-- `ablo.weatherReports.list({ where })` reads a collection asynchronously (server read).
+- `ablo.weatherReports.get({ id })` fetches one row without declaring a decision dependency.
+- `ablo.weatherReports.read({ id })` fetches one guardable decision input.
+- `ablo.weatherReports.list({ where })` fetches an observational collection.
+- `ablo.weatherReports.listAll({ where })` explicitly reads every matching page.
 - `ablo.weatherReports.local.get(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.
+- `ablo.weatherReports.claim({ id, description })` acquires a durable write lease; the HTTP form is awaited.
 
-`local.` narrows a read to what has already synced. `get({ id })` and
+`local.` narrows a query to what has already synced. `get({ id })`, `read({ 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.get(id)` and `local.list({ where })` are the same reads with the
@@ -66,37 +75,78 @@ fallback removed — nothing to await, so they return a value.
 
 | Method | Returns | Use when |
 |---|---|---|
-| `get({ id })` | `Promise<T \| undefined>` | You need one row, hydrating from local store and server. |
-| `list({ where })` | `Promise<ModelList<T>>` | You need to hydrate a collection from local store and server. |
+| `get({ id })` | `Promise<T \| undefined>` | You need to observe one current row. |
+| `read({ id })` | `Promise<CapturedRow<T> \| undefined>` | A later mutation is based on this row. |
+| `list({ where })` | `Promise<ModelList<T>>` | You need to observe a collection. |
+| `listAll({ where, maxPages?, signal? })` | `Promise<T[]>` | You deliberately need every matching row. |
 | `local.get(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. |
-
-`get`, `list`, `create`, `update`, and `delete` are the main path — they go
+| `claim({ id, description })` | `Promise<HeldClaim<T>>` | Slow or expensive work must exclude another writer. |
+| `claim.state({ id })` | `Promise<Claim \| null>` on HTTP | You need the current holder without acquiring the row. |
+| `claim.list({ id })` | `Promise<{ object: 'list'; data: Claim[] }>` on HTTP | You need every disjoint holder on the row. |
+| `claim.queue({ id })` | `Promise<ClaimQueueView>` on HTTP | You need the durable wait line. |
+| `claim.release({ id })` | `Promise<void>` on HTTP | You need to release a claim early. |
+| `claim.reorder({ id, order })` | `Promise<void>` on HTTP | A privileged coordinator needs to reorder the wait line. |
+
+`get`, `read`, `list`, `create`, `update`, `delete`, and `claim` go
 through the server. The `local` reads work off the rows a session has already
 synced, so a cheap re-read needs no round-trip.
 
-### Paging a collection
+### Reading a whole collection
+
+Prefer a filtered `listAll` when the application truly needs one complete
+array. It follows the same cursor loop as async iteration, defaults to at most
+100 pages, and checks an abort signal between requests and rows:
+
+```ts
+const controller = new AbortController();
+const open = await ablo.weatherReports.listAll({
+  where: { status: ['draft', 'review'] },
+  orderBy: { createdAt: 'asc' },
+  maxPages: 25,
+  signal: controller.signal,
+});
+```
+
+A complete traversal can be expensive in latency, memory, and read volume.
+Narrow it with `where`; use `list` and its cursor when a UI or worker can process
+one page at a time.
 
-`list` returns a page. The result is an array, so it maps and iterates as
-before, and it carries `hasMore` and `nextCursor` alongside the rows:
+`for await` walks the pages:
 
 ```ts
-let cursor: string | null = null;
 const open = [];
-do {
-  const page = await ablo.weatherReports.list({
-    where: { status: ['draft', 'review'] },
-    orderBy: { createdAt: 'asc' },
-    limit: 100,
-    ...(cursor ? { cursor } : {}),
-  });
-  open.push(...page);
-  cursor = page.hasMore ? page.nextCursor : null;
-} while (cursor);
+for await (const report of await ablo.weatherReports.list({
+  where: { status: ['draft', 'review'] },
+  orderBy: { createdAt: 'asc' },
+})) {
+  open.push(report);
+}
+```
+
+`list` returns a page, because the server applies a default size and caps the
+largest. The result is an array, so it maps and iterates as before, and it
+carries `hasMore` and `nextCursor` alongside the rows. Iterate it to work with
+the page you were handed; `for await` it to work with the collection.
+
+```ts
+const page = await ablo.weatherReports.list({ where: { status: 'draft' } });
+page.length;    // the rows this page carries
+page.hasMore;   // whether the collection continues past them
+```
+
+Take the cursor yourself when the pages go somewhere other than a loop — one
+screenful at a time, or a job that stops and resumes:
+
+```ts
+const page = await ablo.weatherReports.list({ where: { status: 'draft' }, limit: 100 });
+const next = page.hasMore
+  ? await ablo.weatherReports.list({ where: { status: 'draft' }, limit: 100, cursor: page.nextCursor })
+  : null;
 ```
 
 Keep `where` and `orderBy` the same across pages: the cursor encodes the sort
@@ -106,30 +156,51 @@ position it was issued for, and a read that changes either starts a new walk.
 `{ status: ['draft', 'review'] }` is an `IN`, and tuple form spells the rest
 out, as in `[['title', 'ILIKE', '%storm%'], ['createdAt', '>=', cutoff]]`.
 
-## Protected Writes
+### Changing a field, and clearing one
+
+`null` clears a field:
 
-Use `snapshot` when a write should reject if the row changed mid-flight:
+```ts
+await ablo.weatherReports.update({ id, data: { reviewerId: null } });   // unassigned
+await ablo.weatherReports.update({ id, data: { reviewerId: 'usr_2' } }); // reassigned
+```
+
+An update is a patch, so a field you leave out keeps its value. That makes
+`undefined` and "leave it alone" the same thing: `{ reviewerId: undefined }`
+is dropped from the payload and the old reviewer stays. Reach for `null`
+whenever a value is going away, and the type will hold you to it — only a
+field your schema declares optional accepts one, since a required field has no
+empty value to move to.
+
+## Guarded Writes
+
+Use `read` when a write depends on the row's current state, then pass that exact
+row in `reads`:
 
 ```ts
-const snap = ablo.snapshot({ weatherReports: 'report_stockholm' });
+const report = await ablo.weatherReports.read({ id: 'report_stockholm' });
+if (!report) throw new Error('report not found');
 
 await ablo.weatherReports.update({
-  id: 'report_stockholm',
+  id: report.id,
   data: { status: 'ready' },
-  readAt: snap.stamp,
-  onStale: 'reject',
+  reads: [report],
 });
 ```
 
 Reactive local state changes optimistically at call time; awaiting the model
 write waits for authoritative confirmation.
 
-Protected write options:
+If the row changed after `read`, the write rejects with
+`AbloStaleContextError`. Ablo retains only model, id, and the read watermark as
+evidence; it does not record the row contents. A write without `reads` is an
+intentional unconditional assignment.
+
+Write options:
 
 | Option | Purpose |
 |---|---|
-| `readAt` | The state cursor the write was based on. |
-| `onStale` | Stale-state policy. Prefer `reject` for agent writes. |
+| `reads` | Exact rows returned by `read` that the mutation depends on. |
 | `idempotencyKey` | Stable key for retry-safe writes. The SDK generates one when omitted. |
 | `timeout` | Maximum time to wait for the write call. |
 
@@ -143,10 +214,12 @@ on its own if the holder stops, and is never saved as a row.
 
 You coordinate a row with calls on its model, beside `create`/`update`/`get`:
 `ablo.<model>.claim({ id })` takes the claim and returns a handle,
-`ablo.<model>.claim.state({ id })` reads who currently holds it (synchronous, never
-blocks), and `ablo.<model>.claim.release({ id })` releases it early. The full
-coordination surface is `claim.state({ id })` / `claim.queue({ id })` /
-`claim.release({ id })` / `claim.reorder({ id, order })` hanging off `claim`.
+`ablo.<model>.claim.state({ id })` reads who currently holds it, and
+`ablo.<model>.claim.release({ id })` releases it early. These reads are synchronous
+on the stateful client and awaited server calls on the HTTP client. The full
+coordination surface is `claim.state({ id })` / `claim.list({ id })` /
+`claim.queue({ id })` / `claim.release({ id })` /
+`claim.reorder({ id, order })` hanging off `claim`.
 
 The fields on a claim, its lifecycle diagram, and the full method surface are in
 [Coordination](./coordination.md#the-claim-state-object), which is where that
@@ -156,8 +229,9 @@ line.
 
 ### Reading and claiming
 
-`claim.state({ id })` is the read side for observers: synchronous, never blocks, and
-returns the live claim state object (or `null`). `claim({ id })` is the write
+`claim.state({ id })` is the read side for observers and returns the current claim
+state object (or `null`). It reads the stateful client's local cache synchronously;
+the HTTP client returns a promise because it asks the server. `claim({ id })` is the write
 side: it takes the claim and returns a `ClaimHandle`. Claims don't lock — if someone else
 already holds the row, `claim` waits for them to finish, re-reads the fresh row,
 then hands it to you, so you always proceed from current state. Default reads
@@ -167,7 +241,7 @@ Reads never block on a claim — to wait for a row to free up, `claim({ id })` i
 (the claim queues fairly behind the holder).
 
 ```ts
-const claim = ablo.weatherReports.claim.state({ id: 'report_stockholm' });
+const claim = await ablo.weatherReports.claim.state({ id: 'report_stockholm' });
 if (claim) {
   claim.heldBy;
   claim.description;
@@ -207,7 +281,7 @@ endpoint documents that model's real field contract instead of a generic blob.
 |---|---|
 | `ablo.<model>.create({ data })` | `POST /api/v1/models/{model}` |
 | `ablo.<model>.list({ where })` | `GET /api/v1/models/{model}` |
-| `ablo.<model>.get({ id })` | `GET /api/v1/models/{model}/{id}` |
+| `ablo.<model>.read({ id })` | `GET /api/v1/models/{model}/{id}` |
 | `ablo.<model>.update({ id, data })` | `PATCH /api/v1/models/{model}/{id}` |
 | `ablo.<model>.delete({ id })` | `DELETE /api/v1/models/{model}/{id}` |
 | `ablo.<model>.claim({ id })` | `POST /api/v1/models/{model}/{id}/claim` |

package/docs/branch-development.md

@@ -66,7 +66,9 @@ Login stores one project-scoped `mk_` management credential. It has no
 production/test mode and no application-data authority. It can manage projects
 and branches and exchange for an expiring credential bound to one branch.
 
-If you switch projects, log in for the selected project before running `dev`:
+If you switch projects, log in for the selected project before running `dev`.
+A plain `npx ablo login` offers the organization's projects in the terminal;
+`--project` names one outright:
 
 ```bash
 npx ablo projects use orders
@@ -253,8 +255,8 @@ database's safe coordinates, and an exact readiness fix.
 For a one-shot CI schema check:
 
 ```bash
-# Store the project management credential as the masked secret.
-ABLO_MANAGEMENT_KEY="mk_..." \
+# The one credential input temporarily carries CI's masked management grant.
+ABLO_API_KEY="mk_..." \
 ABLO_BRANCH="preview-pr-${PR_NUMBER}" \
   npx ablo dev --no-watch
 ```
@@ -273,6 +275,22 @@ npx ablo branch ensure "preview-pr-${PR_NUMBER}" \
 result as a secret, mask it in logs, and pass it through the deployment
 provider's secret-variable mechanism.
 
+For live integration tests that should not require a customer database, request
+an explicitly hosted, expiring test branch:
+
+```bash
+npx ablo branch ensure "sandbox-live-${RUN_ID}" \
+  --kind test \
+  --hosted \
+  --expires-at "${EXPIRES_AT}" \
+  --credential \
+  --json
+```
+
+Hosted storage is never inferred. It is accepted only for `kind: test` branches
+that expire within 24 hours; ordinary branches stay unbound until connected to
+the customer's database.
+
 Closing a preview should call `branch delete`. Deletion immediately makes
 branch-bound credentials fail authentication even if their expiry is later.
 
@@ -338,7 +356,8 @@ Run:
 npx ablo login
 ```
 
-For a non-default project:
+The terminal then offers the organization's projects, cursor on the active
+one; a plain Enter keeps it. To name the project and skip the picker:
 
 ```bash
 npx ablo login --project <project>

package/docs/cli.md

@@ -32,8 +32,8 @@ resume a branch and exchanges it for a temporary branch-bound runtime key.
 
 | Command                  | What it does                                                               |
 | ------------------------ | -------------------------------------------------------------------------- |
-| `ablo login`             | Authorize in the browser; store one project management credential.         |
-| `ablo login --project <slug>` | Same, scoped to a project, which becomes active.                     |
+| `ablo login`             | Authorize in the browser, pick a project; store its management credential.  |
+| `ablo login --project <slug>` | Same without the picker: scoped to the named project, which becomes active. |
 | `ablo logout`            | Remove the stored credentials.                                             |
 | `ablo whoami`            | Strictly confirm which project and branch a credential acts on.            |
 | `ablo status`            | Show the active org/project, resolved runtime credential, branch target, and server health. |
@@ -55,9 +55,10 @@ reports the server-confirmed branch before it writes. For one-time recovery,
 putting the secret in argv.
 
 Keys live in `~/.config/ablo/credentials.json` (mode `0600`), keyed by project.
-The non-secret `config.json` holds the active project. In **CI**, don't log in —
-set the project management credential as `ABLO_MANAGEMENT_KEY`; it overrides the
-stored credential during branch bootstrap.
+The non-secret `config.json` holds the active project. There is one explicit
+credential input: `ABLO_API_KEY`. In headless CI it may temporarily contain an
+`mk_` credential during branch bootstrap; the runtime receives the resulting
+branch-bound `sk_` or restricted `rk_` value through the same variable.
 
 ## Development branches and the production root
 
@@ -94,7 +95,8 @@ with `projects use`) selects which profile every command authenticates with.
 | `ablo projects list`          | List the org's projects (marks the active one and the org-default).                |
 | `ablo projects create <slug>` | Create a project (`--name "Display Name"`). Its keys/schema/data are isolated.     |
 | `ablo projects use <slug>`    | Switch the active project. `ablo projects use default` returns to the org-default. |
-| `ablo login --project <slug>` | Store management access for a project and make it active.                          |
+| `ablo login`                  | Pick a project in the terminal; store its management access and make it active.    |
+| `ablo login --project <slug>` | The same for a named project, with no picker.                                      |
 
 Because keys are fixed to a project, `projects use` only changes which profile
 is active — it never re-scopes an existing key. Switch to a project you haven't
@@ -108,12 +110,17 @@ npx ablo projects use war-room
 npx ablo login --project war-room   # stores its management credential, keeps it active
 ```
 
+A plain `npx ablo login` reaches the same place through a picker: once the
+browser has approved, the terminal lists the organization's projects, with the
+cursor on the active one, and the choice becomes the credential's project. An
+organization holding only its default project is not asked.
+
 If you run a project-scoped command (`push`, `dev`) while the active project has
 no key — but other projects do — the CLI **refuses** rather than silently
 deploying with the wrong project's credential, and names the fix
-(`ablo login --project <slug>`). In CI, an explicit `ABLO_MANAGEMENT_KEY`
-bypasses profiles for project/branch administration; the runtime key remains
-`ABLO_API_KEY`.
+(`ablo login --project <slug>`). In CI, an explicit `mk_` in `ABLO_API_KEY`
+bypasses profiles for project/branch administration. Replace it with the
+branch-bound runtime credential before starting application code.
 
 ## Commands
 

package/docs/client-behavior.md

@@ -1,8 +1,11 @@
 # Client Behavior
 
-> Per-write options, claim behavior, and which errors are safe to retry.
+> Guarded writes, 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.
+When several writers touch the same data at once — an agent worker, a Server
+Action, a person in the browser — the SDK protects explicit read dependencies
+and claims records across slow work. This page describes those guarantees 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.
 
@@ -34,7 +37,7 @@ Common options:
 | `baseURL` | Override the hosted sync endpoint for staging or private deployments. An HTTPS origin, optionally with a path prefix; plain HTTP is accepted for localhost. Your key travels here, so a URL carrying its own credentials, a query, or a fragment is refused at construction. |
 | `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 (the `local` reads, `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 model `onChange` subscriptions. `'http'` returns the **stateless** client for server-side actors (agents, workers, serverless): the same `ablo.<model>` read/write/claim surface, but ordinary calls are HTTP round trips with no socket. Stateful-only model methods (`local`, model `onChange`, and `join`) are compile errors. A listener added through `context().onChange` holds one HTTP response open only until its context changes or its last listener stops. |
 | `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. |
@@ -53,7 +56,7 @@ Each schema model becomes a typed model:
 ```ts
 await ablo.ready();
 
-const report = await ablo.weatherReports.get({ id: 'report_stockholm' });
+const report = await ablo.weatherReports.read({ id: 'report_stockholm' });
 const local = ablo.weatherReports.local.get('report_stockholm');
 
 await ablo.weatherReports.create({ data: { location: 'Stockholm', status: 'pending' } });
@@ -65,7 +68,7 @@ On the reactive client, each model write changes local state optimistically
 before the call returns. Its promise always waits for authoritative
 confirmation, so `await update(...)` is the confirmation barrier.
 
-Call `get`/`list` first — they fetch from the server and you `await` them.
+Call `get`/`list` to observe, or `read` when a later mutation depends on the row.
 After that, `local.get`/`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.
@@ -83,14 +86,13 @@ through the same model client path. A human Server Action, a browser view, and a
 agent worker can all use `ablo.weatherReports`:
 
 ```ts
-const report = await ablo.weatherReports.get({ id });
-const snap = ablo.snapshot({ weatherReports: id });
+const report = await ablo.weatherReports.read({ id });
+if (!report) throw new Error('Row not found');
 
 await ablo.weatherReports.update({
   id,
   data: patch,
-  readAt: snap.stamp,
-  onStale: 'reject',
+  reads: [report],
 });
 ```
 
@@ -106,24 +108,28 @@ actor routing through Ablo is coordinated. The one write it can't coordinate is
 one made directly against your database, around Ablo — the WAL echo still catches
 it for reads, but it bypasses claims and ordering.
 
-## Per-Write Options
+## Guarded Writes
 
 ```ts
+const report = await ablo.weatherReports.read({ id: 'report_stockholm' });
+if (!report) throw new Error('report not found');
+
 await ablo.weatherReports.update({
-  id: 'report_stockholm',
+  id: report.id,
   data: { status: 'ready' },
-  readAt: snap.stamp,
-  onStale: 'reject',
+  reads: [report],
   idempotencyKey: 'report_stockholm:mark-ready:v1',
 });
 ```
 
 | Option | Purpose |
 |---|---|
-| `readAt` | State cursor the write was based on. |
-| `onStale` | Policy when the target changed after `readAt`. Prefer `reject`. |
+| `reads` | Exact rows returned by `read` that this mutation depends on. |
 | `idempotencyKey` | Stable key for retry-safe writes. The SDK generates one when omitted. |
 
+A stale premise always rejects with `AbloStaleContextError`. Omit `reads` only
+when the assignment is intentionally unconditional.
+
 ## Claimed Behavior
 
 If your update involves a slow step — an API call, an LLM round-trip — and someone