@abloatai/ablo 0.46.0 → 0.48.0

package/docs/data-sources.md

@@ -2,6 +2,71 @@
 
 > Keep the rows in your own Postgres while Ablo coordinates and confirms every write.
 
+## Localhost development
+
+Ablo Cloud cannot dial `localhost`: from a cloud server, that name means the
+cloud server itself, not your Mac or development container. A development child
+branch can still use Postgres that listens only on your machine by running a
+signed Data Source over Ablo's outbound reverse channel:
+
+```bash
+npx ablo migrate       # once: models + ablo_idempotency + ablo_outbox
+npx ablo dev --local
+```
+
+The command loads `ablo/data-source.ts`, registers the current child branch as
+connector-only, and dials out to Ablo over an authenticated WebSocket. Postgres
+continues listening only on your machine; `DATABASE_URL` never leaves the
+process. This is protocol-scoped, not a general-purpose tunnel: only signed
+Data Source load, list, commit, and event requests traverse it. Use
+`--source <path>` when the handler lives elsewhere.
+
+Keep `ablo dev --local` running alongside the application. It pushes schema
+changes and owns the database connector; stopping it deliberately makes the
+branch's database unavailable instead of silently writing somewhere else.
+
+### Is this full Ablo?
+
+Yes for the Ablo application path: model reads and lists, coordinated writes,
+claims, subscriptions, idempotency, confirmations, and transactional outbox
+settlement all work against localhost Postgres. The browser, server code, and
+agents still connect to Ablo Cloud; only database operations cross the narrow
+signed connector to your machine.
+
+It is not logical replication. Visibility depends on how a row is written:
+
+| Write origin | Visible to Ablo in localhost mode? | Why |
+|---|---:|---|
+| `ablo.<model>.create/update/delete` | Yes | Ablo coordinates the write, the local adapter commits it with idempotency + outbox, and the outbox event confirms it. |
+| Code using the signed Data Source adapter | Yes | The adapter records the row and authoritative event in one transaction. |
+| A supported source push/outbox integration | Yes | It explicitly publishes the authoritative event to Ablo. |
+| Raw SQL, `psql`, or an unrelated ORM write | No, not automatically | There is no WAL reader in signed-endpoint mode, and bypassing the adapter does not append `ablo_outbox`. |
+
+If Ablo must observe every arbitrary SQL/ORM write, use the direct logical-WAL
+path with a network-reachable Postgres endpoint, PrivateLink/peering/VPN, or a
+database-capable secure tunnel. Do not expose Postgres without TLS,
+authentication, and network restrictions.
+
+### Local connector errors
+
+Every stable code links to the generated [error reference](https://docs.abloatai.com/errors):
+
+| Code | Meaning and fix |
+|---|---|
+| `source_connector_not_attached` | The branch is connector-only but no process is attached. Start or restart `ablo dev --local`. |
+| `source_connector_unauthenticated` | The temporary branch key is missing, expired, or rejected. Rerun `ablo dev --local` to mint a fresh key. |
+| `source_connector_requires_secret_key` | The connector received the wrong key kind. Let `ablo dev` supply its branch-bound `sk_` key. |
+| `source_connector_no_source_registered` | No endpoint source exists for this branch. Upgrade/rerun the CLI so registration happens before socket attachment. |
+| `source_connector_localhost_required` | Connector-only registration used a non-local descriptor. Use `ablo dev --local`; deployed handlers use ordinary HTTPS endpoint registration. |
+| `source_connector_timeout` | The handler or local Postgres exceeded the request deadline. Inspect the local process and database. |
+| `source_connector_handler_error` | `ablo/data-source.ts` or its adapter threw. The local terminal contains the underlying error. |
+| `source_connector_protocol_error` | CLI/SDK and service connector protocols disagree. Upgrade the CLI and SDK together. |
+| `source_connector_production_not_enabled` | A root/production key attempted the development connector. Use a supported production route or explicitly enable production reverse-channel support. |
+
+Disconnects, service restarts, and connector replacement are retryable. Keep the
+same idempotency key: Ablo never falls back from this branch to hosted storage or
+another database.
+
 You write through Ablo, and Ablo writes to your Postgres. A call to
 `ablo.<model>.create / update / delete` enters Ablo's commit chokepoint — where
 claims, ordering, and idempotency are enforced — and Ablo applies the change to
@@ -36,6 +101,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 +155,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 +174,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 +183,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 +226,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 +263,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 +329,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 +340,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 +370,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/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/internal/structure.md

@@ -1,5 +1,9 @@
 # Repository Structure
 
+For a verb-by-verb guide to declarations and implementations—including exactly
+where `create`, `update`, `delete`, and `claim` live—read the public
+[`CODEMAP.md`](../../CODEMAP.md).
+
 The public repository preserves the same ownership boundaries as the main
 monorepo. `@abloatai/ablo` is the product package; the packages beneath it are
 implementation owners and first-party extension surfaces.

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