@abloatai/ablo 0.8.0 → 0.9.0

package/docs/cli.md

@@ -12,12 +12,13 @@ npx ablo login     # authorize in the browser
 npx ablo dev       # push schema to the test sandbox + watch
 ```
 
-**Two setups, and they pick your commands.** If Ablo manages your Postgres —
-the default, **hosted** path — use `ablo dev` and `ablo push`. If you
-**bring your own database (BYO)**, use `ablo migrate` to apply changes to your
-own `DATABASE_URL` directly, and `ablo check` / `ablo pull` to adopt tables you
-already have. The commands below are tagged **Hosted** or **BYO** so you can
-tell which apply to you.
+**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
 
@@ -26,12 +27,12 @@ tell which apply to you.
 **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.
@@ -48,18 +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 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` | **BYO** — apply the schema to your own `DATABASE_URL` (you run the DDL). | `--dry-run`, `--output <file>`, `--schema`, `--export` |
-| `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`
 
@@ -140,13 +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` (BYO) vs `push` (Hosted)
+## `migrate` (Direct Postgres) vs `push` (Hosted)
 
-Same engine, two setups. If you **bring your own database (BYO)**, use
+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 your Postgres (the **hosted** path), use `ablo push`
-(and `ablo dev`) — the server applies the change to Ablo-managed Postgres
-and version-gates connecting clients.
+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
@@ -158,15 +158,15 @@ 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
@@ -214,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 (`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

@@ -47,12 +47,12 @@ Each schema model becomes a typed model:
 ```ts
 await ablo.ready();
 
-const report = await 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' });
 ```
 
 Call `retrieve`/`list` first — they fetch from the server and you `await` them.
@@ -73,10 +73,12 @@ 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.retrieve(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',
@@ -86,7 +88,7 @@ await ablo.weatherReports.update(id, patch, {
 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))`
+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.
 
@@ -96,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 |
@@ -121,27 +121,27 @@ await ablo.weatherReports.update(
 
 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, work)`:
+overwriting their change. Check who holds the record with `claim.state({ id })`, then
+take it with `claim({ id })`:
 
 ```ts
-const active = ablo.weatherReports.claim.state('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();
 ```
 
-`claim.state(id)` returns the current holder (or nothing) without ever blocking.
-When you call `claim(id, work)`, the SDK queues other claimers behind you, re-reads
-the latest row, then runs your `work` — so you can't overwrite a change you didn't
-see. Options on the wait:
+`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.
 
@@ -168,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' };

package/docs/coordination.md

@@ -1,7 +1,7 @@
 # Coordination Reference
 
 Coordinate long-running work on a row so humans and agents don't clobber each
-other. Most writes need none of this — `ablo.<model>.update(id, …)` is optimistic
+other. Most writes need none of this — `ablo.<model>.update({ id, data })` is optimistic
 and the server rejects it if the row moved. Reach for `claim` only when you'll
 **hold a row across a slow gap** (read → LLM call → write).
 
@@ -98,8 +98,7 @@ parameters · returns · example**.
 ### `claim`
 
 ```ts
-ablo.<model>.claim(id, work, options?): Promise<R>   // callback form
-ablo.<model>.claim(id, options?): Promise<ClaimedRow<T>>
+ablo.<model>.claim({ id, ...options }): Promise<ClaimHandle<T>>  // handle; AsyncDisposable, auto-releases with `await using`
 ```
 
 Claim a row so other writers serialize behind you until you're done; reads stay
@@ -120,38 +119,36 @@ so two claimers can't both think they won.
 | `options.wait` | `boolean` | no | `true` (default) queues and waits for the lease. `false` is fail-fast — if another participant holds the row, reject immediately with `AbloClaimedError('entity_claimed')` instead of queuing (claim-or-skip, for work dedup where waiting would double-process). |
 | `options.maxQueueDepth` | `number` | no | Backpressure: reject with `AbloClaimedError('queue_too_deep')` instead of joining a line already `>= maxQueueDepth` deep. Omit to wait however deep the queue is. |
 | `options.ttl` | `Duration` | no | Crash-cleanup floor. Rarely set — the lease renews while your connection is alive, so it only matters once you go silent. |
-| `work` | `(row) => …` | no | Callback form: hold the claim for the callback, release when it returns. |
 
 The high-level `claim` queues by default, so on contention you either get the row
 when your turn arrives or one of the [queue errors](#errors) (`claim_lost`,
 `grant_timeout`).
 
-**Returns** — with the callback form, returns whatever `work` returns and
-releases after the callback returns or throws. The manual form returns the
-claimed row (`ClaimedRow<T> = T & AsyncDisposable`): the row data plus a
-release hook for manual scopes.
+**Returns** — a `ClaimHandle<T>` (an `AsyncDisposable`): `handle.data` is the
+fresh row snapshot taken once the lease is yours, and `handle.release()` gives
+the claim back. Bind it with `await using` so the claim auto-releases when the
+scope exits.
 
 **Example**
 
 ```ts
-const forecast = await ablo.weatherReports.claim('report_stockholm', async (report) => {
-  const weather = await weatherAgent.getWeather(report.location);
-  await ablo.weatherReports.update(report.id, { forecast: weather });
-  return weather;
-});
+await using claim = await ablo.weatherReports.claim({ id: 'report_stockholm' });
+const report = claim.data;
+const weather = await weatherAgent.getWeather(report.location);
+await ablo.weatherReports.update({ id: report.id, data: { forecast: weather } });
 ```
 
-The manual scoped form is still available for wider TS 5.2+ scopes, but ordinary
-held work should use the callback form above.
+The claim releases when the `await using` scope exits — on return or throw.
 
 ### Claim-gated reads
 
-`claim.state(id)` always returns immediately. Model reads such as
+`claim.state({ id })` always returns immediately. Model reads such as
 `ablo.<model>.get(id)` are local reads and stay available while a claim is
 held. Server/model reads can choose a claimed policy:
 
 ```ts
-await ablo.model('weatherReports').retrieve('report_stockholm', {
+await ablo.weatherReports.retrieve({
+  id: 'report_stockholm',
   ifClaimed: 'wait',
   claimedTimeout: 30_000,
 });
@@ -164,7 +161,7 @@ await ablo.model('weatherReports').retrieve('report_stockholm', {
 ### `claim.state`
 
 ```ts
-ablo.<model>.claim.state(id)
+ablo.<model>.claim.state({ id })
 ```
 
 Read who's currently working on a row, for observers and UI. Synchronous and
@@ -182,7 +179,7 @@ is free.
 **Example**
 
 ```ts
-const who = ablo.weatherReports.claim.state('report_stockholm');
+const who = ablo.weatherReports.claim.state({ id: 'report_stockholm' });
 if (who) console.log(`${who.heldBy} is ${who.action}`);
 ```
 
@@ -203,7 +200,7 @@ Returns the active claim state when the row is held, or `null` when it's free:
 ### `claim.queue`
 
 ```ts
-ablo.<model>.claim.queue(id)
+ablo.<model>.claim.queue({ id })
 ```
 
 Read the **wait line** behind a row — the FIFO of claims queued behind the
@@ -226,7 +223,7 @@ the active holder; `[]` when no one is waiting.
 **Example**
 
 ```ts
-const { data: waiting } = ablo.weatherReports.claim.queue('report_stockholm');
+const { data: waiting } = ablo.weatherReports.claim.queue({ id: 'report_stockholm' });
 console.log(`${waiting.length} ahead of you`);
 console.log(waiting.map((i) => i.heldBy));
 ```
@@ -234,11 +231,11 @@ console.log(waiting.map((i) => i.heldBy));
 ### `claim.release`
 
 ```ts
-ablo.<model>.claim.release(id): Promise<void>
+ablo.<model>.claim.release({ id }): Promise<void>
 ```
 
-Release a claim you hold. Usually **implicit** — the callback returning releases
-for you, and TTL cleans up a crashed holder.
+Release a claim you hold. Usually **implicit** — the `await using` scope exiting
+releases for you, and TTL cleans up a crashed holder.
 Call this only to give a manually held claim back early (claimed, then decided
 not to write).
 Releasing **promotes the head of the queue**: the next waiter receives the claim.
@@ -254,28 +251,28 @@ Releasing **promotes the head of the queue**: the next waiter receives the claim
 **Example**
 
 ```ts
-const report = await ablo.weatherReports.claim('report_stockholm', { action: 'reviewing' });
+const claim = await ablo.weatherReports.claim({ id: 'report_stockholm', action: 'reviewing' });
+const report = claim.data;
 try {
   const ok = await reviewExternally(report);
   if (!ok) return; // abandon, no write
-  await ablo.weatherReports.update(report.id, { status: 'ready' });
+  await ablo.weatherReports.update({ id: report.id, data: { status: 'ready' } });
 } finally {
-  await ablo.weatherReports.claim.release(report.id);
+  await ablo.weatherReports.claim.release({ id: report.id });
 }
 ```
 
 ### Writing under a claim
 
 There is no separate "write" method on a claim — use the normal
-`ablo.<model>.update(id, data)`. While you hold a claim on `id`, that `update` is
+`ablo.<model>.update({ id, data })`. While you hold a claim on `id`, that `update` is
 automatically stale-guarded against the snapshot the claim took (`readAt` =
 snapshot watermark, `onStale: 'reject'`) and attributed to the claim's lease, so
 it rejects with [`AbloStaleContextError`](#errors) if the row changed under you.
 
 ```ts
-await ablo.weatherReports.claim(id, async (report) => {
-  await ablo.weatherReports.update(report.id, { status: 'ready' }); // guarded by the claim
-});
+await using claim = await ablo.weatherReports.claim({ id });
+await ablo.weatherReports.update({ id: claim.data.id, data: { status: 'ready' } }); // guarded by the claim
 ```
 
 Claims are **enforced server-side**: if you `update`/`delete` a row that *another*
@@ -286,7 +283,7 @@ on fresh data. You never conflict with your own claim, and reads are never gated
 
 ```ts
 try {
-  await ablo.weatherReports.update(id, { status: 'ready' });
+  await ablo.weatherReports.update({ id, data: { status: 'ready' } });
 } catch (err) {
   if (err instanceof AbloClaimedError) {
     // someone else holds it — claim the row and retry from fresh state
@@ -318,10 +315,10 @@ that moved during your generation window — use it for selective regeneration
 
 ```ts
 try {
-  await ablo.weatherReports.claim('report_stockholm', async (report) => {
-    const weather = await weatherAgent.getWeather(report.location); // slow gap
-    await ablo.weatherReports.update(report.id, { forecast: weather });
-  });
+  await using claim = await ablo.weatherReports.claim({ id: 'report_stockholm' });
+  const report = claim.data;
+  const weather = await weatherAgent.getWeather(report.location); // slow gap
+  await ablo.weatherReports.update({ id: report.id, data: { forecast: weather } });
 } catch (err) {
   if (err instanceof AbloClaimedError && err.code === 'claim_lost') {
     // Our lease lapsed mid-flight (we stalled past the TTL). Re-claim and retry.

package/docs/data-sources.md

@@ -54,8 +54,8 @@ ABLO_API_KEY=sk_live_...
 The SDK call is the same in both modes:
 
 ```ts
-await ablo.weatherReports.create({ location: 'Stockholm', status: 'pending' });
-await ablo.weatherReports.update('report_stockholm', { status: 'ready' });
+await ablo.weatherReports.create({ data: { location: 'Stockholm', status: 'pending' } });
+await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' } });
 const report = ablo.weatherReports.get('report_stockholm');
 ```
 
@@ -96,13 +96,13 @@ The shape is the same as a production webhook integration:
 2. Store `ABLO_API_KEY` in your app.
 3. Verify signed HTTP calls before opening a database transaction.
 4. Keep your database credentials in your app.
-5. Write an outbox row when data changes outside Ablo.
+5. Write an outbox row in the same transaction as every app-row change.
 
 ## Route
 
 ```ts
 // app/api/ablo/source/route.ts
-import { dataSource } from '@abloatai/ablo';
+import { dataSource, sourceEventForOperation } from '@abloatai/ablo';
 import { schema } from '@/ablo/schema';
 import { db } from '@/db';
 
@@ -117,7 +117,23 @@ export const POST = dataSource({
   async commit({ operations, clientTxId, context }) {
     const rows = await context.auth.db.transaction(async (tx) => {
       await tx.idempotency.upsert({ key: clientTxId, operations });
-      return applyOperations(tx, operations);
+      const changes = await applyOperations(tx, operations);
+      await tx.outbox.createMany({
+        data: changes.map(({ eventId, operation, entityId, data }) =>
+          sourceEventForOperation({
+            eventId,
+            operation,
+            entityId,
+            data,
+            ...(clientTxId ? { clientTxId } : {}),
+            ...(context.scope?.organizationId
+              ? { organizationId: context.scope.organizationId }
+              : {}),
+            occurredAt: Date.now(),
+          }),
+        ),
+      });
+      return changes.map(({ row }) => row);
     });
 
     return { rows };
@@ -140,11 +156,13 @@ export const POST = dataSource({
 Your app code still writes through the normal model API:
 
 ```ts
-await ablo.weatherReports.update(
-  'report_stockholm',
-  { status: 'ready' },
-  { wait: 'confirmed', readAt: snap.stamp, onStale: 'reject' },
-);
+await ablo.weatherReports.update({
+  id: 'report_stockholm',
+  data: { status: 'ready' },
+  wait: 'confirmed',
+  readAt: snap.stamp,
+  onStale: 'reject',
+});
 ```
 
 ## Commit Request
@@ -188,10 +206,12 @@ Return canonical rows:
 Use explicit `deltas` only when your source already computes canonical change
 events.
 
-## External Writes
+## Outbox Events
 
-If your app changes data outside Ablo, return those changes from an `events`
-handler so connected humans and agents stay current:
+Return your outbox feed from an `events` handler so connected humans and agents
+stay current. Include SDK-origin events too. If Ablo already appended the commit
+directly, `clientTxId` lets Ablo filter the echo; if the direct append failed,
+the same outbox row repairs it on the next poll or push.
 
 ```ts
 export const POST = dataSource({
@@ -218,7 +238,6 @@ export const POST = dataSource({
 });
 ```
 
-`clientTxId` lets Ablo drop SDK echoes that already produced a realtime update.
 Events without `clientTxId` are treated as external writes.
 
 ## Production Checklist
@@ -230,7 +249,8 @@ Before using a customer-owned database in production:
 - Verify signatures before opening a database transaction.
 - Store `clientTxId` in an idempotency table before applying writes.
 - Return canonical rows after each commit.
-- Write outbox events in the same transaction as non-Ablo writes.
+- Write outbox events in the same transaction as every app-row write, including
+  Data Source `commit` writes.
 - Dedupe outbox events by event `id`.
 - Monitor last success, last error, retry count, event lag, and cursor.