@abloatai/ablo 0.46.0 → 0.48.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,154 @@
 # Changelog
 
+## 0.48.0
+
+### A branch is unbound until you connect a database to it
+
+A branch keeps its own storage, and it does not quietly get Ablo's. Until a
+database is connected to that branch, a request needing one fails with
+`no_data_source_registered` and says what to do:
+
+```
+This branch is not connected to your database yet.
+Run `ablo connect` for this branch, then retry.
+```
+
+The old `test_database_not_registered` is gone. It described a sandbox that no
+longer exists, it arrived on requests that had nothing to do with a test
+database, and its advice pointed at options the SDK had already removed. A
+branch created by `ablo dev` now reports its state plainly rather than looking
+ready and then refusing the first schema push.
+
+**Action required.** Replace any handler matching `test_database_not_registered`
+with `no_data_source_registered`. The new code carries the same 4xx meaning and
+a recovery path a caller can act on.
+
+### Failures say which branch they happened on
+
+An unconnected branch previously returned its refusal with nothing written
+server-side, so a support question about one customer's branch could not be
+answered from logs at all. These now carry the request, organization, project,
+branch, key kind and storage state, indexed in Sentry, so a failure can be
+looked up by branch instead of reconstructed from database tables.
+
+### Replication uses your branch's own publication and slot
+
+Registration, validation, writer checks, replication, drift detection and
+`ablo connect` all require the branch-scoped names recorded when the source was
+registered. Nothing falls back to a shared `ablo_publication` or `ablo_slot`
+any more, so two branches on one database can never quietly share a stream.
+`ablo connect scan` reports legacy unsuffixed objects as retired.
+
+Once your engine is on this release and `ablo connect check` is clean, the
+temporary alias can go:
+
+```sql
+DROP PUBLICATION IF EXISTS "ablo_publication";
+```
+
+### Renamed
+
+`FootprintPlane` is now `DataSourceIdentity`, with the same three fields. The
+old name described an internal layout; the new one describes what it
+identifies.
+
+## 0.47.0
+
+### Local Postgres works with Ablo Cloud
+
+Run `npx ablo dev --local` to serve the generated signed Data Source handler
+over an outbound, protocol-scoped connector. Postgres remains private on the
+developer's machine and its connection string never leaves the app process.
+The Data Source guide now explains exactly which writes are visible without
+WAL, and the public error reference includes actionable `source_connector_*`
+codes for every connector lifecycle failure.
+
+### Awaiting a model write now means it is confirmed
+
+`create`, `update`, and `delete` change local reactive state immediately and
+return a promise with a single meaning: the write reached authoritative
+confirmation. An interface stays responsive without awaiting anything, and code
+that needs to know a write survived can await the same call it already makes.
+
+The `wait` option is gone from the client and from individual model calls.
+Awaiting a model write always waits for confirmation, so there is nothing left
+to configure. Explicit control over a queued versus confirmed receipt remains on
+`commits.create`, which still hands back the receipt and its confirmation
+separately.
+
+**Action required.** Remove `wait` from `Ablo({ ... })` and from every
+`create`, `update`, and `delete` call.
+
+- `wait: 'confirmed'` behaves identically once removed.
+- `wait: 'queued'` on a call you never awaited behaves identically once removed.
+- `wait: 'queued'` on a call you did await now waits for confirmation. Move to
+  `commits.create` if the queued receipt was the reason for the option.
+
+### Customer branches connect before accepting a schema
+
+A customer branch now remains in provisioning until it has an active Data
+Source. Ablo does not invent internal storage for customer data: it reads the
+customer's database through WAL and writes through the separately scoped DML
+credential (or uses the explicitly registered signed endpoint fallback).
+
+Database validation now uses the branch-scoped publication and replication slot
+persisted with that Data Source. It no longer falls back to the shared
+`ablo_publication` / `ablo_slot` names, so `ablo connect check` validates the
+same objects that `ablo connect apply` created.
+
+The sandbox-only `test_database_not_registered` error has been removed. An
+unconnected customer branch now consistently returns `no_data_source_registered`
+with the `ablo connect` recovery step.
+
+**Action required for type imports.** `FootprintPlane` has been removed. Import
+`DataSourceIdentity` from `@abloatai/ablo/source` instead; its fields remain
+`organizationId`, optional `projectId`, and `branchId`.
+
+### The CLI names the problem it actually hit
+
+A refused push no longer reports every failure as a missing `schema:push`
+capability. That advice was wrong for most refusals: a database privilege error,
+a row-level security misconfiguration, and an unregistered development database
+each need a different fix, and none of them is a different API key. Each now
+leads with the server's own message and the remedy for that specific cause.
+
+Project names also resolve correctly under a branch-bound key. Listing projects
+is a management operation that such a key is deliberately not allowed to
+perform, so `ablo status` and `ablo push` reported a correctly minted key's
+project as `unnamed` alongside a permission error. The name now comes from the
+stored management credential.
+
+### Deprecations
+
+`METER_EVENT_COUNTS` is deprecated in favour of its per-surface members, and the
+`DatasourceResnapshotResponse` type and its schema are deprecated. All three
+still ship and still work; they will be removed in a later release.
+
 ## 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 +160,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

@@ -22,6 +22,10 @@
 
 ---
 
+> **Reading the implementation?** Start with the
+> **[source code map](./CODEMAP.md)**. It shows which files own `create`,
+> `update`, `delete`, `claim`, schemas, transports, and the reactive client.
+
 Safely coordinate AI agents, humans, workflows, and services writing to the
 same database.
 
@@ -63,7 +67,6 @@ if (!order) throw new Error('Order not found');
 await ablo.orders.update({
   id: order.id,
   data: { status: 'approved' },
-  wait: 'confirmed',
 });
 ```
 
@@ -82,7 +85,6 @@ await ablo.orders.update({
   id: claim.data.id,
   data: { total: priced.total, status: 'repriced' },
   claim,
-  wait: 'confirmed',
 });
 ```
 
@@ -116,6 +118,22 @@ authority, commits, claims, and ordered changes.
 Read the [Quickstart](https://docs.abloatai.com/quickstart), browse
 [docs.abloatai.com](https://docs.abloatai.com), or run `npx ablo docs`.
 
+## Navigating the source
+
+This repository preserves the package ownership boundaries instead of
+flattening the implementation into `packages/ablo`:
+
+- `packages/ablo` is the branded public facade. Its files mostly re-export the
+  package that owns each API.
+- `packages/transaction` owns the shared model-operation contracts and the
+  stateless HTTP implementation.
+- `packages/humans` owns the reactive WebSocket/local/React implementation.
+
+That means searching only inside `packages/ablo/src` will not find the
+implementation of `create`, `update`, `delete`, or `claim`. Read the
+**[source code map](./CODEMAP.md)** for a verb-by-verb ownership table and
+guided call traces for both the default and reactive clients.
+
 ## Contributing
 
 Ablo is free and open source. You can help by

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

@@ -122,7 +122,7 @@ bypasses profiles for project/branch administration; the runtime key remains
 | `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` / `whoami` / `status` | Authentication, exact credential identity, and readiness (above).                                                                              | `whoami --key-env <NAME>`, `whoami --json`, `status --json` |
 | `ablo projects list\|create\|use\|rename` | Manage projects and the active one (see [Projects](#projects)). Each project's keys/schema/data are isolated.                          | `--name "<display>"` (create/rename)                                                                    |
-| `ablo dev`                         | **Hosted**: ensure an isolated Git branch, wire its temporary key, push, then watch `ablo/schema.ts`.                                        | `--branch <slug>`, `--branch-ttl-hours <1-168>`, `--no-watch`, `--schema`, `--export`, `--url` |
+| `ablo dev`                         | Ensure an isolated Git branch, wire its temporary key, push, then watch `ablo/schema.ts`. `--local` also serves local Postgres over an outbound signed connector. | `--branch <slug>`, `--branch-ttl-hours <1-168>`, `--local`, `--source <path>`, `--no-watch`, `--schema`, `--export`, `--url` |
 | `ablo branch list\|status\|check\|create\|ensure\|credential\|delete` | Manage and diagnose immutable branch planes and expiring credentials.                          | Run `ablo branch --help`; use `--json` for automation.                                                   |
 | `ablo logs`                        | Tail the resolved runtime credential's branch activity. Follows by default.                                                                          | `-n, --tail <N>`, `--since <dur\|ts>`, `--model`, `--op`, `--json`, `--no-follow` |
 | `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`         |
@@ -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
@@ -166,8 +166,16 @@ npx ablo dev                              # discover from Git, push + watch
 npx ablo dev --branch preview-pr-482      # explicit branch
 npx ablo dev --no-watch                   # prepare, push once, exit
 npx ablo dev --branch-ttl-hours 24        # change temporary-key lifetime
+npx ablo dev --local                      # keep Postgres private on localhost
 ```
 
+`--local` loads `ablo/data-source.ts` (override with `--source <path>`), registers
+the branch as connector-only, and opens an outbound authenticated WebSocket to
+Ablo. Commit, load, list, and outbox-event requests run through the same signed
+Data Source handler as production; no database credential leaves your process
+and no public tunnel is opened. Because the connector is long-lived, `--local`
+cannot be combined with `--no-watch`.
+
 It does not start your app, run migrations, create a database-provider branch,
 or copy production rows. Read [Branch-first development](./branch-development.md)
 for the exact discovery order, CI flow, database boundary, and troubleshooting.
@@ -330,5 +338,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