@abloatai/ablo 0.37.0 → 0.38.0

package/AGENTS.md

@@ -13,10 +13,10 @@ Don't hand-write the integration. Run the CLI; it generates the current-API sche
 - **Auth:** set `ABLO_API_KEY` in the environment. Do **NOT** run `ablo login` — it opens a browser device flow and blocks an agent.
 - **Connect your database — logical replication (the primary path):** `npx ablo connect` prints the setup SQL (`wal_level=logical`, a publication, a `REPLICATION` role); `npx ablo connect register` registers the source with Ablo in one step. Ablo **consumes your Postgres' logical-replication stream** — it never runs DDL on, writes to, owns, or migrates your database, and your application keeps the write path. Registration **is** the enable; there is no tier or flag to pick. (Ablo hosts only the transaction log + coordination, never your rows.)
 - **Fallback — signed Data Source endpoint** (DB can't grant a `REPLICATION` role): the generated `ablo/data-source.ts` exposes one route; Ablo sends signed requests and your app touches its own DB. **Only in this mode** does `npx ablo migrate` provision the adapter's bookkeeping tables (`ablo_outbox`, `ablo_idempotency`) plus your Ablo models — it does **not** touch your other tables. Keep your own migrations (drizzle-kit / prisma migrate) for auth and anything outside the Ablo schema.
-- **No database yet?** A sandbox `sk_test` key holds throwaway **test data** (Stripe-test-mode style) so you can try Ablo before connecting your own Postgres. Test-mode only — in production every row lives in your database.
+- **No database yet?** Run `npx ablo dev --no-watch --branch <name>` to create an isolated non-root branch and obtain its expiring `sk_test_` credential. The branch uses a throwaway hosted data plane; Production remains the protected root. There is no shared Sandbox mode.
 - **Adopt an existing DB schema:** `npx ablo pull prisma [path]` / `pull drizzle <module>` (lossless) or `pull` (live DB, lossy). Writes `ablo/schema.ts`.
-- **Push your schema — REQUIRED before any write works.** The server keeps its OWN copy of the schema. After you create or edit `ablo/schema.ts`, run `npx ablo push` (one-shot) — or `npx ablo dev --no-watch`. **Skip this and every write to a new or changed model fails with `server_execute_unknown_model`.** (Plain `ablo dev` watches forever — never run it bare in an agent.)
-- **Other long-running:** `npx ablo logs --no-follow` (default tails forever). `npx ablo mode test|live` ALWAYS pass the argument. `status`, `push`, `pull`, `check`, `generate`, `docs` are one-shot — safe as-is.
+- **Prepare a branch and push your schema — REQUIRED before any write works.** The server keeps its OWN copy of the schema. After you create or edit `ablo/schema.ts`, run `npx ablo dev --no-watch --branch <git-or-ci-ref>`: it ensures an isolated branch, mints a temporary branch credential, writes it to gitignored `.env.local`, pushes once, and exits. **Skip this and every write to a new or changed model fails with `server_execute_unknown_model`.** Plain `ablo dev` watches forever — never run it bare in an agent. `ablo push` is the lower-level one-shot command for an already selected key, including reviewed production deploys.
+- **Other long-running:** `npx ablo logs --no-follow` (default tails forever). `status`, `branch check`, `push`, `pull`, `check`, `generate`, `docs`, and `dev --no-watch` are one-shot.
 
 When you use the signed-endpoint fallback, the generated `ablo/data-source.ts` is the whole endpoint and needs no hand-editing: `dataSourceNext({ schema, apiKey, adapter: prismaDataSource(prisma, schema) })` (or `drizzleDataSource(db, schema)`). The adapter owns commit / idempotency / outbox.
 

package/CHANGELOG.md

@@ -1,96 +1,166 @@
 # Changelog
 
+## 0.38.0
+
+### Branch-isolated development
+
+Ablo branches replace the former shared Sandbox mode. Every project has a
+protected Production root and can have multiple isolated development, preview,
+test, or long-lived branches. Credentials are bound to immutable branch
+identities, so changing a slug or request parameter cannot redirect a write.
+
+`npx ablo dev` now discovers the current Git or CI branch, ensures the matching
+Ablo branch, mints an expiring branch credential, writes it to the gitignored
+local environment, pushes the schema, and watches for changes. Use
+`npx ablo dev --no-watch --branch <name>` for a one-shot agent or CI setup.
+
+The CLI also provides `ablo branch list`, `create`, `ensure`, `status`, `check`,
+`credential`, and `delete`. The public HTTP and OpenAPI contracts expose the
+same lifecycle for other languages and deployment systems.
+
+This release removes the CLI mode switch and the dashboard Sandbox surface.
+Production remains the protected root; a development credential cannot select
+another branch or gain production authority.
+
+Source adapters and PostgreSQL footprint helpers now select immutable branches.
+If you construct `FootprintPlane` or `SourceRequestContext`, replace
+`environment`, `mode`, and `sandboxId` with `branchId`.
+
+### Temporal and Inngest integration guides
+
+New runnable examples and documentation show how Temporal and Inngest
+workflows use Ablo without introducing another authority path. Temporal
+activities and Inngest steps create the Ablo client, perform authoritative
+reads, acquire claims for long-running work, and submit idempotent writes
+through the same transaction API as every other caller.
+
+The integrations keep each product in its proper role: Temporal and Inngest
+own durable execution, scheduling, retries, and workflow history; Ablo owns
+shared-data authority, claims, conflicts, idempotency, settlement, and ordered
+observation. Workflow code does not open WebSockets or hold live client state.
+
+### Database adapter foundation, starting with PostgreSQL
+
+Customer-database adapters now declare their database, ORM binding, and
+observation strategy as separate axes. The existing Prisma, Drizzle, and Kysely
+integrations are accurately identified as PostgreSQL bindings using either a
+transactional outbox or PostgreSQL WAL.
+
+All built-in adapters are constructed through one validating factory and the
+shared conformance suite checks that the three axes are present. Impossible
+capability combinations fail during adapter construction instead of silently
+advertising guarantees the database path cannot provide.
+
+PostgreSQL is the first database profile on this axis. The contract leaves room
+for additional databases without pretending their transaction, observation,
+and change-capture guarantees are interchangeable with PostgreSQL.
+
+### Generated language SDK foundation
+
+The HTTP API is now explicitly treated as Ablo's language-neutral product
+boundary. Its OpenAPI artifact follows the current Ablo version and every
+operation has a stable, unique name suitable for deterministic Python and Go
+generation.
+
+The OpenAPI generator and drift check are restored as repository and CI gates.
+Future language clients will generate their transport, wire models, and error
+decoding from this contract, retaining handwritten code only for thin
+language-idiomatic resource and claim façades.
+
+The artifact now names shared claim, receipt, cursor, page, and error schemas;
+references the canonical error envelope from every operation; publishes typed
+pagination parameters and explicit union discriminators; and normalizes Zod's
+JSON Schema output to the portable subset accepted by the Python and Go
+generator candidates. CI also validates the rendered OpenAPI 3.1 document with
+an independent, pinned Redocly CLI.
+
+### AI SDK tools over the transaction API
+
+`@abloatai/ablo/ai-sdk` now exposes small tool adapters for authoritative
+reads, idempotent creates, concurrency-safe updates, and claimed deletes. These
+helpers use the caller's existing typed Ablo model resource; they do not add an
+agent runtime or a second transport.
+
+The public surface follows the model verbs directly: `readTool`, `createTool`,
+`updateTool`, and `deleteTool`. AI SDK metadata and approval policy pass through
+to each tool, destructive tools require approval by default, and cancellation
+stops queued claim acquisition.
+
+This deliberately replaces the previously published `coordinatedTool` naming:
+use `updateTool`, `UpdateToolModel`, `UpdateToolOptions`, `UpdateToolResult`,
+`UpdateStrategy`, and the `status` result field. The former
+`coordinatedTool`, `CoordinatedModel`, `CoordinatedToolOptions`,
+`CoordinatedWriteResult`, and `CoordinationStrategy` exports are removed rather
+than retained as legacy aliases.
+
+Queued tool writes now use Ablo's server-owned FIFO claim queue rather than
+recreating coordination with client-side polling.
+
+Internal job dispatch, concrete worker tools, prompts, sandboxes, and model
+selection remain application concerns and are not part of the public Ablo
+agent surface.
+
+## 0.37.1
+
+### A clearer introduction to Ablo
+
+The package README now explains Ablo from the problem outward: humans already
+coordinate shared work by seeing who is active, agreeing on ownership, waiting,
+and looking again before continuing; Ablo gives agents those same practical
+capabilities in software.
+
+It also makes the headless product explicit. The TypeScript SDK is backed by a
+pure HTTP transaction API, so agents, services, jobs, command-line tools, and
+interactive applications can use the same coordination model without requiring
+a browser or reactive client.
+
+### Lower overhead on busy write paths
+
+Large create batches now return only the inserted identifiers needed for
+idempotency handling instead of sending every inserted column back to the
+server. Live clients also bypass reconciliation work when a publication frame
+contains one change per entity.
+
+These changes reduce server response volume and client materialization work.
+There are no public API changes in 0.37.1.
+
 ## 0.37.0
 
-### Minor Changes
-
-- f60ed16: Harden browser authentication around one typed credential endpoint contract,
-  full-plane persistence isolation, awaited terminal cleanup, actual credential
-  expiry, and least-privilege human sessions.
-
-  Human session minting now requires a non-empty schema-typed `can` grant. It
-  accepts concrete model operations and has no all-data wildcard. Browser
-  credentials remain short-lived, refreshable, and isolated from long-lived
-  server secrets.
-
-  Endpoint URLs move from `apiKey` to `authEndpoint`. The canonical session and
-  capability mint routes are `/v1/ephemeral_keys` and `/v1/capabilities`; legacy
-  route aliases are removed.
-
-  Credential providers now use the `CredentialProvider` type. The former
-  `ApiKeySetter` export is removed.
-
-- 16cc7d1: Claims are field-granular. The `path` and `range` claim targets are removed, and
-  a claim narrows to a whole field or set of fields and no finer. Two agents on the
-  same row proceed concurrently when they hold different fields, and serialize when
-  they share one.
-
-  This is a breaking removal (the `path` and `range` claim options, the
-  `TargetRange` type, and sub-field conflict semantics are gone) and a deliberate
-  one. A claim must not promise finer exclusion than the write path can deliver,
-  and the smallest thing a write addresses is a whole field: nothing writes part of
-  a value. `path`/`range` let two writers hold disjoint spans of one field and told
-  them it was safe, which it is not until concurrent edits to one field can be
-  reconciled (operational transformation). Until that lands, field is the floor;
-  when it lands, sub-field targets return, working.
-
-  If you narrowed a claim by `path` or `range`, claim the field the position lives
-  in instead: `fields: ['content']`. To describe a sub-field region to peers for
-  display, put it in `meta` — that promises nothing about exclusion.
-
-- 08a3cad: Launch the branded Ablo package as the single package application developers
-  install. The root serves headless HTTP callers, while `/client` and `/react`
-  serve WebSocket-backed reactive applications.
-
-  The public surface now provides:
-
-  - `@abloatai/ablo` for agents, services, workers, jobs, and backend code;
-  - `@abloatai/ablo/client` for live local state;
-  - `@abloatai/ablo/react` for React bindings;
-  - branded schema, source-adapter, server, authorization, coordination, and wire
-    subpaths; and
-  - `/source/next`, `/source/drizzle`, `/source/kysely`, and
-    `/source/conformance` for Data Source integrations.
-
-  Authoritative reads use `model.get({ id })`; reactive snapshots use
-  `model.local.get(id)`.
-
-  Ablo is now presented as the transaction and coordination API for state
-  operated by humans, services, tools, and AI agents. Realtime synchronization
-  remains available as a client capability rather than defining the product.
-  Live applications no longer accept HTTP transport configuration, and the old
-  sync-engine package and compatibility paths are removed.
-
-  The public repository preserves the workspace structure used for development
-  instead of flattening sources into a generated package. The branded banner,
-  documentation, examples, license, notices, and release automation remain part
-  of the repository.
-
-  The new package pages direct application developers to the branded Ablo
-  entrypoints while still documenting where integration authors can find the
-  lower-level transaction and interactive-client contracts.
-
-- f60ed16: Improve confirmed commit throughput and live-client materialization without
-  weakening atomic writes, ordered observation, audit delivery, or replay.
-
-  The certified AWS benchmark sustained more than 10,000 committed operations per
-  second for homogeneous creates, mixed creates, updates, and deletes with zero
-  write errors and sub-second publication drain. The result covers the documented
-  single-plane, 12-client, 500-operation benchmark topology rather than claiming
-  universal production capacity.
-
-  Live clients now defer reactive model activation until state reaches a
-  consumer-visible boundary and keep cache eviction work bounded under sustained
-  ingestion. Optimistic state and actively observed models remain immediately
-  reactive.
-
-### Patch Changes
-
-- Updated dependencies [f60ed16]
-- Updated dependencies [16cc7d1]
-- Updated dependencies [08a3cad]
-- Updated dependencies [f60ed16]
-  - @abloatai/transaction@0.37.0
-  - @abloatai/humans@0.37.0
-
-Release notes are generated from the repository changesets.
+### One Ablo SDK for humans, agents, and backend systems
+
+Ablo is now presented and shipped as the transaction and coordination layer for
+shared application state—not only as a realtime synchronization library.
+
+Install `@abloatai/ablo` as the single public SDK:
+
+- `@abloatai/ablo` provides the pure HTTP path for agents, services, workers,
+  jobs, server actions, and other headless runtimes.
+- `@abloatai/ablo/client` adds live local state, optimistic interaction,
+  persistence, and presence for human-facing applications.
+- `@abloatai/ablo/react` provides the React bindings.
+
+Every entrypoint uses the same schema, capabilities, commits, claims,
+idempotency, settlement, and ordered changes. Authoritative reads use
+`model.get({ id })`; local reactive snapshots use `model.local.get(id)`.
+
+### Coordination now matches the unit applications can safely write
+
+Claims can coordinate an entire row or a typed set of fields. Two actors
+working on different fields of the same row can proceed concurrently, while
+overlapping work takes turns.
+
+Sub-field `path` and `range` claims have been removed because the write path
+cannot yet guarantee independent updates within one field. Applications using
+those options should claim the containing field instead and keep any
+cursor/range information in claim metadata for display.
+
+### Safer authority for browser applications
+
+Browser sessions now use one typed, short-lived credential flow and require a
+non-empty schema-typed `can` grant. Applications specify the exact model
+operations a session may perform instead of issuing ambient all-data access.
+
+Use `authEndpoint` for the browser credential endpoint. The supported routes
+are `/v1/ephemeral_keys` and `/v1/capabilities`; the former `apiKey` endpoint
+option and legacy route aliases are removed. Credential callbacks now use the
+`CredentialProvider` type.

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <strong>Transaction and coordination infrastructure for humans, agents, and backend systems.</strong>
+  <strong>The transaction layer for AI agents.</strong>
 </p>
 
 <p align="center">
@@ -22,45 +22,110 @@
 
 ---
 
-Install the public SDK:
+Safely coordinate AI agents, humans, workflows, and services writing to the
+same database.
+
+Ablo is an authoritative transaction layer for shared application state. Every
+write goes through one typed API where authority, idempotency, conflicts,
+ordering, and confirmation can be enforced. Your Postgres remains the source
+of truth.
+
+## Why Ablo
+
+Software used to have one writer: a human clicking through an application. AI
+applications now have humans, agents, workflows, and services acting
+concurrently. Databases keep transactions consistent. They do not coordinate
+autonomous work that reads now, reasons for thirty seconds, and writes later.
+
+Humans handle this naturally. We see that somebody is editing, agree on who
+takes which part, wait our turn, and look again before continuing. Ablo gives
+software actors those same capabilities: bounded authority, shared ownership,
+fresh context, safe handoffs, and an attributed record of what happened.
+
+## Start
 
 ```sh
 npm install @abloatai/ablo
+npx ablo init
+npx ablo dev
 ```
 
-Use the root package for headless agents, services, jobs, and backend code:
+`ablo dev` prepares an isolated Ablo branch for your Git branch, writes its
+temporary credential to gitignored `.env.local`, pushes the schema, and watches
+for changes.
+
+Read and write through the transaction layer:
 
 ```ts
-import { Ablo } from '@abloatai/ablo';
+const order = await ablo.orders.get({ id: orderId });
 
-const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+if (!order) throw new Error('Order not found');
 await ablo.orders.update({
-  id: orderId,
+  id: order.id,
   data: { status: 'approved' },
+  wait: 'confirmed',
 });
 ```
 
-Use the client entrypoint for a WebSocket-backed reactive application:
+`confirmed` means the authoritative database reported the change back. The
+same commit can be retried safely if the caller loses its connection.
+
+When work takes thirty seconds instead of one request, coordinate before the
+agent starts reasoning:
 
 ```ts
-import { Ablo } from '@abloatai/ablo/client';
+await using claim = await ablo.orders.claim({ id: orderId });
+
+const priced = await pricingAgent(claim.data);
 
-const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
-await ablo.ready();
+await ablo.orders.update({
+  id: claim.data.id,
+  data: { total: priced.total, status: 'repriced' },
+  claim,
+  wait: 'confirmed',
+});
 ```
 
-React bindings are available from `@abloatai/ablo/react`.
+Another actor touching the same work waits fairly and receives fresh state when
+its turn begins. If the agent fails, the claim releases automatically. If its
+context became stale, the write is rejected instead of silently overwriting
+work it never saw.
 
-The repository keeps implementation ownership explicit:
+If you use AI SDK, expose the same operation as a typed model tool:
 
-```text
-packages/ablo         branded SDK users install
-packages/transaction  HTTP, contracts, commits, claims, settlement, observation
-packages/humans       WebSocket, local materialization, presence, MobX, React
-packages/agent        agent behavior and perception
-packages/cli          project and operational tooling
+```ts
+import { updateTool } from '@abloatai/ablo/ai-sdk';
+
+const approveOrder = updateTool(ablo.orders, {
+  description: 'Approve an order after reviewing it.',
+  inputSchema: z.object({ orderId: z.string() }),
+  id: ({ orderId }) => orderId,
+  apply: () => ({ status: 'approved' }),
+});
 ```
 
-Realtime synchronization is a consumer of the transaction layer, not a second
-authority path. Humans, agents, and backend services use the same commit,
-idempotency, claim, fencing, settlement, and ordered-observation contracts.
+Ablo supplies `readTool`, `createTool`, `updateTool`, and `deleteTool` over the
+same authoritative resources. AI SDK keeps ownership of the model loop and tool
+execution.
+
+Use `@abloatai/ablo` for agents and backend code,
+`@abloatai/ablo/client` for live applications, and
+`@abloatai/ablo/react` for React. All entrypoints share the same schema,
+authority, commits, claims, and ordered changes.
+
+Read the [Quickstart](https://docs.abloatai.com/quickstart), browse
+[docs.abloatai.com](https://docs.abloatai.com), or run `npx ablo docs`.
+
+## Contributing
+
+Ablo is free and open source. You can help by
+[opening an issue](https://github.com/Abloatai/ablo/issues),
+[suggesting a feature](https://github.com/Abloatai/ablo/issues/new), or
+[contributing code](https://github.com/Abloatai/ablo/pulls).
+
+Please report vulnerabilities privately through
+[GitHub Security Advisories](https://github.com/Abloatai/ablo/security/advisories/new).
+
+## License
+
+Apache License 2.0. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).

package/dist/ai-sdk.d.ts

@@ -0,0 +1,2 @@
+export * from '@abloatai/transaction/ai-sdk';
+//# sourceMappingURL=ai-sdk.d.ts.map

package/dist/ai-sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-sdk.d.ts","sourceRoot":"","sources":["../src/ai-sdk.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC"}

package/dist/ai-sdk.js

@@ -0,0 +1,2 @@
+export * from '@abloatai/transaction/ai-sdk';
+//# sourceMappingURL=ai-sdk.js.map

package/dist/ai-sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-sdk.js","sourceRoot":"","sources":["../src/ai-sdk.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC"}

package/docs/agents.md

@@ -6,7 +6,7 @@ An agent is a **reactive** participant: it wakes on something happening, reads
 what it needs, writes a result, and goes idle. That's a request/response
 workload — so agents talk to Ablo over **plain HTTP**, holding no WebSocket. The
 credential *is* the identity; the server resolves the org, scope, and actor from
-the key on every request (the Stripe server-SDK / Liveblocks-node shape).
+the key on every request.
 
 Agents get the stateless plane (HTTP). People — when you add the `humans()`
 plugin — get the live plane (WebSocket: presence, optimistic, sub-100ms).
@@ -31,7 +31,7 @@ import { schema } from "./schema";
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: "http" });
 
 // Reads + writes, fully typed off your schema.
-// `retrieve` resolves to the row, or `undefined` when none matches.
+// `get` resolves to the row, or `undefined` when none matches.
 const open = await ablo.tasks.list({ where: { status: "todo" } });
 
 const task = await ablo.tasks.get({ id: open[0].id });
@@ -41,11 +41,57 @@ console.log(task.title);
 await ablo.tasks.update({ id: task.id, data: { status: "done" } });
 ```
 
-It exposes `retrieve` / `list` / `create` / `update` / `delete`, plus `commits`
-and `claim`. It does **not** expose the stateful-only surface (`get` /
-`local` reads, `onChange` live subscription) — those need a
-live connection, so with `transport: 'http'` the return type narrows and they
-are a *compile error*, not a runtime surprise.
+It exposes `get` / `list` / `create` / `update` / `delete`, plus `commits`
+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.
+
+## AI SDK tools
+
+Keep AI SDK in charge of the model loop and expose only the Ablo operations the
+model needs:
+
+```ts
+import { generateText } from 'ai';
+import {
+  createTool,
+  deleteTool,
+  readTool,
+  updateTool,
+} from '@abloatai/ablo/ai-sdk';
+
+const tools = {
+  getTask: readTool(ablo.tasks, {
+    description: 'Read the current task.',
+    inputSchema: z.object({ taskId: z.string() }),
+    id: ({ taskId }) => taskId,
+  }),
+  createTask: createTool(ablo.tasks, {
+    description: 'Create a task.',
+    inputSchema: z.object({ requestId: z.string(), title: z.string() }),
+    id: ({ requestId }) => requestId,
+    data: ({ title }) => ({ title, status: 'todo' }),
+  }),
+  updateTask: updateTool(ablo.tasks, {
+    description: 'Update a task without overwriting concurrent work.',
+    inputSchema: z.object({ taskId: z.string(), status: z.string() }),
+    id: ({ taskId }) => taskId,
+    apply: (_current, { status }) => ({ status }),
+  }),
+  deleteTask: deleteTool(ablo.tasks, {
+    description: 'Delete a task after taking its claim.',
+    inputSchema: z.object({ taskId: z.string() }),
+    id: ({ taskId }) => taskId,
+    // Destructive tools require AI SDK approval by default.
+  }),
+};
+
+await generateText({ model, messages, tools });
+```
+
+These are adapters over the same typed resources used by ordinary backend
+code. Ablo does not own the planner, prompt system, memory, provider, worker,
+or workflow runtime.
 
 ## Coordination: claim, queue, reorder
 
@@ -59,7 +105,11 @@ clobber the same record.
 await using claim = await ablo.tasks.claim({ id: taskId });
 const task = claim.data;
 // …no one else can hold this row while you work…
-await ablo.tasks.update({ id: task.id, data: { status: "in_review" } });
+await ablo.tasks.update({
+  id: task.id,
+  data: { status: "in_review" },
+  claim,
+});
 
 await ablo.tasks.claim.state({ id: taskId });   // who holds it now (or null)
 await ablo.tasks.claim.queue({ id: taskId });   // the FIFO wait-line behind the holder
@@ -111,5 +161,5 @@ agents costs nothing on the live plane — that capacity stays for humans.
 `onChange` (live subscriptions) and the `local` reads (local synced-pool
 reads) require a WebSocket and a local store — they're for interactive UIs, not
 stateless agents. An agent reacts to an external trigger (a job/queue/webhook),
-then reads with `list`/`retrieve`. See [client behavior](/client-behavior) for
+then reads with `list`/`get`. See [client behavior](/client-behavior) for
 the full surface and [guarantees](/guarantees) for the coordination semantics.