okengine 0.21.0 → 0.22.0

package/site/content/docs/elements/vault/rotation.mdx

@@ -209,10 +209,25 @@ Builtin encrypted store:
 
 `--url` overrides the SQL URL (`DATABASE_URL` / `OKE_STORE_SQL_URL`).
 
+## Audit sinks
+
+| `vault.audit.sink` | Recorded as                       | `oke vault audit`   |
+| ------------------ | --------------------------------- | ------------------- |
+| `db` (default)     | SQL hash chain                    | list, verify, purge |
+| `stdout`           | One secret-free JSON line         | Refused             |
+| `webhook`          | POST of that JSON to `webhookUrl` | Refused             |
+
+`webhookUrl` must be an absolute `http:` or `https:` URL. The POST uses `redirect: "error"` and a 5 second timeout. A failed delivery does not undo the vault write. `audit.enabled: false` records nothing. The body never contains a secret value.
+
 ## Troubleshooting
 
 <Accordions>
 
+<Accordion title="audit verify requires audit.sink db">
+  `stdout` and `webhook` sinks are not a local hash chain. `oke vault audit` (list, verify, purge)
+  throws `UNSUPPORTED`. Use `sink: "db"` when you need `verify`.
+</Accordion>
+
 <Accordion title="oke vault: no such secret">
   Rotate/get targeted a path that was never set. `oke vault list` (or Console) for live paths;
   remember per-tenant storage uses `{tenantId}/{name}`.

package/site/content/docs/plugins/otp.mdx

@@ -69,7 +69,7 @@ invalidated. Delivery follows `channels` order for addresses you pass.
 </Step>
 
 <Step>
-### Resend on another channel (app mode only)
+### Resend
 
 ```typescript
 const { data } = await api.auth.resendOtp({
@@ -79,8 +79,8 @@ const { data } = await api.auth.resendOtp({
 });
 ```
 
-Same code, same TTL. Default cooldown is 60 seconds. Provider mode has no
-resend surface — the provider owns the code.
+App mode keeps the same code and TTL. Provider mode is SMS only and asks the
+provider for a new code. Default cooldown is 60 seconds either way.
 
 </Step>
 
@@ -108,18 +108,18 @@ const { data } = await api.auth.verifyOtp({
 
 ## Modes
 
-|                      | Provider mode                 | App mode                                      |
-| -------------------- | ----------------------------- | --------------------------------------------- |
-| Config               | `otp({ mode: "provider" })`   | `otp({ mode: "app", channels: [...] })`       |
-| Who owns the code    | Provider (Verify API)         | Your app                                      |
-| Delivery             | `fx.sendOtp` / `fx.verifyOtp` | `fx.deliverOtp` (Channel templates)           |
-| Channels             | SMS only                      | `sms` · `whatsapp` · `email` (declared order) |
-| Resend other channel | Impossible                    | `POST /auth/otp/resend`                       |
-| `exposeDevOtp`       | Forbidden                     | Optional (default off)                        |
+|                   | Provider mode                 | App mode                                      |
+| ----------------- | ----------------------------- | --------------------------------------------- |
+| Config            | `otp({ mode: "provider" })`   | `otp({ mode: "app", channels: [...] })`       |
+| Who owns the code | Provider (Verify API)         | Your app                                      |
+| Delivery          | `fx.sendOtp` / `fx.verifyOtp` | `fx.deliverOtp` (Channel templates)           |
+| Channels          | SMS only                      | `sms` · `whatsapp` · `email` (declared order) |
+| Resend            | SMS only, new provider code   | Same code, any declared channel               |
+| `exposeDevOtp`    | Forbidden                     | Optional (default off)                        |
 
 <Callout type="warn" title="Provider mode limitation">
-  Resend-via-different-channel is impossible in provider mode — the code value is never visible to
-  OKE. Use app mode when you need SMS → email fallback for the same code.
+  A provider resend is a new SMS code (`resendCooldownMs`, default 60s). The code never reaches OKE,
+  so SMS → email for the same code needs `mode: "app"`.
 </Callout>
 
 ### Provider mode setup
@@ -154,27 +154,27 @@ Override copy with `oke({ channel.catalog })` or `.channelCatalog(…)` (later l
 
 ## Options
 
-| Option             | Type                             | Default                    | Meaning                             |
-| ------------------ | -------------------------------- | -------------------------- | ----------------------------------- |
-| `mode`             | `"provider" \| "app"`            | required                   | Delivery mechanism — no auto        |
-| `channels`         | `("sms"\|"whatsapp"\|"email")[]` | required in app mode       | Build-time preferred order          |
-| `ttlMs`            | `number`                         | 10m                        | Challenge lifetime                  |
-| `resendCooldownMs` | `number`                         | 60s                        | App-mode resend spacing             |
-| `exposeDevOtp`     | `boolean`                        | `false`                    | App mode only — raw OTP in response |
-| `from`             | `string`                         | `OKE <no-reply@oke.local>` | Email template From                 |
-| `secret`           | `string`                         | active\*                   | Auth secret (\*from `gate.auth`)    |
-| `sessions`         | `SessionStore`                   | active\*                   | Session store                       |
-| `identities`       | `IdentityStore`                  | new                        | Email → user                        |
-| `phones`           | `PhoneStore`                     | new                        | Phone → user                        |
-| `verifications`    | `VerificationStore`              | new                        | Challenge store                     |
+| Option             | Type                             | Default                    | Meaning                              |
+| ------------------ | -------------------------------- | -------------------------- | ------------------------------------ |
+| `mode`             | `"provider" \| "app"`            | required                   | Delivery mechanism — no auto         |
+| `channels`         | `("sms"\|"whatsapp"\|"email")[]` | required in app mode       | Build-time preferred order           |
+| `ttlMs`            | `number`                         | 10m                        | Challenge lifetime                   |
+| `resendCooldownMs` | `number`                         | 60s                        | Spacing between resends (both modes) |
+| `exposeDevOtp`     | `boolean`                        | `false`                    | App mode only — raw OTP in response  |
+| `from`             | `string`                         | `OKE <no-reply@oke.local>` | Email template From                  |
+| `secret`           | `string`                         | active\*                   | Auth secret (\*from `gate.auth`)     |
+| `sessions`         | `SessionStore`                   | active\*                   | Session store                        |
+| `identities`       | `IdentityStore`                  | new                        | Email → user                         |
+| `phones`           | `PhoneStore`                     | new                        | Phone → user                         |
+| `verifications`    | `VerificationStore`              | new                        | Challenge store                      |
 
 ## Surfaces
 
-| Flow              | Path                     | Gate                     | Mode          |
-| ----------------- | ------------------------ | ------------------------ | ------------- |
-| `auth.requestOtp` | `POST /auth/otp/request` | `gate.public` + otp rate | both          |
-| `auth.verifyOtp`  | `POST /auth/otp/verify`  | `gate.public` + otp rate | both          |
-| `auth.resendOtp`  | `POST /auth/otp/resend`  | `gate.public` + otp rate | app mode only |
+| Flow              | Path                     | Gate                     | Mode                      |
+| ----------------- | ------------------------ | ------------------------ | ------------------------- |
+| `auth.requestOtp` | `POST /auth/otp/request` | `gate.public` + otp rate | both                      |
+| `auth.verifyOtp`  | `POST /auth/otp/verify`  | `gate.public` + otp rate | both                      |
+| `auth.resendOtp`  | `POST /auth/otp/resend`  | `gate.public` + otp rate | both (provider: SMS only) |
 
 ## Troubleshooting
 

package/site/content/docs/recipes/mailpit.mdx

@@ -28,7 +28,7 @@ drivers: {
   },
 },
 images: {
-  channel: { email: "axllent/mailpit:v1.31.1" },
+  channel: { email: "axllent/mailpit:v1.31.2" },
 },
 ```
 

package/site/content/docs/recipes/meilisearch.mdx

@@ -28,7 +28,7 @@ drivers: {
   },
 },
 images: {
-  store: { index: "getmeili/meilisearch:v1.53" },
+  store: { index: "getmeili/meilisearch:v1.54" },
 },
 ```
 

package/site/content/docs/recipes/pgdog.mdx

@@ -26,7 +26,7 @@ create-oke asks **Add PgDog connection pooling…?** (or pass `--pgdog`). Manual
 ```typescript title="oke.config.ts"
 images: {
   "store.sql": "postgres:18-alpine",
-  pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.57",
+  pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.59",
 },
 ```
 

package/site/content/docs/reference/configuration.mdx

@@ -153,8 +153,8 @@ images: {
     kv: "redis:8-alpine",
     files: "rustfs/rustfs:1.0.0",
   },
-  channel: { email: "axllent/mailpit:v1.31.1" },
-  pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.57",
+  channel: { email: "axllent/mailpit:v1.31.2" },
+  pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.59",
   // proxy: "caddy:2-alpine",
 },
 ```

package/site/content/docs/reference/errors.mdx

@@ -120,6 +120,10 @@ at **404**. Clients distinguish by envelope, not status. Domain codes stay **400
 | Code                                             | Status      | Helper                                                 |
 | ------------------------------------------------ | ----------- | ------------------------------------------------------ |
 | `ValidationError`                                | `422`       | none — failed `in`, `do` never runs                    |
+| `IdempotencyKeyMissing`                          | `400`       | none — `idempotency: "required"` and no header         |
+| `IdempotencyKeyInvalid`                          | `400`       | none — header is not 16–255 printable ASCII            |
+| `IdempotencyKeyReused`                           | `422`       | none — same key, different payload                     |
+| `IdempotencyInProgress`                          | `409`       | none — `Retry-After` until the in-flight call finishes |
 | `Unauthorized`                                   | `401`       | `unauthorized` · also a gate denial                    |
 | `Forbidden`                                      | `403`       | `forbidden` · also a gate denial                       |
 | `NotFound`                                       | `404`       | `notFound`                                             |
@@ -301,8 +305,14 @@ Thrown by specific subsystems — each names its own cause:
 <Accordions>
 
 <Accordion title="I hit OKE1001–1009">
-  Explicit `effects` drifted from `do`. Add the missing ledger entry or remove the hand-written
-  `effects` block so inference covers the Flow.
+  The capability token does not include what the Flow touched. Add the missing ledger entry. An
+  `effects` block must include every effect inference can see.
+</Accordion>
+
+<Accordion title="OKE1900 fx hidden from inference">
+  Cause: the Flow renames `fx`, lets a chain alias escape, or passes `fx` to a callee inference
+  cannot resolve. Fix: name the parameter `fx`, keep `const q = fx.store(db)` in the same function,
+  and include every effect the walk can see. Extra keys in an `effects` block are allowed.
 </Accordion>
 
 <Accordion title="OKE1040 pathless HTTP never stamped">

package/site/content/docs/reference/fx.mdx

@@ -54,7 +54,9 @@ async function loadNote(id: string, fx: Fx) {
 }
 ```
 
-A narrower structural type will not match `store()` overloads. See [Flow](/docs/elements/flow).
+Name that parameter `fx`. A narrower structural type will not match `store()` overloads. See [Flow](/docs/elements/flow).
+
+Inference follows `fx` in four shapes: a direct `fx.*` call, a chain alias kept in the same function (`const q = fx.store(db)` then `q.select()`), a project helper whose parameter is named `fx`, and two package intrinsics — `liveQuery(fx, table, …)` records `reads: ["sql:<table>"]`, and `applySearchEmbedCdc` records the static `sqlRef` plus each column's embed model.
 
 </Step>
 
@@ -155,11 +157,13 @@ on(
 | `fx.auth.createTenant({ name, slug?, id? })`                                   | `write` `auth:tenants`  | Creator becomes a member. Session only                                                             |
 | `fx.auth.upsertTenantRole({ tenantId, roleName, scopes })`                     | `write` `auth:tenants`  | Application scopes only — `console:*` is unknown_scope                                             |
 
-`fx.call` starts the callee with an **empty** `fx.auth` (fail-closed for authorization) and
-propagates `fx.tenant.id`. For audit/attribution only, read `fx.principal` — it propagates the
-originating identity without copying into `fx.auth`. Gates never consult `fx.principal`.
-Controlled `return fx.fail(...)` returns a `FlowFailure` value; an unhandled `throw` rethrows
-(never silent `undefined`). The same rules apply to `app.call`.
+`fx.call` starts the callee with an **empty** `fx.auth` (fail-closed) and propagates `fx.tenant.id`.
+Read `fx.principal` for audit — it does not copy into `fx.auth`.
+
+<Callout>
+  Gates never consult `fx.principal`. `return fx.fail(...)` is a `FlowFailure`; an unhandled `throw`
+  rethrows. The same rules apply to `app.call`.
+</Callout>
 
 ## Concurrency and retry
 
@@ -190,11 +194,14 @@ const charge = await fx.step("charge", () =>
 | `when`            | thrown  | Predicate; skips `AbortError` and sleep park |
 
 <Callout title="Cooperative cancel">
-  Losing branches see `fx.signal` abort. Drivers that do not yet honor the signal may still finish
-  in the background — check `fx.signal.aborted` in long user work, and prefer `fx.all` over bare
-  `Promise.all`.
+  Losing branches see `fx.signal` abort. `fx.fetch`, Meilisearch, remote Vault HTTP, and AI streams
+  cancel in flight. An effect that has not started throws `AbortError`.
 </Callout>
 
+SQL (`Bun.sql`), Redis, and a Channel send already on the wire through sently still finish. Those
+clients expose no abort hook, and the shared connection stays open. Prefer `fx.all` over bare
+`Promise.all`.
+
 `fx.using(acquire, release, use)` scopes a process-local resource to one attempt: `release` runs
 exactly once when `use` settles **or** when the ambient signal aborts (a sibling `fx.race` winner,
 a failing `fx.all` sibling). It is not journaled — do not hold handles across durable park/resume.
@@ -221,9 +228,9 @@ contact a provider. Bodies live on `.template({ catalog })` (`{{field}}`, not IC
 
 ## Outbound HTTP
 
-| Signature              | Records                     | Notes                                                                     |
-| ---------------------- | --------------------------- | ------------------------------------------------------------------------- |
-| `fx.fetch(url, init?)` | `fetch` on the URL hostname | Always stamps `EffectEntry.external` with `{ host, kind: "third-party" }` |
+| Signature              | Records                     | Notes                                                                      |
+| ---------------------- | --------------------------- | -------------------------------------------------------------------------- |
+| `fx.fetch(url, init?)` | `fetch` on the URL hostname | Stamps `external: { host, kind: "third-party" }`. Aborts with `fx.signal`. |
 
 Declare hosts in `effects.fetches` (e.g. `["api.stripe.com"]`). Prefer `fx.step`; use
 `fx.retry` only when the remote API is safe to repeat. Dry runs never hit the network.
@@ -340,9 +347,15 @@ to the key — see [Gate](/docs/elements/gate#api-keys).
 <Accordions>
 
 <Accordion title="OKE1001–1007 / 1008 / 1009 undeclared effect">
-  An explicit `effects` block drifted from what `do` touches. Add the missing ledger entry (`reads`
-  · `writes` · `emits` · `sends` · `asks` · `embeds` · `secrets` · `calls` · `fetches`), or drop the
-  block so inference covers the Flow ([Errors](/docs/reference/errors)).
+  The Manifest token does not include what `do` touched. Add the missing ledger entry (`reads` ·
+  `writes` · `emits` · `sends` · `asks` · `embeds` · `secrets` · `calls` · `fetches`). An `effects`
+  block must include every effect inference can see ([Errors](/docs/reference/errors)).
+</Accordion>
+
+<Accordion title="OKE1900 fx hidden from inference">
+  Name the parameter `fx` and keep chain aliases in the same function. Passing `fx` to an unresolved
+  callee, or returning, reassigning, or storing `fx` or a chain alias, fails extract. An `effects`
+  block may add keys. It must include every effect the walk can see.
 </Accordion>
 
 <Accordion title="OKE1240 orphan emit">

package/site/content/docs/reference/idempotency.mdx

@@ -0,0 +1,192 @@
+---
+title: "Idempotency"
+description: "Send one Idempotency-Key so a retried mutating call runs once and a later retry replays the stored response."
+icon: "KeyRound"
+source: "docs/spec/unified-theory.md"
+---
+
+A checkout that times out should not charge the card twice. Send one `Idempotency-Key` for that attempt. The server runs `do` once and replays the stored response when the same key comes back.
+
+<Callout title="The one rule">
+  Mint one key per logical call and send it on every retry of that call. Two submits are two calls
+  unless your app passes the same key. Provider webhooks do not send this header — keep a unique
+  constraint on the provider's event id.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Mark the flow
+
+`idempotency: "required"` rejects a call that omits the header. Leave it off and the header is
+optional. `"required"` on a read, GET, stream, or live flow fails extract.
+
+```typescript
+import { on, flow, http } from "okengine";
+
+export const charge = on(
+  http.post("/charges", { in: ChargeIn, out: ChargeOut }),
+  flow("payments.charge", {
+    idempotency: "required",
+    do: async (input, fx) => {
+      return fx.store(db).insert(charges).values(input);
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Call it
+
+The client sends `Idempotency-Key` on every non-GET call. Pass a string to reuse a key across
+your own retries, or `false` to send none.
+
+```typescript
+await api.payments.charge({ amount: 1000 });
+await api.payments.charge({ amount: 1000 }, { idempotencyKey: "checkout-attempt-9f3a2c" });
+```
+
+</Step>
+
+<Step>
+### Read the replay
+
+The first response is the live result. A later call with the same key, principal, and payload
+returns that stored response and sets `Idempotent-Replayed: true`. The client copies that onto
+`meta.idempotentReplayed`.
+
+</Step>
+
+</Steps>
+
+## When the header is honored
+
+All of these are required. Otherwise the header is ignored.
+
+| Check   | Honored when                                                                                                                        |
+| ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Entry   | HTTP, and the method is not GET. RPC counts. `fx.call` has no request, so it does not.                                              |
+| Effects | Inferred effects include a write, emit, send, call, fetch, ask, or embed — or the flow uses `fx.raw`. Secrets alone do not qualify. |
+| Shape   | Not `stream`, and not a live SSE feed.                                                                                              |
+| Option  | Omitted or `{ ttl }` is `auto` (header optional). `"required"` or `{ required: true }` demands the header. `false` ignores it.      |
+
+`QUERY` is not GET. It qualifies when the rest of the row matches.
+
+| Option                          | Meaning                                             |
+| ------------------------------- | --------------------------------------------------- |
+| omitted                         | `auto` when the flow qualifies. Default TTL `24h`.  |
+| `"required"`                    | Missing header is `400 IdempotencyKeyMissing`.      |
+| `{ ttl: "1h" }`                 | `auto`, with that TTL. `ms`, `s`, `m`, `h`, or `d`. |
+| `{ required: true, ttl: "1h" }` | Required, with that TTL.                            |
+| `false`                         | Header ignored.                                     |
+
+An unparseable TTL, or `required` on a flow that cannot honor the header, fails extract.
+
+The key is 16–255 printable ASCII characters (`0x20`–`0x7E`). Anything else is
+`400 IdempotencyKeyInvalid`.
+
+The scope is tenant, principal, and flow. The principal is `user:<id>`, else `apikey:<id>`, else
+`anon`. The same key from two people is two records. The fingerprint is a hash of the flow name
+and the validated input. The same key with a different payload is `422 IdempotencyKeyReused`.
+
+## What a second request sees
+
+The claim happens after the gate and after input validation. A `401`, `403`, or validation
+failure stores nothing, so the same key can still succeed.
+
+| Row                           | Response                                                                               |
+| ----------------------------- | -------------------------------------------------------------------------------------- |
+| No row, or the TTL has passed | `do` runs. The response is stored until the TTL.                                       |
+| Same payload, completed       | Stored status, body, `content-type`, and `location`, plus `Idempotent-Replayed: true`. |
+| Same payload, still running   | `409 IdempotencyInProgress` and `Retry-After` (seconds until the lease, at least 1).   |
+| Different payload             | `422 IdempotencyKeyReused`.                                                            |
+
+A stream, an SSE body, or a raw `Response` that is not a buffered JSON envelope is not stored.
+The live response is returned and the row is deleted.
+
+A throw before any non-read effect deletes the row. The same key may run again. A throw after a
+write, emit, send, call, fetch, ask, embed, or `fx.raw` stores the `500 InternalError` envelope.
+A new key is required. A declared `fx.fail(...)` is stored as that failure, not as a 500.
+
+## Crashes
+
+The in-progress lease is 30 seconds and is renewed while `do` runs. A disconnect does not cancel
+a claimed `do`. The lease is what notices a crash.
+
+| Flow        | After the lease expires                                                       |
+| ----------- | ----------------------------------------------------------------------------- |
+| Not durable | The next request with the same key runs `do` again. That is at-least-once.    |
+| Durable     | The next request resumes that journal run. Completed steps are not run again. |
+
+A durable sleep stores the `204` and parks the journal run. A retry replays the `204`. The
+scheduler continues the run.
+
+## Where the body lives
+
+Rows sit in `oke_idempotency` on the journal driver: memory in tests, `.oke/idempotency.json`
+beside the journal file, and Postgres when that journal driver is bound.
+
+The stored body can contain personal data and stays until the TTL. Expired rows are deleted on
+the next claim and by a periodic sweep.
+
+The Console flow contract shows an idempotency pill when the mode is `auto` or `required`.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="400 IdempotencyKeyMissing">
+
+The catalog message is `This call requires an Idempotency-Key header.` The flow is `required`
+and this request did not send the header. Send a key, or drop `"required"` if the header should
+stay optional.
+
+</Accordion>
+<Accordion title="400 IdempotencyKeyInvalid">
+
+The catalog message is `Idempotency-Key must be 16–255 printable ASCII characters.` Lengthen the
+key or drop characters outside printable ASCII.
+
+</Accordion>
+<Accordion title="422 IdempotencyKeyReused">
+
+The catalog message is `This Idempotency-Key was already used with a different request.` The
+payload changed. Mint a new key for the new payload.
+
+</Accordion>
+<Accordion title="409 IdempotencyInProgress">
+
+The catalog message is `This Idempotency-Key is still running. Retry after the given delay.`
+Wait for `Retry-After`, then send the same key. The client does this when `retry` is configured.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Calling](/docs/client/calling) — `idempotencyKey` and the retry rule
+- [Errors](/docs/reference/errors) — the four idempotency codes and their statuses
+- [The Architecture](/docs/understand/the-architecture) — a retry of one call runs once
+
+## Next
+
+<Cards>
+  <Card
+    title="Calling"
+    description="Client retry and Idempotency-Key."
+    href="/docs/client/calling"
+  />
+  <Card
+    title="Errors"
+    description="Statuses for the four idempotency codes."
+    href="/docs/reference/errors"
+  />
+  <Card
+    title="The Architecture"
+    description="One retry runs once. Two submits are two calls."
+    href="/docs/understand/the-architecture"
+  />
+</Cards>

package/site/content/docs/reference/index.mdx

@@ -1,7 +1,7 @@
 ---
 title: "Reference"
 description: "Lookup pages — CLI, config, fx, errors, security, and plugins."
-icon: "BookMarked"
+icon: "BookBookmark"
 source: "docs/spec/unified-theory.md"
 ---
 
@@ -23,6 +23,11 @@ Dense tables and command lists. Reach for these when you already know what you a
   />
   <Card title="fx" description="The complete fx surface and effects." href="/docs/reference/fx" />
   <Card title="Errors" description="OKE codes, denials, fixes." href="/docs/reference/errors" />
+  <Card
+    title="Idempotency"
+    description="One Idempotency-Key, one execution."
+    href="/docs/reference/idempotency"
+  />
   <Card
     title="Security"
     description="Host, Origin, planes, MCP posture."

package/site/content/docs/reference/meta.json

@@ -1,6 +1,6 @@
 {
   "title": "Reference",
-  "icon": "BookMarked",
+  "icon": "BookBookmark",
   "pages": [
     "index",
     "cli",
@@ -8,6 +8,7 @@
     "environment-variables",
     "fx",
     "errors",
+    "idempotency",
     "security",
     "i18n",
     "plugins",

package/site/content/docs/understand/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Understand",
   "icon": "Compass",
-  "pages": ["the-architecture", "try-it"]
+  "pages": ["the-architecture", "routing", "try-it"]
 }

package/site/content/docs/{elements/flow → understand}/routing.mdx

@@ -588,28 +588,29 @@ plus a handwritten `http.get("/links")`.
 
 ## Learn more
 
+- [The Architecture](/docs/understand/the-architecture) — derived routes, no hand-written table
+- [Try it](/docs/understand/try-it) — scaffold, run, and hit a stamped path
 - [HTTP](/docs/elements/flow/http) — verbs, envelopes, `http.resource`, live SSE
 - [Client](/docs/client/calling) — `api.links.get`, REST vs RPC, `$routes`
 - [Errors](/docs/reference/errors) — OKE1040 · OKE1030 · OKE1041 · OKE1045 · OKE1070 · OKE1072
-- [The Architecture](/docs/understand/the-architecture) — derived routes, no hand-written table
 - [Gate](/docs/elements/gate) — `.gate(...)` / `.public()` on the same trigger
 
 ## Next
 
 <Cards>
   <Card
-    title="HTTP"
-    description="REST verbs, RFC 10008 QUERY, CRUD mounts, and live SSE on Flow."
-    href="/docs/elements/flow/http"
+    title="The Architecture"
+    description="One law, eight elements, derived Manifest — where routes come from."
+    href="/docs/understand/the-architecture"
   />
   <Card
-    title="Client"
-    description="Typed caller — createClient, envelopes, REST from $routes."
-    href="/docs/client/calling"
+    title="Try it"
+    description="Scaffold shorter, run oke dev, and call a stamped path."
+    href="/docs/understand/try-it"
   />
   <Card
-    title="Consumers"
-    description="Signal workers, named Clock jobs, and SQL CDC — one Flow species."
-    href="/docs/elements/flow/consumers"
+    title="HTTP"
+    description="REST verbs, RFC 10008 QUERY, CRUD mounts, and live SSE on Flow."
+    href="/docs/elements/flow/http"
   />
 </Cards>

package/site/content/docs/understand/the-architecture.mdx

@@ -27,11 +27,11 @@ app.post("/signup", async (req, res) => {
 
 It works. It ships. Then a traffic spike, a silent failure, a compliance question, and a double-submit turn those four lines into six files — endpoint, queue, worker, Redis connection, mail client, audit table — that never agreed with each other about anything.
 
-**A payment webhook.** A provider confirms a charge. Mark the order paid. Simple — until the provider retries the same webhook twice during a network hiccup, and "mark the order paid" needs to somehow know it already ran.
+**A payment webhook.** A provider confirms a charge. Mark the order paid. The provider retries the same event during a hiccup. That attempt is a second run, visible in `fx.runs`. The fix is one line: a unique constraint or upsert on the provider's event id.
 
 **A nightly report.** Summarize yesterday's activity and email it to managers. Trivial — until a manager's access gets revoked at 11:58pm and the report that runs at midnight has no idea the permission it checked when the feature was built isn't the permission that holds right now.
 
-Three teams. Three domains. Nobody on any of them talked to the other two. And all three land on the identical fork: **something has to happen later, exactly once, provably — and nothing in the original four lines said what "provably" would end up costing.**
+Three teams. Three domains. Nobody on any of them talked to the other two. And all three land on the identical fork: **something has to happen later, and the original four lines never said where the retry, the receipt, or the duplicate would be visible.** The door makes that visible. The fix is one line.
 
 ### Follow one all the way through
 
@@ -49,7 +49,7 @@ The endpoint is fast again. It's also no longer one system — it's an endpoint,
 
 <SixSystemsDrift />
 
-From here the same pattern repeats on a longer clock. A support ticket reveals a job failed silently — nobody had configured retries, so you add them, and now a specific number (3? 5? with what backoff?) lives in a file that nobody will remember the reasoning for in six weeks. Compliance asks for proof of every email sent — you add a table written to from inside the worker, and now that worker has two jobs instead of one, quietly capable of disagreeing with itself if the second write fails. Someone double-clicks submit — two jobs enqueue, two emails send, and idempotency becomes a fact that has to live in two systems that were never introduced to each other.
+From here the same pattern repeats on a longer clock. A support ticket reveals a job failed silently — nobody had configured retries, so you add them, and now a specific number (3? 5? with what backoff?) lives in a file that nobody will remember the reasoning for in six weeks. Compliance asks for proof of every email sent — you add a table written to from inside the worker, and now that worker has two jobs instead of one, quietly capable of disagreeing with itself if the second write fails. Someone double-clicks submit — two jobs enqueue, two emails send. The duplicate is two runs. The fix is one line, a unique constraint or upsert, not a second protocol shared by a queue and a database.
 
 None of these were mistakes. Each one was the correct call, made by a competent engineer, in direct response to something that actually happened.
 
@@ -74,7 +74,7 @@ OKE removes the disagreement by removing the choice. It's one rule, in two parts
 
 **First: every trigger reduces to the same shape.** An HTTP request, a scheduled tick, a queue message, a database change — whatever wakes the code up, what follows has one identical anatomy: `on(Trigger) → Effects`. Not four systems that happen to look similar. One system, with four ways to wake it up.
 
-**Second: every effect passes through one door.** Nothing is allowed to touch a database, send an email, check a permission, or read the clock on its own — all of it goes through a single surface. Not because that's tidier. Because it's the only way retries, auditing, idempotency, and permission checks stop being infrastructure every team reinvents at the exact moment they get burned by not having it.
+**Second: every effect passes through one door.** Nothing is allowed to touch a database, send an email, check a permission, or read the clock on its own — all of it goes through a single surface. The Manifest lists every effect. Least privilege is enforced at runtime. Every run is recorded in `fx.runs`. Durability is one line in a known place — `signal.once` retries, or `durable` plus `fx.step` — not a new system.
 
 <FlowShape />
 
@@ -193,7 +193,9 @@ do: async (input, fx) => {
 };
 ```
 
-This one rule is what made the month-8 drift above avoidable: if `fx` is the only door, retries, auditing, and idempotency stop being separate systems teams build by hand, and become properties of the one boundary everything already passes through.
+This one rule is what made the month-8 drift visible: every effect is in the Manifest, every run is in `fx.runs`, and a duplicate is a second run you can see.
+A retried HTTP call can send one `Idempotency-Key`, so that retry runs once.
+A provider event still needs a unique constraint, because the provider does not send that header.
 
 ### Putting the five pieces together
 
@@ -223,14 +225,14 @@ export const signup = on(
 
 Nothing about the code above looks more complicated than the four lines that started the drift — because it isn't. The difference only shows up when the same pressure from that timeline hits it. Every fork was really the same question — _is this safe to retry, safe to audit, safe to run twice?_ — and now it has one home:
 
-| Then: a new system per incident                                      | Now: one door, fixed answer                                             |
-| -------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| **Week 2 spike** — hand-build a queue + worker to run the send later | Running later, safely, is asked of the trigger or the effect itself     |
-| **Month 2 silence** — a retry count in a worker nobody remembers     | Retries are a property of the `fx` boundary every effect passes through |
-| **Month 4 audit** — a `sent_emails` table written by hand from a job | What was sent is already known — nothing sends outside `fx`             |
-| **Month 6 double-submit** — dedup split across a queue and a DB      | One call through one door — no second path for a duplicate              |
+| Then: a new system per incident                                      | Now: the door makes it visible, and the fix is one line                                                                                                                                                                                                                                                            |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Week 2 spike** — hand-build a queue + worker to run the send later | The send is a Signal consumer. The Manifest lists it. The run is in `fx.runs`.                                                                                                                                                                                                                                     |
+| **Month 2 silence** — a retry count in a worker nobody remembers     | The retry count lives on `signal.once` (default 3) or on `durable` + `fx.step`, which skips a step already journaled. A failed HTTP request is not retried by `fx`.                                                                                                                                                |
+| **Month 4 audit** — a `sent_emails` table written by hand from a job | The send is an effect in the Manifest and a run in `fx.runs`. Channel records a receipt. The default receipt ledger is process-local memory.                                                                                                                                                                       |
+| **Month 6 double-submit** — dedup split across a queue and a DB      | A retry of one call runs once when it sends `Idempotency-Key`. Two submits are two calls unless the app passes the same key. Provider webhooks still need a unique constraint on the provider's event id, because providers do not send that header. `{ key }` serializes `once` per key. It does not deduplicate. |
 
-None of that required new code beyond what's above. It required the four lines to already be the kind of thing where those questions have a fixed answer, instead of a new one invented per team, per incident.
+The door makes each of those problems visible, and the fix is one line in a known place. The signup sample is safe to run twice once the user row has a unique constraint or an upsert. The second attempt is a second run in `fx.runs`.
 
 ### Five kinds of trigger