@abloatai/ablo 0.35.0 → 0.37.0

package/docs/api.md

@@ -13,10 +13,10 @@ row, you can optionally `claim` it so they serialize instead of clobbering
 each other.
 
 Two things to know before the method list. **Reads come in two flavors:**
-`retrieve({ id })` / `list({ where })` are async — they answer from what is
+`get({ id })` / `list({ where })` are async — they answer from what is
 already local and fall back to the server. Put `local.` in front of either and
 you get the same read restricted to what is already here, which is why it can
-return a value rather than a promise: `local.retrieve(id)`, `local.list({ where })`,
+return a value rather than a promise: `local.get(id)`, `local.list({ where })`,
 `local.count({ where })`. Use those in render, after data has synced.
 **Claims don't lock.** If another writer holds the row, `claim` waits
 for them, re-reads the fresh row, then hands it to you — so two writers
@@ -38,7 +38,7 @@ const schema = defineSchema({
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
 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('Row not found');
 
 await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' }, wait: 'confirmed' });
@@ -51,24 +51,24 @@ agents, read the [Integration Guide](./integration-guide.md).
 
 Each schema model becomes a typed model on the client:
 
-- `ablo.weatherReports.retrieve({ id })` reads one row asynchronously (server read).
+- `ablo.weatherReports.get({ id })` reads one row asynchronously (server read).
 - `ablo.weatherReports.list({ where })` reads a collection asynchronously (server read).
-- `ablo.weatherReports.local.retrieve(id)` reads one row synchronously from the local graph.
+- `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.
 - `ablo.weatherReports.delete({ id, ...options })` deletes a row.
 
-`local.` narrows a read to what has already synced. `retrieve({ id })` and
+`local.` narrows a read to what has already synced. `get({ id })` and
 `list({ where })` answer from the local graph and fall back to IndexedDB and
 then the network, so reach for them when the row may not be here yet.
-`local.retrieve(id)` and `local.list({ where })` are the same reads with the
+`local.get(id)` and `local.list({ where })` are the same reads with the
 fallback removed — nothing to await, so they return a value.
 
 | Method | Returns | Use when |
 |---|---|---|
-| `retrieve({ id })` | `Promise<T \| undefined>` | You need one row, hydrating from local store and server. |
+| `get({ id })` | `Promise<T \| undefined>` | You need one row, hydrating from local store and server. |
 | `list({ where })` | `Promise<T[]>` | You need to hydrate a collection from local store and server. |
-| `local.retrieve(id)` | `T \| undefined` | You want a synchronous snapshot of one local 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. |
 | `create({ data, ...options })` | `Promise<T>` | You want to create through the schema model. |
@@ -120,49 +120,11 @@ blocks), and `ablo.<model>.claim.release({ id })` releases it early. The full
 coordination surface is `claim.state({ id })` / `claim.queue({ id })` /
 `claim.release({ id })` / `claim.reorder({ id, order })` hanging off `claim`.
 
-### The Claim State Object
-
-| Field | Type | Description |
-|---|---|---|
-| `object` | `'claim'` | String representing the object's type. |
-| `id` | string | Unique identifier for the claim. |
-| `status` | `'active' \| 'queued' \| 'committed' \| 'expired' \| 'canceled'` | The whole lifecycle, in one field. `active` is the holder; `queued` is a waiter in the FIFO line behind it. |
-| `target` | `{ type, id, field? }` | What is being coordinated. |
-| `description` | string | Peer-visible phrase for the work in progress — `'editing'`, `'writing'`, `'reviewing the risk section'`. Defaults to `'editing'`, and rides back in the rejection a blocked writer receives. |
-| `heldBy` | string | Participant id holding the claim. |
-| `participantKind` | `'user' \| 'agent' \| 'system'` | Who's behind it — a human (`user`), an AI (`agent`), or automated infrastructure (`system`). |
-| `createdAt` | number? | Ms-epoch the holder opened it. Optional — derived shapes may omit it. |
-| `expiresAt` | number | Ms-epoch at which the server auto-expires it if the holder doesn't finish. |
-
-```json
-{
-  "object": "claim",
-  "id": "claim_3MtwBwLkdIwHu7ix",
-  "status": "active",
-  "target": { "type": "weatherReports", "id": "report_stockholm", "field": "status" },
-  "description": "editing",
-  "heldBy": "agent:report-writer",
-  "participantKind": "agent",
-  "expiresAt": 1716580000000
-}
-```
-
-### Lifecycle
-
-```
-            claim({ id })              update({ id }) lands
-  (free) ───────────▶ active ───────────────────────▶ committed
-                        │
-            ┌───────────┴───────────┐
-            ▼                       ▼
-        canceled                 expired
-   (release w/o write)        (TTL; holder died)
-```
-
-A target is free when `ablo.<model>.claim.state({ id })` is `null`. Terminal
-states drop out of the live stream, so a present claim is either `active` (the
-holder) or `queued` (waiting in the FIFO line behind the holder; see
-`claim.queue({ id })`).
+The fields on a claim, its lifecycle diagram, and the full method surface are in
+[Coordination](./coordination.md#the-claim-state-object), which is where that
+object is defined. Note that the entity half of `target` is spelled `model`/`id`
+on the SDK's model surface and `type`/`id` on the claim handle and the wait
+line.
 
 ### Reading and claiming
 
@@ -217,7 +179,7 @@ endpoint documents that model's real field contract instead of a generic blob.
 |---|---|
 | `ablo.<model>.create({ data })` | `POST /api/v1/models/{model}` |
 | `ablo.<model>.list({ where })` | `GET /api/v1/models/{model}` |
-| `ablo.<model>.retrieve({ id })` | `GET /api/v1/models/{model}/{id}` |
+| `ablo.<model>.get({ id })` | `GET /api/v1/models/{model}/{id}` |
 | `ablo.<model>.update({ id, data })` | `PATCH /api/v1/models/{model}/{id}` |
 | `ablo.<model>.delete({ id })` | `DELETE /api/v1/models/{model}/{id}` |
 | `ablo.<model>.claim({ id })` | `POST /api/v1/models/{model}/{id}/claim` |

package/docs/audit.md

@@ -23,11 +23,12 @@ with which key — and the chain columns that make the log tamper-evident:
   capabilityId:              string | null,    // the API key/capability used for the write
   capabilityLabel:           string | null,    // its human-readable name, for scanning the log
   delegationChainRootUserId: string | null,    // always points at a human
-  actionType:                string,           // e.g. 'weatherReport.update'
-  modelName:                 string,            // e.g. 'claude-opus-4-8'
+  actionType:                'I' | 'U' | 'D',  // insert, update, delete
+  modelName:                 string,           // the model that changed, e.g. 'orders'
+  modelId:                   string,           // the row that changed
   confirmationState:         'auto' | 'previewed' | 'approved' | 'required_human_approval' | 'auto_historical',
   diffSummary:               unknown,
-  // chain columns — carried on every stored row, checked by verify (below)
+  // chain columns, carried on every stored row and checked by verify (below)
   chainSeq:                  number,
   prevHash:                  string,
   rowHash:                   string,

package/docs/cli.md

@@ -94,18 +94,18 @@ profiles entirely: it acts in whatever project it was minted for.
 
 | Command                            | What it does                                                                                                                                  | Flags                                                                                                  |
 | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `ablo init`                        | Scaffold `ablo/` (`schema.ts`, client, optional Data Source / agent / component), write `.env`, install the SDK. Offers to log in at the end. | —                                                                                                      |
-| `ablo login` / `logout` / `status` | Authentication & status (above).                                                                                                              | —                                                                                                      |
-| `ablo mode [sandbox\|production]`   | Switch active environment.                                                                                                                           | —                                                                                                      |
+| `ablo init`                        | Scaffold `ablo/` (`schema.ts`, client, optional Data Source / agent / component), write `.env`, install the SDK. Offers to log in at the end. |: |
+| `ablo login` / `logout` / `status` | Authentication & status (above).                                                                                                              |: |
+| `ablo mode [sandbox\|production]`   | Switch active environment.                                                                                                                           |: |
 | `ablo projects list\|create\|use\|rename` | Manage projects and the active one (see [Projects](#projects)). Each project's keys/schema/data are isolated.                          | `--name "<display>"` (create/rename)                                                                    |
-| `ablo dev`                         | **Hosted** — push the schema to your test sandbox, then watch `ablo/schema.ts` and re-push on save.                                           | `--no-watch`, `--schema <path>`, `--export <name>`, `--url <url>`                                      |
+| `ablo dev`                         | **Hosted**: push the schema to your test sandbox, then watch `ablo/schema.ts` and re-push on save.                                           | `--no-watch`, `--schema <path>`, `--export <name>`, `--url <url>`                                      |
 | `ablo logs`                        | Tail your scope's commit activity (`stripe logs tail`). Follows by default.                                                                   | `-n, --tail <N>`, `--since <dur\|ts>`, `--model`, `--op`, `--json`, `--no-follow`, `--mode sandbox\|production` |
-| `ablo push`                        | **Hosted** — upload the schema to Ablo; the server diffs, migrates, and activates it.                                                         | `--force`, `--rename old:new`, `--backfill model.field=value`, `--schema`, `--export`, `--url`         |
-| `ablo migrate`                     | **Direct Postgres** — provision just the synced models (plus the adapter's `ablo_outbox` / `ablo_idempotency`) in your own `DATABASE_URL`. Leaves your other tables alone.                                                          | `--dry-run`, `--output <file>`, `--schema`, `--export`                                                 |
-| `ablo pull`                        | **Direct Postgres** — generate `defineSchema(...)` from your existing tables (read-only, like `prisma db pull`).                              | `--out <path>`, `--app-schema <name>`, `--import <pkg>`, `--force`                                     |
-| `ablo check`                       | **Direct Postgres** — verify your _existing_ tables fit the schema (read-only, no schema changes).                                                       | `--schema <path>`, `--export <name>`, `--app-schema <name>`                                            |
+| `ablo push`                        | **Hosted**: upload the schema to Ablo; the server diffs, migrates, and activates it.                                                         | `--force`, `--rename old:new`, `--backfill model.field=value`, `--schema`, `--export`, `--url`         |
+| `ablo migrate`                     | **Direct Postgres**: provision just the synced models (plus the adapter's `ablo_outbox` / `ablo_idempotency`) in your own `DATABASE_URL`. Leaves your other tables alone.                                                          | `--dry-run`, `--output <file>`, `--schema`, `--export`                                                 |
+| `ablo pull`                        | **Direct Postgres**: generate `defineSchema(...)` from your existing tables (read-only, like `prisma db pull`).                              | `--out <path>`, `--app-schema <name>`, `--import <pkg>`, `--force`                                     |
+| `ablo check`                       | **Direct Postgres**: verify your _existing_ tables fit the schema (read-only, no schema changes).                                                       | `--schema <path>`, `--export <name>`, `--app-schema <name>`                                            |
 | `ablo generate`                    | Emit TypeScript types from the schema.                                                                                                        | `--out <path>`, `--schema`, `--export`                                                                 |
-| `ablo docs`                        | Read these pages for the version you installed — offline, no network (see [`ablo docs`](#ablo-docs)).                                          | `--json`                                                                                               |
+| `ablo docs`                        | Read these pages for the version you installed: offline, no network (see [`ablo docs`](#ablo-docs)).                                          | `--json`                                                                                               |
 
 ## `ablo docs`
 
@@ -241,7 +241,7 @@ The one type map, shared by both paths (there is no second mapping):
 | Zod                                                          | Postgres                                                                                                 |
 | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
 | `z.string()`                                                 | `TEXT`                                                                                                   |
-| `z.number()`                                                 | `DOUBLE PRECISION` — never `INTEGER`; a Zod number may be fractional, and truncating is silent data loss |
+| `z.number()`                                                 | `DOUBLE PRECISION`: never `INTEGER`; a Zod number may be fractional, and truncating is silent data loss |
 | `z.boolean()`                                                | `BOOLEAN`                                                                                                |
 | `z.date()`                                                   | `TIMESTAMPTZ`                                                                                            |
 | `z.enum([...])`                                              | `TEXT` + a `CHECK (col IN (...))` constraint                                                             |
@@ -296,7 +296,7 @@ migration can't leave clients gated against tables that don't match.
 
 | Variable                              | Purpose                                                                  | Default                    |
 | ------------------------------------- | ------------------------------------------------------------------------ | -------------------------- |
-| `ABLO_API_KEY`                        | Authenticate without `ablo login` (CI). Always overrides the stored key. | —                          |
+| `ABLO_API_KEY`                        | Authenticate without `ablo login` (CI). Always overrides the stored key. |: |
 | `ABLO_API_URL`                        | Control-plane / API host (`push`, `dev`, `status`).                      | `https://api.abloatai.com` |
 | `ABLO_AUTH_URL`                       | Dashboard origin for `ablo login`'s device flow.                         | `https://abloatai.com`     |
 | `ABLO_CONFIG_DIR` / `XDG_CONFIG_HOME` | Where the credential file lives.                                         | `~/.config/ablo`           |

package/docs/client-behavior.md

@@ -34,7 +34,7 @@ Common options:
 | `baseURL` | Override the hosted sync endpoint for staging or private deployments. |
 | `persistence` | `memory` by default. Use `indexeddb` for a durable browser cache that survives reloads. |
 | `durableWrites` | Optional crash recovery for unacknowledged agent/worker writes. Independent of the default memory cache; accepts `{ store, namespace? }`. |
-| `transport` | `'websocket'` (default) is the live, stateful client — a persistent socket, a local synced pool, and `onChange` subscriptions. `'http'` returns the **stateless** client for server-side actors (agents, workers, serverless): the same `ablo.<model>` read/write/claim surface, but each call is one HTTP round-trip with no socket. Under `'http'` the return type narrows to `AbloHttpClient`, so stateful-only methods (the `local` reads, `onChange`, `join`) are compile errors rather than runtime gaps. |
+| `transport` | `'websocket'` (default) is the live, stateful client: a persistent socket, a local synced pool, and `onChange` subscriptions. `'http'` returns the **stateless** client for server-side actors (agents, workers, serverless): the same `ablo.<model>` read/write/claim surface, but each call is one HTTP round-trip with no socket. Under `'http'` the return type narrows to `AbloHttpClient`, so stateful-only methods (the `local` reads, `onChange`, `join`) are compile errors rather than runtime gaps. |
 | `fetch` | Custom fetch implementation for tests or non-standard runtimes. |
 | `defaultHeaders` | Extra headers attached to every HTTP request. |
 | `defaultQuery` | Extra query parameters attached to every HTTP request. |
@@ -53,8 +53,8 @@ Each schema model becomes a typed model:
 ```ts
 await ablo.ready();
 
-const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
-const local = ablo.weatherReports.local.retrieve('report_stockholm');
+const report = await ablo.weatherReports.get({ id: 'report_stockholm' });
+const local = ablo.weatherReports.local.get('report_stockholm');
 
 await ablo.weatherReports.create({ data: { location: 'Stockholm', status: 'pending' } });
 await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' }, wait: 'confirmed' });
@@ -62,7 +62,7 @@ await ablo.weatherReports.delete({ id: 'report_stockholm', wait: 'confirmed' });
 ```
 
 Call `retrieve`/`list` first — they fetch from the server and you `await` them.
-After that, `local.retrieve`/`local.list`/`local.count` read the already-synced data instantly with
+After that, `local.get`/`local.list`/`local.count` read the already-synced data instantly with
 no `await`, and stay reactive in render. Use the async pair to load, the sync trio
 to read.
 
@@ -79,7 +79,7 @@ through the same model client path. A human Server Action, a browser view, and a
 agent worker can all use `ablo.weatherReports`:
 
 ```ts
-const report = await ablo.weatherReports.retrieve({ id });
+const report = await ablo.weatherReports.get({ id });
 const snap = ablo.snapshot({ weatherReports: id });
 
 await ablo.weatherReports.update({
@@ -93,7 +93,7 @@ await ablo.weatherReports.update({
 
 Once the server accepts the write, every other connected client gets the new row
 automatically — no polling or manual refresh on your side. React clients that use
-`useAblo((ablo) => ablo.weatherReports.local.retrieve(id))` receive the new row, and selectors
+`useAblo((ablo) => ablo.weatherReports.local.get(id))` receive the new row, and selectors
 such as `useAblo((ablo) => ablo.weatherReports.claim.state({ id }))`
 receive active claim state. There is
 no extra multiplayer setup beyond routing shared state through Ablo.
@@ -218,8 +218,8 @@ Only these imports are public SemVer surface:
 - `@abloatai/ablo`
 - `@abloatai/ablo/schema`
 - `@abloatai/ablo/react`
-- `@abloatai/ablo/testing`
 
 `dataSource(...)` is exported from the root package for customer-owned storage
-adapters. Everything outside the four import paths is internal to Ablo-owned
-apps and infrastructure.
+adapters. Everything outside the three import paths is internal to Ablo-owned
+apps and infrastructure. For adapter authors, `@abloatai/ablo/source/conformance`
+is the suite that proves a storage adapter behaves correctly.

package/docs/concurrency-convention.md

@@ -2,9 +2,9 @@
 
 > The governing rule for how Ablo resolves concurrent writes to shared state.
 
-> The governing convention for how Ablo resolves concurrent writes to shared
-> state, and the boundaries of that convention. This is the contract; the
-> three-layer mechanics live in [`coordination.md`](./coordination.md).
+This page is the contract: the `onStale` dispositions, what a conflict is
+checked against, and where the convention stops. The three-layer mechanics of
+claiming live in [Coordination](./coordination.md).
 
 ---
 
@@ -27,8 +27,8 @@ moments in time:
 
 | form | when | mechanism |
 |---|---|---|
-| **Claim** | *prospective* — before you act | reserve the row; others queue. Coordinate so the conflict never forms. |
-| **Notification** | *in-flight* — after a concurrent change | surface the changed value; the actor resolves and re-issues. |
+| **Claim** | *prospective*: before you act | reserve the row; others queue. Coordinate so the conflict never forms. |
+| **Notification** | *in-flight*: after a concurrent change | surface the changed value; the actor resolves and re-issues. |
 
 Use a claim when you will hold the row across a slow read→reason→write gap. Use a
 notification when you didn't, and the premise moved under you.
@@ -42,9 +42,9 @@ when it goes stale. Three modes, split by whether they **force** an outcome:
 
 | mode | coercive? | what the engine does | who resolves | use when |
 |---|---|---|---|---|
-| `notify` | **No** — surface + delegate | Holds the write (does **not** apply it); returns a `StaleNotification` with the current value. | The actor (agent or human) reconciles and re-issues. | The aligned mode: tell the actor what changed, let it solve. |
-| `reject` | **Yes** — force-abort | Throws `AbloStaleContextError`; the batch is discarded. | The caller retries from scratch. | Hard invariants; legacy/strict callers. The current default. |
-| `overwrite` | **Yes** — force-clobber | Overwrites blindly last-writer-wins; **no** signal. | Nobody. | You genuinely own the field and concurrent values are noise. |
+| `notify` | **No**: surface + delegate | Holds the write (does **not** apply it); returns a `StaleNotification` with the current value. | The actor (agent or human) reconciles and re-issues. | The aligned mode: tell the actor what changed, let it solve. |
+| `reject` | **Yes**: force-abort | Throws `AbloStaleContextError`; the batch is discarded. | The caller retries from scratch. | Hard invariants; legacy/strict callers. The current default. |
+| `overwrite` | **Yes**: force-clobber | Overwrites blindly last-writer-wins; **no** signal. | Nobody. | You genuinely own the field and concurrent values are noise. |
 
 > `notify` is the convention. `reject` and `overwrite` are escape hatches for the
 > two ends — "never let this be wrong" and "never bother me." They are not the
@@ -82,9 +82,9 @@ reads: [
 ]
 ```
 
-- **Row** — did this specific row (optionally these fields) change? The literal
+- **Row:** did this specific row (optionally these fields) change? The literal
   per-object premise.
-- **Group** — did *anything* in this sync group change? `group` is a sync-group
+- **Group:** did *anything* in this sync group change? `group` is a sync-group
   key (`workspace:abc`, `document:s1`, `org:X`) — the same unit a participant **watches
   and claims**. This is the more Ablo-native granularity.
 
@@ -108,13 +108,13 @@ Shape (canonical in `coordination/schema.ts`):
 
 | field | meaning |
 |---|---|
-| `object` | Stripe-style type tag — `'stale_notification'` |
+| `object` | Stripe-style type tag: `'stale_notification'` |
 | `model`, `id` | the conflicting row (for a group dep, both are the group key) |
 | `group?` | set when this is a group-scoped notification |
 | `readAt` | the watermark the committer reasoned against |
-| `observedSyncId` | the newest delta on the premise — re-read at/after this |
+| `observedSyncId` | the newest delta on the premise: re-read at/after this |
 | `conflictingFields` | fields that moved (empty for group / whole-entity) |
-| `currentValues` | the live values of those fields — the premise to reconcile against (empty for group) |
+| `currentValues` | the live values of those fields: the premise to reconcile against (empty for group) |
 | `writtenBy` | `{ kind, id }` of the concurrent author, reported faithfully |
 
 Only `notify` produces a notification (the write was held). `reject` throws and
@@ -169,7 +169,7 @@ What the convention **guarantees**, and where it **stops**:
    or human) owns the resolution. The engine does not distinguish them — it is
    actor-neutral by design.
 
-2. **Truthfulness.** `currentValues` / `observedSyncId` reflect committed state at
+2. **Truthfulness:** `currentValues` / `observedSyncId` reflect committed state at
    detection time, inside the same transaction as the write. A notification is
    never speculative.
 
@@ -185,13 +185,11 @@ What the convention **guarantees**, and where it **stops**:
    so they must not be gated by `notify`.
 
 5. **Defaults.** A plain write (no `readAt`) is last-writer-wins with **no**
-   check. A guarded write with `readAt` but no `onStale` defaults to `reject`
-   (back-compat). *Open decision (§7).*
+   check. A guarded write with `readAt` but no `onStale` defaults to `reject`.
 
 6. **Policy seam.** Custom `ConflictPolicy` functions see **write-target**
    conflicts (`stale_context` / `claim_held`). **Batch-premise** conflicts are
-   currently resolved directly via each entry's `onStale`, not through the policy
-   seam. *Open decision (§7).*
+   resolved directly via each entry's `onStale`, not through the policy seam.
 
 7. **Claims win when held.** A non-holder writing to a claimed row is rejected
    (`AbloClaimedError`) regardless of `readAt` — the prospective form takes
@@ -200,29 +198,17 @@ What the convention **guarantees**, and where it **stops**:
 
 ---
 
-## 7. Open decisions (bounded, not yet made)
+## 7. What this convention does not cover
 
-These are deliberately left open; they change behavior and are the user's call.
+Three limits worth knowing before you rely on it.
 
-- **Default disposition for agents.** Should an agent-participant guarded write
-  default to `notify` (philosophy-aligned: surface, don't overwrite) instead of
-  `reject` (back-compat)? Trade-off: alignment vs. a behavior change for existing
-  agent callers.
-- **Batch premises through the policy seam.** Should premise conflicts also
-  pass through `ConflictPolicy` (requires a group-aware conflict shape), or stay
-  on the direct `onStale` mapping?
-
----
-
-## 8. Out of scope
-
-- Irreversible external side-effects (§6.4) — not gated by this convention.
-- Cross-object *serializability proof*. A batch premise is a sound check, not
-  a full precedence-graph guarantee; it catches only what the caller declared.
-  A caller that declares nothing gets **no check at all** — not write-target
-  checking, which needs a `readAt` to check against. A plain write is
-  last-writer-wins, as §6.5 says. The floor is zero, and closing that gap is the
-  subject of ADR 0018.
-- Identity → participant-kind mapping. `writtenBy.kind` reports whatever
-  authenticated (an `sk_` key resolves to `system`, not `agent`); how identities
-  map to kinds is a separate concern.
+- **Irreversible external side-effects.** Emails, payments, and third-party
+  calls are not gated by this convention (§6.4). The engine cannot hold or undo
+  them, so never place one behind `notify`.
+- **A caller that declares nothing gets no check.** The batch premise catches
+  only what you declared. Write-target checking needs a `readAt` to compare
+  against, so a plain write with neither is last-writer-wins (§6.5). What you
+  declare is what is protected.
+- **`writtenBy.kind` reports what authenticated, not what you meant.** An `sk_`
+  key resolves to `system`, not `agent`. How identities map to participant kinds
+  is a separate concern from this convention.