@abloatai/ablo 0.56.0 → 0.58.0

package/docs/customer-organizations.md

@@ -2,8 +2,21 @@
 
 > One account, one schema, and a session scoped to the customer whose data it may read.
 
-Your customers live in your database, in a table you already have. Ablo reaches
-one of them by the groups a session is minted with.
+Serving many customers from one backend has two shapes, and the first question
+is whether isolating them is a security boundary or a routing convenience.
+
+**One Ablo organization per customer** is the hard boundary. Every row carries
+the organization, and the engine compares it on every read and every write,
+below your code. Choose it when one customer reading another's rows would be an
+incident.
+
+**One organization, customers as rows told apart by sync groups** is delivery
+and read routing. It is declarative, it depends on every model being covered,
+and it is not enforced on every path. Choose it when cross-customer reads are
+tolerable or intentional, not when they are a breach.
+
+The rest of this page is the second shape. Read *Where the boundary is enforced*
+before you rely on it.
 
 ```ts
 // 1. src/ablo/schema.ts — your customer table is a scope root.
@@ -82,29 +95,33 @@ session adds is which customer the person in front of it may read.
 
 ## Where the boundary is enforced
 
-Two mechanisms do different jobs, and it is worth knowing which is which before
-you rely on either.
+Two mechanisms do different jobs, and the difference is the whole of this page.
 
 **Your account is the tenant boundary.** Every row Ablo stores carries your
-organization and project, and row-level security compares both against the
-credential on every read and every write. A client cannot reach past it by
-asking, because the values come from the key rather than the request.
-
-**Sync groups are the cut inside your account.** They decide which of your own
-rows a session is delivered and which it may read back over HTTP. This is the
-boundary between one of your customers and the next, and it is the one your
-schema declares.
-
-Reads go through it. `list` and `get` are cut to the session's groups, live
-delivery is cut to the same set, and the initial load is the intersection of
-what the session asked for with what it was minted with.
-
-Coordination reads are cut more coarsely today. Listing claims and reading
-presence are scoped to your account and plane rather than to the session's
-groups, so one customer's session can see that a row is claimed and who is
-present, though never the row's contents. Treat row ids and participant ids on
-those two surfaces as visible across your customers until this page says
-otherwise.
+organization, project, and branch, and all three are compared on every read and
+every write, from the credential rather than the request. A client cannot reach
+past them by asking. This is the boundary that holds unconditionally.
+
+**Sync groups are a cut inside your account, and they are not applied
+everywhere.** They decide which changes are delivered and which rows a
+log-served read returns. That is routing. It is not a universal authorization
+boundary, and the gaps are specific:
+
+| Path | Group cut applied |
+|---|---|
+| Live delivery and fan-out | Yes |
+| HTTP read on a log-served plane (a connected database) | Yes |
+| HTTP read on a hosted or direct-query plane | **No.** Scoped by organization |
+| Writes | **No.** The groups are recorded on the change, never checked against the row |
+| Claim listings and presence | Yes |
+
+So a session cut to one customer, on a hosted plane, can read another
+customer's rows over HTTP; and on any plane it can write to them. What stops it
+today is the organization, which both customers share under this shape.
+
+If isolating your customers is a security requirement, give each one its own
+Ablo organization. The stronger row-and-subject authorization that would make
+this shape safe on every path is not in the engine yet.
 
 ## Naming a group
 
@@ -120,16 +137,17 @@ Resolve `member.customerId` from the membership you just authenticated on the
 server. A signed-in person can put any value in a request body, and the session
 you mint is what decides what they can read.
 
-## When a customer really is an account
+## When a customer should be its own organization
 
-There is one shape where each of your customers should be its own Ablo
-organization: when each is a separate paying business that signs in to Ablo
-itself, holds its own subscription, and invites its own developers. That is what
-an identity provider looks like, and it is what the `organization:act-as` scope
-on a secret key exists for.
+Whenever their isolation has to hold. Give each customer its own Ablo
+organization when one of them reading or writing another's rows would be an
+incident rather than a bug, when you cannot audit group coverage across every
+model, or when a customer is a separate paying business that signs in to Ablo
+itself and invites its own developers.
 
-It is rare, and it is not what a platform serving customers from one product
-looks like. If your customers never see Ablo, they belong in your schema.
+Your backend then names the customer's organization on the mint, which takes a
+secret key carrying `organization:act-as`. The customer never sees Ablo; the
+scope exists because the session leaves the organization the key belongs to.
 
 ## Onboarding a customer
 

package/docs/data-sources.md

@@ -110,12 +110,12 @@ migrations — your migration tool stays in charge of the shape of your database
 Ablo only writes rows into tables you already have, through a role scoped to
 exactly that.
 
-> **Just trying Ablo?** You don't need a database to start. Pass an `apiKey` only,
-> and Ablo keeps your rows in its own log so you can build the whole app today.
-> `ablo dev` gives each Git branch its own isolated plane.
-> Keep it hosted with no database, or point that branch at a separate/local
-> Postgres. Connect your production root (below) when you're ready for its
-> database to be the system of record.
+> **Just trying Ablo?** Start on a throwaway Postgres rather than your production
+> one. `ablo dev` gives each Git branch its own isolated plane, so point that
+> branch at a separate or local database, build against it, and connect your
+> production root (below) when you're ready for its database to be the system of
+> record. A branch with nothing connected refuses a schema push, which is the
+> first thing you'll hit if you skip this.
 
 Connecting sets up two capabilities on your Postgres: **logical replication**, so
 Ablo can read and confirm, and a **scoped DML role**, so Ablo can write. `ablo
@@ -475,6 +475,12 @@ directly by other application code is visible only if that code writes the same
 outbox record in its transaction. Native WAL observation sees both Ablo and
 external writes.
 
+Endpoint events use a versioned envelope. Version 2 freezes `syncGroups` in the
+writing transaction; version 1 is retained only to decode events written by an
+older adapter during a rolling upgrade. Poll requests keep `cursor` (where to
+read) separate from `acknowledgedThrough` (what Ablo has durably accepted), and
+the built-in adapters prune acknowledged rows in bounded batches.
+
 ## Next steps
 
 - [Quickstart](./quickstart.md) — connect and write through `ablo.<model>`.

package/docs/debugging.md

@@ -86,7 +86,7 @@ Read it as the lifecycle of one claim:
 - **`queued … position N of M`:** the row was held, so you're waiting in the FIFO line. This is the "an agent is waiting behind a claim" moment; it re-logs only when your position changes, so you can watch it advance.
 - **`granted … your turn`:** you reached the head of the line; the lease is now yours and the row may have changed while you waited.
 - **`rejected … held by <who>`:** your claim was refused because someone else holds it (and the model's policy didn't let you in).
-- **`lost`:** you held the lease and it was taken (preempted by a higher-priority writer, or it expired).
+- **`lost`:** you held the lease and it ended (the queue fairness ceiling advanced, or it expired).
 - **`released`:** you (or `await using`'s scope exit) gave the lease back.
 
 ## Where the logs run

package/docs/examples/agent-human.md

@@ -25,7 +25,7 @@ a typed error if the row moved underneath you while the agent was busy.
 ## Schema-Backed Worker
 
 The worker uses the same schema client the app uses. It reads the record from the
-server with `get({ id })`, claims the row, and writes through
+server with `read({ id })`, claims the row, and writes through
 `ablo.records.update(...)` with a stale-check so a concurrent edit can't be
 overwritten.
 
@@ -49,8 +49,8 @@ const ablo = Ablo({
 export async function markDone(recordId: string) {
   await ablo.ready();
 
-  // get({ id }) is an async server read — await it.
-  const record = await ablo.records.get({ id: recordId });
+  // read({ id }) is an async server read — await it.
+  const record = await ablo.records.read({ id: recordId });
   if (!record) return { status: 'not_found' };
 
   try {
@@ -67,21 +67,9 @@ export async function markDone(recordId: string) {
     await using claim = acquired;
     if (claim.data.status === 'done') return { status: 'noop' };
 
-    // Inside an active claim, `update` is stale-checked automatically: the SDK
-    // attaches the claim's snapshot version as `readAt` and sets
-    // `onStale: 'reject'`. The write below is therefore equivalent to passing
-    // those options yourself:
-    //
-    //   ablo.records.update({
-    //     id: claim.data.id,
-    //     data: { status: 'done' },
-    //     readAt: <claim snapshot version>,
-    //     onStale: 'reject',
-    //   });
-    //
-    // If a newer version landed mid-run, the row no longer matches `readAt`, so
-    // the server rejects this commit with AbloStaleContextError (caught below)
-    // instead of clobbering that edit.
+    // The claim handle carries its acquisition snapshot. If a newer version
+    // somehow lands mid-run, the server rejects this commit with
+    // AbloStaleContextError instead of clobbering that edit.
     const updated = await ablo.records.update({
       id: claim.data.id,
       data: { status: 'done' },

package/docs/examples/coordination-conformance.md

@@ -0,0 +1,69 @@
+# Verify hosted coordination separately
+
+> Prove claim behavior once, without coupling the proof to a document, workflow, or GraphQL schema.
+
+Use two test layers when adopting Ablo behind an existing application:
+
+| Proof | Responsibility |
+|---|---|
+| Domain contract | State transitions, stale evidence, provenance, idempotency, and old/new path parity. |
+| Hosted coordination conformance | Participant identity, exclusion, heartbeat, release, and lease-expiry recovery. |
+
+The runnable hosted proof is
+[`examples/coordination-conformance`](../../../../examples/coordination-conformance/README.md).
+It creates a temporary test branch that inherits an existing non-production
+schema. It does not push a schema or change domain rows.
+
+## File structure
+
+```text
+src/conformance/index.ts
+  -> src/conformance/claimExclusion.ts
+  -> src/conformance/contract.ts
+src/runtime/index.ts
+  -> src/runtime/client.ts
+  -> src/runtime/config.ts
+live/index.ts
+  -> live/claimAndExit.ts
+```
+
+The conformance operation depends on a narrow structural claim interface. The
+runtime child supplies the real Ablo model resource. Domain examples depend on
+the same narrow behavior without inheriting this runner's branch or credential
+setup.
+
+## Run
+
+First run the deterministic structure and configuration checks:
+
+```bash
+cd examples/coordination-conformance
+npm test
+npm run typecheck
+```
+
+Then name an existing model on the CLI login's dedicated non-production
+project:
+
+```bash
+ABLO_CONFORMANCE_MODEL=existingModel npm run test:live
+```
+
+The model name supplies only a typed claim namespace. Every claim target is a
+new random identifier; the proof creates no model row. The disposable branch
+is deleted even when an assertion fails.
+
+The runtime deliberately calls `model.claim(id, options)`. This identifier
+overload is row-free. `model.claim({ id, ...options })` is the row-backed form:
+it reads the model row and is not interchangeable in a coordination-only
+rollout.
+
+## What this lets domain examples omit
+
+A document-processing example does not need its own branch provisioning,
+session delegation, heartbeat, or process-death fixture. It must still test its
+own behavior when a claim is won, skipped, released after failure, and combined
+with changing evidence.
+
+This separation prevents a vertical testcase from force-replacing an inherited
+schema merely to re-prove generic lease behavior.