@abloatai/ablo 0.47.0 → 0.48.0

package/CHANGELOG.md

@@ -1,16 +1,128 @@
 # 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
 
-### 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
 

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.
 
@@ -114,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/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.

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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.47.0",
+  "version": "0.48.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.47.0",
-    "@abloatai/transaction": "^0.47.0"
+    "@abloatai/humans": "^0.48.0",
+    "@abloatai/transaction": "^0.48.0"
   },
   "peerDependencies": {
     "ai": "^6.0.0 || ^7.0.0",

package/docs/internal/agent-orchestration.md

@@ -1,57 +0,0 @@
-# Agent Orchestration
-
-Do not model parent and child agents as directly talking to each other over WebSocket.
-
-Model them as actors coordinating through models:
-
-```txt
-parent creates job -> child claims job -> child commits result -> parent reads result
-```
-
-The WebSocket is delivery infrastructure. The product model is shared state.
-
-## Model Shape
-
-A parent creates a job through its typed model client:
-
-```ts
-const jobId = `forecast:${runId}`;
-await ablo.agentJobs.create({
-  id: jobId,
-  idempotencyKey: `job:${runId}`,
-  data: {
-    status: 'open',
-    kind: 'forecast_report',
-    target: { model: 'weatherReports', id: 'report_stockholm', field: 'forecast' },
-  },
-});
-```
-
-The child claims the job. If another worker holds it, the claim waits fairly,
-then returns the fresh row:
-
-```ts
-await using claim = await ablo.agentJobs.claim({
-  id: jobId,
-  description: 'complete',
-  ttl: '5m',
-});
-const job = claim.data;
-
-await ablo.agentJobs.update({
-  id: job.id,
-  data: {
-    status: 'completed',
-    result: { text },
-  },
-});
-```
-
-The child commits completion through the normal `update`, which is stale-guarded
-under the held claim. The claim releases when its scope exits.
-
-The parent retrieves the job result by model ID. Later, `ablo.events` can make that reactive, but the state model does not change.
-
-## Rule
-
-Nested agents should create or complete models. They should not require a separate agent-to-agent protocol for normal work.