@gemmein/sdk 0.4.7 → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,147 @@
+# Changelog — @gemmein/sdk
+
+All notable changes to the SDK are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+semver. A change that asks something of your app has a note in
+[`migrations/`](./migrations/README.md) naming the version it arrived in
+and the version by which the action is required.
+
+The SDK and the local engine (`@gemmein/cli`) share a minor version from
+0.6.0 / 0.7.0 onward: a feature that lands in one lands in the other in
+the same release.
+
+## [Unreleased]
+
+## [0.6.0] — 2026-09-04
+
+### Changed
+- `list({ limit })` is honoured or refused, never clamped: a `limit`
+  outside 1..100 answers 400 `invalid_limit` ("limit must be between 1 and
+  100"). The default stays 25 and the maximum 100. Apps that asked for more
+  than 100 and read the first page as the whole set now get the refusal —
+  page with `cursor`. See `migrations/list-limit-refusal.md`.
+- `verifyEmailCode` throws `GemmeinError` with code `invalid_response`
+  (status 0) when a 200 answer carries no session token, where it threw a
+  bare `Error` before. Every error the SDK raises is now a `GemmeinError`.
+- `engines.node` is `>=20`. Node 18 reached end of life in April 2025; the
+  SDK is built and tested on 20 and 22.
+
+### Added
+- Relays. One JSON file, `gemmein/relays/<name>.json`: a trigger (a
+  provider's signed webhook at `POST /hooks/<appId>/<name>`, a schedule, or a
+  record change) and one to ten of Gemmein's own verbs (write a record, grant
+  or revoke access, email the person, call your URL), run in order with
+  retries and a replay button in the dashboard. No SDK method: the surface is
+  the file and the dashboard. `REFERENCE.md` carries the definition, the
+  triggers, the actions, the `call_url` contract and its signature header,
+  the templates, the lifecycle and the codes; `llms.txt` carries the
+  GoCardless worked example. A `call_url` that writes back through the SDK
+  fires `data_change` like any write. Stripe stays built in; any provider that
+  signs its webhooks drives access the same way.
+- `GrantSource` gains `relay`: a grant a relay's `grant_access`
+  wrote. `holdings` and `verifySession` list it by kind like the other six;
+  `ManualGrantSource` is unchanged — no key can mint it.
+- `gemmeinServer(...).invitePerson(email)` creates a person by email before
+  they sign in, or returns the one that exists (`{ person, created }`, type
+  `InvitedPerson`). Behind the third key capability, "Create a person by
+  email before they sign in". Refusals: `invalid_email`, `invite_capped`
+  (500 accepted calls per app per day, raised on request). An invited person
+  shows as invited on the person page until their first sign-in and is not
+  counted in the people band (the billable unit) until then.
+- Every request carries `x-client-info: gemmein-sdk/<version>`. The Keys
+  page shows the SDK build behind a key's most recent call ("Last seen
+  from gemmein-sdk/0.6.0, as reported"). `SDK_VERSION` and `CLIENT_INFO`
+  are exported.
+- `CHANGELOG.md` and `migrations/` ship in the package.
+
+## [0.5.0] — 2026-09-03
+
+### Added
+- The server gate on `gemmeinServer(sk)`: `verifySession(token)`,
+  `holdings(personId)`, `grantAccess(personId, { entitlement, reason? })`,
+  `revokeAccess(personId, grantId, { reason? })`. Grant and revoke require
+  the key's `grantAccess` capability (minted on the Keys page).
+- Exported types `Holdings`, `Grant`, `GatePerson`, `GrantSource`,
+  `ManualGrantSource`.
+
+## [0.4.7] — 2026-09-02
+
+### Changed
+- Documentation-only release. The packaged `llms.txt` and `REFERENCE.md`
+  carry the W5 teaching: a promote run carries new fields as well as new
+  collections.
+
+## [0.4.6] — 2026-08-26
+
+### Changed
+- `reaffirm.mjs` runs the 16-probe harness; its teachings are rewritten.
+
+## [0.4.5] — 2026-08-26
+
+### Changed
+- Documentation-only release. `REFERENCE.md` catches up with documents,
+  `since`, `watch()`, `notify()`, the file laws and `purchases.mine()`.
+
+## [0.4.4] — 2026-08-26
+
+### Added
+- `upload(file, { for })` addresses a file to one person; the file-kind
+  (image or document) and file-class teaching.
+
+## [0.4.3] — 2026-08-25
+
+### Added
+- `gemmeinServer(sk).notify(personId, { subject, text, kind?, key? })`.
+
+### Changed
+- `watch()` stops on an auth-terminal answer instead of retrying it.
+
+## [0.4.2] — 2026-08-25
+
+### Added
+- `list({ since })` with `ListResult.deleted` and `ListResult.watermark`;
+  `watch()` on a collection.
+
+## [0.4.1] — 2026-08-22
+
+### Added
+- `GemmeinError.requires` (and `requiresAny`) on 403 `entitlement_required`,
+  on both the collection path and the runtime clients.
+
+## [0.4.0] — 2026-07-30
+
+### Changed
+- A product's file lives on the product card and the purchase is the
+  authorisation to read it.
+
+## [0.3.2] — 2026-07-29
+
+### Fixed
+- The wave-audit fixes for the 0.3 line.
+
+## [0.3.1] — 2026-07-29
+
+### Changed
+- Documentation: the guide teaches paid access.
+
+## [0.3.0] — 2026-07-29
+
+### Added
+- The file reference contract: records store references, files resolve
+  through the SDK.
+
+## [0.2.1] — 2026-07-22
+
+### Changed
+- Documentation-only refresh.
+
+## [0.2.0] — 2026-07-22
+
+### Changed
+- Two-layer shape: `g.collection(name)` plus the self-service primitives.
+
+## [0.1.0] — 2026-07-11
+
+### Added
+- First published release: built `dist`, persistent sessions, journey
+  signposts.

package/REFERENCE.md

@@ -21,10 +21,15 @@ The browser client. `appKey` is your public `pk_...` key. `options` (optional):
 
 ### `gemmeinServer(secretKey, options?) → GemmeinServer`
 Server-only client for a `sk_...` secret key — **never ship this to the
-browser.** Exposes read/update on collections without a signed-in user,
+browser.** `options` (optional): `{ apiUrl?: string }` — **the option is
+`apiUrl`**, not `baseUrl`. An unknown option is ignored silently, so a script
+that passes `baseUrl` to reach a local or staging server quietly talks to
+production instead. Exposes read/update on collections without a signed-in user,
 `notify()` to email one of your app's own verified people (see **Notify**),
-plus `testSession()` for CI self-tests (dev environments only — see
-**Reaffirm**).
+the gate — `verifySession()` / `holdings()` / `grantAccess()` /
+`revokeAccess()` / `invitePerson()`, for code of yours running on your own
+host (see **Server gate**) — plus `testSession()` for CI self-tests (dev
+environments only — see **Reaffirm**).
 
 The client has two layers. **Your app's collections** — `g.collection(name)`
 (the canonical spelling; `g.storage.collection(name)` is the same client). And
@@ -179,7 +184,7 @@ type ListResult<T> = {
 };
 
 type ListOptions = {
-  limit?: number;
+  limit?: number;                    // 25 by default, 100 at most — a larger ask is refused (400 invalid_limit); page with cursor
   sort?: "newest" | "oldest" | "updated";
   where?: Record<string, unknown>;   // exact-match on data fields (and link fields)
   cursor?: string;                   // from a previous ListResult
@@ -233,6 +238,10 @@ Plans are `g.subscriptions`; one-off things are `g.payments`. `checkout` and
 don't also redirect to the returned `url`, and never build a Stripe URL
 yourself. Gate features on `(await g.subscriptions.mine())?.plan === "pro"`;
 gate one-off fulfilment on the receipt record, never the redirect.
+By-hand grants (trial, promotion, a support comp) are not listed to the
+app — a gated read simply succeeds — so never rebuild the paywall from
+`mine()`; let the server refuse with `entitlement_required`. The two grant
+families and what ends each are in llms.txt, "Two FAMILIES of grant".
 
 ---
 
@@ -262,6 +271,298 @@ honestly, not hidden.)
 
 ---
 
+## Server gate — `gemmeinServer(sk).verifySession` / `holdings` / `grantAccess` / `revokeAccess` / `invitePerson`
+
+Gemmein hosts no compute. **Your own** function — Vercel, a VPS, a cron box,
+anywhere — asks Gemmein the only three questions it has: *who is this person,
+what do they hold, change what they hold* — and, when the person has never
+signed in, it can create them by email first.
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `verifySession` | `(token)` | `Promise<{ ok: true, person: { id, email, role }, holdings: Holdings }>` — the browser's session token in, identity **and** holdings out. Needs no capability on the key (the caller already holds the person's token) and never touches the session: no extension, no last-seen |
+| `holdings` | `(personId)` | `Promise<{ ok: true, person: { id, email, role, suspended }, holdings: Holdings }>` — for the paths with no token in hand. A **suspended** person is returned, flagged `suspended: true`, with their holdings; `verifySession` refuses them |
+| `grantAccess` | `(personId, { entitlement, source?, expiresAt?, reason? })` | `Promise<{ ok: true, grant: Grant, holdings: Holdings }>` (201) — `holdings` is the state **after**; the owner's audit row carries before→after and the key's name |
+| `revokeAccess` | `(personId, grantId, { reason? }?)` | `Promise<{ ok: true, grant: Grant, holdings: Holdings }>` — the returned grant carries `revokedAt` |
+| `invitePerson` | `(email)` | `Promise<{ person: InvitedPerson, created: boolean }>` — create a person by email **before they sign in** (201 `created: true`), or find them (200 `created: false`); idempotent, case-insensitive, one id. `InvitedPerson = { id, email, role, invited, suspended }` — `invited` stays true until their first sign-in; a suspended person is returned flagged. The one server call that takes an email |
+
+```ts
+type Holdings = {
+  access: string[]                 // the keys they hold NOW — ["access:pro"]
+  grants: Grant[]                  // the LIVE grants behind them (revoked/expired are gone)
+  credits: { balance: number } | null   // reserved — null today; credits are NOT shipped
+}
+
+type Grant = {
+  id: string
+  entitlement: string              // "access:<slug>" — the plan's or product's own key
+  source: "subscription" | "purchase" | "manual" | "trial" | "promotion" | "migration" | "relay"
+  startsAt: string
+  expiresAt: string | null
+  revokedAt?: string | null        // present on the grant revokeAccess returns
+}
+```
+
+- **Pointing at a non-default server.** `gemmeinServer(sk, { apiUrl })` — the option
+  is **`apiUrl`**. `baseUrl` is not an option name and is ignored in silence, so a
+  test or E2E script that passes it runs against **production** without saying so.
+- **One call per request.** `verifySession` answers identity *and* holdings
+  together — don't call it twice, and don't cache the answer past the request.
+- **Holdings, not billing.** The gate never returns subscription status,
+  amounts, Stripe ids, or a grant's `sourceId` — the source **kind** only
+  (`relay` is the kind a relay's `grant_access` writes; see
+  **Relays**). Gate
+  on what a person *holds*, never on what they pay. Person id, never an email.
+- **Three capabilities, ticked by the human.** `verifySession` needs none.
+  `holdings` needs **"Look up a person's access by id"**; `grantAccess` and
+  `revokeAccess` need **"Grant and revoke access"**; `invitePerson` needs
+  **"Create a person by email before they sign in"** — plain-English checkboxes
+  the owner ticks when minting the key. Existing keys have all three off, so
+  nothing in production changes.
+- **The invite door.** `invitePerson(email)` is how your server addresses
+  someone who has never signed in — the envelope, the invoice, the client
+  portal, the booking-winner email: create the person, hand them the file,
+  address the record, notify them; their first sign-in lands on a ready
+  account. The address is trimmed and lowercased; the person's row shows
+  "Invited · hasn't signed in yet" in the owner's dashboard until they sign
+  in, and is not counted in the people band before then. 500 invite calls per
+  app per day — a fetch of an existing person is a call too.
+- **Manual sources only.** `source` ∈ `manual | trial | promotion | migration`
+  (default `manual`). Purchases and subscriptions come from the built-in Stripe
+  path; a payment from any other provider that signs its webhooks drives access
+  through a relay (source `relay`). A key cannot mint paid access. A key *may* end a payment-made grant (the same as the
+  dashboard's "end this access"); the payment itself is untouched.
+- **One grant, one reason.** `reason` (≤ 200 chars) is what the owner reads in
+  their logs and is never edited. `sourceId` is minted per call, so two calls
+  make two grants — call it once and keep your own retry key.
+- **Nothing silent, within a stated bound.** Every `/server/*` call a **resolved
+  secret key** makes, ok or refused, lands in that key's usage ledger — the owner
+  reads the summary on their Keys page and the full day × route × outcome table in
+  the key's own room. A rejected or publishable (`pk_`) key can't be attributed to a
+  key row, so its refusal reaches only the request log. Refusals also write one audit
+  row per key, route and code each hour (exact counts stay in the ledger); grants and
+  revokes write full before→after rows, attributed to the key by name. A refusal
+  counts as *use*: "last used" means last seen, not last worked. In `gemmein dev` the
+  local key already holds both capabilities, and the usage read is cloud-only — the
+  local runtime never mounts the console.
+
+| code | status | meaning · do |
+|------|--------|--------------|
+| `session_invalid` | 401 | No session matches this token — send the person to sign in again; never store or reuse tokens across people |
+| `session_expired` | 401 | The session ended (the message names when) — send them back to sign-in |
+| `session_revoked` | 401 | A newer sign-in, a sign-out, or the owner ended it — send them back to sign-in |
+| `person_suspended` | 403 | The owner suspended this person — access is off until the owner reactivates them in the dashboard |
+| `person_not_found` | 404 | No person with this id in this app and environment — ids come from `verifySession` or the dashboard, never from an email. Existence is never leaked |
+| `capability_required` | 403 | The key's box isn't ticked — mint a key with "Look up a person's access by id" / "Grant and revoke access" / "Create a person by email before they sign in" ticked (purchase and subscription grants come from the built-in Stripe path; another provider's payment grants through a relay) |
+| `invalid_email` | 400 | `invitePerson`: the address must look like `name@domain` — trimmed, one `@`, a dotted domain, at most 254 characters, no whitespace |
+| `invite_capped` | 429 | `invitePerson`: this app has made 500 invite calls today — the limit is temporary; write to hello@gemmein.com to raise it. `err.resetAt` says when the window ends |
+| `invalid_source` | 400 | `purchase` / `subscription` asked for by hand — refused; those come from Stripe's signed webhook, and another provider's payment grants through a relay |
+| `invalid_entitlement` | 400 | Not a valid `access:<slug>` key — or drop the key and pass the plan's or product's own NAME, which the gate resolves for you |
+| `unknown_plan` | 400 | No plan or product by that name — the owner adds it on the Payments page. (Checkout's `unknown_plan` is a **404**; the gate's is a **400** — it is a bad argument to a write, not a missing resource) |
+| `grant_not_found` | 404 | Not this person's grant, in this app and environment — re-read `holdings` |
+| `already_revoked` | 409 | A grant ends once (`revokedAt` is set and never edited) — it is already ended |
+| `invalid_body` | 400 | One malformed field, whichever it is — `token` (missing, not a string, over 512 chars), `expiresAt` (unparseable or in the past), `reason` (not text, over 200 chars). Branch on the code, read the **message**: it names the field |
+| `scope_denied` | 403 | Not a secret key — the gate is server-only, never the browser |
+| `invalid_id` | 400 | A prototype name (`__proto__`, `constructor`, `prototype`) was sent as a person id or a grant id. Ids come from `verifySession()` or the dashboard — never from a name |
+| `unknown_route` | 404 | Not one of the gate's five routes — the message lists them all |
+| `method_not_allowed` | 405 | The right route, the wrong verb: `verifySession`, `grantAccess`, `revokeAccess` and `invitePerson` are POST, `holdings` is GET |
+
+---
+
+## Relays — `gemmein/relays/<name>.json`
+
+Route, map, authorise, never compute. A relay is one trigger — a
+provider's webhook arriving, a clock, a record changing — and one to ten of
+Gemmein's **own** verbs, run in order: write a record, grant or revoke access,
+email the person, call your URL. Gemmein runs no code of yours inside one;
+compute lives on your host, behind `call_url`. The definition is a JSON file
+your AI writes; the owner's dashboard shows it read-only with its receiver URL,
+its secrets (shown once), every event with each action's result, and a replay
+button. There is no SDK method: the surface is the file and the dashboard.
+Stripe stays built in; any provider that signs its webhooks — GoCardless, Paddle,
+Lemon Squeezy among them — drives access the same way through a relay, and the
+founder keeps their provider. This chapter is the full depth; `llms.txt` carries
+the card, the worked example and one pointer here.
+
+### The definition
+
+```jsonc
+{
+  "name": "gocardless-paid",             // ^[a-z][a-z0-9-]{1,62}$ — the file name AND the receiver URL's last segment
+  "trigger": { ... },                    // exactly one: receiver | schedule | data_change
+  "actions": [ ... ]                     // 1 to 10, run in order
+}
+```
+
+Unknown fields are refused **by name**, one sentence per problem
+(`invalid_definition`). A trigger's `kind` cannot change after creation —
+delete and create instead.
+
+### Triggers
+
+**`receiver`** — `POST /hooks/<appId>/<name>`, provider-agnostic.
+
+```jsonc
+{
+  "kind": "receiver",
+  "verify": { "scheme": "hmac_sha256_header", "header": "Webhook-Signature" },
+  "map": { "event_id": "events.0.id", "event_type": "events.0.action", "person_email": "events.0.details.customer_email" },
+  "when": { "event_type": "confirmed" }
+}
+```
+
+| `verify.scheme` | fields | what is checked |
+|---|---|---|
+| `hmac_sha256_header` | `header`, `timestampHeader?`, `toleranceSeconds?` (default and maximum 300), `encoding?: "hex" \| "base64"` (default hex) | HMAC-SHA256 of the raw body with the receiver secret; when `timestampHeader` is named, of `<timestamp>.<body>` inside the window. GoCardless: header `Webhook-Signature`, hex, raw body |
+| `stripe` | — | the `stripe-signature` header (`t=`/`v1=`), 5-minute window |
+| `svix` | — | `svix-id` / `svix-timestamp` / `svix-signature`, 5-minute window |
+| `shared_token` | `header?` (default `x-webhook-token`), `query?` (default `token`) | the token matches in either place — a query token travels in URLs, prefer the header |
+
+- **Secrets.** Minted by Gemmein at create (`rcv_…`), shown once, never readable
+  again; rotate mints a new one. A provider that only shows its own secret
+  (Stripe, svix senders) is stored through rotate with a `value`.
+- **`map`** — up to 20 names, each a dotted path into the body
+  (`events.0.details.customer_email`; prototype names are never followed).
+  `event_id` is the dedupe key: a repeat answers `{ received: true,
+  duplicate: true, eventId }` and runs nothing; without it the body's hash
+  deduplicates within the same UTC day. `event_type` is what `when` usually
+  reads. `person_email` names the person: created-or-fetched through the same
+  door as `invitePerson` (same daily cap, shown as invited until first sign-in,
+  audited with the relay as the actor). Every other name rides into
+  templates as `{{mapped.<name>}}`.
+- **`when`** — exact string match on the **mapped** fields; its keys must be in
+  the map. A non-match answers 200 `{ received: true, ignored: "when" }` and
+  records no event, so a typo in `when` reads as the provider never calling.
+  Test with a real event first.
+- **Answers.** 200 `{ received: true, eventId }` only once the event row is
+  stored — the row is the acknowledgement.
+
+| code | status | meaning |
+|---|---|---|
+| `unknown_receiver` | 404 | no receiver relay with this name on this app — a deleted one no longer receives, a paused one still does |
+| `bad_signature` | 401 | the signature did not verify against this receiver's secret — check the secret and the header the scheme expects |
+| `body_too_large` | 413 | over 256 KB |
+| `invalid_json` | 400 | the body is not JSON |
+| `receiver_capped` | 429 | more than 120 verified events in a minute for this app; `resetAt` says when. Unverified traffic never spends this budget |
+| `not_recorded` | 503 | the event could not be stored — nothing ran; send it again |
+
+The URL names no environment: the secret decides which environment's
+relay receives, so development and production may share a name, each
+with its own secret. Renaming a relay renames its URL.
+
+**`schedule`** — `{ "kind": "schedule", "every": "1d", "at": "09:00" }`.
+`every` ∈ `15m | 30m | 1h | 6h | 12h | 1d`; `at` is `HH:MM` UTC and only with
+`1d`. One tick per period; a relay created mid-period first fires next
+period; after a gap the most recent missed period runs late and older missed
+periods land as dead rows you can replay. A schedule has no person, so
+`grant_access`, `revoke_access`, `email_person` and `to: "person"` are refused
+on it at validation.
+
+**`data_change`** — `{ "kind": "data_change", "collection": "bookings", "on": ["created"], "where": { "status": "won" } }`.
+`on` ⊆ `created | updated | deleted`; `where` is an exact match on the record's
+data fields (server-managed fields are refused). Fires for writes from your
+app, the dashboard's editor and Stripe receipts, at most once per write per
+relay; never for the runner's own writes (the loop guard) and never for
+an account erasure. A `call_url` that writes back through the SDK does fire —
+a loop through your host is yours to avoid. A definition change applies within
+5 s. The person is the record's owner, else its recipient; an app-owned record
+has none and person actions on it record `skipped`. **Authorisation law:** a
+`where` on a field the signed-in user can write is a self-service grant —
+authorise on fields they cannot set, or from a receiver.
+
+### Actions
+
+| type | fields | notes |
+|---|---|---|
+| `write_record` | `collection`, `data`, `to?: "person"` | keyed per event so a retry never duplicates; written through the same door as your app (plain-text and file laws apply); `to: "person"` addresses it to the event's person and is required on addressed and direct collections; the record is app-owned |
+| `grant_access` | `entitlement` (plan or product **name**, or `access:<slug>`), `expiresAt?` (`"30d"`, `"12h"`, `"2w"` or an ISO date), `reason?` (≤ 200, templated) | source `relay`, the seventh grant source; skipped when this event already granted |
+| `revoke_access` | `entitlement` | ends every live grant of that entitlement the person holds; skipped when none |
+| `email_person` | `subject` (≤ 300), `text` (≤ 10,000), `kind?: "event" \| "account"` | rides `notify()`'s caps (200 per app per hour, 5 event sends per person per day) and the owner's sends switch; deduped per event |
+| `call_url` | `url` | https only, no template in the URL, no IP literal, never a gemmein.com host, no credentials in the URL; `gemmein dev` allows http to localhost |
+
+**The `call_url` contract.** Gemmein POSTs JSON:
+
+```jsonc
+{
+  "id": "<event id>",                       // the same id on every retry and replay
+  "relay": { "id": "...", "name": "gocardless-paid" },
+  "trigger": "receiver",                    // receiver | schedule | data_change
+  "event": { ... },                         // the stored payload: { event, mapped } | { record, previous? } | { tick }
+  "person": { "id": "...", "email": "..." } | null,
+  "results": [ ... ]                        // the actions that ran before this one
+}
+```
+
+Headers: `content-type: application/json`, `user-agent: Gemmein-Relays/1`,
+`X-Gemmein-Signature: t=<unix seconds>,v1=<hex>` where `v1` is the HMAC-SHA256
+of `<t>.<body>` with the relay's signing secret (`asig_…`, shown once at
+create, rotatable). Verify over the raw body, in constant time. 2xx is done; a
+redirect is a failure and is never followed; 10 s timeout; the status and the
+first 4 KB of the answer are kept on the event. **Not idempotent on Gemmein's
+side:** every retry and replay POSTs the same `id` — deduplicate on it. The
+whole event rides in the body, so the URL receives private data.
+
+```js
+import { createHmac, timingSafeEqual } from "node:crypto";
+const [t, v1] = req.headers["x-gemmein-signature"].split(",").map((part) => part.slice(part.indexOf("=") + 1));
+const expected = createHmac("sha256", process.env.GEMMEIN_SIGNING_SECRET).update(`${t}.${rawBody}`).digest("hex");
+const ok = expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
+```
+
+Egress refusals arrive as the action's error, naming the rule: `https_only`,
+`ip_literal`, `own_host`, `unresolvable`, `private_address`.
+
+### Templates
+
+In string values only — `write_record.data`, `email_person.subject` / `text`,
+`grant_access.reason`; never in `call_url.url` or an `entitlement`:
+`{{event.a.b}}` (the raw body), `{{mapped.x}}`, `{{record.data.x}}`,
+`{{record.id}}`, `{{person.email}}`, `{{person.id}}`, `{{tick.periodStart}}`.
+A path that names nothing renders empty and adds a warning to the event;
+objects render as JSON. No expressions, no filters.
+
+### Lifecycle
+
+Every trigger lands as a durable event row **before** any action runs.
+`queued → running → done`, or `failed` with retries at 1m, 5m, 30m, 2h, 8h,
+16h (seven attempts in all), then `dead`: the owner gets the
+`relay_failed` alert (on by default, switchable) and a replay button that
+resets the count. A definition-level failure (a suspended person, a missing
+collection, an unknown entitlement) is dead on the first attempt. Actions stop
+at the first failure; a retry or replay runs every action again, and
+`write_record`, `grant_access`, `revoke_access` and `email_person` each find
+their own earlier work and record `skipped` — `call_url` POSTs again. Events
+are kept 30 days. A paused relay still records receiver events and record
+changes (they wait for resume); schedule ticks during a pause are not
+recorded. Every run is one audit row with per-action before→after; every grant,
+email and record a relay makes is attributed to the relay by name.
+
+### Console codes
+
+| code | status | meaning |
+|---|---|---|
+| `invalid_definition` | 400 | one sentence naming the field, why, and what to do |
+| `relay_capped` | 400 | 20 relays in this environment — delete one, or fold two into one |
+| `name_taken` | 409 | a relay with this name exists in this environment |
+| `version_conflict` | 409 | the definition moved since it was read — re-read and reapply |
+| `not_replayable` | 409 | replay applies to a dead, failed or done event; a queued or running one is already on its way |
+| `unknown_environment` | 400 | the environment does not belong to this app |
+| `not_found` | 404 | no relay or event with this id in this app and environment |
+
+**Current limits:** 20 relays per environment, 10 actions each, 120
+events per minute, 32 KB stored per event (a larger body is truncated with a
+flag; `mapped` survives), events kept 30 days. Limits are raised on request:
+hello@gemmein.com.
+
+**Both rails.** `gemmein dev` runs receivers (the boot card prints each
+receiver's local URL), schedules and data changes with the same runner and
+prints `RELAY · <name> · <trigger> · <n actions> · ok|failed`;
+`npx gemmein sync` carries the files to the cloud app's development
+environment with the collections — contract, never data; the cloud mints its
+own secrets.
+
+---
+
 ## Reaffirm — prove your app's boundaries in CI
 
 Gemmein enforces the rules **server-side**, so your frontend is never the source
@@ -329,7 +630,10 @@ class GemmeinError extends Error {
 }
 ```
 
-Branch on `err.code`. The stable codes:
+Branch on `err.code`. The gate's own codes (`session_invalid`,
+`session_expired`, `session_revoked`, `person_suspended`, `person_not_found`,
+`capability_required`, `invalid_source`, `unknown_plan`, `grant_not_found`,
+`already_revoked`) are in **Server gate** above, each with its action. The rest:
 
 | code | meaning | do |
 |------|---------|-----|
@@ -345,6 +649,7 @@ Branch on `err.code`. The stable codes:
 | `invalid_shape` | field not in a locked (live) collection's shape — or a file field given the wrong kind (the message names which) | after the field exists in development, one promote run adds it (the owner answers blank or a default) — until then send only the fields the shape has / send the kind the field takes |
 | `unknown_file` | a ref-shaped value points at a file that doesn't exist or isn't yours to hand — every rule, every write | fix the ref — never invent one |
 | `invalid_since` | `since` isn't a strict ISO 8601 timestamp, or came with `sort` | pass the previous answer's watermark; drop `sort` |
+| `invalid_limit` | `limit` isn't a whole number from 1 to 100 (the message says so: "limit must be between 1 and 100") | ask for at most 100 and page with `cursor` — nothing is clamped for you |
 | `not_a_customer` (404) | `notify()`'s recipient isn't a verified person of this app and environment | fix the person id — one code on purpose |
 | `in_flight` (409) | a `notify()` with the same `key` is sending right now | retry in a moment — a delivered send answers idempotently |
 | `invalid_audience` | `for` isn't a user of this app | fix the recipient id |
@@ -359,6 +664,7 @@ Branch on `err.code`. The stable codes:
 | `unsupported_file_type` (415) | upload isn't an allowed type | images (JPEG/PNG/WebP/GIF/HEIC) or documents (PDF/ZIP/EPUB) |
 | `invalid_key` | a keyed create's `key` breaks the charset/length law | 1-120 chars of letters, numbers, `: _ . @ / -` |
 | `invalid_secret_key` (client-side) | `gemmeinServer()` got a missing/`pk_` key | pass the `sk_` key from a server env var |
+| `invalid_response` (client-side, status 0) | the server answered 200 to `verifyEmailCode` without a session token — a proxy or mock in the path, not Gemmein | check `apiUrl` and anything rewriting responses; the call is safe to retry |
 | `authentication_required` (401) | checkout/subscription/pay without a signed-in user | sign the user in first |
 | `plan_has_no_link` (409) | the paid plan has no Payment Link pasted yet | ask the owner to paste it in their dashboard |
 | `account_suspended` (403) | the app owner's account is suspended (billing) | the owner fixes payment at app.gemmein.com |