@abloatai/ablo 0.7.0 → 0.9.0

package/docs/audit.md

@@ -1,7 +1,11 @@
 # Audit log
 
-Every commit becomes one row. Rows are hash-chained per principal —
-tamper-evident, queryable, exportable.
+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 signed in a chain so you can later prove the history wasn't altered.
+You can filter it, page through it, and export it.
+
+Every commit becomes one row.
 
 ## Row shape
 
@@ -12,10 +16,10 @@ tamper-evident, queryable, exportable.
   actorId:              string,
   onBehalfOfKind:       'user' | 'agent' | 'system' | null,
   onBehalfOfId:         string | null,
-  credentialId:         string | null,
-  credentialLabel:      string | null,
+  credentialId:         string | null,    // the API key/credential used for the write
+  credentialLabel:      string | null,    // its human-readable name, for scanning the log
   delegationChainRoot:  string | null,    // always points at a human
-  causedByRunId:        string | null,
+  causedByRunId:        string | null,    // the agent run that produced this write — group every change from one run
   actionType:           string,           // e.g. 'weatherReport.update'
   modelName:            string | null,    // e.g. 'claude-opus-4-7'
   diffSummary:          unknown,
@@ -28,9 +32,9 @@ tamper-evident, queryable, exportable.
 
 ## Delegation chain
 
-`delegationChainRoot` always points at the human who started the chain.
-There is no audit row whose root is an agent. Autonomous AI writes are not
-a thing in this system; every chain starts with a person.
+Every action traces back to a human. Even when an agent makes the change,
+`delegationChainRoot` names the person who set that work in motion — there is no
+audit row whose root is an agent.
 
 ## Verify
 
@@ -71,7 +75,10 @@ curl 'https://<your-app>/api/orgs/<slug>/audit/export?actorKind=agent&since=2026
   > may-agent-writes.csv
 ```
 
-CSV up to a hard cap per request. For larger windows, paginate.
+One request exports CSV up to a hard row cap. If your window is larger than the
+cap, the response is truncated at the cap rather than erroring — so for large
+windows, split the window by date and request each slice, or page through the
+JSON `GET` endpoint above using `nextCursor`.
 
 ## Compliance posture
 

package/docs/cli.md

@@ -2,9 +2,9 @@
 
 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 — the CLI and the hosted
-server lower it to **the same SQL** through one engine
-(`generateProvisionPlan` / `generateMigrationPlan` in `@abloatai/ablo/schema`).
+`defineSchema(...)` is the single source of truth: whether you run the CLI
+locally or push to the hosted server, the same engine turns it into the same
+SQL — so what you test is what ships.
 
 ```bash
 npx ablo init      # scaffold ablo/schema.ts + client
@@ -12,6 +12,14 @@ npx ablo login     # authorize in the browser
 npx ablo dev       # push schema to the test sandbox + watch
 ```
 
+**Two setup styles, and they pick your commands.** If your app database is the
+source of truth, expose a [Data Source endpoint](./data-sources.md) and keep DB
+credentials in your app. If you explicitly want Ablo to open a Postgres
+connection, use the **Direct Postgres connector** commands: `ablo migrate`
+applies changes to your own `DATABASE_URL`, and `ablo check` / `ablo pull`
+adopt tables you already have. Hosted sandbox commands are tagged **Hosted**;
+direct-connector commands are tagged **Direct Postgres**.
+
 ## Authenticate
 
 `ablo login` runs the OAuth 2.0 device flow: it opens your browser, you choose
@@ -19,12 +27,12 @@ npx ablo dev       # push schema to the test sandbox + watch
 **test + live key pair** (90-day, restricted) and stores them locally. This
 mirrors `stripe login`.
 
-| Command | What it does |
-| --- | --- |
-| `ablo login` | Authorize in the browser; provisions + stores a test and a live key. |
-| `ablo logout` | Remove the stored keys. |
-| `ablo status` | Show the active org, mode, both keys (prefix + expiry), and server health. |
-| `ablo mode [test\|live]` | Switch the active mode. With no argument, prompts. |
+| Command                  | What it does                                                               |
+| ------------------------ | -------------------------------------------------------------------------- |
+| `ablo login`             | Authorize in the browser; provisions + stores a test and a live key.       |
+| `ablo logout`            | Remove the stored keys.                                                    |
+| `ablo status`            | Show the active org, mode, both keys (prefix + expiry), and server health. |
+| `ablo mode [test\|live]` | Switch the active mode. With no argument, prompts.                         |
 
 Keys are stored in `~/.config/ablo/config.json` (mode `0600`). In **CI**, don't
 log in — set `ABLO_API_KEY`, which always overrides the stored key.
@@ -41,17 +49,18 @@ either mode) defines the same models test and live see; only the rows differ.
 
 ## Commands
 
-| Command | What it does | Flags |
-| --- | --- | --- |
-| `ablo init` | Scaffold `ablo/` (`schema.ts`, client, optional Data Source / agent / component), write `.env`, install the SDK. Offers to log in at the end. | — |
-| `ablo login` / `logout` / `status` | Authentication & status (above). | — |
-| `ablo mode [test\|live]` | Switch active mode. | — |
-| `ablo dev` | **Hosted** — push the schema to your test sandbox, then watch `ablo/schema.ts` and re-push on save. | `--no-watch`, `--schema <path>`, `--export <name>`, `--url <url>` |
-| `ablo logs` | Tail your scope's commit activity (`stripe logs tail`). Follows by default. | `-n, --tail <N>`, `--since <dur\|ts>`, `--model`, `--op`, `--json`, `--no-follow`, `--mode test\|live` |
-| `ablo schema push` | **Hosted** — upload the schema to Ablo; the server diffs, migrates, and activates it. | `--force`, `--rename old:new`, `--backfill model.field=value`, `--schema`, `--export`, `--url` |
-| `ablo pull` | **BYO** — generate `defineSchema(...)` from your existing tables (read-only, like `prisma db pull`). | `--out <path>`, `--app-schema <name>`, `--import <pkg>`, `--force` |
-| `ablo check` | **BYO** — verify your *existing* tables fit the schema (read-only, no DDL). | `--schema <path>`, `--export <name>`, `--app-schema <name>` |
-| `ablo generate` | Emit TypeScript types from the schema. | `--out <path>`, `--schema`, `--export` |
+| Command                            | What it does                                                                                                                                  | Flags                                                                                                  |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `ablo init`                        | Scaffold `ablo/` (`schema.ts`, client, optional Data Source / agent / component), write `.env`, install the SDK. Offers to log in at the end. | —                                                                                                      |
+| `ablo login` / `logout` / `status` | Authentication & status (above).                                                                                                              | —                                                                                                      |
+| `ablo mode [test\|live]`           | Switch active mode.                                                                                                                           | —                                                                                                      |
+| `ablo dev`                         | **Hosted** — push the schema to your test sandbox, then watch `ablo/schema.ts` and re-push on save.                                           | `--no-watch`, `--schema <path>`, `--export <name>`, `--url <url>`                                      |
+| `ablo logs`                        | Tail your scope's commit activity (`stripe logs tail`). Follows by default.                                                                   | `-n, --tail <N>`, `--since <dur\|ts>`, `--model`, `--op`, `--json`, `--no-follow`, `--mode test\|live` |
+| `ablo push`                        | **Hosted** — upload the schema to Ablo; the server diffs, migrates, and activates it.                                                         | `--force`, `--rename old:new`, `--backfill model.field=value`, `--schema`, `--export`, `--url`         |
+| `ablo migrate`                     | **Direct Postgres** — apply the schema to your own `DATABASE_URL` (you run the DDL).                                                          | `--dry-run`, `--output <file>`, `--schema`, `--export`                                                 |
+| `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 DDL).                                                       | `--schema <path>`, `--export <name>`, `--app-schema <name>`                                            |
+| `ablo generate`                    | Emit TypeScript types from the schema.                                                                                                        | `--out <path>`, `--schema`, `--export`                                                                 |
 
 ## `ablo dev`
 
@@ -98,10 +107,11 @@ point: review it, then run `ablo check`.
 
 ## `ablo check`
 
-The BYO front door. Instead of migrating (DDL on your database), Ablo *adopts*
-the tables you already have: `ablo check` introspects `DATABASE_URL`, compares it
-to your `defineSchema(...)`, and reports — per model — whether the table is
-adoptable. It never writes or alters anything.
+`ablo check` is how you adopt a database you already own. Instead of creating or
+altering tables, it inspects your existing ones and tells you which fit the
+schema: it introspects `DATABASE_URL`, compares each table to your
+`defineSchema(...)`, and reports — per model — whether the table is adoptable.
+It never writes or alters anything.
 
 A table is adoptable when it has a primary key `id` and (for org-scoped models)
 an `organization_id` column — the tenancy marker the engine isolates on. Every
@@ -131,12 +141,12 @@ If a table can't carry `organization_id` (or has business logic Ablo shouldn't
 bypass), keep it behind a [Data Source endpoint](/data-sources) rather than
 reshaping it. `ablo check` is read-only; it never proposes a migration.
 
-## `migrate` vs `schema push`
+## `migrate` (Direct Postgres) vs `push` (Hosted)
 
-Two front doors to the same engine. Use `migrate` when your app owns the
-database (it applies to `DATABASE_URL`); use `schema push` (and `dev`) on the
-hosted path (the server applies to Ablo-managed Postgres and version-gates
-connecting clients).
+Same engine, two setups. If you use the **Direct Postgres connector**, use
+`ablo migrate` — it applies the schema to your own `DATABASE_URL`, and you run
+the DDL. If Ablo manages the sandbox/hosted store, use `ablo push` and
+`ablo dev` — the server applies the change and version-gates connecting clients.
 
 ```bash
 ablo migrate --dry-run            # preview the exact SQL
@@ -148,20 +158,20 @@ ablo migrate --output schema.sql  # write SQL to a file
 
 The one type map, shared by both paths (there is no second mapping):
 
-| Zod | Postgres |
-| --- | --- |
-| `z.string()` | `TEXT` |
-| `z.number()` | `DOUBLE PRECISION` — never `INTEGER`; a Zod number may be fractional, and truncating is silent data loss |
-| `z.boolean()` | `BOOLEAN` |
-| `z.date()` | `TIMESTAMPTZ` |
-| `z.enum([...])` | `TEXT` + a `CHECK (col IN (...))` constraint |
-| `z.object` / `z.array` / `z.record` / `z.union` / `z.custom` | `JSONB` |
-| `.optional()` / `.nullable()` | nullable column |
+| Zod                                                          | Postgres                                                                                                 |
+| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| `z.string()`                                                 | `TEXT`                                                                                                   |
+| `z.number()`                                                 | `DOUBLE PRECISION` — never `INTEGER`; a Zod number may be fractional, and truncating is silent data loss |
+| `z.boolean()`                                                | `BOOLEAN`                                                                                                |
+| `z.date()`                                                   | `TIMESTAMPTZ`                                                                                            |
+| `z.enum([...])`                                              | `TEXT` + a `CHECK (col IN (...))` constraint                                                             |
+| `z.object` / `z.array` / `z.record` / `z.union` / `z.custom` | `JSONB`                                                                                                  |
+| `.optional()` / `.nullable()`                                | nullable column                                                                                          |
 
 Each table also gets the platform columns (`id`, `organization_id`,
 `created_by`, `created_at`, `updated_at`), an `organization_id` index, and
-row-level security keyed on `current_setting('app.current_org_id')` for tenant
-isolation.
+row-level security so each org only sees its own rows — the engine sets this per
+request (via `current_setting('app.current_org_id')`); you don't manage it.
 
 `.default(...)` is **not** emitted as a SQL column default — Zod applies the
 default at write time (`create`), in one place, so a DB default and a schema
@@ -185,7 +195,7 @@ that broke and the Postgres SQLSTATE, not just "migration failed".
 }
 ```
 
-`ablo schema push` (hosted) returns the canonical error envelope (HTTP 500),
+`ablo push` (hosted) returns the canonical error envelope (HTTP 500),
 which the SDK reconstructs as a typed `AbloServerError`:
 
 ```json
@@ -204,9 +214,9 @@ migration can't leave clients gated against tables that don't match.
 
 ## Environment
 
-| Variable | Purpose | Default |
-| --- | --- | --- |
-| `ABLO_API_KEY` | Authenticate without `ablo login` (CI). Always overrides the stored key. | — |
-| `ABLO_API_URL` | Control-plane / API host (`schema push`, `dev`, `status`). | `https://api.abloatai.com` |
-| `ABLO_AUTH_URL` | Dashboard origin for `ablo login`'s device flow. | `https://abloatai.com` |
-| `ABLO_CONFIG_DIR` / `XDG_CONFIG_HOME` | Where the credential file lives. | `~/.config/ablo` |
+| Variable                              | Purpose                                                                  | Default                    |
+| ------------------------------------- | ------------------------------------------------------------------------ | -------------------------- |
+| `ABLO_API_KEY`                        | Authenticate without `ablo login` (CI). Always overrides the stored key. | —                          |
+| `ABLO_API_URL`                        | Control-plane / API host (`push`, `dev`, `status`).                      | `https://api.abloatai.com` |
+| `ABLO_AUTH_URL`                       | Dashboard origin for `ablo login`'s device flow.                         | `https://abloatai.com`     |
+| `ABLO_CONFIG_DIR` / `XDG_CONFIG_HOME` | Where the credential file lives.                                         | `~/.config/ablo`           |

package/docs/client-behavior.md

@@ -1,6 +1,8 @@
 # Client Behavior
 
-This page covers the SDK behavior around options, errors, retries, and runtimes.
+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.
+
+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.
 
 ## Constructor
 
@@ -45,42 +47,48 @@ Each schema model becomes a typed model:
 ```ts
 await ablo.ready();
 
-const [report] = await ablo.weatherReports.load({ where: { id: 'report_stockholm' } });
-const local = ablo.weatherReports.retrieve('report_stockholm');
+const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
+const local = ablo.weatherReports.get('report_stockholm');
 
-await ablo.weatherReports.create({ location: 'Stockholm', status: 'pending' });
-await ablo.weatherReports.update('report_stockholm', { status: 'ready' }, { wait: 'confirmed' });
-await ablo.weatherReports.delete('report_stockholm', { wait: 'confirmed' });
+await ablo.weatherReports.create({ data: { location: 'Stockholm', status: 'pending' } });
+await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' }, wait: 'confirmed' });
+await ablo.weatherReports.delete({ id: 'report_stockholm', wait: 'confirmed' });
 ```
 
-`load` is async hydration from local store and server. `retrieve`, `list`, and
-`count` are synchronous local reads after data is loaded.
+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
+no `await`, and stay reactive in render. Use the async pair to load, the sync trio
+to read.
 
-`list` accepts the same practical read options the React selector path uses:
-`where`, `filter`, `orderBy`, `limit`, `offset`, and `scope`. Scope defaults to
-`'live'`; pass `'archived'` or `'all'` when you intentionally want non-live
-rows.
+`getAll` 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.
 
 ## Multiplayer Behavior
 
-Multiplayer works when every participant uses the same model client path. A
-human Server Action, a browser view, and an agent worker can all use
-`ablo.weatherReports`:
+Two writers both try to mark `report_stockholm` ready at the same time. To stop
+the second write from silently overwriting the first, every participant goes
+through the same model client path. A human Server Action, a browser view, and an
+agent worker can all use `ablo.weatherReports`:
 
 ```ts
-const [report] = await ablo.weatherReports.load({ where: { id } });
+const report = await ablo.weatherReports.retrieve({ id });
 const snap = ablo.snapshot({ weatherReports: id });
 
-await ablo.weatherReports.update(id, patch, {
+await ablo.weatherReports.update({
+  id,
+  data: patch,
   readAt: snap.stamp,
   onStale: 'reject',
   wait: 'confirmed',
 });
 ```
 
-The confirmed write fans out over realtime subscriptions. React clients that use
-`useAblo((ablo) => ablo.weatherReports.retrieve(id))` receive the new row, and selectors
-such as `useAblo((ablo) => ablo.weatherReports.claimState(id))`
+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
+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.
 
@@ -90,17 +98,15 @@ until the app reports it through Data Source events.
 ## Per-Write Options
 
 ```ts
-await ablo.weatherReports.update(
-  'report_stockholm',
-  { status: 'ready' },
-  {
-    wait: 'confirmed',
-    readAt: snap.stamp,
-    onStale: 'reject',
-    idempotencyKey: 'report_stockholm:mark-ready:v1',
-    timeout: 20_000,
-  },
-);
+await ablo.weatherReports.update({
+  id: 'report_stockholm',
+  data: { status: 'ready' },
+  wait: 'confirmed',
+  readAt: snap.stamp,
+  onStale: 'reject',
+  idempotencyKey: 'report_stockholm:mark-ready:v1',
+  timeout: 20_000,
+});
 ```
 
 | Option | Purpose |
@@ -113,26 +119,34 @@ await ablo.weatherReports.update(
 
 ## Claimed Behavior
 
+If your update involves a slow step — an API call, an LLM round-trip — and someone
+else might write the same record meanwhile, claiming the record stops you from
+overwriting their change. Check who holds the record with `claim.state({ id })`, then
+take it with `claim({ id })`:
+
 ```ts
-const active = ablo.weatherReports.claimState('report_stockholm');
+const active = ablo.weatherReports.claim.state({ id: 'report_stockholm' });
 
 if (active) {
   return { status: 'claimed', active };
 }
 
-await ablo.weatherReports.claim('report_stockholm', async (report) => {
-  await ablo.weatherReports.update(report.id, { status: 'ready' });
-});
+const handle = await ablo.weatherReports.claim({ id: 'report_stockholm' });
+await ablo.weatherReports.update({ id: handle.data.id, data: { status: 'ready' } });
+await handle.release();
 ```
 
-Reads never silently block. For schema model calls, use `claimState(id)` to observe
-current work and `claim(id, work)` to serialize a write across a slow step:
+`claim.state({ id })` returns the current holder (or nothing) without ever blocking.
+When you call `claim({ id })`, the SDK queues other claimers behind you, re-reads
+the latest row, then hands you the fresh row — so you can't overwrite a change you didn't
+see. Options on the claim:
 
-- default `claim` waits in the fair queue and re-reads before invoking `work`;
+- default `claim` waits in the fair queue and re-reads before handing you the row;
 - `{ wait: false }` rejects with `AbloClaimedError` instead of queuing;
 - `{ maxQueueDepth }` rejects if the wait line is already too deep.
 
-Schema clients use the realtime stream for waits.
+While waiting, schema clients learn when the claim clears from the live claim
+stream, so they never poll.
 
 ## Errors
 
@@ -154,7 +168,7 @@ All SDK errors extend `AbloError` and carry a stable `type`.
 import { AbloClaimedError } from '@abloatai/ablo';
 
 try {
-  await ablo.weatherReports.update('report_stockholm', { status: 'ready' }, { wait: 'confirmed' });
+  await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' }, wait: 'confirmed' });
 } catch (error) {
   if (error instanceof AbloClaimedError) {
     return { status: 'claimed' };