@fabrika/app 0.4.8 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/app",
-	"version": "0.4.8",
+	"version": "0.5.0",
 	"type": "module",
 	"license": "MIT",
 	"repository": {
@@ -93,13 +93,14 @@
 		"test": "bun test --path-ignore-patterns='src/react/**' && bun test --isolate src/react"
 	},
 	"dependencies": {
-		"@fabrika/auth": "0.4.8",
-		"@fabrika/auth-core": "0.4.8",
-		"@fabrika/db": "0.4.8",
-		"@fabrika/jwks": "0.4.8",
-		"@fabrika/platform": "0.4.8",
-		"@fabrika/platform-node": "0.4.8",
-		"@fabrika/proxy-core": "0.4.8",
+		"@fabrika/auth": "0.5.0",
+		"@fabrika/auth-core": "0.5.0",
+		"@fabrika/db": "0.5.0",
+		"@fabrika/email": "0.5.0",
+		"@fabrika/jwks": "0.5.0",
+		"@fabrika/platform": "0.5.0",
+		"@fabrika/platform-node": "0.5.0",
+		"@fabrika/proxy-core": "0.5.0",
 		"jose": "^5.9.0"
 	},
 	"peerDependencies": {

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fabrika-app
-version: 0.4.8
+version: 0.5.0
 description: >
   How to write and change a Fabrika application: src/vocabulary.ts, db/migrations/, src/db/tables.ts, the
   slices' endpoints.ts with their handlers, fabrika.contract.ts, jobs, files, webhooks, share links, connectors
@@ -226,6 +226,7 @@ the access check. `references/spa.md` shows the stack.
 | rows outside its capability    | `unscoped: { <table>: 'read' }` | `ctx.db.unscoped.<table>`                          |
 | another application's export   | `connect: ['<import>']`         | `ctx.connect.<import>`                             |
 | a share link                   | `issues: '<link mount>'`        | `ctx.links.issue`                                  |
+| e-mail (a cron job only)       | `mailer: 'installation'`        | `ctx.mail.send`                                    |
 | a trigger, function or view    | its migration                   | —                                                  |
 
 Scope every scoped table a raw statement reads with `${ctx.sql.scope(<capability>, '<table>', '<alias>')}`, a conjunct
@@ -242,8 +243,11 @@ Which promise the types, the checker, boot, the runtime or the approver keeps, a
 ## Rules
 
 - Data work first, external calls after. The invocation's one transaction rolls back on a throw; IAM, object storage
-  and connector calls do not. An endpoint the generated tests cover calls no outside service (an e-mail, a provider's
-  API): it records an outbox row, and a job sends it (`references/jobs.md`).
+  and connector calls do not. An endpoint the generated tests cover calls no outside service (a provider's API): it
+  records an outbox row, and a job makes the call (`references/jobs.md`).
+- An endpoint never sends e-mail; it has no `ctx.mail`. It records an outbox row and declares `then: '<job>'`, which
+  starts that job once its transaction committed. The job declares `mailer` and sends with `ctx.mail`, under a key
+  derived from the row, and sends again only where `ctx.mail.mayRetry(error)` allows it (`references/jobs.md`).
 - No `as` (except `as const`), `any`, `@ts-ignore`, `@ts-expect-error`, `process.env` or `Bun.env`.
 - Never log an error object, a request, headers or the environment.
 - Never edit a generated file (`src/db/schema.generated.ts`, the generated tests, `fabrika/entry.generated.ts`,
@@ -296,7 +300,7 @@ change an uncommitted migration, migrate into a fresh schema with another `FABRI
 
 `bunx fabrika app dev` serves the application on a loopback port through its test kit, filled by `dev/seed.ts`
 through the endpoints. Pick a persona at `/__fabrika/dev`; the toolbar on every page switches it and lists the mail IAM
-sent. Write the seed and use it as `references/dev.md` says; it never replaces a test.
+and the application's jobs sent. Write the seed and use it as `references/dev.md` says; it never replaces a test.
 
 ## References
 
@@ -306,7 +310,7 @@ their errors, the caller, the components, routing, theming, screen tests), `tabl
 (access forms, which `over`, the caller's scopes, handles, lists and aggregates, `fromRow`, `ctx.sql`, audited CSV
 downloads, members and labels), `tests.md` (generated tests, seeds, `testKit`, a reused scope, a caller's label, confirming a file ran),
 `errors.md` (checker findings, type errors, runtime answers), `dev.md` (the seed and the preview), `jobs.md` (which dimension `ctx.within` names, the UTC
-day), `files.md` and `webhooks-links-connectors.md`, all under `references/`. Two are applications of their own:
+day, e-mail through `ctx.mail`, the outbox and `then`), `files.md` and `webhooks-links-connectors.md`, all under `references/`. Two are applications of their own:
 `start.md`, a new application before its first table (its first test, adding the first table, installing and updating
 this skill), and `public-intake.md`, a public page, a form, a job that issues links and e-mails them, a link holder's
 files, HR's review with its history.
@@ -314,6 +318,8 @@ files, HR's review with its history.
 ## Not built yet
 
 - The data layer runs on Bun and Postgres only (Zerops). On Cloudflare an application has no tables, jobs or files.
-- Jobs are cron only and app-wide: no `ctx.jobs.enqueue`, no job per scope. A list write is off the road (`sql`).
+- Jobs are cron only and app-wide: no `ctx.jobs.enqueue`, no job per scope. A mutation's `then` starts a run of its
+  job; it carries nothing. A list write is off the road (`sql`).
+- `ctx.mail` sends no attachments.
 - An MCP workspace has no shell, so `codegen` and `test-scaffold` cannot run there. Tell the human; never write a
   generated file by hand.

package/skill/references/app-setup.md

@@ -19,20 +19,20 @@ the SPA is added with it.
 		"test": "bun test --isolate"
 	},
 	"dependencies": {
-		"@fabrika/app": "0.4.8",
-		"@fabrika/db": "0.4.8",
-		"@fabrika/provider-zerops": "0.4.8",
-		"@fabrika/proxy-core": "0.4.8",
-		"@fabrika/ui": "0.4.8",
+		"@fabrika/app": "0.5.0",
+		"@fabrika/db": "0.5.0",
+		"@fabrika/provider-zerops": "0.5.0",
+		"@fabrika/proxy-core": "0.5.0",
+		"@fabrika/ui": "0.5.0",
 		"kysely": "0.29.6",
 		"react": "^19.0.0",
 		"react-dom": "^19.0.0",
 		"zod": "^3.25.76"
 	},
 	"devDependencies": {
-		"@fabrika/check": "0.4.8",
-		"@fabrika/cli": "0.4.8",
-		"@fabrika/platform": "0.4.8",
+		"@fabrika/check": "0.5.0",
+		"@fabrika/cli": "0.5.0",
+		"@fabrika/platform": "0.5.0",
 		"@happy-dom/global-registrator": "^20.11.2",
 		"@types/bun": "latest",
 		"@types/react": "^19.0.0",
@@ -158,15 +158,16 @@ export default serve(contract, { database: scoped(tables) })
   per-form limit: raise it, and use the challenge. `references/public-intake.md` builds a whole public intake on it.
 - `then: '<job>'` on `c.form` names a cron job of the same contract (`jobs`), which each accepted submission kicks
   once its row committed: a run starts within seconds, under the job's own key, and the answer stays the same constant
-  and never waits for it. Kicks coalesce on the job's lease (at most one run and one pending, however many visitors
+  and never waits for it. A mutation declares the same `then` for the outbox row it records (`references/jobs.md`). Kicks coalesce on the job's lease (at most one run and one pending, however many visitors
   submit), so the job still drains its inbox in batches under its own budgets. Keep its schedule: it is the recovery
   path for a kicked run that died. A kick carries nothing; the job reads its inbox. `kit.runJob` first waits for the
   kicked runs.
 - `src/app.ts` composes and does nothing else. A dependency built from the application's own variables is
   `defineDeps(build)`, passed as `serve(contract, { database, deps })` and read in a handler with `get()`. Never read
   `process.env`. `build` runs at every boot, the generated tests' too, which pass no variable: read a variable when
-  the dependency is used, and fail there (`src/mail.ts` in `references/public-intake.md`). A handler of an endpoint the
+  the dependency is used, and fail there (`src/links.ts` in `references/public-intake.md`). A handler of an endpoint the
   generated tests cover records an outbox row instead, and a job calls the dependency (`references/endpoint.md`).
+  E-mail needs no dependency: a job that declares `mailer` sends through `ctx.mail` (`references/jobs.md`).
 
 ## The deploy surface (Zerops)
 

package/skill/references/dev.md

@@ -64,27 +64,36 @@ export default seed
   does: a token is single use. For the widget on a page, set the `siteKey` variable to Turnstile's always-passing test
   key `1x00000000000000000000AA`. Its token is the same every time, and `app dev` admits that one token again at each
   submission; a deployed application records it like any other, so there it passes once.
-- Point an outside provider at the dev outbox: `app dev` captures every request the process sends to
-  `https://outbox.invalid` (`DEV_OUTBOX_ORIGIN` of `@fabrika/app/testing`) and answers `200 {"id": …}`. The mail view
-  lists each one, by the `to` and `subject` of a JSON body, and opens its body; its headers are not kept.
-- The seed's second argument reads the outbox: `outside.outbox()` is every captured request, oldest first
-  (`{ id, method, path, contentType, body }`), so the seed can open a link the application mailed.
+- A job's e-mail goes to the kit's mail stand-in (`dev.mail`, as `kit.mail` in a test): nothing is delivered, and no
+  mail variable is needed. The mail view lists each message, newest first, beside IAM's invitations: the recipient,
+  the subject, the key the job passed, the time and the transport's answer. It opens to every field, the text, and the
+  HTML in a sandboxed frame that runs no script and loads nothing. `dev.mail.refuse('provider_rejected')` in the seed
+  previews a refused one; `dev.mail.heal()` ends it.
+- The seed's second argument reads what left the application: `outside.mails()` is every message a job handed to the
+  stand-in, oldest first (`{ id, at, to, subject, text, html, key, transportKey, answer, outcome, delivered, … }`), so
+  the seed can open a link the application mailed. Run the job first (`dev.runJob('<job>')`), or let a mutation's
+  `then` kick it and `await dev.drain()`.
+- Point another outside service at the dev outbox: `app dev` captures every request the process sends to
+  `https://outbox.invalid` (`DEV_OUTBOX_ORIGIN` of `@fabrika/app/testing`) and answers `200 {"id": …}`. A section of
+  its own lists each one, by the `to` and `subject` of a JSON body, and opens its body; its headers are not kept.
+  `outside.outbox()` is every captured request, oldest first (`{ id, method, path, contentType, body }`).
 
 ```text dev/dev.env
 # Stand-in values for fabrika app dev.
 TURNSTILE_SECRET=dev
 TURNSTILE_SITE_KEY=1x00000000000000000000AA
-MAIL_API_URL=https://outbox.invalid/mail
-MAIL_API_KEY=dev
+ARCHIVE_URL=https://outbox.invalid/archive
+ARCHIVE_KEY=dev
 ```
 
 ## In the browser
 
 - `/__fabrika/dev` is the picker: the personas, another role of the vocabulary (a membership role with a scope value),
-  anonymous, the link pages, and the mail: what IAM sent and what reached the dev outbox. It speaks the vocabulary's `locale` and shows its `displayName`.
+  anonymous, the link pages, the mail IAM and the application's jobs sent, and the dev outbox. It speaks the vocabulary's `locale` and shows its `displayName`.
 - Every SPA page carries a toolbar in the bottom corner: who you are, the personas to switch to (the page reloads as
-  that caller), the picker, the link pages, and the mail. An invitation's link accepts it; the browser is the invited
-  person from then on.
+  that caller), the picker, the link pages, the mail and the dev outbox. An invitation's link accepts it; the browser
+  is the invited person from then on. A job's message opens at `/__fabrika/dev/mail/<id>`.
 - The choice stays in a cookie the application never sees. The data is gone when the command stops.
 - It serves this machine only (`--host` is a loopback address, `--port=0` picks a free port), answers no request
-  addressed to another host name, and runs no cron job on its schedule: the seed runs one with `dev.runJob`, a test with `kit.runJob`.
+  addressed to another host name, and runs no cron job on its schedule: the seed runs one with `dev.runJob`, a test with `kit.runJob`. A form's or a
+  mutation's `then` still starts its job, as deployed.

package/skill/references/endpoint.md

@@ -60,10 +60,12 @@ export const OrgInput = z.strictObject({ orgId: z.string().min(1).max(100) })
   (`{ kind: 'service', id, label }`) has no address. `label` is for display: the address as the person spelled it.
 - **An endpoint the generated tests cover calls no outside service.** They boot without your variables, so a handler
   that calls one answers 500 in each case, and a request cannot undo the call when its transaction rolls back. Such an
-  endpoint records an outbox row in its transaction, and a job sends it with an attempt count and an idempotency key
-  (`references/jobs.md`). A call that is the request's whole purpose, such as a test e-mail to the caller, lives in a
-  `{ member: true }` endpoint, which they do not cover (`references/public-intake.md`). The framework's own calls (IAM,
-  the file store, `ctx.connect`) are not outside.
+  endpoint records an outbox row in its transaction, and a job makes the call with an attempt count and an idempotency
+  key (`references/jobs.md`). A call that is the request's whole purpose lives in a `{ member: true }` endpoint, which
+  they do not cover. The framework's own calls (IAM, the file store, `ctx.connect`) are not outside.
+- **An endpoint never sends e-mail**, covered or not: it has no `ctx.mail`. It records the message in an outbox row
+  and declares `then: '<job>'` on the mutation, so the job that declares `mailer` sends it within seconds of the
+  commit (`references/jobs.md`; the test e-mail in `references/public-intake.md`). Only a mutation declares `then`.
 - `ctx.principal.label` is a `string`, never `null`: the label IAM holds for the person (the one its directory
   shows), or the id when the token carries none. When the caller owns what it writes (the creator of a deal, the
   assignee of a task nobody was picked for), store `ctx.principal.id` and `ctx.principal.label`, never a

package/skill/references/files.md

@@ -10,7 +10,7 @@ import { members } from './src/members/endpoints'
 import { priorities } from './src/priorities/endpoints'
 import { projects } from './src/projects/endpoints'
 import { reports } from './src/reports/endpoints'
-import { digest } from './src/tasks/digest'
+import { archive } from './src/tasks/archive'
 import { tasks } from './src/tasks/endpoints'
 import { erase } from './src/tasks/erase'
 
@@ -34,7 +34,7 @@ export const contract = app.contract((c) => ({
 			maxPerOwner: 20,
 		}),
 	},
-	jobs: { digest, erase },
+	jobs: { archive, erase },
 	health: c.health('/healthz'),
 }))
 ```
@@ -108,21 +108,22 @@ Every call needs the collection's `read`, so a write capability alone sees no fi
 document is declared with an action that is the collection's `read` too, or the check runs where the caller holds
 `read`: never mint or widen a capability to list.
 
-A job mints the owner's `Ref` with `ctx.ref` and opens each live file, here to attach it to an e-mail of `deps`:
+A job mints the owner's `Ref` with `ctx.ref` and opens each live file, here to hand it to an archive service of
+`deps`. `ctx.mail` carries no attachments, so a file leaves through a service of the application's own:
 
-```ts src/tasks/digest.ts
+```ts src/tasks/archive.ts
 import { app } from '../app-kit'
-import { mailer } from '../mail'
+import { archiver } from '../archive'
 
-/** The largest report one e-mail carries: the collection's maxBytes. */
+/** The largest report the archive takes in one call: the collection's maxBytes. */
 const REPORT_MAX_BYTES = 5242880
 
-export const digest = app.cron('0 6 * * *', {
+export const archive = app.cron('0 6 * * *', {
 	actions: ['tasks.read'],
 	scope: 'app',
 })
 	.handle(async ({ ctx }) => {
-		const mail = mailer.get()
+		const store = archiver.get()
 		const tasks = ctx.db.over(ctx.within('tasks.read', 'project')).tasks
 		const done = await tasks.list({ where: [['status', '=', 'done']], limit: 50 })
 		for (const task of done.items) {
@@ -136,12 +137,12 @@ export const digest = app.cron('0 6 * * *', {
 				)
 			}
 			ctx.signal.throwIfAborted()
-			await mail.sendReports(task.title, reports, ctx.signal)
+			await store.putReports(task.id, reports, ctx.signal)
 		}
 	})
 ```
 
-```ts src/mail.ts
+```ts src/archive.ts
 import { defineDeps } from '@fabrika/app/implement'
 
 export interface Report {
@@ -150,10 +151,10 @@ export interface Report {
 	readonly bytes: Uint8Array
 }
 
-export interface Mailer {
-	/** Sends the reports of one task; throws when the provider refuses, and gives up once `signal` aborts. */
-	sendReports(
-		title: string,
+export interface Archiver {
+	/** Stores the reports of one task under its id; throws when the service refuses, and gives up once `signal` aborts. */
+	putReports(
+		taskId: string,
 		reports: readonly Report[],
 		signal: AbortSignal,
 	): Promise<void>
@@ -167,27 +168,28 @@ const variable = (env: Readonly<Record<string, unknown>>, name: string) => {
 	return value
 }
 
-export const mailer = defineDeps((env): Mailer => ({
-	async sendReports(title, reports, signal) {
-		const response = await fetch(variable(env, 'MAIL_API_URL'), {
-			method: 'POST',
-			headers: {
-				Authorization: `Bearer ${variable(env, 'MAIL_API_KEY')}`,
-				'Content-Type': 'application/json',
+export const archiver = defineDeps((env): Archiver => ({
+	async putReports(taskId, reports, signal) {
+		const response = await fetch(
+			`${variable(env, 'ARCHIVE_URL')}/tasks/${taskId}`,
+			{
+				method: 'PUT',
+				headers: {
+					Authorization: `Bearer ${variable(env, 'ARCHIVE_KEY')}`,
+					'Content-Type': 'application/json',
+				},
+				body: JSON.stringify({
+					files: reports.map((file) => ({
+						filename: file.name ?? 'report',
+						contentType: file.type,
+						content: Buffer.from(file.bytes).toString('base64'),
+					})),
+				}),
+				signal,
 			},
-			body: JSON.stringify({
-				to: variable(env, 'REPORTS_TO'),
-				subject: `Reports of ${title}`,
-				attachments: reports.map((file) => ({
-					filename: file.name ?? 'report',
-					contentType: file.type,
-					content: Buffer.from(file.bytes).toString('base64'),
-				})),
-			}),
-			signal,
-		})
+		)
 		if (!response.ok) {
-			throw new Error(`the mail provider answered ${response.status}`)
+			throw new Error(`the archive answered ${response.status}`)
 		}
 	},
 }))
@@ -197,12 +199,14 @@ export const mailer = defineDeps((env): Mailer => ({
 import { serve } from '@fabrika/app/implement'
 import { scoped } from '@fabrika/db'
 import { contract } from '../fabrika.contract'
+import { archiver } from './archive'
 import { tables } from './db/tables'
-import { mailer } from './mail'
 
-export default serve(contract, { database: scoped(tables), deps: mailer })
+export default serve(contract, { database: scoped(tables), deps: archiver })
 ```
 
+The `PUT` under the task's id makes a repeated run replace the same object, so a retried attempt stores nothing twice.
+
 `removeAll` runs in a mutation and in a job's `tx.files`, in the same transaction as the handler's writes: an erasure
 that blanks a record and removes its files keeps both or neither. A query and a job's `ctx.files` only read. The
 framework's sweep deletes the removed files' objects within the hour, and so the objects of a deleted owner's files.

package/skill/references/jobs.md

@@ -2,7 +2,9 @@
 
 Background work is a cron job: `app.cron(schedule, { actions, scope: 'app' })` with its `.handle(…)` in the
 `endpoints.ts` of the slice whose data it works on, mounted under `jobs` in the contract. There are no timers, loops,
-`setInterval` or self-scheduled work, and no `ctx.jobs.enqueue`: work for later is a row that the next run picks up.
+`setInterval` or self-scheduled work, and no `ctx.jobs.enqueue`: work for later is a row that a run picks up. A
+mutation that declares `then: '<job>'` starts a run within seconds of its commit (the outbox below); the schedule
+picks up whatever that run leaves.
 
 ```ts src/overdue/endpoints.ts
 import { app } from '../app-kit'
@@ -135,19 +137,62 @@ export const contract = app.contract((c) => ({
   `ctx.links.issue(await ctx.ref('<issuedBy>', '<dimension>', id), { mount, days })`, and `ctx.links.revoke(id)` for
   a link it issued. It is a widening for closer review. `references/public-intake.md` is the whole recipe: a form's
   inbox, the record, the link and its e-mail, each step recorded before the next.
-- A job reads a file collection through `ctx.files('<collection>')` with a `Ref` it minted (`list`, `open` to attach a
-  file to an e-mail), and removes an owner's files only inside its transaction, `tx.files('<collection>').removeAll(ref)`
+- A job reads a file collection through `ctx.files('<collection>')` with a `Ref` it minted (`list`, `open` to hand a
+  file to another service), and removes an owner's files only inside its transaction, `tx.files('<collection>').removeAll(ref)`
   (`references/files.md`). The framework's own `fabrika-file-sweep` then deletes their objects; never write a sweep.
 - `ctx.signal` aborts when the attempt ends (its timeout, a lost lease). Call `ctx.signal.throwIfAborted()` before
   each external effect and pass the signal to `fetch`, so a stale attempt starts nothing after its replacement.
-- A failed attempt names its failure in `kit.runJob`'s answer and the log: `handler_failed`, or a framework refusal
-  with its reason (`query_refused: undeclared_reach`, `capability_refused: undeclared_action`; `references/errors.md`).
+- A failed attempt names its failure in `kit.runJob`'s answer and the log: `handler_failed`, a framework refusal
+  with its reason (`query_refused: undeclared_reach`, `capability_refused: undeclared_action`; `references/errors.md`),
+  or `mail_failed` with the transport's code (`mail_failed: provider_rejected`).
+
+## E-mail: `mailer` and `ctx.mail`
+
+Only a cron job that declares `mailer` sends e-mail, through `ctx.mail`. An endpoint has no `ctx.mail` (a type error
+that says so): it records an outbox row and kicks the job (below). `references/public-intake.md` shows both jobs whole.
+
+- `mailer: 'installation'` sends through the installation's transport: the operator configures one provider, and
+  Control hands it to each application whose job declares it. The application holds no provider key and writes no
+  transport code. An installation without a transport still deploys it, and `ctx.mail.available` is then false.
+- `mailer: 'own'` sends through the application's own transport: `serve(contract, { database, mail: (env) => sender })`,
+  where `sender` is an `EmailSender` (`@fabrika/app/implement`) built from the application's own variables, or `null`
+  when they configure none. Never name a variable `FABRIKA_EMAIL_*`: those are the installation's.
+- `mailer` is reach the approver sees (`installation` for closer review). Declare it only after the human said yes.
+  Without it, `ctx.mail` is a type error that names the declaration. A boot without the declared transport fails and
+  says which job needs it; the test kit and `fabrika app dev` stand one in (`kit.mail`, `references/tests.md`).
+- `ctx.mail.send({ to, subject, text, html?, replyTo?, fromName?, idempotencyKey }, signal?)` hands one message to the
+  transport and answers `{ status: 'accepted', provider, messageId }`. It always aborts with the attempt's
+  `ctx.signal`; pass `AbortSignal.timeout(ms)` for a deadline of the message's own. The sending address is the
+  transport's; `fromName` and `replyTo` are the application's, per message. There are no attachments.
+- `idempotencyKey` is 1 to 200 visible ASCII characters, unique per message in the application environment, and
+  derived from the outbox row (`intake-link-<link id>`), never random. `ctx.mail` puts a prefix of the installation
+  and the environment in front of it, so no other application on the same provider account shares it.
+- `ctx.mail.available` is false where the installation has no transport. Every send then fails `mail_not_configured`
+  (`not_sent`). Check it before the batch: when it is false, return and leave every row as it is, so no attempt is
+  spent. The rows leave on the first run after the operator adds a transport and redeploys the application.
+- A refused send throws `EmailDeliveryError` (`@fabrika/app/implement`): a fixed `code` and an `outcome`, `not_sent`
+  (the message did not leave) or `unknown` (it may have). `ctx.mail.mayRetry(error)` says whether the message may go
+  again: false for a refused message or configuration, and for an `unknown` outcome over a transport that does not
+  deduplicate a key (`ctx.mail.capabilities.idempotent` is false). Where it is false, never send again: the row is
+  dead, for a person.
+- A send error the handler does not catch fails the attempt as `mail_failed`, and the runner retries the attempt only
+  where `mayRetry` holds. Catch it per row instead, as the outbox below does.
+- Never log a message, its address or its key: log the row's id and the error's `code`.
 
 ## An outbox: what a request asks a job to do
 
-A request handler calls no outside service (`references/endpoint.md`). It records what to do in a row, in its own
-transaction: a form's inbox row, or a state of its record (`link_state = 'due'`). A job does the work and calls the
-service. `references/public-intake.md` is the whole recipe; its rules:
+A request handler calls no outside service and sends no e-mail (`references/endpoint.md`). It records what to do in a
+row, in its own transaction: a form's inbox row, an outbox row (`test_mails`), or a state of its record
+(`link_state = 'due'`). A job does the work and calls the service. `references/public-intake.md` is the whole recipe.
+
+**The kick.** A mutation that records such a row declares `then: '<job>'`: once its transaction committed, the job
+runs within seconds, under its own key, and the answer does not wait for it. A form's `then` does the same for its
+inbox. A thrown handler, a refused answer and a failed commit kick nothing. Kicks coalesce: at most one run is active
+and one pending, however many calls arrive. A kick carries nothing; the job reads its rows, and its schedule stays the
+recovery. `then` names one cron job of the contract, as a literal (`r.mutation({ …, then: 'testMails' })`); a query,
+an export, a webhook and a job declare none.
+
+The rules of the job:
 
 - **Bounded batches.** Each run takes at most a fixed number of records (`order by received_at, id limit 50`), oldest
   first; the next run takes the rest.
@@ -157,13 +202,26 @@ service. `references/public-intake.md` is the whole recipe; its rules:
   `attempts`, keeps a fixed step code in `last_failure` (never the error's message, which can quote a value), and the
   run goes on with the next record. Rethrow when `ctx.signal` aborted: that failure is the attempt's, and the next
   run meets the record as it is. So give each external call a deadline of its own inside the attempt's
-  (`AbortSignal.any([ctx.signal, AbortSignal.timeout(ms)])`): a call that hangs then fails its record, not the run.
+  (`AbortSignal.any([ctx.signal, AbortSignal.timeout(ms)])` for a `fetch`; `ctx.mail.send` adds `ctx.signal` itself,
+  so it takes only `AbortSignal.timeout(ms)`): a call that hangs then fails its record, not the run.
+- **A backoff per record.** A failure sets the record's `next_attempt_at` one minute ahead, doubled per attempt up to
+  an hour (`now() + least(interval '1 minute' * power(2, attempts), interval '1 hour')`), and a run takes only records
+  whose time has come (`where next_attempt_at <= now()`). Kicks start runs seconds apart: without the wait, a short
+  provider outage spends every attempt of a record at once. Set it, with the attempt, in the transaction that claims
+  the record before the call (the test e-mail), and a run that dies during the call waits too. A record a person
+  revives (a resend) is due at once again.
 - **A dead state.** A record that failed `MAX_ATTEMPTS` times is dead: the batch skips it, the job logs it once by its
   id (never an address), and an operator fixes or deletes it. Give the record a way back when the cause can go away
   (a resend revives a dead delivery).
-- **A key on every external call**, derived from the record: the e-mail's `Idempotency-Key`, a provider's request id.
-  The provider then acts once per key, however often the job hands the call over. A retry sends the same request
-  under the same key: keep what it needs in the row until the call is known done (sealed, when it holds a secret).
+- **A key on every external call**, derived from the record: the e-mail's `idempotencyKey`, a provider's request id.
+  A provider that deduplicates then acts once per key, however often the job hands the call over. A retry sends the
+  same request under the same key: keep what it needs in the row until the call is known done (sealed, when it holds a
+  secret).
+- **A retry only where the transport allows it.** Mark the record `sending` before the send. A run that finds it still
+  `sending` (a crash, a lost answer) sends it again only when `ctx.mail.capabilities.idempotent` holds, and otherwise
+  makes it dead: the e-mail may have arrived, and a second one cannot be taken back. A failed send goes again only
+  where `ctx.mail.mayRetry(error)` holds, and is dead at once otherwise; one whose `outcome` is `not_sent` returns to
+  the state it had before `sending`.
 - **Each step recorded before the next effect**, so the next run finishes a stopped one.
 - An inbox needs a row key for this: `id UUID NOT NULL DEFAULT gen_random_uuid()`, since a form writes only its input
   fields.