@abloatai/ablo 0.31.0 → 0.33.0

package/docs/integration-guide.md

@@ -446,7 +446,7 @@ scope.
 ```ts
 await using claim = await ablo.weatherReports.claim({
   id: reportId,
-  reason: 'forecasting',
+  description: 'forecasting',
 });
 const claimed = claim.data;
 if (!claimed) return;
@@ -513,7 +513,7 @@ them.
 | `update({ id, data, ...opts })`        | Update through the model client.                                                 |
 | `delete({ id, ...opts })`              | Delete through the model client.                                                 |
 | `claim.state({ id })`                  | See who is currently working on a row (synchronous).                             |
-| `claim({ id, reason?, ttl? })`         | Acquire a disposable handle: wait for your turn, re-read, and hold the row.       |
+| `claim({ id, description?, ttl? })`    | Acquire a disposable handle: wait for your turn, re-read, and hold the row.       |
 
 Keep first integrations on the model methods above. Every mutation and
 server-read verb takes one options object; only the synchronous `get(id)` stays

package/docs/interaction-model.md

@@ -70,7 +70,7 @@ automatically when the scope exits:
 ```ts
 await using claim = await ablo.weatherReports.claim({
   id: 'report_stockholm',
-  reason: 'editing',
+  description: 'editing',
 });
 await ablo.weatherReports.update({ id: claim.data.id, data: { status: 'ready' } }); // rejected if the row changed under the claim
 ```
@@ -87,8 +87,8 @@ Schema updates can carry `readAt` and `onStale`. If the state advanced past
 `readAt`, Ablo applies the `onStale` policy:
 
 - `reject` — fail the commit (first writer wins).
-- `merge` — apply the write if it does not overlap with concurrent changes.
-- `force` — apply the write unconditionally.
+- `notify` — accept the write, but flag it for product review.
+- `overwrite` — apply the write unconditionally.
 
 The choice is per-commit. No CRDT default; the policy is explicit.
 

package/docs/quickstart.md

@@ -110,21 +110,21 @@ connection.
 # Point it at an admin connection once — it does the whole ceremony: creates the
 # roles + publication, turns on logical decoding where it can, registers both
 # scoped roles with Ablo, and proves it by reading back. Nothing lands in your .env.
-npx ablo connect --apply --url postgres://admin:...@host:5432/db
+npx ablo connect apply --url postgres://admin:...@host:5432/db
 
 # ...or print the SQL and run it yourself, then register:
 #   npx ablo connect            # prints the publication + two scoped roles
-#   npx ablo connect --check    # validates the database is ready
-#   npx ablo connect --register # hands the two scoped roles to Ablo
+#   npx ablo connect check    # validates the database is ready
+#   npx ablo connect register # hands the two scoped roles to Ablo
 ```
 
-`ablo connect --apply` generates two roles and their passwords — an
+`ablo connect apply` generates two roles and their passwords — an
 `ablo_replicator` role (`REPLICATION` + `SELECT`, for reads and confirmation) and
 an `ablo_writer` role (scoped row DML, for writes) — and registers both connection
 strings with Ablo's control plane, encrypted. Ablo's runtime uses them to read and
 write your database. The admin credential you pass to `--url` is used on this
 machine only and never persisted. The role passwords are generated for you and
-never printed — rotate them any time with `ablo connect --rotate`.
+never printed — rotate them any time with `ablo connect rotate`.
 
 Your **app** holds only the API key — never a connection string:
 
@@ -230,7 +230,7 @@ locked.
 // Claim the row so other participants serialize behind us while we work.
 await using handle = await ablo.weatherReports.claim({
   id: 'weather_stockholm',
-  reason: 'checking_weather',
+  description: 'checking_weather',
   ttl: '2m',
 });
 

package/docs/webhooks.md

@@ -1,30 +1,22 @@
 # Webhooks
 
-Ablo owns the ordered transaction log — the source of truth. **Webhooks are how
-that log reaches your database.** Ablo streams every committed change to an
-endpoint in your app as a signed event; your handler writes your own database.
+Ablo keeps an ordered transaction log of every committed change and coordinates
+the writers — people and agents — that produce it. Your rows live in your own
+database; Ablo holds only the log. **Webhooks stream that log to your systems as
+signed events:** every committed change is POSTed to an endpoint in your app, and
+your handler decides what to do with it.
 
 It's the same two-sided shape as Stripe: you call Ablo to make changes (the
-client), and Ablo calls you to persist them (this webhook). Ablo never holds your
-database credentials.
+client), and Ablo calls you with each change (this webhook). Webhooks are the
+*push* way to keep a store in step with the log — your own database, a warehouse,
+a search index, a background job. The *direct* alternative is `ablo connect`,
+where Ablo reads your write-ahead log and writes back through a scoped role. Either
+way your handler owns the write: the webhook path gives Ablo no database
+credentials at all.
 
 ## The loop
 
-```mermaid
-flowchart LR
-    App["Your app<br/>(the client)"]
-    subgraph Ablo["Ablo (hosted)"]
-        Log["Transaction log<br/><i>source of truth</i>"]
-    end
-    Clients["Other clients<br/>(live, optimistic)"]
-    Route["/api/ablo/[...all]<br/>(your webhook route)"]
-    DB[("Your database")]
-
-    App -->|write| Log
-    Log -->|realtime sync| Clients
-    Log -->|signed event| Route
-    Route -->|write| DB
-```
+![Your app writes to Ablo's ordered log — the source of truth, which holds the log and coordination only, never your rows. The log fans out two ways: realtime sync to live clients for an instant, optimistic UI, and a signed event to your webhook route, which writes the durable copy into your own database.](/the-loop.svg)
 
 There are two ways data flows out of Ablo, and they're for different jobs:
 
@@ -55,8 +47,8 @@ Every delivery is a batch of events. Each event:
 
 | field | meaning |
 |---|---|
-| `type` | `"<model>.<verb>"`, e.g. `task.updated` |
-| `model` | the model name (`task`) — the table to write |
+| `type` | `"<model>.<verb>"` with the model name lowercased, e.g. `task.updated` |
+| `model` | the model name exactly as declared in your schema — the table to write |
 | `objectId` | the changed row's id |
 | `data` | the post-change row, or `null` on delete (like Stripe's `event.data.object`) |
 | `syncId` | monotonic log position — **dedupe and order by this** |
@@ -138,12 +130,21 @@ npx ablo webhooks create https://yourapp.com/api/ablo/[...all]
 # ✓ Wrote ABLO_WEBHOOK_SECRET to .env.local (shown once)
 ```
 
+Scope which models fire and label the endpoint at creation with `--events` and
+`--description` (both optional; events default to `*` = every model):
+
+```bash
+npx ablo webhooks create https://yourapp.com/api/ablo/[...all] \
+  --events task,project --description "prod mirror"
+```
+
 Manage and inspect endpoints:
 
 ```bash
 npx ablo webhooks list          # endpoints + delivery health (status, cursor, last error)
 npx ablo webhooks roll <id>     # mint a fresh signing secret
 npx ablo webhooks enable <id>   # re-enable a disabled endpoint
+npx ablo webhooks rm <id>       # remove an endpoint
 ```
 
 Or call the API directly — the org is derived from your secret key:

package/llms.txt

@@ -88,6 +88,10 @@ visible through `claim.state({ id })`, and stale writes can be rejected with `re
 If an app writes directly to its own database outside Ablo, that write bypasses
 coordination until the app reports it through Data Source events.
 
+## Change propagation
+
+A change to one row reaches other rows three ways. ROUTING: a write fans out to every sync group the row belongs to, INCLUDING its ancestors' groups (editing a layer routes to `layer:` + `slide:` + `deck:`), so everyone watching the deck sees it — delivery, not recomputation. DELETE CASCADE: deleting a parent emits explicit tombstone deltas for its descendants, so open clients never silently hold rows that are gone. VALUE: derived values are NOT recomputed server-side — Ablo surfaces that the source moved and the actor decides. To keep dependent work fresh, declare what you read as a batch premise: `reads: [{ group: 'deck:abc', readAt: N, onStale: 'notify' }]`. At commit the server checks whether anything in that group moved past `readAt`; `notify` holds the write and returns a `StaleNotification` (re-read the group and regenerate), `reject` aborts. To chain A→B→C, put A+B in one group and B+C in another: A's change reaches B, and C hears it only once B ITSELF writes — the engine wires the edges and signals each hop, the actor walks them. No transitive auto-recompute, no convergence guarantee for cycles.
+
 ## Nouns
 
 - `Model client` is the typed `ablo.<model>` object generated from schema.
@@ -123,11 +127,13 @@ A schema is model fields and relations. Advanced schema helpers such as `mutable
 
 ## Storage Boundary
 
-THE ONE PATH IS LOGICAL REPLICATION. In production every schema model is backed by YOUR OWN database, and Ablo connects to it by CONSUMING ITS WRITE-AHEAD LOG (logical replication) — the Electric/PowerSync/Zero model. Ablo tails the WAL and fans changes out; YOUR APPLICATION CONTINUES TO OWN THE WRITE PATH (your own backend, your existing API). Ablo never runs DDL on, writes to, owns, or migrates your database. Connect once with `npx ablo connect` (prints the setup SQL: `wal_level=logical`, a publication, a `REPLICATION` role) then `npx ablo connect --register`. Validate with `npx ablo connect --check`. The role's privilege footprint is narrow but real — a `REPLICATION`-attributed role that streams the WAL and `SELECT`s; do NOT describe it as "read-only" (a security reviewer will push back — it is a replication privilege, just tightly scoped).
+YOU WRITE THROUGH ABLO; ABLO WRITES TO YOUR POSTGRES. In production every schema model is backed by YOUR OWN database. You call `ablo.<model>.create/update/delete`; the write enters Ablo's commit chokepoint (claims, ordering, idempotency enforced there) and Ablo applies it to your Postgres through a scoped writer role (`ablo_writer`: `SELECT, INSERT, UPDATE, DELETE`, `NOSUPERUSER NOBYPASSRLS`, `row_security on` — no DDL, no ownership, no schema migration). Ablo then TAILS your write-ahead log (logical replication) to CONFIRM the write landed (`queued` → `confirmed`) and to serve live reads. Your rows live in your database; Ablo holds only the ordered transaction log. Connect in ONE command: `npx ablo connect apply --url <admin-conn>` — it creates the writer + `REPLICATION` roles, the publication, turns on logical decoding, and registers with Ablo; the admin credential is used once and discarded. Your app then holds only `ABLO_API_KEY` — never a connection string. WAL is how Ablo CONFIRMS and READS, NOT the write path — you write THROUGH Ablo.
+
+RLS GOVERNS ABLO'S WRITES. The writer role is `NOSUPERUSER NOBYPASSRLS`, and before every write Ablo `SET LOCAL`s a tenant context on the connection (`app.current_org_id`, `app.current_project_id`, `app.current_environment`, participant id/kind) with `row_security = on` — so your row-level security enforces on Ablo's writes. If your policies read a DIFFERENTLY-NAMED GUC (e.g. an `app.current_app_org_id` your app sets per-connection), declare a tenant-context mapping in your schema so Ablo forwards its context into that GUC (ADR 0011) — do NOT carve a policy exception for the writer role. A role that can bypass RLS (e.g. via Neon's `neon_superuser` inheritance) is rejected with `database_role_cannot_enforce_rls`.
 
-FALLBACK (only when the database can't grant a `REPLICATION` role, e.g. a locked-down managed DB): a signed Data Source endpoint that hands Ablo an ORM `adapter` (Drizzle default; Prisma and Kysely supported) — it owns the transaction, exactly-once idempotency, and outbox in ONE pass; your credentials never leave your infrastructure.
+FALLBACK (only when Ablo can't dial the database, e.g. a private VPC with no inbound route): a signed Data Source endpoint that hands Ablo an ORM `adapter` (Drizzle default; Prisma and Kysely supported) — Ablo writes and confirms through it, and it owns the transaction, exactly-once idempotency, and outbox in ONE pass; your credentials never leave your infrastructure.
 
-DEPRECATED — being removed, do NOT recommend or scaffold: the `databaseUrl` constructor option (the dial-in, where Ablo held a read/write connection and committed directly to your DB). The end-state constructor is `Ablo({ schema, apiKey })`; the database is connected out of band via `ablo connect`, not through `databaseUrl`. The role rule you may have seen belongs ONLY to this dial-in: a `databaseUrl` had to name a NON-superuser, NON-BYPASSRLS role, or Ablo rejected it with `database_role_cannot_enforce_rls` (it enforced row-level security through the connection it held, so an owner/BYPASSRLS role — e.g. Neon's `neondb_owner` — would have silently skipped RLS). The WAL path retires that rule entirely: Ablo never holds a connection to your rows, so there is no `DATABASE_URL` to scope — `ablo connect` needs a `REPLICATION` role instead. `ablo init` still scaffolds `--storage direct`/`databaseUrl` for existing dial-in projects and the CLI now warns on it; prefer `ablo connect` regardless of what `init` scaffolds.
+DEPRECATED — removed, do NOT recommend or scaffold: the `databaseUrl` constructor option (the old DIAL-IN, where the CLIENT held a read/write connection string and committed directly, bypassing Ablo's coordination). It is deleted. DO NOT confuse it with the current model: today's writes also land in your Postgres, but through Ablo's SERVER-SIDE commit chokepoint and a scoped writer role Ablo provisions — coordination is never bypassed, and no connection string lives in your app. The NON-superuser / NON-BYPASSRLS role rule is NOT retired — it now applies to the scoped writer role `ablo connect` provisions (see RLS above), because Ablo does hold a scoped connection to write your rows. The end-state constructor is `Ablo({ schema, apiKey })`; the database is connected out of band via `ablo connect`. `ablo init` may still scaffold legacy `--storage direct`/`databaseUrl` for old projects and the CLI warns on it; prefer `ablo connect`.
 
 ```ts
 // app/api/ablo/source/route.ts
@@ -188,7 +194,7 @@ Do not teach `/api`, `/agent`, `/ai-sdk`, `/core`, `/realtime`, or internal subp
 `ablo init` and other prompts need a TTY; an agent/CI run has none and will HANG. Always:
 
 - `npx ablo init --yes` (flags: `--framework`, `--auth`, `--storage direct|endpoint`, `--no-agent`, `--no-pull`, `--no-install`, `--no-login`). Generates `ablo/schema.ts` + the `Ablo({ schema, apiKey })` client. `--storage endpoint` also scaffolds the `ablo/data-source.ts` fallback endpoint; `--storage direct` (deprecated, CLI warns) wires the legacy `databaseUrl`.
-- `npx ablo connect` connects your database via logical replication — the read path (prints the `wal_level=logical` + publication + `REPLICATION`-role SQL); `npx ablo connect --register` registers it, `npx ablo connect --check` validates.
+- `npx ablo connect` connects your database via logical replication — the read path (prints the `wal_level=logical` + publication + `REPLICATION`-role SQL); `npx ablo connect register` registers it, `npx ablo connect check` validates the registered database from Ablo's own side and needs only `ABLO_API_KEY` (no database credential in your environment). `npx ablo connect apply` does the whole setup from a one-time admin connection and leaves your app holding only `ABLO_API_KEY`.
 - Key: see "Start here" — env → `.env.local` → ask the human to `npx ablo login`; never run `login` yourself, never copy keys by hand (`ablo push` writes `.env.local`).
 - Adopt an existing DB: `npx ablo pull prisma [path]` / `npx ablo pull drizzle <module>`.
 - `npx ablo push` pushes the schema (sandbox) AND writes `ABLO_API_KEY` to `.env.local`; `npx ablo dev --no-watch` is the push-once form of the watcher; `npx ablo logs --no-follow` exits instead of tailing forever; `npx ablo mode sandbox|production` always needs the argument. `npx ablo push`/`status`/`pull`/`check`/`generate` are one-shot.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",