@abloatai/ablo 0.30.2 → 0.32.0

package/docs/groups.md

@@ -0,0 +1,160 @@
+# Change Propagation
+
+> How a change to one row reaches the rows and actors that depend on it, and how
+> to keep a chain of dependent work fresh. This is the propagation half of sync
+> groups; [`identity.md`](./identity.md) is the access half (who may read a
+> group), and [`concurrency-convention.md`](./concurrency-convention.md) is the
+> convention this rests on.
+
+---
+
+## Start from the problem
+
+An agent reads deck `A` to write slide `B`. A moment later it reads `B` to write
+layer `C`. Between those steps someone else edits `A`. The agent is now building
+`C` on a premise that has moved — and nothing about writing `C` looks wrong in
+isolation. That is stale context, and it is the thing sync groups let you catch.
+
+The recipe is one field on the commit: declare the group you read as a premise,
+and say what should happen if it moved.
+
+```ts
+// The agent read everything under deck:abc to compose this write.
+await ablo.layers.update({
+  id: 'layer-C',
+  data: { text: revised },
+  reads: [{ group: 'deck:abc', readAt: watermark, onStale: 'notify' }],
+});
+```
+
+At commit, inside the write transaction, the engine asks a single question: *did
+any delta routed to `deck:abc` land after `watermark`?* If nothing moved, the
+write applies. If something moved, `onStale` decides — `notify` holds the write
+and hands the agent a `StaleNotification` naming the group, so it re-reads
+`deck:abc` and regenerates; `reject` aborts the batch with a `409`. The agent
+never persists work built on a premise it can no longer see.
+
+---
+
+## Three ways a change reaches other rows
+
+"A affects B and C" means three different things. The engine does the first two
+for you and leaves the third to you — on purpose.
+
+**Routing — who hears about a change.** Every row belongs to one or more sync
+groups, and a write fans out to all of them. A row also inherits its ancestors'
+groups: editing a layer stamps the delta with `layer:…`, `slide:…`, *and*
+`deck:…`, so everyone watching the deck sees the layer move. This is delivery,
+resolved by walking the ownership tree at commit time. It routes the change; it
+never recomputes a value.
+
+**Structural cascade — what disappears with a change.** Deleting a deck removes
+its slides and layers. The database does that through `ON DELETE CASCADE`, but a
+database-level cascade emits no delta, so open clients would quietly hold rows
+that no longer exist. The engine closes that gap: before the delete it snapshots
+the subtree and emits a tombstone for each descendant, routed to the right
+group. Watchers see the whole subtree vanish.
+
+**Value recomputation — what a change implies for derived state.** If `B` holds a
+number rolled up from `A`, the engine does not recompute `B` when `A` changes. It
+surfaces that `A` moved and lets the actor decide what `B` should become. This is
+the non-coercion principle: coordinate and report, resolve nothing by fiat.
+Merging derived state is a judgment call, and for an agent in the loop that
+judgment is the whole point.
+
+---
+
+## The chain: A → B → C
+
+Model a dependency as shared group membership. Put `A` and `B` in one group, `B`
+and `C` in another, and you have wired the edges of a chain. What travels along
+those edges is a *signal*, one hop at a time — not a recomputation.
+
+```
+A writes ──▶ group {A,B} ──▶ B hears it
+                                  │  B decides, B writes
+                                  ▼
+                             group {B,C} ──▶ C hears it
+```
+
+A's delta lands in `{A,B}` and stops there. `C` is not in that group, so `C`
+learns nothing from A directly. `C` advances only when **B itself writes** and
+that new delta lands in `{B,C}`. `B` is the translator: it takes "A moved,"
+decides what that means for its own state, commits, and *its* commit is what
+reaches `C`.
+
+The direction matters. The signal flows forward, A to B to C, and each hop is a
+real write an actor chose to make. The engine supplies the edges (group
+membership) and a stale signal on each edge (the read-dependency check); the
+actors are the runtime that walks them. It is closer to a spreadsheet an analyst
+recalculates cell by cell than to a reactive engine that recomputes the whole
+column for you.
+
+Two consequences worth designing around:
+
+- **The chain runs as fast as actors react.** If `B` never acts on its signal,
+  the chain stops at `B` and `C` stays as it was. Freshness is an actor
+  responsibility; the engine guarantees the signal, not the follow-through.
+- **Cycles don't settle themselves.** If `C` writes back to `A`, each hop is a
+  separate commit with its own stale check, and nothing damps the oscillation.
+  Keep the dependency graph acyclic, or give one actor the job of reaching a
+  fixpoint. Convergence lives above the engine.
+
+---
+
+## Declaring a read premise
+
+A read-dependency is a premise for the *whole* batch: its disposition governs
+every write in the commit, not just one operation. You choose the granularity per
+entry.
+
+```ts
+reads: [
+  { group: 'deck:abc', readAt: N, onStale: 'notify' },      // did anything in the deck move?
+  { model: 'Slide', id: 's-1', readAt: N, fields: ['title'] }, // did this row (this field) move?
+]
+```
+
+A **group** premise asks "did anything I was watching change?" — the native
+Ablo granularity, and the right tool for the chain above. A **row** premise is
+literal: this object, optionally these fields. A row premise with `fields`
+conflicts only on real field overlap, so two actors editing disjoint fields of
+the same row don't collide.
+
+`onStale` has three settings, defaulting to `reject`:
+
+- **`notify`** holds every write in the batch and returns a `StaleNotification`.
+  For a group premise it carries the group name and the new watermark
+  (`observedSyncId`); re-read the group at that point and regenerate. This is the
+  setting a chain wants — the actor gets the truth and resolves it.
+- **`reject`** aborts the batch with a `stale_context` error (`409`). The right
+  default when there is nothing to reconcile and the write should simply not
+  land.
+- **`overwrite`** skips the check and lets the write land — last-write-wins, the
+  explicit escape hatch.
+
+---
+
+## Sizing groups
+
+A group is the unit of both delivery and staleness, so its size is a real
+tradeoff. A change fans out to every subscriber of every group it touches, and a
+group premise fires when *anything* in the group moves — so a group that is too
+broad wakes actors for changes they don't care about, and one that is too narrow
+misses the dependency you meant to track.
+
+The rule of thumb: **make a group the smallest set of rows that must stay
+mutually consistent.** A deck and its slides belong together because editing one
+changes what the others mean; two unrelated decks do not. Reach for finer,
+overlapping groups when you genuinely have a dependency chain to track, and keep
+them coarse everywhere else.
+
+---
+
+## Where this is defined
+
+- **Access** — who may read or write a group — is [`identity.md`](./identity.md).
+- **The convention** — non-coercion, the read-set, and the notification — is
+  [`concurrency-convention.md`](./concurrency-convention.md) (§4 and §5).
+- **The mechanics** — the three coordination layers underneath — are
+  [`coordination.md`](./coordination.md).

package/docs/guarantees.md

@@ -66,10 +66,8 @@ snapshot, the server rejects the write instead of applying stale reasoning.
 Advanced policies exist for controlled product flows:
 
 - `reject` fails the write when state moved.
-- `force` applies the write without stale protection.
-- `flag` accepts the write and marks it for product review.
-
-`merge` is not yet available.
+- `overwrite` applies the write without stale protection.
+- `notify` accepts the write and marks it for product review.
 
 ## Claim Coordination
 
@@ -148,9 +146,13 @@ separates workflow or deployment lanes sharing the same store.
 
 ## Storage Boundary
 
-Ablo does not need a customer database URL. When your own database is canonical,
-Ablo calls a signed Data Source endpoint and records the coordination result for
-receipts, realtime fanout, and audit. See [Connect Your Database](./data-sources.md).
+Your rows live in your database; Ablo holds only the transaction log and the
+coordination state. Writes enter Ablo's commit chokepoint and land in your
+Postgres through a scoped writer role, and the WAL echo confirms them
+(`queued` → `confirmed`). For a database that can't grant replication, Ablo
+forwards the write to a signed Data Source endpoint instead — the marked
+fallback. Either way Ablo never holds a database connection string. See
+[Connect Your Database](./data-sources.md).
 
 ## Writes
 

package/docs/how-it-works.md

@@ -0,0 +1,110 @@
+# How Ablo Works
+
+You write through Ablo, and Ablo writes to your Postgres. That one sentence is the
+whole model — everything below explains what it means and how to use it.
+
+```ts
+// You call Ablo. Ablo lands the change in your database and confirms it.
+await ablo.tasks.update({ id: 'task_42', data: { status: 'done' }, wait: 'confirmed' });
+
+// Reads come back live, kept current from your database.
+const task = ablo.tasks.get('task_42');
+```
+
+## The mental model — read this once
+
+Ablo is a **coordination layer in front of your Postgres**. Humans, agents, and
+background jobs all change the same application data through one API, and Ablo
+makes sure their writes don't clobber each other.
+
+- **Writes go through Ablo.** `ablo.<model>.create / update / delete` enter Ablo's
+  commit chokepoint — where claims, ordering, and idempotency are enforced — and
+  Ablo applies the change to your Postgres through a scoped writer role. The commit
+  is accepted (`queued`) the moment Ablo takes it.
+- **Your database confirms the write.** Ablo tails your write-ahead log (WAL). When
+  the row it wrote shows up there, the receipt is promoted to `confirmed`. So your
+  database, not Ablo, is the source of truth for row state — the WAL echo is how
+  Ablo *confirms*, not how it writes.
+- **Reads are live.** Ablo serves current state and keeps every connected client up
+  to date off that same stream.
+- **Ablo stores only the log.** Ablo holds the ordered transaction log
+  (`sync_deltas`) and the coordination state — the claims, the ordering, the
+  watermarks. Your rows live in your database. Ablo runs no DDL and owns no schema;
+  your migration tool stays in charge of the shape of your database.
+
+That's the shape: **you write through Ablo → it lands in your Postgres → the WAL
+echo confirms it → everyone connected sees it live.**
+
+## Where your data lives
+
+You point Ablo at a Postgres database, and that's where its rows live. Only *which*
+database differs by environment — the code is identical.
+
+- **Production** — your Postgres. `ablo connect` sets up a scoped writer role and
+  logical replication; your rows live in your database, and Ablo writes to them
+  through that role.
+- **Sandbox and local dev** — a separate or local Postgres you can throw away. Same
+  models, same code, a different database behind them.
+- **Before you connect one** — Ablo keeps state in its own log, so you can build the
+  whole app today and point it at a real database when you're ready.
+
+Registering the database is the whole switch. There is no tier or flag to choose.
+
+## Use it end to end
+
+```bash
+# 1. Install and scaffold.
+npm install @abloatai/ablo
+npx ablo init
+
+# 2. Push your schema (the models humans and agents edit together).
+npx ablo push
+
+# 3. Connect your database — one command, admin credential used once and discarded.
+npx ablo connect apply --url postgres://admin:...@host:5432/db
+```
+
+```bash
+# Your app's environment holds only the API key — never a connection string.
+ABLO_API_KEY=sk_live_...
+```
+
+```ts
+// 4. Build the client once.
+import Ablo from '@abloatai/ablo';
+import { schema } from './ablo/schema';
+export const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+
+// 5. Write through Ablo. It lands in your Postgres; wait: 'confirmed' blocks
+//    until the WAL echo proves the row is there.
+await ablo.tasks.update({ id: 'task_42', data: { status: 'done' }, wait: 'confirmed' });
+
+// 6. Read — live, no fetch loop.
+const task = ablo.tasks.get('task_42');
+
+// 7. Coordinate when more than one actor can touch a row. Hold a claim and Ablo
+//    serializes writes on that key against everyone else; read after claiming,
+//    then write. The lease releases automatically at the end of the scope.
+await using _hold = await ablo.tasks.claim('task_42');
+const latest = ablo.tasks.get('task_42'); // read after claiming, not from memory
+await ablo.tasks.update({ id: 'task_42', data: { status: 'done' } });
+```
+
+## Reading the architecture correctly
+
+The model changed once (ADR 0010), and older material described the earlier one.
+If you've read that a customer's app keeps writing while Ablo only tails the WAL,
+here is the current, correct reading:
+
+- **"Ablo tails the WAL."** True — to *confirm* your writes and serve live reads.
+  It is not the write path. You write **through** Ablo.
+- **"Ablo is out of the write path."** Not anymore. Ablo is the write chokepoint;
+  every write flows through its coordination and then into your database.
+- **"Ablo holds my rows."** Only in the no-database-yet sandbox. Once you connect a
+  database, your rows live in *your* Postgres — Ablo keeps just the log.
+- **"Ablo migrates my schema."** No. Ablo writes rows through a scoped role and runs
+  no DDL; your migrations own the shape of your database.
+
+For the setup details, see [Connect Your Database](./data-sources.md). For the
+coordination loop, see [Concurrency Convention](./concurrency-convention.md). For
+what `queued` and `confirmed` guarantee, see [Guarantees](./guarantees.md).

package/docs/integration-guide.md

@@ -47,11 +47,12 @@ objects by hand.
 Every schema model is backed by **your own database**. The SDK call shape is the
 same everywhere.
 
-In this guide — an app that already owns its backend and database — keep
-`DATABASE_URL` inside your app and connect it out of band: run `npx ablo connect`
-for logical replication (Ablo tails your WAL), or expose a signed Data Source
-endpoint where Ablo coordinates each write and your app commits it to your
-Postgres. Either way, application and agent code hold only `ABLO_API_KEY` — the
+In this guide — an app that already owns its backend and database — keep the
+database credentials inside your server runtime and connect out of band: run `npx
+ablo connect` to set up logical replication and a scoped writer role, or expose a
+signed Data Source endpoint when your database can't grant replication. Either way,
+you write through `ablo.<model>`; Ablo lands each change in your Postgres and
+confirms it over the WAL. Application and agent code hold only `ABLO_API_KEY` — the
 client never sees a connection string. [Connect Your Database](./data-sources.md)
 is the single source of truth for both paths.
 
@@ -445,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;
@@ -512,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

@@ -2,15 +2,16 @@
 
 Build with Ablo on **the Postgres you already have**. You declare a small Ablo
 schema for the models humans and agents edit together, connect Ablo to your
-database with **logical replication** (`ablo connect`), and coordinate every read
-and claim through `ablo.<model>`. Your database stays the system of record: your
-app keeps writing through its own backend, Ablo tails your write-ahead log (WAL),
-and the confirmed rows fan out to every connected client. Ablo **never runs DDL,
-owns, or migrates your schema**.
+database (`ablo connect`), and read and write every one of those models through
+`ablo.<model>`. You write through Ablo; it lands the change in your Postgres and
+confirms it by tailing your write-ahead log (WAL). Your rows live in your database,
+which stays the system of record. Ablo writes rows but **runs no DDL and owns no
+schema** — your migration tool stays in charge of the shape of your database.
 
-> No database yet? The hosted **sandbox** can host rows in Ablo's test plane —
-> pass an `apiKey` only and skip the database setup, like Stripe test mode — so
-> you can try Ablo before connecting your Postgres.
+> No database yet? Pass an `apiKey` only and Ablo keeps your rows in its own log,
+> so you can build the whole app today — like Stripe test mode. Point it at a
+> separate or local Postgres for a throwaway sandbox, or at your production
+> database when you're ready.
 
 ## 1. Install and initialize
 
@@ -97,32 +98,38 @@ collapses to the untyped client.
 
 ## 3. Connect your database with `ablo connect`
 
-Connecting a real database = Postgres logical replication, and `ablo connect` is
-the one way to set it up. Ablo **reads** your WAL and never runs DDL, owns, or
-migrates your schema — your app keeps writing through its own backend.
+`ablo connect` sets your database up so Ablo can write your rows (a scoped DML
+role) and read them back to confirm (logical replication). It writes rows through
+that role but runs no DDL and owns no schema — your migration tool stays in charge.
 
-```bash
-# 1. Enable logical decoding (then RESTART Postgres — wal_level is not reloadable)
-#    ALTER SYSTEM SET wal_level = 'logical';
-#    On RDS/Aurora: set rds.logical_replication = 1 in the parameter group, reboot.
-
-# 2. Print the exact publication + replication-role SQL for YOUR Postgres, run it:
-npx ablo connect
+You run `ablo connect` once, out of band — it provisions the roles and hands them
+to Ablo. From then on Ablo does the connecting; your app never opens a database
+connection.
 
-# 3. Put the replication role's connection string in DATABASE_URL, then validate:
-npx ablo connect --check
+```bash
+# 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
+
+# ...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
 ```
 
-`ablo connect` prints the copy-pasteable SQL (a publication named
-`ablo_publication` and a least-privilege `ablo_replicator` role with
-`REPLICATION` + `SELECT`, password you choose). `ablo connect --check` connects to
-`DATABASE_URL` and verifies `wal_level=logical`, the publication, the role's
-`REPLICATION` attribute, and that every published table has a usable
-`REPLICA IDENTITY` — a green checklist or the precise fix per item.
+`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`.
+
+Your **app** holds only the API key — never a connection string:
 
 ```bash
 # .env — server runtime only, never the browser
-DATABASE_URL=postgres://ablo_replicator:<password>@host:5432/db?sslmode=require
 ABLO_API_KEY=sk_test_...
 ```
 
@@ -137,9 +144,9 @@ export const ablo = Ablo({
 });
 ```
 
-The full setup, the honest footprint (publication + slot + `REPLICATION` role +
-the `wal_level` restart + slot/WAL retention Ablo monitors), and the Preview
-status of the WAL runtime are in [Connect Your Database](./data-sources.md).
+The full setup, the honest footprint (publication + slot + the `REPLICATION` and
+writer roles + the `wal_level` restart + slot/WAL retention Ablo monitors), and the
+Preview status are in [Connect Your Database](./data-sources.md).
 
 ## 4. Push the schema, then map it to tables
 
@@ -223,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/schema-contract.md

@@ -102,11 +102,13 @@ the fresh row. Reads stay open; only acting on the row serializes.
 
 ## Storage boundary
 
-Every schema model is backed by your own database. There are three start states,
-all covered in [Connect Your Database](./data-sources.md) (the single source of
-truth): the sandbox (`apiKey` only, no database), logical replication set up with
-`npx ablo connect` (Ablo tails your WAL), or a signed Data Source endpoint where
-your app keeps the database credential and commits each write itself.
+Every schema model is backed by your own database, and you write to it through
+`ablo.<model>`. There are three start states, all covered in [Connect Your
+Database](./data-sources.md) (the single source of truth): the sandbox (`apiKey`
+only, no database — Ablo keeps your rows in its own log), `npx ablo connect` (a
+scoped writer role plus logical replication, so Ablo writes your rows and confirms
+them over the WAL), or a signed Data Source endpoint when your database can't grant
+replication.
 
 Your database connects out of band, so the client holds only `ABLO_API_KEY` —
 never a connection string. Browser code goes through `<AbloProvider>` or a scoped

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.30.2",
+  "version": "0.32.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",