@abloatai/ablo 0.47.0 → 0.49.0

package/AGENTS.md

@@ -11,7 +11,7 @@ Don't hand-write the integration. Run the CLI; it generates the current-API sche
 - **Read the docs for THIS version:** `npx ablo docs` lists every page, `npx ablo docs <page>` prints one. They ship inside the installed package, so they describe the code in `node_modules` and work with no network. Read them instead of a docs URL — a website describes the newest release, so against a pinned version it will hand you a call your package doesn't have (`retrieve`/`list` replaced `get`/`getAll`/`getCount` in 0.35.0).
 - **Scaffold:** `npx ablo init --yes` — flag-driven, never prompts. Override defaults with `--framework <nextjs|vite|remix|vanilla>`, `--auth <apikey|…>`, `--no-agent`, `--no-pull`, `--no-install`, `--no-login`. (Plain `ablo init` needs a TTY and will **HANG** in an agent/CI run — always pass `--yes`.)
 - **Auth:** set `ABLO_API_KEY` in the environment. Do **NOT** run `ablo login` — it opens a browser device flow and blocks an agent.
-- **Connect your database — logical replication (the primary path):** `npx ablo connect` prints the setup SQL (`wal_level=logical`, a publication, a `REPLICATION` role); `npx ablo connect register` registers the source with Ablo in one step. Ablo **consumes your Postgres' logical-replication stream** — it never runs DDL on, writes to, owns, or migrates your database, and your application keeps the write path. Registration **is** the enable; there is no tier or flag to pick. (Ablo hosts only the transaction log + coordination, never your rows.)
+- **Connect your database — logical replication (the primary path):** `npx ablo connect apply --url <postgres-url>` provisions scoped roles and replication using the admin credential supplied for that command. Model writes then go through Ablo and land in your Postgres; its change stream confirms them. Ablo does not own your rows or run application-schema migrations. Your ORM remains responsible for tables, columns, and constraints.
 - **Fallback — signed Data Source endpoint** (DB can't grant a `REPLICATION` role): the generated `ablo/data-source.ts` exposes one route; Ablo sends signed requests and your app touches its own DB. **Only in this mode** does `npx ablo migrate` provision the adapter's bookkeeping tables (`ablo_outbox`, `ablo_idempotency`) plus your Ablo models — it does **not** touch your other tables. Keep your own migrations (drizzle-kit / prisma migrate) for auth and anything outside the Ablo schema.
 - **No database yet?** Run `npx ablo dev --no-watch --branch <name>` to create an isolated non-root branch and obtain its expiring `sk_` credential. The branch uses a throwaway hosted data plane; Production remains the protected root. There is no shared Sandbox mode.
 - **Adopt an existing DB schema:** `npx ablo pull prisma [path]` / `pull drizzle <module>` (lossless) or `pull` (live DB, lossy). Writes `ablo/schema.ts`.
@@ -21,7 +21,7 @@ Don't hand-write the integration. Run the CLI; it generates the current-API sche
 
 When you use the signed-endpoint fallback, the generated `ablo/data-source.ts` is the whole endpoint and needs no hand-editing: `dataSourceNext({ schema, apiKey, adapter: prismaDataSource(prisma, schema) })` (or `drizzleDataSource(db, schema)`). The adapter owns commit / idempotency / outbox.
 
-**Working on a real database?** Ablo never runs DDL, migrates, or drops on your database, and every model write is claim-checked and reversible in the log — so reads and `ablo.<model>.update(...)` are yours to run freely, while raw DDL (`ALTER TABLE …`) and a `--yes` cutover belong to a human. When you're unsure whether a write fits, `npx ablo check` reports the live column-by-column fit read-only, before anything runs. Full sorting rule: [Operating on Your Database](./docs/operating-on-your-database.md).
+**Working on a real database?** Plain model writes are last-write-wins when no active claim applies. Use a functional update, a held claim, or `readAt` when a result depends on an earlier value. Reads are safe to inspect; raw application DDL (`ALTER TABLE …`) and a `--yes` connection cutover belong to a human. When you're unsure whether a write fits, `npx ablo check` reports the live column-by-column fit read-only, before anything runs. Full sorting rule: [Operating on Your Database](./docs/operating-on-your-database.md).
 
 ## Rule
 

package/CHANGELOG.md

@@ -1,16 +1,235 @@
 # Changelog
 
+## 0.49.0
+
+### An agent can tell Ablo what it read before it writes
+
+An agent reads a row, spends a model call deciding what to do, and then writes.
+Another agent can change that row while the model is still thinking, and the
+write lands anyway, on top of a decision that is no longer true. Pass the rows
+the decision was based on:
+
+```ts
+const task = await ablo.tasks.get({ id: taskId });
+await ablo.tasks.update({
+  id: task.id,
+  data: { status: 'done', result: `Completed: ${task.title}` },
+  reads: [task],
+});
+```
+
+If either row moved while the agent was thinking, the write is refused instead
+of overwriting. The rows carry that evidence themselves, so there is nothing to
+set up around your agent and no wrapper to run it inside. One row or several,
+the same row you are writing or a different one, all use `reads`. Rows an agent
+read without passing stay out of it, so `reads` says what the decision rested on
+rather than everything the agent happened to look at.
+
+`idempotencyKey` stays a separate option. It gives a write one stable identity if
+the agent retries, which is a different question from what the write assumed.
+
+### A claim holds while an agent thinks
+
+Agents that take minutes per turn can now hold work safely. A claim waits its
+turn or skips, expires on its own, and keeps itself alive with a heartbeat while
+the agent works.
+
+If an agent loses its claim during a model call, its final write is refused. Two
+agents cannot both believe they own the same task and both write, and a slow
+agent cannot land its answer on top of whoever picked the work up after it. Ablo
+decides who holds the claim, so an agent cannot assert one it does not have.
+
+### An agent can read back what it committed
+
+Ask what happened to a write, using the same key the agent wrote with:
+
+```ts
+const record = await ablo.commits.get({ id: commitId });
+```
+
+The answer says who committed, what they intended, whether it is confirmed, and
+which claim protected it. `commits.list` walks the history a page at a time, so
+one agent can review what another already did before repeating it.
+
+What an agent sent is not kept. Prompts, reasoning, and your customers' row
+values are removed before the record is stored, so reading history back never
+replays an agent's inputs. Records are kept for 90 days, and permanently for a
+database you connected.
+
+### An agent can check what its key allows before it acts
+
+An agent holding a key can now ask what that key permits and get the answer from
+Ablo, whether it keeps a connection open or calls over HTTP for a single turn.
+An agent that mints a narrower key for a sub-task can confirm what it handed
+over.
+
+### A refused action says which permission was missing
+
+When Ablo refuses, the error names the permission the agent needed. An agent can
+report exactly what it lacked, or request it, instead of retrying a call that
+will never succeed.
+
+### Models named in camelCase resolve when writing to your own database
+
+A model whose key mixes capital letters did not match its declared name when the
+write went to your database directly, so those writes could not find their
+target. They resolve now.
+
+### `ablo connect apply` says when a database is already connected
+
+Connecting a database that another project already owns reported a missing table
+mapping, which described a symptom rather than the reason the command could not
+continue. It now says the database is already connected. Nothing is written
+while it checks, and a project with no models still gets its preflight.
+
+**Action required.** Install this version rather than a tarball or a Git
+dependency. This release pairs the SDK with the engine running behind
+`api.abloatai.com`, which is already serving it, so there is nothing to
+coordinate on your side.
+
+## 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";
+```
+
+### `ablo dev --local` connects a branch to the database on your machine
+
+The rule above raises a fair question: if a branch is unbound until a database
+is connected, what connects one during development? `--local` does.
+
+```bash
+npx ablo dev --local
+```
+
+It registers a connector-only endpoint for that exact branch and opens a
+long-lived secure connector. Your database stays where it is: Ablo receives an
+endpoint descriptor and a signing key, never a connection string, and reaches
+your source back through the connector rather than dialling it. `DATABASE_URL`
+is read from `.env.local` into the handler running on your machine and goes no
+further.
+
+The branch is then connected like any other, so schema pushes, reads and writes
+behave the way they will in production. Because the connector is long-lived,
+`--local` cannot be combined with `--no-watch`.
+
+### 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
 
-### Minor Changes
+### 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.
 
-- 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`.
+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.
 
-### Patch Changes
+### Deprecations
 
-- Updated dependencies [101ca2c]
-  - @abloatai/transaction@0.47.0
-  - @abloatai/humans@0.47.0
+`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
 
@@ -321,7 +540,7 @@ through the same transaction API as every other caller.
 
 The integrations keep each product in its proper role: Temporal and Inngest
 own durable execution, scheduling, retries, and workflow history; Ablo owns
-shared-data authority, claims, conflicts, idempotency, settlement, and ordered
+shared-data authority, claims, conflicts, idempotency, confirmation, and ordered
 observation. Workflow code does not open WebSockets or hold live client state.
 
 ### Database adapter foundation, starting with PostgreSQL
@@ -425,7 +644,7 @@ Install `@abloatai/ablo` as the single public SDK:
 - `@abloatai/ablo/react` provides the React bindings.
 
 Every entrypoint uses the same schema, capabilities, commits, claims,
-idempotency, settlement, and ordered changes. Authoritative reads use
+idempotency, confirmation, and ordered changes. Authoritative reads use
 `model.get({ id })`; local reactive snapshots use `model.local.get(id)`.
 
 ### Coordination now matches the unit applications can safely write

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <strong>The transaction layer for AI agents.</strong>
+  <strong>Collaboration infrastructure for AI agents.</strong>
 </p>
 
 <p align="center">
@@ -22,13 +22,12 @@
 
 ---
 
-Safely coordinate AI agents, humans, workflows, and services writing to the
-same database.
+Ablo is collaboration infrastructure for AI agents: one API for agents, apps,
+and services to claim, change, and confirm the same rows.
 
-Ablo is an authoritative transaction layer for shared application state. Every
-write goes through one typed API where authority, idempotency, conflicts,
-ordering, and confirmation can be enforced. Your Postgres remains the source
-of truth.
+Every write goes through it, so authority, idempotency, conflicts, ordering,
+and confirmation are enforced in one place. Your Postgres remains the source of
+truth.
 
 ## Why Ablo
 
@@ -54,7 +53,7 @@ npx ablo dev
 temporary credential to gitignored `.env.local`, pushes the schema, and watches
 for changes.
 
-Read and write through the transaction layer:
+Read and write through one typed API:
 
 ```ts
 const order = await ablo.orders.get({ id: orderId });
@@ -114,6 +113,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

@@ -12,7 +12,7 @@ HTTP, or be replayed from the sync cursor.
 | Need | Use | Why |
 | --- | --- | --- |
 | "I am holding this row because..." | `claim({ description, meta })` | Live and low-latency. Peers see it through presence while the claim exists. |
-| "Remember this handoff/status/request" | A `messages` model | Durable row. Ordered in `sync_deltas`, replayed after reconnect, readable by HTTP agents. |
+| "Remember this handoff/status/request" | A `messages` model | Durable row, replayed after reconnect and readable by HTTP agents. |
 
 Claim context is ephemeral. If a participant was offline, reconnected later, or
 only uses `transport: "http"`, it can miss claim/presence frames. Message rows
@@ -141,6 +141,6 @@ their cursor and see the rows they missed while offline.
 ## Retention
 
 Deleting or archiving old `messages` rows is your app's policy. The sync log is
-still durable audit/history: `sync_deltas` has no message-specific TTL. That is
+still durable audit/history: messages have no message-specific TTL. That is
 useful for coordination and compliance, but a chat-scale product should plan
 retention before writing high-volume conversation traffic.

package/docs/api.md

@@ -2,8 +2,8 @@
 
 > The per-method reference for every model call an agent or an interface can make.
 
-> **Upgrading?** Every breaking change and its migration is on the
-> [Version History & Migration Guide](./migration.md).
+> **Upgrading?** Follow the version-matched workflow in the
+> [Upgrade Guide](./migration.md), then read the intervening changelog entries.
 
 This is the per-method reference for reading and writing rows that stay in
 sync across sessions. You declare your models once, then call the same

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`         |
@@ -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.