@abloatai/ablo 0.46.0 → 0.47.0

package/AGENTS.md

@@ -79,7 +79,7 @@ await ablo.weatherReports.update({
 
 ## Coordination surface
 
-Claims live on a callable namespace beside `create` / `update` / `retrieve`. Every member takes an options object:
+Claims live on a callable namespace beside `create` / `update` / `get`. Every member takes an options object:
 
 - `await using claim = await ablo.<model>.claim({ id })` — acquire the row (waits if held); read it via `claim.data`; auto-releases on scope exit (or call `claim.release()`).
 - `ablo.<model>.claim.state({ id })` — who is currently working on the row (synchronous; never blocks).

package/CHANGELOG.md

@@ -1,7 +1,42 @@
 # Changelog
 
+## 0.47.0
+
+### Minor Changes
+
+- 101ca2c: Make schema model writes optimistic with one stable promise contract: local reactive state changes immediately, while awaiting `create`, `update`, or `delete` always waits for authoritative confirmation. Remove the model-level and client-level `wait` options; explicit queued-versus-confirmed receipt control remains on `commits.create`.
+
+### Patch Changes
+
+- Updated dependencies [101ca2c]
+  - @abloatai/transaction@0.47.0
+  - @abloatai/humans@0.47.0
+
 ## 0.46.0
 
+### Provider branches isolate environments; schemas isolate projects
+
+Several Ablo projects can now share one physical Postgres database safely when
+each owns a separate schema. `ablo connect apply --schema mail` binds the
+authenticated project branch to `(database, mail)` and derives an independent
+slot, publication, replication role, and writer role. Publications enumerate
+schema-qualified mapped tables and the idempotency ledger lives in the selected
+schema. A provider branch's distinct direct URL remains the environment boundary
+for Neon, Supabase, and similar hosts.
+
+Registration enforces one owner per `(database, schema)` globally, without
+revealing another organization's coordinates, and refuses a new binding when
+`max_replication_slots` has no capacity. Runtime replication, rotate,
+resnapshot, disconnect, and scan use the binding's stored/derived footprint;
+legacy manual setups remain single-binding.
+
+New clients can pin their intended project and branch with `projectId` /
+`ABLO_PROJECT_ID` and `branchId` / `ABLO_BRANCH_ID`. `ablo dev` writes both
+immutable coordinates beside its branch-bound key, and `ready()` compares them
+with the key's server-resolved target before opening the sync connection. A mail
+deployment carrying a slides key now fails with `project_scope_denied`; a
+same-project key for the wrong environment fails with `branch_scope_denied`.
+
 ### Pre-existing rows arrive on their own
 
 Connecting a database that already holds data no longer leaves those rows
@@ -13,6 +48,19 @@ snapshot completes, and `ablo status --json` exposes the progress as
 `complete`. Row-touch backfill scripts are unnecessary; the snapshot is the
 engine's job.
 
+The snapshot reader now detects row-level security that would filter its
+ordinary `SELECT` even though WAL carries every published row. New setup plans
+give the read-only replication role `BYPASSRLS` (with `SELECT` still restricted
+to published tables), and readiness refuses to call an RLS-filtered snapshot
+safe. Existing connections can run `ablo connect resnapshot` after repairing
+the role; it recreates only the slot and keeps the DataSource and credentials.
+The same completion guard rejects an empty or partial snapshot mapping: if a
+pushed model's table is absent from the publication, completion stays pending
+until coverage is repaired and a fresh snapshot is requested. Snapshot and WAL
+mapping now use the DataSource's configured Postgres schema as part of relation
+identity, so an identically named table in another schema cannot be loaded into
+the model or falsely satisfy publication coverage.
+
 ## 0.45.0
 
 ### Claim admission is authoritative

package/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2025-2026 Fablo Innovation AB
+   Copyright 2025-2026 Lukas Andersson
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/NOTICE

@@ -1,10 +1,10 @@
 @ablo/ablo
-Copyright 2025-2026 Fablo Innovation AB
+Copyright 2025-2026 Lukas Andersson
 
-This product includes software developed by Fablo Innovation AB
+This product includes software developed by Lukas Andersson
 (https://ablo.finance).
 
-"Ablo" is a trademark of Fablo Innovation AB. This license does not grant
+"Ablo" is a trademark of Lukas Andersson. This license does not grant
 permission to use the Ablo name, logo, or trademarks. Third parties
 may describe their use of or compatibility with Ablo factually (e.g.,
 "built with @ablo/ablo") but may not use the Ablo name in a way

package/README.md

@@ -63,7 +63,6 @@ if (!order) throw new Error('Order not found');
 await ablo.orders.update({
   id: order.id,
   data: { status: 'approved' },
-  wait: 'confirmed',
 });
 ```
 
@@ -82,7 +81,6 @@ await ablo.orders.update({
   id: claim.data.id,
   data: { total: priced.total, status: 'repriced' },
   claim,
-  wait: 'confirmed',
 });
 ```
 

package/docs/agent-messaging.md

@@ -106,7 +106,6 @@ try {
       aboutEntityId: workItemId,
       aboutIntentId: claim.claimId,
     },
-    wait: "confirmed",
   });
 } finally {
   await claim.release();

package/docs/agents.md

@@ -147,7 +147,7 @@ default caller here, not a bolt-on.
 
 ```text
 something happens ──▶ your agent (HTTP, no socket)
-  (a job, a webhook,     read context (list/retrieve)
+  (a job, a webhook,     read context (list/get)
    a queue message)      claim → work → commit
                          done — no held connection
 ```

package/docs/api.md

@@ -41,7 +41,7 @@ await ablo.ready();
 const report = await ablo.weatherReports.get({ id: 'report_stockholm' });
 if (!report) throw new Error('Row not found');
 
-await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' }, wait: 'confirmed' });
+await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' } });
 ```
 
 For end-to-end app setup across React, existing backends, Data Source, and
@@ -75,7 +75,7 @@ fallback removed — nothing to await, so they return a value.
 | `update({ id, data, ...options })` | `Promise<T>` | You want to update through the schema model. |
 | `delete({ id, ...options })` | `Promise<void>` | You want to delete through the schema model. |
 
-`retrieve`, `list`, `create`, `update`, and `delete` are the main path — they go
+`get`, `list`, `create`, `update`, and `delete` are the main path — they 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.
 
@@ -91,17 +91,18 @@ await ablo.weatherReports.update({
   data: { status: 'ready' },
   readAt: snap.stamp,
   onStale: 'reject',
-  wait: 'confirmed',
 });
 ```
 
+Reactive local state changes optimistically at call time; awaiting the model
+write waits for authoritative confirmation.
+
 Protected write options:
 
 | Option | Purpose |
 |---|---|
 | `readAt` | The state cursor the write was based on. |
 | `onStale` | Stale-state policy. Prefer `reject` for agent writes. |
-| `wait` | `queued` resolves after local queueing; `confirmed` waits for server acceptance. |
 | `idempotencyKey` | Stable key for retry-safe writes. The SDK generates one when omitted. |
 | `timeout` | Maximum time to wait for the write call. |
 
@@ -113,7 +114,7 @@ row, `claim` waits for them, re-reads the fresh row, then hands it to you — so
 two writers serialize instead of clobbering. A claim is temporary: it expires
 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`/`retrieve`:
+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

package/docs/cli.md

@@ -145,9 +145,9 @@ npx ablo docs --json           # the page list, machine-readable
 
 These pages ship inside the npm package, so they describe the code beside them
 and stay reachable with no network — isolated agent environments and CI runners
-often have none. That matters most when a project is pinned: `get` / `getAll` /
-`getCount` became `retrieve` / `list` in 0.35.0, and a website always describes
-the newest release, so an agent on an earlier version reads the new name and
+often have none. That matters most when a project is pinned: `claim` took a
+callback before it returned a disposable handle, and a website always describes
+the newest release, so an agent on an earlier version reads the new shape and
 writes a call its own package doesn't have.
 
 Pass a slug (`coordination`), a path (`docs/coordination.md`), or a file name
@@ -330,5 +330,5 @@ migration can't leave clients gated against tables that don't match.
 | ------------------------------------- | ------------------------------------------------------------------------ | -------------------------- |
 | `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_AUTH_URL`                       | Dashboard origin for `ablo login`'s device flow.                         | `https://www.abloatai.com` |
 | `ABLO_CONFIG_DIR` / `XDG_CONFIG_HOME` | Where the credential file lives.                                         | `~/.config/ablo`           |

package/docs/client-behavior.md

@@ -57,11 +57,15 @@ const report = await ablo.weatherReports.get({ id: 'report_stockholm' });
 const local = ablo.weatherReports.local.get('report_stockholm');
 
 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' });
+await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' } });
+await ablo.weatherReports.delete({ id: 'report_stockholm' });
 ```
 
-Call `retrieve`/`list` first — they fetch from the server and you `await` them.
+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.
 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.
@@ -87,7 +91,6 @@ await ablo.weatherReports.update({
   data: patch,
   readAt: snap.stamp,
   onStale: 'reject',
-  wait: 'confirmed',
 });
 ```
 
@@ -109,7 +112,6 @@ it for reads, but it bypasses claims and ordering.
 await ablo.weatherReports.update({
   id: 'report_stockholm',
   data: { status: 'ready' },
-  wait: 'confirmed',
   readAt: snap.stamp,
   onStale: 'reject',
   idempotencyKey: 'report_stockholm:mark-ready:v1',
@@ -118,7 +120,6 @@ await ablo.weatherReports.update({
 
 | Option | Purpose |
 |---|---|
-| `wait` | `queued` resolves after local queueing; `confirmed` waits for server acceptance. |
 | `readAt` | State cursor the write was based on. |
 | `onStale` | Policy when the target changed after `readAt`. Prefer `reject`. |
 | `idempotencyKey` | Stable key for retry-safe writes. The SDK generates one when omitted. |
@@ -180,7 +181,7 @@ All SDK errors extend `AbloError` and carry a stable `type`.
 import { AbloClaimedError } from '@abloatai/ablo';
 
 try {
-  await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' }, wait: 'confirmed' });
+  await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' } });
 } catch (error) {
   if (error instanceof AbloClaimedError) {
     return { status: 'claimed' };

package/docs/coordination.md

@@ -313,7 +313,7 @@ four axes. `claim({ id })` alone is a complete call; each axis is opt-in.
 
 | name | type | required | description |
 |---|---|---|---|
-| `id` | `string` | yes | The row id: same id as `retrieve` / `update`. |
+| `id` | `string` | yes | The row id: same id as `get` / `update`. |
 | `options.fields` | field selector | no | Claim fields declared by the model's Zod schema instead of the whole row: `fields: (task) => task.status`, or `fields: (task) => [task.status, task.title]` for several. The model supplies its own fields, so autocomplete is exact, a typo does not compile, and a schema rename is a compile error at every use. Two sets conflict where they intersect, so holders of disjoint fields do not wait for each other; see [claiming part of a row](#claiming-part-of-a-row). |
 
 *What others see* — the presence half:
@@ -510,7 +510,7 @@ summary into the same snapshot immediately.
 
 **You don't subscribe to anything first.** Reading or claiming a row
 automatically enrolls you in that row's sync group: reading it (including
-`retrieve`/`get`, or `claim.state` itself) gives you **read-interest**, and
+`get`, or `claim.state` itself) gives you **read-interest**, and
 `claim`-ing it gives you a **pinned write-intent**. So `claim.state({ id })`
 observes co-participants on that row from **any** client — a browser, a Server
 Action, or a Node agent — and a holder sees its own claim, with no manual

package/docs/data-sources.md

@@ -36,6 +36,36 @@ npx ablo connect apply --env-file .env.local --yes
 The explicit flag makes the credential choice visible and loads both the
 branch-bound key and database URL. Shell environment variables take precedence.
 
+### One database, several projects
+
+Provider database URLs and Postgres schemas solve different isolation jobs:
+
+```text
+database URL = production, staging, or preview environment
+schema       = application/project inside that database
+ABLO_API_KEY = exact Ablo project branch to bind
+```
+
+It is safe to keep several apps in one production database when each app has its
+own schema:
+
+```bash
+ABLO_API_KEY="$MAIL_KEY" DATABASE_URL="$PRODUCTION_URL" \
+  npx ablo connect apply --schema mail --yes
+
+ABLO_API_KEY="$SLIDES_KEY" DATABASE_URL="$PRODUCTION_URL" \
+  npx ablo connect apply --schema slides --yes
+```
+
+For a Neon or Supabase preview branch, use that branch's direct URL and keep the
+schema name stable. Ablo binds one plane to `(database, schema)`: the same
+database may add `billing`, but a second project cannot also claim `mail`.
+Cross-organization conflicts reveal only that the binding is occupied.
+
+Push the Ablo schema before connecting, or pass `--tables`. The publication is
+an explicit list of schema-qualified mapped tables; Ablo never uses a
+database-wide `FOR ALL TABLES` publication for this multi-project path.
+
 If scoped roles already exist but their passwords are unavailable, do not drop
 them or run `DROP OWNED`. Rotate them in place and re-register the fresh
 credentials:
@@ -60,11 +90,12 @@ without printing the secret. Retire the old variable after the move.
 ## Connect in one command
 
 ```bash
-npx ablo connect apply --url postgres://admin:...@host:5432/db
+npx ablo connect apply --url postgres://admin:...@host:5432/db --schema mail
 ```
 
-Pass an admin connection string with `--url` and it creates the publication, the
-two scoped roles, and the grants, turns on logical decoding where it can, registers
+Pass an admin connection string with `--url` and select the application namespace
+with `--schema` (default `public`). It creates a per-binding publication, two
+per-binding scoped roles, and the grants, turns on logical decoding where it can, registers
 both scoped roles with Ablo, and proves the setup by reconnecting and reading back.
 The admin credential is used on this machine only and never persisted — nothing is
 written to your `.env`, which keeps holding only `ABLO_API_KEY`. Pass `--show-sql`
@@ -78,7 +109,7 @@ to run it by hand or review exactly what changes.
 
 When Ablo creates the replication slot, it takes a consistent initial snapshot of
 every mapped table in the publication before following new changes. Rows that
-predate `ablo connect` therefore become available to `retrieve`, `list`, and
+predate `ablo connect` therefore become available to `get`, `list`, and
 reactive `local.*` reads without an application backfill.
 
 Run `ablo connect check` before removing an existing HTTP/database read fallback.
@@ -87,6 +118,24 @@ write a script that updates every row to make it visible: an Ablo update require
 the row to be visible already, and touching application rows is neither necessary
 nor a safe bootstrap mechanism.
 
+If a connection was snapshotted with an older replication role whose row-level
+security hid historical rows, repair that role and request the load again without
+deregistering or rotating credentials:
+
+```bash
+npx ablo connect rotate      # reasserts BYPASSRLS and safely re-registers both roles
+npx ablo connect resnapshot  # recreates only the slot; the load is asynchronous
+npx ablo connect check       # repeat until the existing-row load is complete
+```
+
+Use the same `resnapshot` step after adding an existing populated table to the
+publication. Following its future WAL changes is not enough to load rows written
+before publication membership; the snapshot coverage guard therefore refuses to
+record completion when even one mapped table is absent. Relation matching is
+schema-qualified using the DataSource's configured `schema` (default `public`):
+an identically named table in another Postgres schema neither counts as coverage
+nor enters the snapshot or WAL stream for your model.
+
 ## The setup, step by step
 
 ### 1. Enable logical decoding
@@ -112,24 +161,34 @@ npx ablo connect
 `ablo connect` prints the exact, copy-pasteable setup SQL for **your** Postgres.
 Run it against your database as a superuser or the DB owner. It creates:
 
-- **A publication** naming the tables Ablo reads and confirms against
-  (`ablo_publication`, the single canonical name the runtime subscribes to):
+- **A per-binding publication** naming only the schema-qualified mapped tables
+  Ablo reads and confirms against. Its suffix is derived from the authenticated
+  Ablo plane and is stable across re-runs:
 
   ```sql
-  CREATE PUBLICATION "ablo_publication" FOR ALL TABLES;
+  CREATE PUBLICATION "ablo_publication_<suffix>"
+    FOR TABLE "mail"."messages", "mail"."threads";
   ```
 
-  Scope it to a subset with `npx ablo connect --tables a,b,c`.
+  Override the pushed model set with `--tables a,b,c`.
 
 - **A replication role:** it streams the WAL and `SELECT`s, nothing more. This is
   the role Ablo reads and confirms through. You choose the password; it never
   passes through Ablo's CLI or servers:
 
   ```sql
-  CREATE ROLE "ablo_replicator" WITH REPLICATION LOGIN PASSWORD '<password>';
-  GRANT SELECT ON ALL TABLES IN SCHEMA public TO "ablo_replicator";
+  CREATE ROLE "ablo_replicator_<suffix>" WITH
+    NOSUPERUSER BYPASSRLS NOCREATEDB NOCREATEROLE REPLICATION NOINHERIT
+    LOGIN PASSWORD '<password>';
+  GRANT SELECT ON TABLE "mail"."messages", "mail"."threads"
+    TO "ablo_replicator_<suffix>";
   ```
 
+  `BYPASSRLS` is required because the initial load is an ordinary `SELECT`,
+  while logical replication already exposes every row in the publication
+  independently of row-level-security policies. Keep this role's `SELECT`
+  grants scoped to the published tables; it has no write or DDL privileges.
+
   On Amazon RDS the `REPLICATION` attribute is granted, not set directly:
   `GRANT rds_replication TO "ablo_replicator";`.
 
@@ -139,15 +198,23 @@ Run it against your database as a superuser or the DB owner. It creates:
   can change rows in your tables; it cannot change your database:
 
   ```sql
-  CREATE ROLE "ablo_writer" WITH LOGIN PASSWORD '<write-password>'
+  CREATE ROLE "ablo_writer_<suffix>" WITH LOGIN PASSWORD '<write-password>'
     NOSUPERUSER NOBYPASSRLS NOCREATEDB NOCREATEROLE NOREPLICATION NOINHERIT;
-  GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO "ablo_writer";
+  GRANT SELECT, INSERT, UPDATE, DELETE
+    ON TABLE "mail"."messages", "mail"."threads"
+    TO "ablo_writer_<suffix>";
   ```
 
   Rename either role with `--role <name>` / `--write-role <name>`.
 
-The **replication slot** is created and owned by Ablo's runtime when it first
-subscribes — you don't pre-create it.
+The schema-local `ablo_idempotency` ledger lives beside that app's tables. The
+**replication slot** (`ablo_slot_<suffix>`) is created and owned by Ablo's runtime
+when it first subscribes — you don't pre-create it. Registration checks
+`max_replication_slots` first and explains how to free or add capacity.
+
+`ablo connect --manual` retains the legacy canonical object names for
+compatibility and is therefore single-binding within a physical database. Use
+`connect apply --schema …` when several projects share that database.
 
 ### 3. Register the database with Ablo
 
@@ -197,6 +264,8 @@ Your **app** holds only the API key — never a connection string:
 ```bash
 # .env — server runtime only, never the browser
 ABLO_API_KEY=sk_...
+ABLO_PROJECT_ID=proj_...
+ABLO_BRANCH_ID=br_...
 ```
 
 ```ts
@@ -206,9 +275,18 @@ import { schema } from './ablo/schema';
 export const ablo = Ablo({
   schema,
   apiKey: process.env.ABLO_API_KEY,
+  projectId: process.env.ABLO_PROJECT_ID,
+  branchId: process.env.ABLO_BRANCH_ID,
 });
 ```
 
+`ABLO_PROJECT_ID` and `ABLO_BRANCH_ID` are safety assertions, not routing inputs.
+The API key still selects the project and branch; during `ready()` Ablo asks the
+server what the key actually targets and refuses startup when either coordinate
+differs. `ablo dev` writes all three values together, so accidentally exporting
+a slides key into the mail app—or a mail development key into production—fails
+before any read, write, or subscription begins.
+
 The Ablo schema describes **only your synced, collaborative models** — the rows
 Ablo coordinates and fans out in realtime. It is _not_ your whole-database schema
 and does _not_ replace your `schema.prisma` (or Drizzle schema). Your auth,
@@ -227,7 +305,7 @@ landed:
 await ablo.weatherReports.update({ id: 'report_stockholm', data: { high: 21 } });
 
 // Block until your database has it and the WAL echo confirms.
-await ablo.weatherReports.update({ id: 'report_stockholm', data: { high: 21 }, wait: 'confirmed' });
+await ablo.weatherReports.update({ id: 'report_stockholm', data: { high: 21 } });
 
 // Reads are live off the same stream.
 const report = ablo.weatherReports.local.get('report_stockholm');

package/docs/debugging.md

@@ -267,7 +267,6 @@ import { AbloError } from '@abloatai/ablo';
 try {
   await ablo.documents.create({
     data,
-    wait: 'confirmed',
   });
 } catch (error) {
   if (error instanceof AbloError) {
@@ -276,10 +275,10 @@ try {
 }
 ```
 
-With `wait: 'confirmed'`, the awaited call rejects with that complete typed
-error. `onMutationFailure` remains the notification channel for optimistic
-writes that return before the server answers; it is not required to recover
-details from a confirmed write.
+An awaited model write rejects with that complete typed error.
+`onMutationFailure` remains the notification channel for deliberately
+unawaited optimistic writes; it is not required to recover details from an
+awaited write.
 
 ### Local reads versus a confirmed server read
 

package/docs/examples/agent-human.md

@@ -75,7 +75,6 @@ export async function markDone(taskId: string) {
     //   ablo.tasks.update({
     //     id: claim.data.id,
     //     data: { status: 'done' },
-    //     wait: 'confirmed',
     //     readAt: <claim snapshot version>,
     //     onStale: 'reject',
     //   });
@@ -86,7 +85,6 @@ export async function markDone(taskId: string) {
     const updated = await ablo.tasks.update({
       id: claim.data.id,
       data: { status: 'done' },
-      wait: 'confirmed',
     });
 
     return { status: 'done', task: updated };

package/docs/examples/existing-python-backend.md

@@ -255,7 +255,6 @@ await ablo.weatherReports.update({
   data: { status: 'ready' },
   readAt: snap.stamp,
   onStale: 'reject',
-  wait: 'confirmed',
 });
 ```
 
@@ -294,7 +293,6 @@ await ablo.weatherReports.update({
   data: { status: 'ready' },
   readAt: snap.stamp,
   onStale: 'reject',
-  wait: 'confirmed',
 });
 ```
 

package/docs/examples/nextjs.md

@@ -23,7 +23,7 @@ app/
       route.ts              # mints a per-user ek_ token for the browser
   tasks/
     [id]/
-      page.tsx              # RSC: retrieve + render
+      page.tsx              # RSC: get + render
       actions.ts            # Server Action: claim, then write
       TaskEditor.tsx        # Client: live updates
 lib/
@@ -168,7 +168,6 @@ export async function markDone(id: string) {
     id,
     data: { status: 'done' },
     claim,
-    wait: 'confirmed',
   });
 
   return { status: 'done', task };

package/docs/examples/server-agent.md

@@ -69,7 +69,6 @@ export async function completeTask(taskId: string, workerId: string) {
   const updated = await ablo.tasks.update({
     id: claim.data.id,
     data: { status: 'done' },
-    wait: 'confirmed',
   });
 
   return { status: 'done', task: updated };
@@ -79,8 +78,8 @@ export async function completeTask(taskId: string, workerId: string) {
 
 `get({ id })` is an async server read — it hits the server and returns the
 row (or `undefined`, which the early `not_found` guard handles). The update runs
-while the claim is held, and `wait: 'confirmed'` makes it resolve only once your
-database has confirmed the row landed.
+while the claim is held; awaiting it resolves only once your database has
+confirmed the row landed.
 
 The two options on the claim:
 

package/docs/groups.md

@@ -266,7 +266,7 @@ try {
   await ablo.tasks.update({ id, data });
 } catch (err) {
   if (err.code === 'stale_context') {
-    const fresh = await ablo.documents.retrieve({ id: 's-1' });   // read
+    const fresh = await ablo.documents.get({ id: 's-1' });   // read
     await ablo.documents.track({ id: 's-1', onStale: 'reject' }); // acknowledge
     await ablo.tasks.update({ id, data: reconsider(fresh) });     // now it lands
   }

package/docs/guarantees.md

@@ -14,14 +14,13 @@ of clobbering.
 
 ## Confirmed Writes
 
-`wait: 'confirmed'` resolves only after the server accepts the write and returns
-the authoritative sync cursor.
+Awaiting a schema model write resolves only after authoritative confirmation
+and returns the updated row.
 
 ```ts
 const updated = await ablo.weatherReports.update({
   id: 'report_stockholm',
   data: { status: 'ready' },
-  wait: 'confirmed',
 });
 ```
 
@@ -37,9 +36,8 @@ Schema model writes return the updated model row.
 Schema model writes update local state optimistically. This keeps UI and agent
 tools responsive while the commit is sent to the server.
 
-- With `wait: 'queued'` or omitted, the promise resolves after the local mutation
-  is queued.
-- With `wait: 'confirmed'`, the promise waits for server confirmation.
+- The local model changes immediately, before the promise settles.
+- The promise always waits for authoritative confirmation.
 - If the server rejects the write, the SDK rolls back the optimistic change and
   raises a typed error.
 
@@ -58,7 +56,6 @@ await ablo.weatherReports.update({
   data: { status: 'ready' },
   readAt: snap.stamp,
   onStale: 'reject',
-  wait: 'confirmed',
 });
 ```
 

package/docs/how-it-works.md

@@ -7,7 +7,7 @@ whole model — everything below explains what it means and how to use it.
 
 ```ts
 // You call Ablo. Ablo lands the change in your database and confirms it.
-await ablo.tasks.update({ id: 'task_42', data: { status: 'done' }, wait: 'confirmed' });
+await ablo.tasks.update({ id: 'task_42', data: { status: 'done' } });
 
 // Reads come back live, kept current from your database.
 const task = ablo.tasks.local.get('task_42');
@@ -42,10 +42,10 @@ echo confirms it → everyone connected sees it live.**
 | Primitive | Plane | Purpose |
 |---|---|---|
 | `Schema` | State | Declares typed models the app and agents can read and write. |
-| `Model` | State | The generated `ablo.<model>` model. Use `retrieve`/`list` (async reads), `local.get`/`local.list`/`local.count` (the same verbs, synchronous and local-only), `create`, `update`, and `delete`. |
+| `Model` | State | The generated `ablo.<model>` model. Use `get`/`list` (async reads), `local.get`/`local.list`/`local.count` (the same verbs, synchronous and local-only), `create`, `update`, and `delete`. |
 | `Claim` | Coordination | Who is working on a target. Taken via `ablo.<model>.claim({ id })` and read via `ablo.<model>.claim.state({ id })`. Ephemeral, never persisted. |
 | `Commit` | Protocol | The durable write underneath model updates. Most users do not call it directly. |
-| `Receipt` | Protocol | The lower-level durable result for custom runtimes. Schema writes use `wait: 'confirmed'`. |
+| `Receipt` | Protocol | The lower-level durable result for custom runtimes. Awaiting a schema write waits for confirmation. |
 
 ### Why each primitive is separate
 
@@ -102,9 +102,9 @@ import Ablo from '@abloatai/ablo';
 import { schema } from './ablo/schema';
 export const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
-// 5. Write through Ablo. It lands in your Postgres; wait: 'confirmed' blocks
-//    until the WAL echo proves the row is there.
-await ablo.tasks.update({ id: 'task_42', data: { status: 'done' }, wait: 'confirmed' });
+// 5. Write through Ablo. Local state changes immediately; await blocks until
+//    the authoritative feed proves the row is there.
+await ablo.tasks.update({ id: 'task_42', data: { status: 'done' } });
 
 // 6. Read — live, no fetch loop.
 const task = ablo.tasks.local.get('task_42');

package/docs/idempotency.md

@@ -14,7 +14,6 @@ await ablo.tasks.update({
   id: taskId,
   data: { status: 'done' },
   idempotencyKey: `task:${taskId}:mark-done:v1`,
-  wait: 'confirmed',
 });
 ```
 

package/docs/identity.md

@@ -517,7 +517,7 @@ an agent pointed at the entities it's working on. You **never hand-write**
    const ablo = Ablo({ schema, apiKey: session.token });
    ```
 
-2. **Automatically, on read or claim.** Reading a row (`retrieve`/`get`/
+2. **Automatically, on read or claim.** Reading a row (`get`/
    `claim.state`) auto-enrolls the client in that row's entity group
    (**read-interest**), and `claim`-ing it pins a **write-intent** subscription.
    So an agent's reachable set **accretes** as it works — no extra subscribe call.

package/docs/index.md

@@ -14,7 +14,6 @@ await using claim = await ablo.reports.claim({ id: reportId });
 await ablo.reports.update({
   id: claim.data.id,
   data: { forecast: await generateForecast(claim.data) },
-  wait: 'confirmed',
 });
 ```
 
@@ -90,7 +89,7 @@ based on a row that has since changed is turned away rather than applied.
     const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: 'http' });
     ```
 
-    Read with `list` / `retrieve`, coordinate with `claim`, write with `create` / `update` /
+    Read with `list` / `get`, coordinate with `claim`, write with `create` / `update` /
     `delete`. See [Agents](./agents.md) for the loop and [API Reference](./api.md) for the shape.
   </Step>
 

package/docs/integration-guide.md

@@ -77,8 +77,7 @@ When handing this to a coding agent, give it a concrete target:
 ```txt
 Add Ablo to this app for one model your agents edit.
 Run npx ablo dev and use its branch-bound key. Declare schema, add the Ablo client, replace
-one write with ablo.<model>.update(..., { readAt, onStale: 'reject',
-wait: 'confirmed' }), and add a smoke test for two concurrent writers.
+one write with ablo.<model>.update(..., { readAt, onStale: 'reject' }), and add a smoke test for two concurrent writers.
 ```
 
 ## 1. Declare A Schema
@@ -261,9 +260,9 @@ Reads come in two flavors, and you pick based on whether you can wait.
 store) — they're async, so you `await` them. `local.get(id)`,
 `local.list({ where })`, and `local.count({ where })` read the already-synced local
 graph synchronously, so they're the ones you call in render — and the ones you
-use inside a `useAblo` selector, never the async `retrieve`/`list`.
+use inside a `useAblo` selector, never the async `get`/`list`.
 
-Use `retrieve` when the row may not be local yet — it fetches from the server
+Use `get` when the row may not be local yet — it fetches from the server
 and waits.
 
 ```ts
@@ -316,7 +315,7 @@ const ablo = useAblo();
 For simple writes:
 
 ```ts
-await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' }, wait: 'confirmed' });
+await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' } });
 ```
 
 For writes based on state the user or agent already read, snapshot first and
@@ -330,12 +329,12 @@ await ablo.weatherReports.update({
   data: { status: 'ready' },
   readAt: snap.stamp,
   onStale: 'reject',
-  wait: 'confirmed',
 });
 ```
 
-`wait: 'confirmed'` resolves after the server accepts the write. Rejections roll
-back optimistic local state and throw a typed `AbloError`.
+The local row changes optimistically at once. Awaiting the model write waits for
+authoritative confirmation; a rejection rolls the optimistic state back and
+throws a typed `AbloError`.
 
 ## 5. Multiplayer Is Automatic
 
@@ -468,7 +467,6 @@ if (!claimed) return;
 await ablo.weatherReports.update({
   id: claimed.id,
   data: { status: 'ready', forecast: await getForecast(claimed) },
-  wait: 'confirmed',
 });
 ```
 
@@ -489,7 +487,6 @@ const completeReport = tool({
       data: { status: 'ready', forecast },
       readAt: snap.stamp,
       onStale: 'reject',
-      wait: 'confirmed',
     });
   },
 });

package/docs/integrations/inngest.md

@@ -58,7 +58,6 @@ export const approveOrder = inngest.createFunction(
         id: orderId,
         data: { status: 'approved', approvalNote },
         idempotencyKey: `${operationId}:approve-order:${orderId}`,
-        wait: 'confirmed',
       }),
     );
   },
@@ -99,7 +98,7 @@ For every mutating step:
 1. Accept a stable business operation ID in the triggering event.
 2. Derive a separate key for each logical effect.
 3. Reuse the key and mutation body for every retry.
-4. Use `wait: 'confirmed'` when later steps depend on the authoritative result.
+4. Await every model write before a later step depends on its authoritative result.
 5. Treat reuse of a key with another body as an application bug.
 6. Keep the complete retry horizon within Ablo's documented
    [idempotency retention window](../idempotency.md).
@@ -133,7 +132,6 @@ await step.run('apply-order-review', () =>
     id: orderId,
     data: { status: 'approved', approvalNote },
     idempotencyKey: `${operationId}:apply-order-review:${orderId}`,
-    wait: 'confirmed',
   }),
 );
 ```
@@ -167,7 +165,6 @@ await step.run('apply-review-with-claim', async () => {
       data: { status: 'approved', approvalNote },
       claim,
       idempotencyKey: `${operationId}:apply-review:${orderId}`,
-      wait: 'confirmed',
     });
   } finally {
     await claim.release();

package/docs/integrations/temporal.md

@@ -46,7 +46,6 @@ export async function approveOrder(input: ApproveOrderInput) {
       approvalNote: input.approvalNote,
     },
     idempotencyKey: input.idempotencyKey,
-    wait: 'confirmed',
   });
 }
 ```
@@ -135,7 +134,7 @@ For every mutating Activity:
 1. Create the key in deterministic Workflow code or accept a stable operation
    ID in the Workflow input.
 2. Reuse the key and mutation body for every retry of the same logical effect.
-3. Use `wait: 'confirmed'` when later Workflow steps depend on the
+3. Await each model write before later Workflow steps depend on the
    authoritative database result.
 4. Treat reuse of a key with a different body as an application bug.
 5. Keep the Temporal retry horizon within Ablo's documented
@@ -165,7 +164,6 @@ export async function applyReview(orderId: string, note: string) {
     id: claim.data.id,
     data: { approvalNote: note },
     claim,
-    wait: 'confirmed',
   });
 }
 ```

package/docs/internal/agent-orchestration.md

@@ -24,7 +24,6 @@ await ablo.agentJobs.create({
     kind: 'forecast_report',
     target: { model: 'weatherReports', id: 'report_stockholm', field: 'forecast' },
   },
-  wait: 'confirmed',
 });
 ```
 

package/docs/internal/serializable-schema.md

@@ -69,7 +69,7 @@ FNV-1a content hash used for connect-time gating. Round-trip tested in
   error, createdBy, createdAt, activatedAt)`, unique `(orgId, version)`. State
   `pending|validated|active|overwritten|failed`, ≤1 active per tenant (Convex
   `_schemas` machine; Zero's "row in the operational DB"). *Migration written,
-  not applied — 0 users, Neon direct-endpoint rule.*
+  not applied — 0 users at the time.*
 - **`pgSchemaStore` / `memorySchemaStore`** (`schemaStore.ts`) — mirrors
   `pgApiKeyStore`. `insertPending` assigns `MAX(version)+1`; `activate` is a
   transaction that demotes the current active → `overwritten` then promotes the

package/docs/migration.md

@@ -293,7 +293,7 @@ helper, and the agent/task type family (`Agent`, `AgentOptions`,
 + const { token } = await server.sessions.create({ agent: { id: agentId } });
 + const agent = Ablo({ schema, apiKey: token });
 + await using claim = await agent.tasks.claim({ id });
-+ await agent.tasks.update({ id, data: { status: 'done' }, wait: 'confirmed' });
++ await agent.tasks.update({ id, data: { status: 'done' } });
 ```
 
 Per-run token/cost now lives in Langfuse, not an `agent_tasks` table. The only
@@ -324,10 +324,10 @@ modifier are named siblings. Reactive local reads stay on the synchronous
 
 ```diff
 - await ablo.tasks.update(id, { status: 'done' }, { wait: 'confirmed' })
-+ await ablo.tasks.update({ id, data: { status: 'done' }, wait: 'confirmed' })
++ await ablo.tasks.update({ id, data: { status: 'done' } })
 
 - await ablo.tasks.retrieve(id)
-+ await ablo.tasks.retrieve({ id })
++ await ablo.tasks.get({ id })
 
 - useAblo((ablo) => ablo.tasks.retrieve(id)) ?? serverTask
 + useAblo((ablo) => ablo.tasks.local.get(id)) ?? serverTask

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

@@ -46,7 +46,7 @@ Sort any action you're about to take into one of these, and the right move
 follows.
 
 **Run freely — read-only or reversible.**
-Reads (`retrieve`, `list`, `get`), `ablo check`, and `ablo pull` observe and
+Reads (`get`, `list`), `ablo check`, and `ablo pull` observe and
 never change anything. Previews — `--show-sql`, `--dry-run` — print the exact
 SQL a command would run without executing it. Model writes through
 `ablo.<model>.create` / `update` are claim-checked, optimistic, rolled back if
@@ -95,7 +95,7 @@ read-only checks:
   Read-only, like `prisma db pull`.
 - `--show-sql` / `--dry-run` on `connect` and `migrate` — the exact statements,
   printed and unexecuted, so you approve the SQL before it runs.
-- Read the row and its claim state before you write — `retrieve` / `list`, and
+- Read the row and its claim state before you write — `get` / `list`, and
   `ablo.<model>.claim.state({ id })` for who is already working on it.
 
 The pattern underneath all of it is steady: reads and model writes flow freely

package/docs/react.md

@@ -143,7 +143,7 @@ const reports = useAblo((ablo) =>
 const report = await ablo.weatherReports.get({ id });
 ```
 
-Use `retrieve` in Server Components when the row may not be in the local pool
+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
 `list({ where })` for many; both are async. The synchronous local reads are
@@ -162,7 +162,6 @@ await ablo.weatherReports.update({
   data: patch,
   readAt: snap.stamp,
   onStale: 'reject',
-  wait: 'confirmed',
 });
 ```
 
@@ -180,7 +179,6 @@ async function markReady() {
     data: { status: 'ready' },
     readAt: snap.stamp,
     onStale: 'reject',
-    wait: 'confirmed',
   });
 }
 ```

package/docs/schema-contract.md

@@ -6,7 +6,7 @@ Ablo's schema is the integration contract. Define it once, pass it to `Ablo(...)
 and every actor gets the same typed model surface:
 
 ```txt
-defineSchema(...) -> ablo.<model>.create/retrieve/update/claim(...)
+defineSchema(...) -> ablo.<model>.create/get/update/claim(...)
 ```
 
 That one object drives:
@@ -84,7 +84,7 @@ const pending = ablo.weatherReports.local.list({ where: { status: 'pending' } })
 Use model writes for every actor:
 
 ```ts
-await ablo.weatherReports.update({ id: reportId, data: { status: 'ready' }, wait: 'confirmed' });
+await ablo.weatherReports.update({ id: reportId, data: { status: 'ready' } });
 ```
 
 ## Coordination

package/examples/README.md

@@ -21,7 +21,7 @@ const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 Then:
 
 - create with `ablo.weatherReports.create`
-- read with `ablo.weatherReports.retrieve` or `ablo.weatherReports.list`
+- read with `ablo.weatherReports.get` or `ablo.weatherReports.list`
 - coordinate long-running work with `ablo.weatherReports.claim`
 - write with `ablo.weatherReports.update`
 - dispose the client when the worker finishes

package/llms.txt

@@ -61,11 +61,10 @@ await using claim = await ablo.weatherReports.claim({ id: 'report_stockholm' });
 const updated = await ablo.weatherReports.update({
   id: claim.data.id,
   data: { status: 'ready', forecast: await getForecast(claim.data) },
-  wait: 'confirmed',
 });
 ```
 
-That is the normal app path: declare models in a schema, then use `ablo.<model>.retrieve(...)`, `ablo.<model>.create(...)`, `ablo.<model>.update(...)`, and `ablo.<model>.delete(...)`.
+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.
 
 Treat the schema as the integration contract. It drives typed model clients,
 React selectors, server and agent writes, Data Source request/response shape,
@@ -137,7 +136,7 @@ frees. Use `ifClaimed: 'fail'` when you'd rather refuse to read a claimed row.
 
 ## Guarantees
 
-`wait: 'confirmed'` means the server accepted the write. Schema model writes are optimistic by default; 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, 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`.
 
 Claims coordinate writers; they do not block readers. Most users should stay on
 schema-backed reads/writes and `claim(...)`; manual protocol bookkeeping is not

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "description": "The public Ablo SDK for coordinated reads, commits, claims, observation, and reactive applications.",
   "license": "Apache-2.0",
   "type": "module",
@@ -124,8 +124,8 @@
     "directory": "packages/ablo"
   },
   "dependencies": {
-    "@abloatai/humans": "^0.46.0",
-    "@abloatai/transaction": "^0.46.0"
+    "@abloatai/humans": "^0.47.0",
+    "@abloatai/transaction": "^0.47.0"
   },
   "peerDependencies": {
     "ai": "^6.0.0 || ^7.0.0",