@abloatai/ablo 0.24.0 → 0.26.0

package/AGENTS.md

@@ -6,16 +6,18 @@ Claims don't lock. If another writer holds the row, `claim` waits for them and r
 
 ## Start here — scaffold with `ablo init`
 
-Don't hand-write the integration. Run the CLI; it generates the current-API schema, client, Data Source endpoint, and (for Next.js) the browser provider + session route:
+Don't hand-write the integration. Run the CLI; it generates the current-API schema, client, the database connection (logical replication by default, or a signed Data Source endpoint as the fallback), and (for Next.js) the browser provider + session route:
 
 - **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.
-- **Provision your DB (Data Source mode):** `npx ablo migrate` creates the tables for your Ablo models plus the adapter's bookkeeping tables (`ablo_outbox`, `ablo_idempotency`). It does **not** touch your other tables — keep your own migrations (drizzle-kit / prisma migrate) for auth and anything not in the Ablo schema.
+- **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.)
+- **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?** A sandbox `sk_test` key holds throwaway **test data** (Stripe-test-mode style) so you can try Ablo before connecting your own Postgres. Test-mode only — in production every row lives in your database.
 - **Adopt an existing DB schema:** `npx ablo pull prisma [path]` / `pull drizzle <module>` (lossless) or `pull` (live DB, lossy). Writes `ablo/schema.ts`.
 - **Push your schema — REQUIRED before any write works.** The server keeps its OWN copy of the schema. After you create or edit `ablo/schema.ts`, run `npx ablo push` (one-shot) — or `npx ablo dev --no-watch`. **Skip this and every write to a new or changed model fails with `server_execute_unknown_model`.** (Plain `ablo dev` watches forever — never run it bare in an agent.)
 - **Other long-running:** `npx ablo logs --no-follow` (default tails forever). `npx ablo mode test|live` ALWAYS pass the argument. `status`, `push`, `pull`, `check`, `generate` are one-shot — safe as-is.
 
-The generated `ablo/data-source.ts` is the whole Data Source endpoint and needs no hand-editing: `dataSourceNext({ schema, apiKey, adapter: prismaDataSource(prisma, schema) })` (or `drizzleDataSource(db, schema)`). The adapter owns commit / idempotency / outbox.
+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.
 
 ## Rule
 

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.26.0
+
+### Minor Changes
+
+- **`ablo connect --register` works against any deployment.** Registering your database as an Ablo data source over logical replication is now a first-class path everywhere — the gate that could refuse a new connection-string registration is gone. Point `ablo connect --register` at your Postgres and Ablo begins consuming its replication stream while your application keeps owning the write path; registering the source _is_ the enable, with no tier or flag to choose. The signed `dataSource()` endpoint remains the explicit fallback for databases that can't grant replication.
+
+- **More engine failures surface as typed errors you can branch on**, instead of opaque `500`s. New `AbloError` codes: `schema_provisioning_forbidden` (`403` — a push tried to create tables in a database where the engine isn't permitted to run DDL), `request_too_large` (`413` — a query or commit body exceeded the size limit), `commit_operation_invalid` (`400` — a malformed commit operation), and `upload_not_configured` (`503` — an upload was attempted with no blob store wired).
+
+- **`@abloatai/ablo/wire` now exports the protocol schemas.** `commitOperationSchema`, `commitPayloadSchema`, and the frame schemas let tooling and tests validate client↔engine frames against the same contract the engine enforces.
+
+- **Protocol version negotiation is surfaced.** `@abloatai/ablo/wire` exports `PROTOCOL_VERSION`, `MIN_SUPPORTED_PROTOCOL_VERSION`, `WS_CLOSE_PROTOCOL_VERSION`, `PROTOCOL_VERSION_HEADER`, `protocolVersionProblem`, and `ERROR_CONTRACT_VERSION` — the single integer the client and server compare on connect to detect an incompatible peer and fail with a clear reason instead of a cryptic wire error.
+
+- **`@abloatai/ablo/coordination` exposes the conflict-policy vocabulary** — `defaultPolicy`, `capabilityPreemptPolicy`, and `interpretConflictAxis` — for server-side consumers building on the claim model. `@abloatai/ablo/schema` gains the role primitives (`identityRole`, `entityRole`, and their types and schemas) for declaring identity- and entity-scoped roles.
+
+- **Removed unused API surface.** Dropped the `@abloatai/ablo/server/next` subpath export and the unused `MutationDispatcher` interface (plus its `MockMutationDispatcher` test double) and the offline-mutation-queue internals behind them — none had documented consumers. Every supported entry point (`@abloatai/ablo`, `/ai-sdk`, `/react`, `/source`, `/coordination`, `/schema`, `/keys`, `/auth`, `/wire`, …) is unchanged.
+
+- **Internal:** the SDK's largest modules — the `Ablo` client, the data-source runtime, the transaction queue, and the WebSocket sync loop — were decomposed into cohesive leaf modules. No public runtime API or import path changed.
+
+- **CLI & docs.** `ablo push` prints a calmer, information-first deploy banner (a production push still requires typing the project name to confirm). The README and `AGENTS.md` now lead with the one-path logical-replication model and clarify that sandbox is test-mode only — in production your rows stay in your database and Ablo holds only the transaction log.
+
+## 0.25.0
+
+### Minor Changes
+
+- ca30064: Logical replication is now the documented default storage path, with self-service data-source registration from the CLI.
+  - **`ablo connect --register`** — registers your database as an Ablo data source over logical replication in one step: it runs the same pre-flight replication probe `ablo connect` uses (server reachable, `REPLICATION` privilege, `wal_level=logical`, publication/slot creatable), and on success `POST`s the connection to the engine's `/v1/datasources`. The `ek_`-authed call scopes the source to your org automatically; the password is stored decomposed as a secret, never echoed back. This is the "registration is the enable" path — there is no separate tier or flag to pick.
+  - **`ablo init` leads with logical replication** — the default storage mode is now `replication` (was `endpoint`); the generated env + next-steps point at `ablo connect` / `ablo connect --register`. The signed-endpoint and direct modes remain as the explicit fallback / legacy options.
+  - **`ablo status`** — a data-plane diagnostic that probes whether your registered source is reachable and replicating (failure-only reporting, so it never falsely reports healthy).
+  - **`ablo push`** — minor guard/UX refinements (deploy-target clarity).
+  - **Docs (README, `docs/data-sources.md`, `llms.txt`)** rewritten to the one-path model: Ablo consumes your database's logical-replication stream and your application owns the write path. The security wording is precise — a logical-replication connection requires the `REPLICATION` privilege (it is **not** a read-only SQL account), so reviews are not misled by a "read-only" claim.
+
+  No breaking changes to the SDK runtime API. The server-side WAL read cutover these CLI changes support ships by deploying the engine, not this package.
+
 ## 0.24.0
 
 ### Minor Changes

package/README.md

@@ -55,11 +55,13 @@ claims are visible while the work is still in progress.
 [Version History & Migration Guide](./docs/migration.md)
 
 It works with the auth and database you already have. **In production, your
-database is the system of record.** Ablo is the transaction layer on top of it:
-realtime data is scoped to *sync groups* from your own identity, and every
-committed row lives in your Postgres. (Trying Ablo with no database yet? The
-hosted **sandbox** can host rows in Ablo's test plane — apiKey only, like
-Stripe test mode — so you can explore before pointing it at your Postgres.)
+database is the system of record.** Ablo is the sync + coordination layer on top
+of it: it consumes your Postgres' logical-replication stream, scopes realtime
+data to *sync groups* from your own identity, and your application keeps owning
+the write path — every row lives in your Postgres. (Trying Ablo with no database
+yet? A **sandbox** `sk_test` key holds throwaway **test data** — like Stripe test
+mode — so you can explore before pointing it at your Postgres. Test-mode only; in
+production every row lives in your database.)
 
 **Built for** collaborative editors, AI agent workflows, and internal tools —
 anywhere people and agents change shared state and everyone has to see it live.
@@ -92,11 +94,11 @@ what's configured at any time.
 
 **Keys & runtime.** Ablo needs Node 24+ and TypeScript 5+. Keys come in two of
 *your* environments — `sk_test_` and `sk_live_`, like Stripe — and `ablo login`
-mints both. Keep the key and the database URL in trusted server runtimes only.
-In the browser, `<AbloProvider>` authenticates with the signed-in user's
-session — never the raw key, never the database URL. Prefer the connection
-string never leaving your infrastructure? Expose a signed
-[Data Source endpoint](./docs/data-sources.md) instead and omit `databaseUrl`.
+mints both. Keep the key in trusted server runtimes only. In the browser,
+`<AbloProvider>` authenticates with the signed-in user's session — never the raw
+key. Your database is connected once, out of band, via `npx ablo connect`
+(logical replication); if it can't grant a replication role, expose a signed
+[Data Source endpoint](./docs/data-sources.md) instead.
 
 For production (React, an existing backend, Data Source, agents), the
 [Integration Guide](./docs/integration-guide.md) is the deeper map.
@@ -175,8 +177,9 @@ const schema = defineSchema({
 const ablo = Ablo({
   schema,
   apiKey: process.env.ABLO_API_KEY, // written to .env.local by `npx ablo push`
-  databaseUrl: process.env.DATABASE_URL, // your Postgres, passed explicitly — rows live here
 });
+// Your Postgres is connected once via `npx ablo connect` (logical replication) —
+// not passed here. Ablo tails its WAL; your rows never leave your database.
 
 await ablo.ready();
 
@@ -319,10 +322,10 @@ import Ablo from '@abloatai/ablo';
 import { AbloProvider, useAblo } from '@abloatai/ablo/react';
 import { schema } from './ablo/schema';
 
-// Build the client once — it authenticates via your session route, no key in the browser.
+// Build the client once — authEndpoint is your session route; no key in the browser.
 const ablo = Ablo({
   schema,
-  apiKey: () => fetch('/api/ablo-session').then((r) => r.text()),
+  authEndpoint: '/api/ablo-session',
 });
 
 function App() {
@@ -378,7 +381,7 @@ to sync-group strings.
 // team membership is asserted server-side when the session route mints the token.
 const ablo = Ablo({
   schema,
-  apiKey: () => fetch('/api/ablo-session').then((r) => r.text()),
+  authEndpoint: '/api/ablo-session',
 });
 
 <AbloProvider client={ablo} userId={user.id}>
@@ -403,10 +406,12 @@ each other's changes in real time — that's the default, not a feature you turn
 - `useAblo(...)` gives React clients the live row, kept current automatically.
 - `ablo.<model>.claim({ id })` / `claim.state({ id })` / `claim.queue({ id })` let humans and agents coordinate (and observe) active work on a row — and the line waiting behind it — before a write lands.
 
-Always write through Ablo — either the SDK model methods
-(`ablo.<model>.create/update/delete`) or the HTTP write endpoint below. If you
-write straight to your own database instead, those changes won't reach connected
-clients.
+Your application owns the write path: writes that land in your database — through
+your own backend, your existing API, any path — are tailed off the WAL and fanned
+out to connected clients automatically (the Electric model). The SDK model
+methods (`ablo.<model>.create/update/delete`) and the HTTP write endpoint are the
+*JavaScript/agent* ergonomic surface — they participate in claims and confirmation
+— but they are not a requirement for your normal writes to show up.
 
 ## HTTP Writes
 
@@ -429,35 +434,39 @@ curl https://api.abloatai.com/v1/commits \
 
 ## Your Database
 
-In production, every schema model is backed by **your own database** — Ablo is
-the transaction layer on top of it. Two ways to connect it:
+In production, every schema model is backed by **your own database** — Ablo
+**consumes** it, never owns it. The model is Electric's (and PowerSync's, and
+Zero's): Ablo consumes your Postgres' logical-replication stream and fans the
+changes out; **your application continues to own the write path.** Two ways Ablo
+connects:
 
-| | How Ablo reaches your Postgres | Use when |
+| | How Ablo connects to your Postgres | Use when |
 | --- | --- | --- |
-| **Connection string** (primary) | `databaseUrl` at init — passed explicitly, never auto-read from the environment. Ablo registers the connection once (sent over TLS, stored sealed, never echoed back) and commits each write directly — through a non-superuser role, behind row-level security. | You can hand over a scoped connection string. |
-| **Signed endpoint** | Your app exposes one route built from an ORM adapter (`prismaDataSource` / `drizzleDataSource`); Ablo sends signed commit requests and your app writes its own database. | Database credentials must never leave your infrastructure. |
+| **Logical replication** (primary) | `npx ablo connect` prints the setup SQL (`wal_level=logical`, a publication, a `REPLICATION` role); `npx ablo connect --register` tells Ablo to replicate it. Ablo tails the WAL — it never runs DDL on, writes to, owns, or migrates your database. | Your database can grant a `REPLICATION` role (most can). |
+| **Signed endpoint** (fallback) | Your app exposes one route built from an ORM adapter (`prismaDataSource` / `drizzleDataSource`); Ablo sends signed requests and your app touches its own database. Needs no database configuration. | Your database **can't** grant a replication role (a locked-down managed DB). |
 
-(No database yet? The hosted **sandbox** can host rows in Ablo's test plane —
-omit `databaseUrl` and pass an `apiKey` only, like Stripe test mode — so you can
-try Ablo before connecting your Postgres.)
+(No database yet? A **sandbox** `sk_test` key lets you try Ablo's full API and
+coordination with throwaway **test data** — like Stripe test mode — before you
+connect your own Postgres. Test-mode only: in production your rows always live in
+your database and Ablo holds just the transaction log, never your data.)
 
-Same product, same truth either way: in production your database is the system of
-record. See
-[Connect Your Database](./docs/data-sources.md) for both shapes.
+Your database is the system of record. The old `databaseUrl` dial-in (Ablo
+holding a read/write connection) is **deprecated and being removed** — connect
+via logical replication instead. See
+[Connect Your Database](./docs/data-sources.md).
 
 ## Configuration
 
-`Ablo({ ... })` takes your schema, your key, and — in production — your database,
-either as an explicit `databaseUrl` here or as a signed
-[Data Source endpoint](./docs/data-sources.md) in your app. (`databaseUrl` is
-never auto-read from the environment; omit it to try Ablo against the hosted
-sandbox.) Every other option has correct defaults:
+`Ablo({ ... })` takes your schema and your key. Your database is connected
+**out of band** — once, via `npx ablo connect` (logical replication) or a signed
+[Data Source endpoint](./docs/data-sources.md) — not through the constructor.
+Every other option has correct defaults:
 
 | Option | Type | Default | Purpose |
 | --- | --- | --- | --- |
 | `schema` | `Schema` | — (required) | Typed model proxies (`ablo.<model>.*`) |
 | `apiKey` | `string \| ApiKeySetter \| null` | `process.env.ABLO_API_KEY` | Server key — a string, or an async function for rotation |
-| `databaseUrl` | `string \| null` | `—` | Your Postgres, registered as the data plane. **Must be passed explicitly — it is not auto-read from the environment.** If you have a `DATABASE_URL` set for another tool (Prisma, Drizzle, docker-compose), `Ablo()` ignores it unless you pass `databaseUrl` explicitly. Server runtimes only — the SDK throws if it sees this in a browser. Omit it when your app exposes a signed [Data Source endpoint](./docs/data-sources.md) instead, or when trying Ablo against the hosted sandbox. |
+| `databaseUrl` | `string \| null` | `—` | **Deprecated — being removed.** The old dial-in (Ablo holding a read/write connection to your DB). Connect via `npx ablo connect` (logical replication) instead; Ablo tails your WAL rather than dialing in. See [Connect Your Database](./docs/data-sources.md). |
 
 Keep `apiKey` in trusted server runtimes. In the browser, `<AbloProvider>`
 authenticates with the signed-in user's session; the raw-key path is gated
@@ -512,7 +521,7 @@ contract; there are no retry or timeout knobs to tune.
 - [React](./docs/react.md) — `<AbloProvider>`, `useAblo`, presence, status, and bootstrap gating.
 - [Coordination](./docs/coordination.md) — `claim` / `claim.state` / `claim.queue` / `claim.release` reference: hold a row across slow agent work, and observe the line waiting behind it.
 - [Client Behavior](./docs/client-behavior.md) — options, errors, retries, timeouts, and public imports.
-- [Connect Your Database](./docs/data-sources.md) — connect your Postgres by connection string (`databaseUrl`) or signed endpoint; your database is the system of record either way.
+- [Connect Your Database](./docs/data-sources.md) — connect your Postgres by logical replication (`npx ablo connect`) or, as a fallback, a signed endpoint; your database is the system of record either way.
 - [Existing Python Backend](./docs/examples/existing-python-backend.md) — migrate existing Python endpoints to multiplayer and agent-safe writes gradually.
 - [AI SDK Tool](./docs/examples/ai-sdk-tool.md) — use Ablo inside an AI SDK tool call.
 - [Server Agent](./docs/examples/server-agent.md) — schema-backed worker.