@abloatai/ablo 0.56.0 → 0.57.0

package/CHANGELOG.md

@@ -1,19 +1,251 @@
 # Changelog
 
+## 0.57.0
+
+### Before you upgrade: drain the endpoint outbox
+
+This release adds a `sync_groups` column to the source outbox, and the migration
+refuses to run while legacy rows are still sitting in it. That refusal is
+deliberate. A legacy row has no routes recorded, and assigning it one would
+either invent an audience or give it none, so the migration stops and tells you
+rather than guessing.
+
+If you run a `dataSource()` endpoint, do this on the previous release, in order:
+
+1. Let Ablo poll until every event already in `ablo_outbox` has been consumed.
+2. Confirm the polling cursor has advanced past the last of them.
+3. Delete those consumed rows.
+
+Then upgrade and run the migration. If you connect your database over
+replication rather than an endpoint, there is no outbox and nothing to do.
+
+### A row is authorized by the subject its schema declares
+
+A model may now declare which field decides who a row belongs to, and that rule
+is enforced on every path: reads, writes, claims, presence, and every storage
+adapter, including the endpoint ones. A row is authorized exactly when the
+request carries the sync group `${group}:${row[field]}`.
+
+This is what 0.56.0's boundary change was heading towards. Sync groups routed
+delivery and did not decide authorization, so a model that used them as though
+they did was relying on something the guide told you not to rely on. A declared
+subject is that rule made real, checked in one place and failing closed.
+
+Two consequences worth knowing. A subject-scoped model stamps exactly one group
+on a change, because delivery matching is OR-based and a second group would
+widen the audience rather than narrow it. And a tombstone now reaches only the
+row's authorized subject group, where before a delete could be announced more
+widely than the row ever was.
+
+A schema that routes by sync group without a matching row-access policy is
+flagged. If the routing really is only routing, acknowledge it explicitly and
+the flag goes quiet.
+
+### Creating many rows is one commit
+
+`create` takes a list as well as a single row, under the same verb:
+
+```ts
+const rows = await ablo.weatherReports.create({
+  data: [
+    { location: 'Stockholm', summary: 'Clear' },
+    { location: 'Oslo', summary: 'Rain' },
+  ],
+});
+```
+
+They are written as one atomic commit rather than one request each, so either
+every row lands or none does. The result comes back in the order you gave it,
+not the order the batch settled, and carries whatever defaults the server
+stamped. An empty list writes nothing rather than opening an empty commit.
+
+### Reading a whole collection, in as many words
+
+`listAll({ where, maxPages, signal })` reads a complete collection by walking the
+same cursor `list` returns, so the common case stops being a hand-rolled loop:
+
+```ts
+const open = await ablo.weatherReports.listAll({
+  where: { status: ['draft', 'review'] },
+  maxPages: 20,
+});
+```
+
+It is bounded on purpose. `maxPages` is how you say how much you are willing to
+read, and `signal` cancels a walk that is taking longer than the work is worth.
+A complete read that cannot say when it will stop is how a page turns into an
+outage.
+
+### A claimed write carries its stale guard again
+
+Holding a claim and then writing gave mutual exclusion but not lost-update
+detection, on the stateless transport agents run. The claim handle carries the
+position the row was read at, and the write defaults to rejecting on a change
+since then. Unwrapping the handle cleared the claim before that default was
+read, so the guard was unreachable and every model write through the public
+surface lost it.
+
+It read as though both protections were present: claim, read, decide, write. The
+watermark now travels with the handle, and your own `readAt` or `onStale` still
+win where you set them.
+
+### A create on an id that already exists is refused
+
+It reported success and returned a row. A caller-selected id is a claim about
+which row this is, so a create that finds one already there is a conflict rather
+than an update, and it now says so.
+
+### CLI: a session route that revalidates before it mints
+
+`ablo init` scaffolds a Next.js session route that re-checks membership at mint
+time rather than trusting the caller, and puts secret clients behind the
+framework's `server-only` boundary so a key cannot be imported into a component
+that ships to a browser.
+
+### Filtering a server read by a reference field
+
+`list({ where: { issueId } })` matched nothing on a replicated plane. It raised
+no error and returned a well-formed empty array, so the read looked like a
+question with no answers rather than a filter that never ran. Filtering on
+`id`, `title` or `body` worked, which made the failure look like a property of
+the data instead of a property of the field name.
+
+The cause was a key space. A row served from the log is a snapshot in the wire
+shape, so its fields are spelled the way your schema spells them, while the
+filter looked them up by their database column. Those two agree exactly when a
+column is a single word, and part ways on every `issueId`, `teamId` or
+`assigneeId`. Ordering, relation expansion and any field declared with
+`.from()` were reading the same wrong spelling: a `related` list came back
+empty, and a `.from()` field was simply absent from the row.
+
+If you page a collection and filter it in your own code to work around this,
+that code can go.
+
+A filter naming a field the model does not declare is now refused, with the
+same error the direct-database plane already gave it. It used to return
+nothing, which reads as an answer.
+
+### A list read walks its own pages
+
+`list` returns a page, and a page of 20 looks exactly like a complete answer of 20. Every caller either checked `hasMore` or, more often, reasoned about a
+truncated collection without knowing there was more.
+
+Iterate the result for the page. Walk it for the collection:
+
+```ts
+for await (const issue of await ablo.issues.list({ where: { teamId } })) {
+  …
+}
+```
+
+`hasMore` and `nextCursor` are unchanged, and taking the cursor yourself is
+still the right thing when the pages go somewhere other than a loop.
+
+### Clearing a field
+
+`null` clears a field, and the types now say so. They used to accept only the
+field's own type or `undefined`, and `undefined` means "leave this alone": it
+is dropped from the payload, so an unassign written that way kept the old
+assignee and reported success. The only spelling that both compiled and worked
+was one that cast the payload, which turned off type checking for the whole
+write.
+
+Only a field your schema declares optional accepts `null`. A required field has
+no empty value to move to, and the type says that too.
+
+### A write that does not name its row is refused
+
+`delete({ where: { id } })` reads like it should work, and `where` is what the
+commit protocol takes one layer down. It used to spell the missing id into the
+request as the literal text `undefined`, match no row, and return an ordinary
+receipt. It now fails at the call, naming the model, the action, and `{ id }`.
+
+The same guard covers `update`.
+
+### A create honours the id you gave it
+
+An id passed inside `data`, which the create input has always allowed, was
+never read: the row was written under a generated id and you were handed back
+one you had not named. Both spellings now work, and the standalone `id` wins if
+they disagree.
+
+### Every response says what your allowance is
+
+The limiter knew the allowance and the refill and told you neither, so the only
+strategy available was to retry and find the wall again.
+
+```
+RateLimit-Policy: "secret";q=600;w=12
+RateLimit: "secret";r=573;t=8
+Retry-After: 3
+```
+
+`RateLimit-Policy` is the standing allowance and is always present.
+`RateLimit` reports what is left and when it refills, once a request is
+attributed to a key. A 429 adds `Retry-After` in whole seconds. Pace against
+these rather than retrying blind.
+
+### A route says when it is going away
+
+Every response carries `Ablo-Version`, a date stamp for the contract being
+served, so a caller can notice the contract moved under it.
+
+A route being withdrawn now says so on itself for at least 180 days first.
+`Deprecation` (RFC 9745) carries when the deprecation took effect, and the route
+keeps answering; `Sunset` (RFC 8594) carries when it stops. The same operations
+are marked `deprecated: true` in the OpenAPI document, so a generated client
+sees it too.
+
+Breaking changes still arrive as a new path segment beside `/v1`, never as a
+change to it. Additive ones land in `/v1`, so ignore what you do not recognise.
+
+### The documentation answers a reader that is not a browser
+
+The surfaces `llms.txt` names are routes now rather than a promise:
+`/llms-full.txt` for the whole corpus in one fetch, `/openapi.json` for the REST
+contract, `/developers` naming every developer surface on one page,
+`/.well-known/mcp.json` for the MCP manifest.
+
+Every page also answers from its own URL in Markdown. Send
+`Accept: text/markdown`, or append `.md` where a client cannot set headers.
+Responses carry `Vary: Accept`, a client that will take neither type gets a 406
+listing what is available, and a path that does not exist answers a real 404
+rather than a 200 carrying a sign-in page.
+
+### Renamed and removed
+
+`SourceRequestContext.requiredSyncGroups` is now `syncGroups`. Ablo populates
+both spellings this release, so a source adapter still reading the old name gets
+the groups rather than `undefined`, which on a routing field would read as "no
+groups" rather than as a field that moved. The old spelling is removed in
+0.58.0.
+
+`DeltaPosition`, `deltaPositionSchema`, `ReadSetWatermark`, and
+`readSetWatermarkSchema` are removed, as 0.56.0 announced. Use `LogPosition` and
+`logPositionSchema`, which they have resolved to since then.
+
 ## 0.56.0
 
-### One customer no longer sees another's live work
+### Coordination reads are scoped to the customer, not the organization
+
+Coordination has always been scoped to the organization, and through 0.51.0 that
+was the whole boundary: a platform gave each customer its own organization, and
+the sessions guide was explicit that sync groups decide which changes travel
+rather than what a session may read.
+
+This release moves that line. A platform's customers are rows in its own schema,
+reached by the sync groups on the session, so many customers share one
+organization and the organization is no longer the finest boundary. The delivery
+path already applied the finer cut. The claim listing and the presence read did
+not, so under that newer arrangement one customer could see which rows another
+had claimed, who held them, what the work was called, and who was online. Row
+contents were never exposed; everything around them was.
 
-A platform's customers are rows in its own schema, so they share one
-organization and one plane. The claim listing and the presence read were scoped
-to exactly that pair and nothing finer. One customer could therefore see which
-rows another had claimed, who held them, what the work was called, and who was
-online. Row contents were never exposed; everything around them was.
+Both reads now take the same cut, from the groups each side already carries.
 
-Both reads now apply the same cut the delivery path already applies, taken from
-the groups each side already carries. A customer sees the coordination for the
-rows it can see, and nothing else. If you serve many customers from one
-organization, this closes the gap without any change on your side.
+If you give each customer its own organization, nothing changes for you and
+nothing was reachable across customers. If you serve many customers from one
+organization, this closes the gap with no change on your side.
 
 ### A client converges on the head it was measured against
 

package/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2025-2026 Lukas Andersson
+   Copyright 2025-2026 Ablo Inc.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/NOTICE

@@ -1,10 +1,10 @@
 @ablo/ablo
-Copyright 2025-2026 Lukas Andersson
+Copyright 2025-2026 Ablo Inc.
 
-This product includes software developed by Lukas Andersson
+This product includes software developed by Ablo Inc.
 (https://abloatai.com).
 
-"Ablo" is a trademark of Lukas Andersson. This license does not grant
+"Ablo" is a trademark of Ablo Inc. This license does not grant
 permission to use the Ablo name, logo, or trademarks. Third parties
 may describe their use of or compatibility with Ablo factually (e.g.,
 "built with @ablo/ablo") but may not use the Ablo name in a way

package/docs/agents.md

@@ -46,6 +46,63 @@ and `claim`. It does **not** expose stateful-only `local` reads or `onChange`
 subscriptions. Those need a live connection, so with `transport: 'http'` they
 are compile errors rather than runtime surprises.
 
+## Managed scoped agents
+
+When this process owns the secret client and also runs the agent, prefer
+`agents.create`. It mints the restricted credential, returns a schema-typed
+client, and renews that credential for a long run. `sessions.create({ agent })`
+is the raw-token path for handing identity to another runtime.
+
+Derive identity and groups from the run row or trusted job payload—not from
+model output or an HTTP request body. A serverless handler normally creates and
+disposes one child per invocation:
+
+```ts
+const run = await control.runs.get({ id: verifiedRunId });
+if (!run) throw new Error('run not found');
+
+const agent = await control.agents.create({
+  id: `run:${run.id}`,
+  name: 'run-worker',
+  can: { records: ['read', 'update'] },
+  syncGroups: [`workspace:${run.workspaceId}`],
+});
+try {
+  await executeRun(agent, run);
+} finally {
+  await agent.dispose();
+}
+```
+
+Use a stable id only when one logical run is serialized; two concurrent workers
+that share an id appear as the same participant. For independent concurrent
+work, omit `id` and let Ablo create distinct identities.
+
+A long-running worker may cache one managed client per stable scope, but the
+cache owns lifecycle: evict idle clients, call `dispose()` on eviction, and
+dispose every client during graceful shutdown. Never cache a client and later
+reuse it for a different workspace or capability set.
+
+```ts
+const agents: Record<
+  string,
+  Awaited<ReturnType<typeof control.agents.create>> | undefined
+> = {};
+
+async function agentFor(run: Run) {
+  const key = `${run.workspaceId}:${run.workerSlot}`;
+  const cached = agents[key];
+  if (cached) return cached;
+  const created = await control.agents.create({
+    id: `worker:${key}`,
+    can: { records: ['read', 'update'] },
+    syncGroups: [`workspace:${run.workspaceId}`],
+  });
+  agents[key] = created;
+  return created;
+}
+```
+
 ## AI SDK tools
 
 Keep AI SDK in charge of the model loop and expose only the Ablo operations the

package/docs/api.md

@@ -53,6 +53,7 @@ Each schema model becomes a typed model on the client:
 
 - `ablo.weatherReports.get({ id })` reads one row asynchronously (server read).
 - `ablo.weatherReports.list({ where })` reads a collection asynchronously (server read).
+- `ablo.weatherReports.listAll({ where })` explicitly reads every matching page.
 - `ablo.weatherReports.local.get(id)` reads one row synchronously from the local graph.
 - `ablo.weatherReports.create({ data })` creates a row.
 - `ablo.weatherReports.update({ id, data, ...options })` updates a row.
@@ -68,6 +69,7 @@ fallback removed — nothing to await, so they return a value.
 |---|---|---|
 | `get({ id })` | `Promise<T \| undefined>` | You need one row, hydrating from local store and server. |
 | `list({ where })` | `Promise<ModelList<T>>` | You need to hydrate a collection from local store and server. |
+| `listAll({ where, maxPages?, signal? })` | `Promise<T[]>` | You deliberately need every matching row. |
 | `local.get(id)` | `T \| undefined` | You want a synchronous snapshot of one local row. |
 | `local.list(options?)` | `T[]` | You want a synchronous snapshot of a local collection. |
 | `local.count(options?)` | `number` | You want a synchronous count of local rows. |
@@ -79,24 +81,57 @@ fallback removed — nothing to await, so they return a value.
 through the server. The `local` reads work off the rows a session has already
 synced, so a cheap re-read needs no round-trip.
 
-### Paging a collection
+### Reading a whole collection
 
-`list` returns a page. The result is an array, so it maps and iterates as
-before, and it carries `hasMore` and `nextCursor` alongside the rows:
+Prefer a filtered `listAll` when the application truly needs one complete
+array. It follows the same cursor loop as async iteration, defaults to at most
+100 pages, and checks an abort signal between requests and rows:
+
+```ts
+const controller = new AbortController();
+const open = await ablo.weatherReports.listAll({
+  where: { status: ['draft', 'review'] },
+  orderBy: { createdAt: 'asc' },
+  maxPages: 25,
+  signal: controller.signal,
+});
+```
+
+A complete traversal can be expensive in latency, memory, and read volume.
+Narrow it with `where`; use `list` and its cursor when a UI or worker can process
+one page at a time.
+
+`for await` walks the pages:
 
 ```ts
-let cursor: string | null = null;
 const open = [];
-do {
-  const page = await ablo.weatherReports.list({
-    where: { status: ['draft', 'review'] },
-    orderBy: { createdAt: 'asc' },
-    limit: 100,
-    ...(cursor ? { cursor } : {}),
-  });
-  open.push(...page);
-  cursor = page.hasMore ? page.nextCursor : null;
-} while (cursor);
+for await (const report of await ablo.weatherReports.list({
+  where: { status: ['draft', 'review'] },
+  orderBy: { createdAt: 'asc' },
+})) {
+  open.push(report);
+}
+```
+
+`list` returns a page, because the server applies a default size and caps the
+largest. The result is an array, so it maps and iterates as before, and it
+carries `hasMore` and `nextCursor` alongside the rows. Iterate it to work with
+the page you were handed; `for await` it to work with the collection.
+
+```ts
+const page = await ablo.weatherReports.list({ where: { status: 'draft' } });
+page.length;    // the rows this page carries
+page.hasMore;   // whether the collection continues past them
+```
+
+Take the cursor yourself when the pages go somewhere other than a loop — one
+screenful at a time, or a job that stops and resumes:
+
+```ts
+const page = await ablo.weatherReports.list({ where: { status: 'draft' }, limit: 100 });
+const next = page.hasMore
+  ? await ablo.weatherReports.list({ where: { status: 'draft' }, limit: 100, cursor: page.nextCursor })
+  : null;
 ```
 
 Keep `where` and `orderBy` the same across pages: the cursor encodes the sort
@@ -106,6 +141,22 @@ position it was issued for, and a read that changes either starts a new walk.
 `{ status: ['draft', 'review'] }` is an `IN`, and tuple form spells the rest
 out, as in `[['title', 'ILIKE', '%storm%'], ['createdAt', '>=', cutoff]]`.
 
+### Changing a field, and clearing one
+
+`null` clears a field:
+
+```ts
+await ablo.weatherReports.update({ id, data: { reviewerId: null } });   // unassigned
+await ablo.weatherReports.update({ id, data: { reviewerId: 'usr_2' } }); // reassigned
+```
+
+An update is a patch, so a field you leave out keeps its value. That makes
+`undefined` and "leave it alone" the same thing: `{ reviewerId: undefined }`
+is dropped from the payload and the old reviewer stays. Reach for `null`
+whenever a value is going away, and the type will hold you to it — only a
+field your schema declares optional accepts one, since a required field has no
+empty value to move to.
+
 ## Protected Writes
 
 Use `snapshot` when a write should reject if the row changed mid-flight:

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/examples/nextjs.md

@@ -45,6 +45,8 @@ has no credential and the engine fails to initialize with `session_expired`.
 
 ```ts
 // lib/ablo.ts — server-only
+import 'server-only';
+
 import Ablo from '@abloatai/ablo';
 import { schema } from './ablo.schema';
 
@@ -58,30 +60,59 @@ export const ablo = Ablo({
 ## Session Route
 
 The browser can't hold `sk_`, so a backend route mints a scoped, short-lived
-`ek_` for the signed-in user. Guard it with your own auth.
+`ek_` for the signed-in user. Being signed in is not workspace authorization:
+revalidate the active membership immediately before every mint, and derive all
+organization, workspace, team, and group ids on the server. Never accept them
+from the request body.
 
 ```ts
 // app/api/ablo-session/route.ts
 import { ablo } from '@/lib/ablo';
 import { getCurrentUser } from '@/auth';
+import { headers } from 'next/headers';
 import {
   credentialEndpointErrorSchema,
   credentialEndpointSuccessSchema,
 } from '@abloatai/ablo/auth';
 
-export async function POST() {
+const noStore = { 'Cache-Control': 'no-store' };
+
+export async function POST(request: Request) {
+  if (!(await isSameOrigin(request))) {
+    return Response.json(
+      credentialEndpointErrorSchema.parse({
+        error: { code: 'origin_mismatch', message: 'Cross-origin mint rejected' },
+      }),
+      { status: 403, headers: noStore },
+    );
+  }
+
   const user = await getCurrentUser();
   if (!user) {
     return Response.json(
       credentialEndpointErrorSchema.parse({
         error: { code: 'session_expired' },
       }),
-      { status: 401, headers: { 'Cache-Control': 'no-store' } },
+      { status: 401, headers: noStore },
+    );
+  }
+
+  // Query your membership table now—not when the login session was created.
+  // The helper reads the active workspace from server-side session state and
+  // returns null when the membership is stale or revoked.
+  const scope = await authorizeActiveWorkspace(user.id);
+  if (!scope) {
+    return Response.json(
+      credentialEndpointErrorSchema.parse({
+        error: { code: 'policy_denied', message: 'Workspace membership is stale or revoked' },
+      }),
+      { status: 403, headers: noStore },
     );
   }
 
   const { token, expiresAt } = await ablo.sessions.create({
     user: { id: user.id },
+    syncGroups: scope.syncGroups,
     can: { records: ['read', 'create', 'update'] },
   });
   return Response.json(
@@ -90,11 +121,23 @@ export async function POST() {
       expiresAt,
       credentialKind: 'ephemeral',
     }),
-    { headers: { 'Cache-Control': 'no-store' } },
+    { headers: noStore },
   );
 }
+
+async function isSameOrigin(request: Request): Promise<boolean> {
+  const origin = request.headers.get('origin');
+  if (!origin) return request.headers.get('sec-fetch-site') !== 'cross-site';
+  const host = (await headers()).get('host');
+  return host !== null && new URL(origin).host === host;
+}
 ```
 
+`authorizeActiveWorkspace` is application code: it must query the authoritative
+membership store and return server-derived sync groups. If fifteen-minute token
+expiry is too slow for your revocation requirements, mint a shorter
+`ttlSeconds` and revoke active sessions when membership changes.
+
 ## Provider
 
 The browser client points `authEndpoint` at that route and is handed to

package/docs/integration-guide.md

@@ -494,6 +494,31 @@ const completeReport = tool({
 
 Keep agent writes on the same schema client surface as the app.
 
+## One command changes an Ablo model and an ORM-only table
+
+Two independently committed calls are not one atomic command. If an Ablo write
+lands and a following Prisma/Drizzle transaction fails—or the reverse—the
+application must expect and repair the partial result. Calling that path
+“coordinated” does not extend Ablo’s claims, stale-read checks, attribution, or
+commit ordering into the ORM transaction.
+
+The supported atomic answer is to model every invariant-bearing row in the
+Ablo schema and submit the operations in one `commits.create` batch (the HTTP
+equivalent is `POST /api/v1/commits`). This applies on both database paths:
+
+- With direct logical replication, Ablo’s batch is one customer-database
+  transaction. A separate ORM transaction is still separate.
+- With a signed Data Source endpoint, the adapter applies the Ablo batch,
+  idempotency record, and outbox entry in one customer-database transaction.
+  Unrelated ORM work outside that adapter is still separate.
+
+There is no general transactional callback that can safely splice arbitrary
+application SQL into the hosted direct-write path. If a table must remain
+ORM-only, treat the command as a saga: give both steps the same durable business
+operation id, make each step idempotent, record progress, retry unfinished
+steps, and define compensation for a result that cannot be completed. State
+that guarantee as eventual completion with repair—not atomicity.
+
 ## Optional Surface
 
 | Optional piece                            | Why it exists                                                     |
@@ -517,6 +542,7 @@ them.
 | -------------------------------------- | -------------------------------------------------------------------------------- |
 | `get({ id })`                     | Async read of one row from the server (await it).                                |
 | `list({ where })`                      | Async read of many rows from the server (await it).                              |
+| `listAll({ where, maxPages?, signal? })` | Explicit bounded traversal of every matching page; filter before collecting.   |
 | `local.get(id)`                   | Synchronous local read of one synced row (use in render).                        |
 | `local.list({ where })`                | Synchronous local read of many synced rows.                                      |
 | `local.count({ where })`               | Synchronous local count of synced rows.                                          |

package/docs/session-settings.md

@@ -50,6 +50,7 @@ context, whether or not you map anything:
 | `app.current_participant_id` | The participant making the write |
 | `app.current_participant_kind` | Whether that participant is a person, an agent, or the system |
 | `app.current_user_id` | The person on whose behalf the write is made |
+| `app.current_subject_groups` | The subject groups the caller belongs to, as a JSON array of `group:value` strings |
 
 If your policies read these names directly, you need no mapping at all — this
 page is for the case where they read different ones.
@@ -62,6 +63,14 @@ from `app.current_org_id` can be useful as defense in depth, but it is not a
 substitute for the tenant policy and you should never loosen RLS to make an
 Ablo write pass.
 
+`app.current_subject_groups` is the one a model with a `subject` rule reads. A
+subject rule names a field and a group — `subject: { field: 'teamId', group:
+'team' }` — and Ablo provisions a policy asking whether the array contains
+`team:` followed by that row's value. The setting is always present, and it is
+`[]` when the caller belongs to no group, so a policy on a pooled connection
+reads an empty membership as an empty membership rather than inheriting what the
+previous transaction left behind.
+
 `app.current_user_id` is worth reading twice, because it has three states rather
 than two. It carries a person's id when a person is behind the write. It carries
 `*` when a backend credential is acting as the organization itself, which is the

package/examples/data-source/customer-server.ts

@@ -114,10 +114,14 @@ export const handleAbloSource = dataSource({
     // own transaction. The example uses a synchronous in-memory
     // update; the surrounding `apply` helper shows where you would
     // open `db.transaction(async (tx) => { ... })`.
-    commit({ operations, clientTxId }) {
+    commit({ operations, clientTxId, context }) {
+      // The routes an outbox event carries come from the trusted scope Ablo
+      // signed into the request, never from the row itself. Ablo adds the
+      // organization group on its side; these are the finer ones.
+      const syncGroups = context.scope?.syncGroups ?? [];
       const rows: RecordRow[] = [];
       for (const op of operations) {
-        const row = applyOperation(op, clientTxId);
+        const row = applyOperation(op, clientTxId, syncGroups);
         if (row) rows.push(row);
       }
       return { rows };
@@ -145,6 +149,7 @@ export const handleAbloSource = dataSource({
 function applyOperation(
   op: SourceOperation,
   clientTxId: string | undefined,
+  syncGroups: readonly string[],
 ): RecordRow | null {
   if (op.model !== 'records') return null;
   const id = op.id ?? `record_${Math.random().toString(36).slice(2, 10)}`;
@@ -160,7 +165,7 @@ function applyOperation(
         : {}),
     };
     recordStore.set(id, row);
-    appendOutbox({ operation: op, entityId: id, data: row, clientTxId });
+    appendOutbox({ operation: op, entityId: id, data: row, clientTxId, syncGroups });
     return row;
   }
 
@@ -169,7 +174,7 @@ function applyOperation(
     if (!existing) return null;
     const next: RecordRow = { ...existing, ...(op.input as Partial<RecordRow>) };
     recordStore.set(id, next);
-    appendOutbox({ operation: op, entityId: id, data: next, clientTxId });
+    appendOutbox({ operation: op, entityId: id, data: next, clientTxId, syncGroups });
     return next;
   }
 
@@ -177,7 +182,7 @@ function applyOperation(
     const existing = recordStore.get(id);
     if (!existing) return null;
     recordStore.delete(id);
-    appendOutbox({ operation: op, entityId: id, data: null, clientTxId });
+    appendOutbox({ operation: op, entityId: id, data: null, clientTxId, syncGroups });
     return existing;
   }
 
@@ -189,6 +194,7 @@ function appendOutbox(input: {
   entityId: string;
   data: RecordRow | null;
   clientTxId: string | undefined;
+  syncGroups: readonly string[];
 }): void {
   outboxSequence += 1;
   outbox.push(
@@ -197,6 +203,7 @@ function appendOutbox(input: {
       operation: input.operation,
       entityId: input.entityId,
       data: input.data,
+      syncGroups: input.syncGroups,
       ...(input.clientTxId ? { clientTxId: input.clientTxId } : {}),
     }),
   );

package/llms.txt

@@ -6,6 +6,57 @@ Here is the problem it solves. Two agents reach for `report_stockholm` at once.
 
 Use AI SDK for the agent loop. Use Ablo when agent reads and writes must persist, coordinate with concurrent work, and leave an audit trail.
 
+## When to use Ablo
+
+Reach for Ablo when MORE THAN ONE writer changes the same rows and the second one must not clobber the first. That is the whole judgement. If a single process owns the data, an ORM against your database is simpler and you should use it.
+
+These are the jobs it is right for:
+
+- **Two or more agents on one workload.** A planner and three workers editing the same records; a swarm assigned overlapping tickets; a retry that restarts while the first attempt is still running. Each takes `claim({ id })` before its slow step, so the second waits and is handed the row as the first left it instead of overwriting.
+- **A read → LLM call → write gap.** The row can change during the seconds your model is thinking. Pass the `readAt` stamp from your read back into the write and a stale write is refused (`AbloStaleContextError`) rather than silently applied on top of someone else's.
+- **A human and an agent in the same record.** A person editing in your app is just another holder of the claim. The agent queues behind them; nobody's edit is lost, and neither side needs to know the other exists.
+- **Work that must survive the process.** Commits are durable and receipts are idempotent, so a crashed or re-scheduled agent replays its write with the same `idempotencyKey` and gets the original result instead of a duplicate.
+- **Anything you will later have to explain.** Every accepted change lands in an append-only log with who wrote it, when, and against which read. `logs` answers "what did the agents actually do" without you having instrumented for the question in advance.
+- **Data you are not allowed to move.** Ablo runs on the customer's own Postgres. It tails the replication stream and writes back through a scoped role; your rows never live in Ablo. If a data-residency or procurement rule forbids a vendor holding the records, this is the shape that passes.
+
+These are the jobs it is WRONG for, and saying so saves you a wasted integration:
+
+- **One writer, no concurrency.** Use Prisma, Drizzle, or SQL. Ablo's coordination costs a round trip and buys you nothing here.
+- **Chat history, traces, or evals.** Append-only telemetry has no contention to resolve. Write it wherever you write logs.
+- **A cache, a queue, or a pub/sub bus.** Ablo is a commit chokepoint over a system of record, not a message broker. Emit your events as usual and use Ablo for the state they are about.
+- **Vector search, embeddings, or retrieval.** Different problem. Ablo coordinates the rows; your vector store indexes them.
+- **A file, blob, or artifact store.** Coordinate the ROW that points at the object; put the bytes in object storage.
+
+How to call it, shortest path first: install `@abloatai/ablo`, run `npx ablo init --yes --framework <nextjs|vite|remix|vanilla>`, and construct `Ablo({ schema, apiKey: process.env.ABLO_API_KEY })`. Read with `ablo.<model>.get({ id })` / `.list({ where })`, write with `ablo.<model>.update({ id, data, readAt })`, and wrap anything slow in `await using claim = await ablo.<model>.claim({ id })`. The sections below cover the rest; "Start here" is the first thing to run.
+
+## Machine-readable surfaces
+
+Everything below is public, needs no credential, and is served from `https://www.abloatai.com`:
+
+- `/llms.txt` — this file.
+- `/llms-full.txt` — the entire published documentation corpus in one fetch.
+- `/developers` — every developer surface named on one page: the SDK, the API reference, the OpenAPI document, the MCP server, the CLI.
+- `/openapi.json` — the REST contract as OpenAPI 3.1: every route, a stable `operationId` and description on each, typed responses, and the `ErrorEnvelope` every 4xx and 5xx decodes through. Generate a client from it when no SDK exists for your runtime.
+- `/mcp` — the integration-helper MCP server over Streamable HTTP. POST your JSON-RPC here; a GET returns a descriptor rather than the protocol.
+- `/.well-known/mcp.json` — that server's manifest, in the MCP registry's `server.json` format.
+- `/api/docs/<page>` — any documentation page as plain Markdown, for a client that fetches URLs rather than speaking MCP.
+- `/sitemap.xml` — every indexable page on the domain.
+
+Every page on that host serves a Markdown representation from its own URL: send
+`Accept: text/markdown` (q-values are honoured), or append `.md` to the path if
+your client cannot set the header. Responses carry `Vary: Accept`, a client that
+will accept neither `text/html` nor `text/markdown` gets a `406` listing what is
+available, and a path that does not exist answers a real `404` — never a `200`
+carrying a sign-in page.
+
+## Versioning and deprecation
+
+Every route lives under `/v1`, and that segment is part of the address you call. A change that would break you arrives as a new segment beside it, never as a change to this one. Additive changes do land in `/v1` — a new response field, a new optional parameter, a new error code — so ignore what you do not recognize.
+
+Every response carries `Ablo-Version`, a date stamp for the contract being served. A route being withdrawn says so on itself for at least 180 days first: `Deprecation` (RFC 9745) carries when the deprecation took effect and the route keeps answering; `Sunset` (RFC 8594) carries when it stops. The same operations are marked `deprecated: true` in `/openapi.json`.
+
+Responses also carry `RateLimit-Policy` (the standing allowance, e.g. `"secret";q=600;w=12`) and, once your request is attributed to a key, `RateLimit` (what is left and when it refills). A 429 adds `Retry-After` in whole seconds. Pace against these rather than retrying blind.
+
 ## Surfaces: pick by who is calling
 
 Every surface reaches the same coordinated state. They are not interchangeable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.56.0",
+  "version": "0.57.0",
   "description": "The public Ablo SDK for coordinated reads, commits, claims, observation, and reactive applications.",
   "license": "Apache-2.0",
   "type": "module",
@@ -139,8 +139,8 @@
     "directory": "packages/ablo"
   },
   "dependencies": {
-    "@abloatai/humans": "^0.56.0",
-    "@abloatai/transaction": "^0.56.0",
+    "@abloatai/humans": "^0.57.0",
+    "@abloatai/transaction": "^0.57.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {