@abloatai/ablo 0.55.0 → 0.57.0

package/CHANGELOG.md

@@ -1,5 +1,313 @@
 # 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
+
+### 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.
+
+Both reads now take the same cut, from the groups each side already carries.
+
+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
+
+Catch-up measured the plane head, paged the log under the client's own scope, and
+then set the cursor to the last row that scope happened to contain. On a plane
+carrying traffic the client cannot see, that row sits below the head. Where the
+scope held nothing at all, the cursor never moved.
+
+The client half was the mirror image: it reconciled in one direction only and
+could not adopt a head above its own. Together those left a client permanently
+behind, and the catch-up poll turned that into standing load, taking the plane's
+advisory lock every thirty seconds to find the same gap and serve the same
+nothing. The head reads a global sequence, so on any deployment with more than
+one active writer plane this was every client rather than an edge case.
+
+The server now advances to the head it measured, and the client adopts a head
+above its cursor when the response carries no deltas, because an empty response
+is proof rather than a hint.
+
+### A replicated array column arrives as an array
+
+Every array column read through replication arrived one level too deep: `{a,b}`
+as `[["a","b"]]`, and `{}` as `[[]]`. The driver's array parsers expect the
+literal without its leading brace, and given the whole literal they read that
+brace as the start of a nested array. The control plane refused such a value
+outright; a `text[]` column in your own database would have carried it into the
+log silently.
+
+### `ablo doctor` separates two different failures
+
+A plane where nothing routed at all and a plane where some changes did not have
+different causes, so they no longer read the same:
+
+```
+  ✗ delivery   no change reached anyone (41 in the last hour)
+               → run `ablo check`. When nothing routes, the tenancy value is usually missing for the whole plane rather than for particular rows.
+```
+
+### `LogPosition` is the one name for a position in the log
+
+`DeltaPosition`, `deltaPositionSchema`, `ReadSetWatermark`, and
+`readSetWatermarkSchema` still resolve to it and are removed in 0.57.0. Where a
+position needs an owner, the owner goes in the field name rather than into a
+second type.
+
+`ABLO_DOCS_BASE_URL` and `ABLO_SITE_BASE_URL` are exported for tools that link
+back to the documentation.
+
+### What an organization is, and what your customers are
+
+The customer-organizations guide is rewritten around the distinction it kept
+blurring. An organization is a team account: people join it with their own
+logins, and share what it owns and is billed for. Nobody invites their customers
+into that.
+
+So a platform's customers are not organizations, and they are not projects
+either, since a project is bound one to one to a database schema and an account
+with four applications could no longer say which of the four a customer belonged
+to. They are rows in the platform's own schema, reached by the sync groups on the
+session: the account is ambient and derived from the key, the customer is a plain
+row, and the session is minted against one of them.
+
 ## 0.55.0
 
 ### `ablo doctor` says whether the writes reached anyone

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

@@ -1,71 +1,62 @@
-# Customer Organizations
+# Serving Many Customers
 
-> Serve many customer organizations from one backend and one shared schema without weakening tenant isolation.
+> One account, one schema, and a session scoped to the customer whose data it may read.
 
-An application serving many customers has two independent choices: where
-customer data is isolated and where the schema is authored. Ablo lets every
-customer keep a hard organization boundary while all of them use the schema
-pushed once by the owning project.
+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.
 
-## Choose the customer boundary first
+**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.
 
-| Customer model | Isolation guarantee | Choose it when |
-|---|---|---|
-| One Ablo organization with customer scope roots | Whatever read boundary every model declares in `policy` | Cross-customer reads are intentional, or every model is explicitly and continuously policy-partitioned |
-| One Ablo organization per customer | Structural organization filtering and RLS on every row | Customers must stay isolated even when a model has no customer-specific policy |
-
-Sync-groups decide which changes are delivered. They do not, by themselves,
-authorize HTTP reads. If you cannot audit matching policies across every model,
-use one Ablo organization per customer.
-
-The rest of this guide uses organization-per-customer: one trusted backend
-holds one dedicated mint key, every customer has an `organizationId`, and each
-user session names that customer organization.
-
-## What you need
-
-- An owning project containing the schema every customer uses.
-- The schema pushed to that project's production root.
-- A server-side `sk_` carrying only `organization:act-as`.
-- A customer `organizationId` resolved from your authenticated application
-  membership, never accepted unchecked from the browser.
-- A model-by-model `can` grant for the UI being opened.
-
-The cross-organization key is a minting credential, not a tenant-data
-credential. Keep it in a secret manager and expose only your own authenticated
-session endpoint.
+**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.
 
-## Mint on your backend
-
-Create the Ablo client once in server-only code:
+The rest of this page is the second shape. Read *Where the boundary is enforced*
+before you rely on it.
 
 ```ts
-import Ablo from '@abloatai/ablo';
-import { schema } from '@/ablo/schema';
-
-export const customerSessions = Ablo({
-  schema,
-  apiKey: process.env.ABLO_API_KEY,
-});
+// 1. src/ablo/schema.ts — your customer table is a scope root.
+import { defineSchema, identityRole, relation, model, z } from '@abloatai/ablo/schema';
+
+export const schema = defineSchema(
+  {
+    // Its rows form the group `customer:<id>`; the kind comes from `groups.root`.
+    customers: model(
+      { name: z.string() },
+      { groups: { root: 'customer' } },
+    ),
+    // A child inherits its customer's group through the `parent` edge.
+    decks: model(
+      { customerId: z.string(), title: z.string() },
+      { relations: { customer: relation.belongsTo('customers', 'customerId', { parent: true }) } },
+    ),
+  },
+  {
+    identityRoles: [
+      identityRole({ kind: 'org', source: 'organizationId' }),
+      identityRole({ kind: 'user', source: 'userId' }),
+    ],
+  },
+);
 ```
 
-After your application authenticates the user, resolve the customer from that
-trusted membership and mint the session:
-
 ```ts
+// 2. app/api/ablo-session/route.ts — mint for one customer, on your backend.
+import { syncGroup } from '@abloatai/ablo/schema';
 import { credentialEndpointSuccessSchema } from '@abloatai/ablo/auth';
-import { customerSessions } from '@/ablo/customer-sessions';
+import { ablo } from '@/ablo/server';
 
 export async function POST() {
-  const member = await requireSignedInCustomerMember();
+  const member = await requireSignedInMember();
 
-  const session = await customerSessions.sessions.create({
+  const session = await ablo.sessions.create({
     user: { id: member.userId },
-    organizationId: member.abloOrganizationId,
-    can: {
-      projects: ['read'],
-      records: ['read', 'create', 'update'],
-    },
+    can: { customers: ['read'], decks: ['read', 'create', 'update'] },
+    syncGroups: [syncGroup('customer', member.customerId)],
   });
 
   return Response.json(
@@ -79,137 +70,126 @@ export async function POST() {
 }
 ```
 
-Do not take `organizationId` directly from request JSON. A signed-in user could
-replace it with another customer's id. Derive it from the server-side membership
-you just authenticated.
+That is the whole integration. The rest of this page is why each line is where
+it is.
 
-## Connect the browser
+## What each layer is
 
-The browser knows only your session endpoint. It never receives the
-cross-organization key:
+Four things carry a name in this arrangement, and mixing two of them up is the
+one mistake worth spending a page to prevent.
 
-```tsx
-'use client';
+| Layer | What it is | Where it lives |
+|---|---|---|
+| Your account | The organization you signed up with. Colleagues join it with their own logins and share one bill. | Ablo |
+| Your application | A project. One per app you run, bound to one schema in your database. | Ablo |
+| Your customer | A row in your own table, with your own id on it. | Your database |
+| One person's session | An `ek_` your backend mints, cut to one customer's group. | Minted per sign-in |
 
-import Ablo from '@abloatai/ablo';
-import { AbloProvider } from '@abloatai/ablo/react';
-import { schema } from '@/ablo/schema';
+Your customers sit in the third row. They are not accounts, because an account
+is something you invite colleagues into. They are not projects, because a
+project binds to a Postgres schema and you run one application, not one per
+customer.
 
-const ablo = Ablo({
-  schema,
-  authEndpoint: '/api/ablo-session',
-});
+Your `sk_` already carries your account, so a session never names it. What the
+session adds is which customer the person in front of it may read.
 
-export function Providers({ children }: { children: React.ReactNode }) {
-  return <AbloProvider client={ablo}>{children}</AbloProvider>;
-}
-```
+## Where the boundary is enforced
 
-The client re-mints before expiry. Your endpoint should return
-`session_expired` only when the application's own login is gone; network and
-server failures are transient and must not sign the user out.
+Two mechanisms do different jobs, and the difference is the whole of this page.
 
-## Schema and data stay on different axes
+**Your account is the tenant boundary.** Every row Ablo stores carries your
+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.
 
-For a cross-organization mint, Ablo derives the schema binding from the owning
-key automatically:
+**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:
 
-```text
-owning key organization/project    -> schema shape
-customer organization              -> rows, RLS, database, sync groups
-session can                         -> allowed model operations
-model policy                        -> allowed reads inside that organization
-```
+| 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.
 
-Most applications should not pass a schema option. An explicit override exists for
-migrations or advanced routing:
+## Naming a group
+
+Build a group with the `syncGroup(kind, id)` helper rather than a string. The
+kind is the one you declared in `groups.root`, and the id is your own
+identifier for the customer.
 
 ```ts
-await customerSessions.sessions.create({
-  user: { id: member.userId },
-  organizationId: member.abloOrganizationId,
-  schemaProject: {
-    organizationId: schemaOwnerOrganizationId,
-    projectId: migratingSchemaProjectId,
-  },
-  can: { records: ['read', 'update'] },
-});
+syncGroups: [syncGroup('customer', member.customerId)]
 ```
 
-Both schema coordinates move together; customer data does not move with them.
+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.
 
-## Customer lifecycle checklist
+## When a customer should be its own organization
 
-When onboarding a customer:
+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.
 
-1. Provision or resolve its Ablo organization and store that immutable id on
-   your customer record.
-2. Connect that organization's production data source if it owns a separate
-   database.
-3. Keep the shared schema in the owning project; do not copy it into every
-   customer organization.
-4. Mint a test user session through the same backend route production uses.
-5. Verify one known read and write in the customer organization before enabling
-   the integration.
+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.
 
-When offboarding, stop minting immediately, revoke active sessions when an
-immediate cutoff is required, and retire the customer's data-source access
-through the control-plane process you use for provisioning.
+## Onboarding a customer
 
-## Security checklist
+Insert the row. There is nothing to register with Ablo, because the group is
+derived from the row's id, and the first session minted against it is delivered
+its data.
 
-- Store the cross-organization key only in the backend secret manager.
-- Give it only `organization:act-as`; do not combine minting with schema or
-  data authority.
-- Resolve `organizationId` from authenticated membership server-side.
-- Keep `can` to the smallest model/verb set the UI needs.
-- Use organization-per-customer when a missing model policy must not expose
-  another customer's rows.
-- Rotate the cross-organization key on a schedule and after personnel or
-  infrastructure changes.
-- Record target organization, user, session id, and request id without logging
-  plaintext credentials.
+Add a project only when you add an application. `npx ablo projects create` takes
+a management credential from `ablo login`, and one project holds one schema.
 
 ## Troubleshooting
 
-### The mint is forbidden
-
-The presenting credential must be a secret `sk_` with
-`organization:act-as`. A normal project key can mint users into its own
-organization but cannot name another one. Run `npx ablo whoami --json` in the
-backend environment to confirm which project and branch the configured key
-actually belongs to; the command never prints the full secret.
+### A session reads nothing
 
-### The session mints but bootstrap is empty
+Check the groups the session was minted with against the kind in `groups.root`.
+A group whose kind is not declared matches nothing, which reads as an empty
+database rather than an error.
 
-Confirm that the cross-organization key belongs to the project where the schema
-was pushed, and that the customer's organization has its data source/root
-branch ready. Do not copy the schema into the customer organization. If you
-supplied `schemaProject`, remove it unless you intentionally override the
-owning-key default.
+### A session reads another customer's rows
 
-### The mint reports an unknown model
+Check that the model declares a `parent` edge up to the scope root. A model with
+no group of its own and no parent belongs to no group, so a group cut does not
+narrow it.
 
-Every model named by `can` must exist in the active shared schema. Check the
-model key spelling against the schema used to construct `customerSessions`, then
-push that schema to the key's branch deliberately.
+### The mint is refused
 
-### Data appears under the wrong customer
+Naming `organizationId` reaches into a different account and takes
+`organization:act-as`. A platform serving its own customers names groups
+instead, and its key needs no scope at all.
 
-Inspect the membership-to-`organizationId` lookup in your backend route first.
-The schema project never selects the data tenant. The `organizationId` passed to
-`sessions.create` does, and it must come from trusted server-side membership.
+## See it yourself
 
-### Realtime looks isolated but an HTTP read is too broad
+```
+npx ablo whoami --json
+```
 
-Sync-groups route changes; they are not a read policy. Add or correct the
-model's `policy`, or move customers to separate Ablo organizations when the
-boundary must hold structurally across every model.
+The `syncGroups` it reports are the cut the engine will apply. If a customer's
+group is missing there, no read will show its rows.
 
 ## Related guides
 
-- [Sessions](./sessions.md) — session lifecycle, refresh, revocation, and grants.
-- [API Keys](./api-keys.md) — credential classes, scopes, inspection, and rotation.
-- [Identity & Sync Groups](./identity.md) — participant delivery groups versus model read policy.
-- [Connect Your Database](./data-sources.md) — customer-owned database setup.
-- [Deployment](./deployment.md) — production schema and database rollout order.
+- [Identity & Sync Groups](/identity) — how groups are declared and resolved.
+- [Sessions](/sessions) — session lifetime, refresh, and revocation.
+- [API Keys](/api-keys) — credential classes and scopes.
+- [Projects](/projects) — one project per application.

package/docs/data-sources.md

@@ -355,13 +355,11 @@ Because Ablo checks from its own network, a database your own machine can't reac
 IPv6-only, IP-allowlisted, behind a VPN — still verifies. Re-run it until every
 item is green.
 
-Your **app** holds only the API key — never a connection string:
+Your **app** holds only the API key, never a connection string:
 
 ```bash
-# .env — server runtime only, never the browser
+# .env, server runtime only, never the browser
 ABLO_API_KEY=sk_...
-ABLO_PROJECT_ID=proj_...
-ABLO_BRANCH_ID=br_...
 ```
 
 ```ts
@@ -371,17 +369,17 @@ import { schema } from './ablo/schema';
 export const ablo = Ablo({
   schema,
   apiKey: process.env.ABLO_API_KEY,
-  projectId: process.env.ABLO_PROJECT_ID,
-  branchId: process.env.ABLO_BRANCH_ID,
 });
 ```
 
-`ABLO_PROJECT_ID` and `ABLO_BRANCH_ID` are safety assertions, not routing inputs.
-The API key still selects the project and branch; during `ready()` Ablo asks the
-server what the key actually targets and refuses startup when either coordinate
-differs. `ablo dev` writes all three values together, so accidentally exporting
-a entries key into the mail app—or a mail development key into production—fails
-before any read, write, or subscription begins.
+The key names its own project and branch, so there is nothing else to configure.
+
+If you want a process to refuse a key you did not expect, pin `projectId` or
+`branchId` (they default to `ABLO_PROJECT_ID` and `ABLO_BRANCH_ID`). Both are
+assertions, never routing inputs: during `ready()` Ablo asks the server what the
+key actually targets and refuses to start when a coordinate differs. That is
+worth setting where one deployment can be handed keys for more than one
+environment, and worth leaving out everywhere else.
 
 The Ablo schema describes **only your synced, collaborative models** — the rows
 Ablo coordinates and fans out in realtime. It is _not_ your whole-database schema

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.55.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",
@@ -120,6 +120,8 @@
     "lint:pricing": "tsx scripts/check-pricing-docs.mts",
     "generate:openapi": "tsx --conditions=@ablo/source scripts/generate-openapi.mts",
     "lint:openapi": "tsx --conditions=@ablo/source scripts/generate-openapi.mts --check",
+    "generate:discovery": "tsx --conditions=@ablo/source scripts/generate-discovery-docs.mts",
+    "lint:discovery": "tsx --conditions=@ablo/source scripts/generate-discovery-docs.mts --check",
     "validate:openapi": "redocly lint ../../docs/ablo/public/openapi.json --extends=recommended --skip-rule=no-server-example.com",
     "build:docs": "node scripts/build-blume-docs.mjs",
     "lint:docs-site": "node scripts/build-blume-docs.mjs --check",
@@ -137,8 +139,8 @@
     "directory": "packages/ablo"
   },
   "dependencies": {
-    "@abloatai/humans": "^0.55.0",
-    "@abloatai/transaction": "^0.55.0",
+    "@abloatai/humans": "^0.57.0",
+    "@abloatai/transaction": "^0.57.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {