@abloatai/ablo 0.35.0 → 0.37.0

package/docs/identity.md

@@ -24,9 +24,9 @@ that.
 A **sync group** is a named channel of shared state — a string like
 `org:acme` or `workspace:abc123`. It is simultaneously:
 
-- **the unit of fan-out** — a confirmed write to a row publishes a delta to
+- **the unit of fan-out:** a confirmed write to a row publishes a delta to
   every participant subscribed to that row's sync group(s), and
-- **the unit of access** — a participant receives a row's deltas *only if* the
+- **the unit of access:** a participant receives a row's deltas *only if* the
   row's sync group is in their allowed set.
 
 There is no built-in `org` / `team` / `user` concept in the engine. Those are
@@ -101,16 +101,16 @@ const ablo = Ablo({ schema, apiKey: session.token });
 
 That's the whole surface. The rest of this doc is the *why* behind each line.
 
-## Two kinds of group — the whole mental model
+## Two kinds of group: the whole mental model
 
 You just saw a human get `org` / `team` groups and an agent get one `workspace`
 group. That split is the model. Every sync group is named after one of two
 things:
 
-- **Membership groups** — named after *who you are*: `org:{id}`, `team:{id}`,
+- **Membership groups:** named after *who you are*: `org:{id}`, `team:{id}`,
   `user:{id}`. Produced from **identity** (`identityRoles`, Half 1). They're
   standing and durable — they don't change as you work.
-- **Entity groups** — named after *a thing*: `dataroom:{id}`, `workspace:{id}`,
+- **Entity groups:** named after *a thing*: `dataroom:{id}`, `workspace:{id}`,
   `document:{id}`. Produced from a **row's id** (a model's entity scope, Half 2).
   They're granular — one per record — and any participant can be pointed at a
   specific set of them.
@@ -122,8 +122,8 @@ they are, so you declare them once in the schema.
 
 | | Subscribed by | Declared where | Gets |
 | --- | --- | --- | --- |
-| **Human** | *who they are* — membership | **the schema** (`identityRoles`) — a rule, written once | every `org` / `team` / `user` group their identity implies — their whole standing world |
-| **Agent** | *what it's been given* — entities | **code, at the spawn site** — chosen per run | a handful of entity groups: the dataroom it's in, the documents it has read — never beyond what its user's membership could reach |
+| **Human** | *who they are*: membership | **the schema** (`identityRoles`): a rule, written once | every `org` / `team` / `user` group their identity implies: their whole standing world |
+| **Agent** | *what it's been given*: entities | **code, at the spawn site**: chosen per run | a handful of entity groups: the dataroom it's in, the documents it has read: never beyond what its user's membership could reach |
 
 > **One line:** humans subscribe by who they are; agents subscribe by what
 > they've been given.
@@ -180,6 +180,7 @@ await mintUserSessionKey({
     organizationId: schemaOwnerOrgId,
     projectId: schemaProjectId,
   },
+  operations: ['task.read', 'task.update'],
   ttlSeconds: 3600,
 });
 ```
@@ -197,7 +198,7 @@ Scoping is two declarations that meet in the middle. One describes the
 (which group does this row belong to?). A participant sees a row **iff** the
 row's sync group is in the participant's allowed set.
 
-### Half 1 — `identityRoles`: identity → allowed groups
+### Half 1 (`identityRoles`): identity → allowed groups
 
 Declared once, on the schema, via the `identityRole({ kind, source })` factory.
 Each role is **pure data**: a `kind` (the group's prefix — `org`, `user`, `team`)
@@ -238,7 +239,7 @@ in-process and on a hosted server that only ever sees the compiled JSON.
 > `user:{id}` role above already covers it — see
 > [Agents are participants too](#agents-are-participants-too).
 
-### Half 2 — per-model scope: row → group
+### Half 2 (per-model scope): row → group
 
 You never write a sync-group string for a row. You declare a model's *place* in
 the entity graph and the engine derives the groups its rows fan out on. Three
@@ -308,9 +309,9 @@ exposed the whole table cross-tenant, so `validate_schema` rejects the removed
 options as `tenancy-option-removed` errors and steers you to `policy: { by:
 'parent' }` (FK inheritance) or, for genuinely global reference data, the
 explicit `policy: { by: 'none' }`. See
-`packages/sync-engine/src/schema/model.ts` for the full option set.
+`packages/transaction/src/schema/model.ts` for the full option set.
 
-## How identity reaches Ablo — the proxy model
+## How identity reaches Ablo: the proxy model
 
 This is the part the README's "authenticates with the signed-in user's
 session" glossed over. Concretely:
@@ -400,9 +401,9 @@ What carries identity — and just as importantly, what does *not* set the bound
 
 | Where        | Purpose                                                                                          |
 | ------------ | ------------------------------------------------------------------------------------------------ |
-| `userId` prop | App-level participant id, used for app-owned fields and read by your `identityRole` `source`. **Not** the security boundary — the server enforces scope from the authenticated request. |
+| `userId` prop | App-level participant id, used for app-owned fields and read by your `identityRole` `source`. **Not** the security boundary: the server enforces scope from the authenticated request. |
 | `teamIds` (on the client) | Team ids expanded into team sync groups via your `identityRoles`.                   |
-| `syncGroups` (at session mint) | Optional. **Narrows** a minted session's subscription to a subset of what auth already allows — it can never widen it. Passed to `sessions.create({ user \| agent, syncGroups })`; build entries with `syncGroup(kind, id)`. Use it to scope an agent (or a focused page's session) to one entity, e.g. `[syncGroup('workspace', 'abc123')]`. |
+| `syncGroups` (at session mint) | Optional. **Narrows** a minted session's subscription to a subset of what auth already allows: it can never widen it. Passed to `sessions.create({ user \| agent, syncGroups })`; build entries with `syncGroup(kind, id)`. Use it to scope an agent (or a focused page's session) to one entity, e.g. `[syncGroup('workspace', 'abc123')]`. |
 
 Because the server is the boundary, a client that changes `userId` to another
 user's id does not gain their data — the server resolves and enforces the real
@@ -431,7 +432,7 @@ agent authority = (triggering user's allowed set)    ← ceiling, inherited (on-
 ```
 
 Concretely: each model an agent edits declares a `scope`
-([Half 2](#half-2--per-model-scope-row--group)), so each row forms its own
+([Half 2](#half-2-per-model-scope-row--group)), so each row forms its own
 group. The agent subscribes only to the groups for the rows it touches. Declare
 an entity anchor on the models an agent operates on:
 
@@ -475,22 +476,21 @@ not *what's reachable*.
 Three rules make agent access safe, and they fall out of the model above rather
 than needing a separate agent permission system:
 
-- **Inherit the user, and no more** — the OAuth
+- **Inherit the user, and no more:** the OAuth
   [on-behalf-of](https://workos.com/blog/oauth-on-behalf-of-ai-agents) model: the
   agent's reach is tied to the consenting user, never the org.
-- **Least privilege, just-in-time** — scoped to the task's entities, not standing
+- **Least privilege, just-in-time:** scoped to the task's entities, not standing
   org-wide access (the over-privilege pattern
   [OWASP's NHI Top 10](https://www.token.security/assets/the-ultimate-non-human-identity-security-guide)
   flags as the dominant agent risk).
-- **Dual-principal attribution** — record both the executing agent and the
+- **Dual-principal attribution:** record both the executing agent and the
   triggering human.
 
 Identity is 1:1 with a human participant; authority is narrowed to the work. That
 split is what lets Ablo keep *one model API for every actor* without ever
 granting an agent standing access to everything its user can see. The agent that
-runs the [Coordinating long agent work](../README.md#coordinating-long-agent-work)
-`claim` loop is, to the scoping layer, that same participant — scoped to the row
-it claimed.
+runs the [Coordination](./coordination.md) `claim` loop is, to the scoping layer,
+that same participant — scoped to the row it claimed.
 
 ## Narrowing to specific entities
 
@@ -530,7 +530,7 @@ an agent pointed at the entities it's working on. You **never hand-write**
 
 > **`groups.root` is the schema model option, not a client setting.**
 > `groups: { root: 'workspace' }` in `model(...)` declares a scope root
-> ([Half 2](#half-2--per-model-scope-row--group)) — it names the group
+> ([Half 2](#half-2-per-model-scope-row--group)) — it names the group
 > (`workspace:<id>`) that the mechanisms above then subscribe to.
 > There is no `Ablo({ scope })` constructor option. The lifecycle filter on
 > [`list()`](./api.md#model-methods) is a separate axis named **`state`**
@@ -543,7 +543,7 @@ an agent pointed at the entities it's working on. You **never hand-write**
 > can't reach a workspace its capability doesn't already permit, no matter what it
 > passes. Smaller bootstrap, less fan-out, same server-enforced boundary.
 
-## How this compares — and the best practices it follows
+## How this compares, and the best practices it follows
 
 Ablo's identity model is not novel; it's the convergent answer every serious
 realtime / sync SDK arrived at. Knowing which industry pattern it *is* tells you
@@ -551,7 +551,7 @@ how to reason about it.
 
 **Realtime authorization splits into two shapes.** Ablo is firmly in the first:
 
-- **Server derives scope from authenticated identity** — the server decides what
+- **Server derives scope from authenticated identity:** the server decides what
   a participant may read/write and the client cannot override it. This is Ablo's
   proxy model. It's the same shape as
   [Supabase Realtime's RLS-on-connect](https://supabase.com/docs/guides/realtime/authorization)
@@ -560,7 +560,7 @@ how to reason about it.
   checks the permissions for you" — recommended for production), and
   [ElectricSQL **proxy auth**](https://electric-sql.com/docs/guides/auth) (a
   reverse-proxy sets shape params server-side before forwarding).
-- **Client proposes, server authorizes the exact request** — the client names
+- **Client proposes, server authorizes the exact request:** the client names
   the room/shape and the server signs off, as in
   [Pusher's channel authorization endpoint](https://pusher.com/docs/channels/server_api/authorizing-users/),
   [ElectricSQL **gatekeeper auth**](https://github.com/electric-sql/electric/blob/main/examples/gatekeeper-auth/README.md),

package/docs/index.md

@@ -1,6 +1,6 @@
 # Ablo Docs
 
-> The agentic coordination layer: one API for AI agents, apps, and services to claim, change, and confirm the same rows.
+> Collaboration infrastructure for AI agents: one API for agents, apps, and services to claim, change, and confirm the same rows.
 
 Two agents reach for the same row. One claims it, does slow work — an LLM call,
 a fetch, a chain of tools — and commits. The second is neither rejected nor
@@ -110,12 +110,12 @@ Every surface reaches the same coordinated state. Pick by who is calling.
 
 | Surface | Use it for |
 |---|---|
-| **SDK** — `@abloatai/ablo`, `transport: 'http'` | The agents themselves. Stateless, request/response, nothing held open. The main path. |
-| **Coordination MCP** — `@abloatai/mcp` | An agent living inside an MCP host that needs claim and commit as tools. A data plane. |
-| **`humans()`** — with `@abloatai/ablo/react` | The interfaces a person watches agent work arrive in: presence, live queries, a local copy. |
-| **CLI** — `ablo` | Scaffolding, schema push, connecting a database. Terminals and CI. |
-| **REST** — `/api/v1` | Runtimes with no SDK. |
-| **Integration-helper MCP** — hosted `/api/mcp` | Teaching a coding assistant the SDK while you build. Docs, lint, and scaffolds only. |
+| **SDK**: `@abloatai/ablo`, `transport: 'http'` | The agents themselves. Stateless, request/response, nothing held open. The main path. |
+| **Coordination MCP**: `@abloatai/mcp` | An agent living inside an MCP host that needs claim and commit as tools. A data plane. |
+| **`humans()`**: with `@abloatai/ablo/react` | The interfaces a person watches agent work arrive in: presence, live queries, a local copy. |
+| **CLI**: `ablo` | Scaffolding, schema push, connecting a database. Terminals and CI. |
+| **REST**: `/api/v1` | Runtimes with no SDK. |
+| **Integration-helper MCP**: hosted `/api/mcp` | Teaching a coding assistant the SDK while you build. Docs, lint, and scaffolds only. |
 
 The two MCP servers are not interchangeable. The coordination server changes
 your data; the integration-helper server serves documentation and has no
@@ -136,6 +136,7 @@ default caller, not a special one.
 
 ## Concepts
 
+- [How Ablo Works](./how-it-works.md) — the mental model in one page: you write through Ablo, it lands in your Postgres, the write-ahead log confirms it. **Read this first.**
 - [Coordination](./coordination.md) — `claim`, `claim.state`, and `claim.queue`: who holds a row, and who is waiting.
 - [Concurrency Convention](./concurrency-convention.md) — the governing rule for how concurrent writes resolve.
 - [Guarantees](./guarantees.md) — what a confirmed write, a stale-write rejection, and a claim each promise.
@@ -144,7 +145,6 @@ default caller, not a special one.
 - [Agents](./agents.md) — the stateless participant: wake, read, claim, commit, idle.
 - [Agent Messaging](./agent-messaging.md) — durable handoffs between agents, linked to the claim they discuss.
 - [Identity & Sync Groups](./identity.md) — who is connecting, and which slice of state they see.
-- [Interaction Model](./interaction-model.md) — the schema, claim, update, confirmation loop.
 - [Change Propagation](./groups.md) — how one row's change reaches the actors that depend on it.
 - [Client Behavior](./client-behavior.md) — options, errors, retries, timeouts, and imports.
 

package/docs/integration-guide.md

@@ -11,7 +11,7 @@ backend and a database, one model at a time.
 
 Three things hold no matter which actor is writing:
 
-- **One model API for every actor.** `ablo.<model>.update(...)` is what
+- **One model API for every actor:** `ablo.<model>.update(...)` is what
   React components, server actions, background workers, and AI agents
   all call. No separate "agent SDK," no parallel mutation path. The
   attribution comes from the credential, not the call site.
@@ -30,6 +30,7 @@ The normal integration is one client:
 
 ```ts
 import Ablo from '@abloatai/ablo';
+import { credentialEndpointSuccessSchema } from '@abloatai/ablo/auth';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 ```
 
@@ -158,7 +159,7 @@ For rows that don't carry `organization_id` themselves but inherit tenancy via a
 foreign key, set `policy: { by: 'parent', fk: '<fk>', parent: '<parentTable>' }`.
 For genuinely global/reference data, `policy: { by: 'none' }`. ⚠ `by: 'none'`
 exposes the whole table cross-tenant, so it's an explicit, named branch — never a
-falsy flag. See `packages/sync-engine/src/schema/model.ts` for the full option set.
+falsy flag. See `packages/transaction/src/schema/model.ts` for the full option set.
 
 ## 2. Create The Client
 
@@ -220,8 +221,18 @@ const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
 export async function POST() {
   const session = await auth(); // your own auth — returns the signed-in user
-  const { token } = await sync.sessions.create({ user: { id: session.userId } });
-  return Response.json({ token });
+  const { token, expiresAt } = await sync.sessions.create({
+    user: { id: session.userId },
+    can: { tasks: ['read', 'update'] },
+  });
+  return Response.json(
+    credentialEndpointSuccessSchema.parse({
+      token,
+      expiresAt,
+      credentialKind: 'ephemeral',
+    }),
+    { headers: { 'Cache-Control': 'no-store' } },
+  );
 }
 ```
 
@@ -255,8 +266,8 @@ refreshes before expiry.
 ## 3. Read State
 
 Reads come in two flavors, and you pick based on whether you can wait.
-`retrieve({ id })` and `list({ where })` hit the server (and hydrate the local
-store) — they're async, so you `await` them. `get(id)` (positional),
+`get({ id })` and `list({ where })` hit the server (and hydrate the local
+store) — they're async, so you `await` them. `local.get(id)`,
 `local.list({ where })`, and `local.count({ where })` read the already-synced local
 graph synchronously, so they're the ones you call in render — and the ones you
 use inside a `useAblo` selector, never the async `retrieve`/`list`.
@@ -267,15 +278,15 @@ and waits.
 ```ts
 await ablo.ready();
 
-const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
+const report = await ablo.weatherReports.get({ id: 'report_stockholm' });
 if (!report) throw new Error('report not found');
 ```
 
-Use `local.retrieve`, `local.list`, and `local.count` for synchronous local-graph reads after
+Use `local.get`, `local.list`, and `local.count` for synchronous local-graph reads after
 data has synced.
 
 ```ts
-const report = ablo.weatherReports.local.retrieve('report_stockholm');
+const report = ablo.weatherReports.local.get('report_stockholm');
 const activeReports = ablo.weatherReports.local.list({
   where: { projectId: 'proj_123' },
   filter: (report) => report.status !== 'ready',
@@ -296,7 +307,7 @@ export function ReportRow({
 }: {
   report: { id: string; location: string; status: string };
 }) {
-  const report = useAblo((ablo) => ablo.weatherReports.local.retrieve(serverReport.id)) ?? serverReport;
+  const report = useAblo((ablo) => ablo.weatherReports.local.get(serverReport.id)) ?? serverReport;
   const active = useAblo((ablo) => ablo.weatherReports.claim.state({ id: serverReport.id }));
 
   return <button disabled={Boolean(active) || report.status === 'ready'}>{report.location}</button>;
@@ -351,8 +362,19 @@ server   -> ablo.weatherReports.update(...)
 Ablo coordinates those writes, fans out confirmed deltas, exposes active claims,
 and lets callers reject stale writes with `readAt`.
 
-Direct writes to your own database bypass that stream until your app reports the
-change through Data Source events.
+A write that reaches your database some other way still reaches connected
+clients. A `psql` session, a cron job, an admin tool, a legacy endpoint: Ablo
+tails your write-ahead log, so a change it did not make is picked up and fanned
+out like any other, attributed to the data source rather than to an agent.
+
+What such a write does not get is the coordination. It never entered the commit
+chokepoint, so no claim was checked, no `readAt` was compared, and no idempotency
+key was honoured. It can land on top of a row an agent is holding. Route anything
+that must respect a claim through `ablo.<model>`.
+
+On the [Data Source endpoint fallback](./data-sources.md) there is no replication
+stream to tail, and there the original caveat holds: a direct write stays
+invisible until your app reports it through Data Source events.
 
 ## 6. Existing API Backend
 
@@ -376,7 +398,7 @@ The migration can be gradual:
 
 1. Declare schema for one model, such as `reports`.
 2. Keep existing server loads for first paint.
-3. Add `useAblo((ablo) => ablo.weatherReports.local.retrieve(id)) ?? serverReport` for live rows.
+3. Add `useAblo((ablo) => ablo.weatherReports.local.get(id)) ?? serverReport` for live rows.
 4. Add one Data Source endpoint that calls the existing service layer.
 5. Move one mutation button from `fetch('/api/reports/...')` to `ablo.weatherReports.update(...)`.
 6. Add an outbox/events path for writes that still happen outside Ablo.
@@ -505,9 +527,9 @@ them.
 
 | Method                                 | Use it for                                                                       |
 | -------------------------------------- | -------------------------------------------------------------------------------- |
-| `retrieve({ id })`                     | Async read of one row from the server (await it).                                |
+| `get({ id })`                     | Async read of one row from the server (await it).                                |
 | `list({ where })`                      | Async read of many rows from the server (await it).                              |
-| `get(id)`                              | Synchronous local read of one synced row (positional id; use in render).         |
+| `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.                                          |
 | `create({ data, id? })`                | Create through the model client.                                                 |
@@ -517,5 +539,5 @@ them.
 | `claim({ id, description?, ttl? })`    | Acquire a disposable handle: wait for your turn, re-read, and hold the row.       |
 
 Keep first integrations on the model methods above. Every mutation and
-server-read verb takes one options object; only the synchronous `get(id)` stays
+server-read verb takes one options object; the synchronous `local.get(id)` stays
 positional.

package/docs/internal/README.md

@@ -0,0 +1,18 @@
+# Internal Architecture Notes
+
+These documents explain implementation and protocol decisions for contributors.
+They are not extra public import paths.
+
+The ownership rule is:
+
+- transaction owns transport-neutral and HTTP contracts;
+- humans owns reactive state, WebSockets, presence, browser persistence, and React;
+- agent owns agent-specific behavior and perception;
+- the branded `@abloatai/ablo` package maps stable public entrypoints to those
+  owners;
+- `apps/sync-server` owns backend execution.
+
+Consumer code should import `@abloatai/ablo` and its documented subpaths.
+Contributor code should import the narrow owner package or module it actually
+uses. Do not add forwarding compatibility packages or duplicate contract
+definitions.

package/docs/internal/agent-fleet-coordination-design.md

@@ -0,0 +1,171 @@
+# Coordination as Eyes and Ears for Agent Fleets
+
+The design intent behind claims, presence, and stale-context — stated as one
+picture so it can be argued about and built against, not re-derived each time
+someone asks "how do the coordination agents work?"
+
+## The thesis
+
+Humans coordinating in a shared document already have everything they need:
+they *see* each other's cursors, they *hover* to highlight the region they're
+touching, and they *say* what they're doing ("I'm rewriting the intro"). Nobody
+overwrites anybody because everybody has eyes and ears.
+
+Agents don't. They work directly and silently, at machine speed, in fleets — say
+100 agents across 10 groups, each group on its own area of the data. The
+coordination layer's job is to give that fleet the same social awareness a room
+of humans has, expressed as a protocol: **see who is working where, learn what
+they are doing, and take a turn instead of a collision.**
+
+At fleet scale the load-bearing property is that this stays *local*. The layer
+does not lock "the fleet." It coordinates per row. 100 agents over 10
+non-overlapping areas are 100 parallel tracks that only ever meet on the
+handful of rows two agents genuinely both want. Cost is paid at the overlap, not
+across the fleet — which is why adding agents on separate areas adds no
+coordination cost.
+
+## The one principle: two channels, never crossed
+
+Awareness and safety are different channels, and keeping them apart is what makes
+this safe *and* loop-free at machine speed.
+
+- **Safety is pull, at write time.** An agent acts on its best read and its write
+  is rejected if the row moved underneath it. The rejection is the signal, and it
+  only ever fires when an agent actually chooses to write. A pull channel cannot
+  loop — nothing is being pushed.
+- **Awareness is push, and it is the only channel that can storm.** So it is the
+  only channel we coalesce and rate-limit. Hot data that changes every
+  millisecond lives entirely on the safe *pull* side and therefore generates zero
+  awareness traffic — an agent that cares about a fast-ticking value just tries
+  its write and re-reads if it lost, rather than being woken on every tick.
+
+Collapse the two channels — "notify every reader on every change" — and a
+millisecond-ticking field produces read → notify → re-read → act → notify →
+forever. Keeping them separate is the whole reason that loop can't form.
+
+## The six behaviors
+
+### 1. Eyes: see who is working where
+
+Presence broadcasts, live, which agent holds which row. Before an agent commits
+to work, it can see the area is already taken. This is advisory: it informs, it
+forces nothing.
+
+```ts
+const who = ablo.tasks.claim.state({ id: 'task_123' }); // holder or null
+// who.heldBy      === 'agent:forecaster'
+// who.description === 'rewriting the risk section to match Q3'
+```
+
+### 2. Ears: learn *what* they are doing
+
+A claim carries a single `description` — the machine version of the
+hover-highlight plus the spoken "what I'm doing," in one field. It is the
+sentence a peer reads to decide whether to wait, work elsewhere, or move on. It
+defaults to `'editing'` when a claim is taken without one.
+
+```ts
+await using claim = await ablo.tasks.claim({
+  id: 'task_123',
+  description: 'rewriting the risk section to match Q3 numbers',
+});
+```
+
+### 3. Reject *before* the tokens are spent
+
+The claim is a **cheap pre-flight, taken before the generation, not before the
+write.** A human wastes nothing by starting to type into a locked paragraph; an
+agent wastes a whole expensive completion. So the discipline is:
+
+```txt
+claim (cheap)  ->  if granted: generate the block  ->  write
+             \->   if held:    never generate anything
+```
+
+An agent that is told "no" at the claim never produced the write that would have
+lost — the large token spend simply did not happen. This is the single most
+important reason the claim exists before the work, not after it.
+
+### 4. Reject *with* the description, so the blocked agent can decide
+
+A bare "taken" forces a blind retry. The rejection carries the holder's
+`description`, and the SDK renders it into the `AbloClaimedError` message:
+*"Claimed by agent:forecaster: rewriting the risk section to match Q3."* So the
+blocked agent reasons on real information: wait for the turn, go work somewhere
+else, or drop the task because the work is already being done. "No, because
+someone is rewriting the risk section" is actionable in a way "no" is not.
+
+### 5. Queue: take a turn, with an opt-out if the line is long
+
+Contention is a fair FIFO queue: the blocked agent waits its turn and is
+*notified* the moment it arrives (push, not poll — it does not sit and spin).
+When promoted, it re-reads so it works from the latest, with the previous
+holder's change already in place. And the queue has an opt-out: past a depth
+bound, an agent is told the area is too busy and moves on rather than joining a
+long line.
+
+```ts
+await using claim = await ablo.tasks.claim({
+  id: 'task_123',
+  description: '...',
+  maxQueueDepth: 3, // don't join a line deeper than this
+});
+```
+
+### 6. Notify on change: without acting on stale data, without looping
+
+An agent that read a row and is about to act on it is stopped if the row moved
+since the read; it re-reads instead of acting stale. Where a genuine
+notification is wanted, it is **coalesced** (one settled signal, not a stream)
+and **relevance-gated** (only the fields a decision depends on can wake the
+agent). A fast-ticking value never wakes anyone; a rarely-changing value that
+matters can push one settled signal. Same primitive, two behaviors, chosen by
+whether reacting is worth it — see the two-channel principle above.
+
+## The three layers, as a rising scale
+
+The behaviors above compose into three layers of increasing firmness. An agent
+climbs only as high as the situation needs.
+
+| Layer | Kind | What it does | Forces anything? |
+| --- | --- | --- | --- |
+| **Presence** | awareness (push) | Shows who holds what, and why, live. | No: informs only. |
+| **Stale-context** | safety (pull) | Rejects a write built on a read the row has moved past. | Yes: at write time. |
+| **Claim + queue** | reservation (push) | Reserves a row across a slow gap; contenders take turns. | Yes: mutual exclusion. |
+
+Most work is a quick write and needs only the safety layer. An agent reaches for
+a claim only when it will *hold* a row across a slow gap (read → LLM → write) —
+the case where taking a turn beats colliding.
+
+## What's shipped, and the one open point
+
+One piece of the fleet story that once read as future design work is already
+built; one is genuinely still open. Both are called out so neither is misjudged.
+
+1. **Rich work surfaced at reject time — shipped.** A claim carries a single
+   `description` (behavior 2) as a first-class field on the wire. It rides the
+   presence broadcast, comes back inside the rejection's holder summary
+   (`heldByClaim`), and the SDK's `formatClaimedErrorMessage` renders it into the
+   `AbloClaimedError`. So "no" already becomes "no, because someone is rewriting
+   the risk section" (behavior 4) — the piece that prevents the wasteful blind
+   retry works today.
+
+2. **Coalesced, relevance-gated notify — open.** The anti-loop guarantee
+   (behavior 6) depends on the awareness channel being coalesced and gated by
+   relevance, and on hot data staying on the pull side. This is the sharp one,
+   and it is the one not yet built: what exists is the write-time pull guard
+   (`onStale`) and operation-level batching, not a coalesced, relevance-gated
+   *push* on the presence broadcast. Get it wrong and a millisecond-ticking field
+   storms the fleet. The rule to hold: an agent is *rejected at write time* on
+   hot data, never *subscribed-and-woken* by it.
+
+## Related
+
+- [`coordination.md`](../coordination.md) — the public claim/queue/stale-context
+  reference this note motivates.
+- [`agent-orchestration.md`](./agent-orchestration.md) — parent/child agent work
+  modeled through claimed job rows; this note is the coordination substrate under
+  it.
+- ADR 0009 (`docs/decisions/0009-claim-durability-two-reclaim-clocks.md`) — what a
+  claim survives when a holder vanishes, and why liveness can be best-effort while
+  correctness is fenced at commit.

package/docs/internal/agent-orchestration.md

@@ -0,0 +1,58 @@
+# Agent Orchestration
+
+Do not model parent and child agents as directly talking to each other over WebSocket.
+
+Model them as actors coordinating through models:
+
+```txt
+parent creates job -> child claims job -> child commits result -> parent reads result
+```
+
+The WebSocket is delivery infrastructure. The product model is shared state.
+
+## Model Shape
+
+A parent creates a job through its typed model client:
+
+```ts
+const jobId = `forecast:${runId}`;
+await ablo.agentJobs.create({
+  id: jobId,
+  idempotencyKey: `job:${runId}`,
+  data: {
+    status: 'open',
+    kind: 'forecast_report',
+    target: { model: 'weatherReports', id: 'report_stockholm', field: 'forecast' },
+  },
+  wait: 'confirmed',
+});
+```
+
+The child claims the job. If another worker holds it, the claim waits fairly,
+then returns the fresh row:
+
+```ts
+await using claim = await ablo.agentJobs.claim({
+  id: jobId,
+  description: 'complete',
+  ttl: '5m',
+});
+const job = claim.data;
+
+await ablo.agentJobs.update({
+  id: job.id,
+  data: {
+    status: 'completed',
+    result: { text },
+  },
+});
+```
+
+The child commits completion through the normal `update`, which is stale-guarded
+under the held claim. The claim releases when its scope exits.
+
+The parent retrieves the job result by model ID. Later, `ablo.events` can make that reactive, but the state model does not change.
+
+## Rule
+
+Nested agents should create or complete models. They should not require a separate agent-to-agent protocol for normal work.