okengine 0.21.1 → 0.23.0

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/dragonfly.mdx

@@ -1,13 +1,13 @@
 ---
 title: "Dragonfly"
-description: "Multi-threaded Redis-wire runtime — OKE_STORE_KV_PASSWORD, memlock ulimit, no maxmemory-policy flag."
+description: "Default store.kv image — multi-threaded Redis-wire runtime, memlock ulimit, OKE_STORE_KV_PASSWORD."
 icon: "Zap"
 source: "docs/spec/unified-theory.md"
 ---
 
-Dragonfly is a multi-threaded, memory-efficient reimplementation of the Redis protocol —
-same `redis://` wire format, different engine. Slots behind the same `redis` driver with
-zero Flow changes.
+Dragonfly is the default `store.kv` image in `dev` and `prod`: a multi-threaded Redis-protocol engine.
+Same `redis://` wire format and the same `redis` driver, so Flows do not change.
+Pin Redis or Valkey when you want those engines instead.
 
 <Callout title="The one rule">
   Driver id stays `redis`. Dragonfly is an image choice — every KV call through `fx.store` behaves
@@ -23,7 +23,7 @@ zero Flow changes.
 
 ```typescript title="oke.config.ts"
 images: {
-  "store.kv": "docker.dragonflydb.io/dragonflydb/dragonfly",
+  "store.kv": "docker.dragonflydb.io/dragonflydb/dragonfly:v2.0.0",
 },
 ```
 

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

@@ -51,15 +51,15 @@ Driver id stays `redis` for every image below.
 
 <Cards>
   <Card
-    title="Redis"
-    description="Default store.kv — requirepass + maxmemory."
-    href="/docs/recipes/redis"
+    title="Dragonfly"
+    description="Default store.kv — multi-threaded Redis-wire runtime."
+    href="/docs/recipes/dragonfly"
   />
   <Card title="Valkey" description="BSD-licensed Redis-wire fork." href="/docs/recipes/valkey" />
   <Card
-    title="Dragonfly"
-    description="Multi-threaded Redis-wire runtime."
-    href="/docs/recipes/dragonfly"
+    title="Redis"
+    description="Opt-in Redis Open Source — requirepass + maxmemory."
+    href="/docs/recipes/redis"
   />
 </Cards>
 

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/recipes/postgres.mdx

@@ -106,11 +106,11 @@ Scale out with [PgDog](/docs/recipes/pgdog) so `N × Bun.SQL pool` does not exha
   Recreate `store-sql` after a recipe change — the data volume can stay.
 </Callout>
 
-| Step    | What you do                                                       |
-| ------- | ----------------------------------------------------------------- |
-| Preload | Recipe already sets `shared_preload_libraries=pg_stat_statements` |
-| Create  | `CREATE EXTENSION IF NOT EXISTS pg_stat_statements`               |
-| Console | Store → SQL band → **Performance**                                |
+| Step    | What you do                                                            |
+| ------- | ---------------------------------------------------------------------- |
+| Preload | Recipe already sets `shared_preload_libraries=pg_stat_statements`      |
+| Create  | `oke db push` runs `CREATE EXTENSION IF NOT EXISTS pg_stat_statements` |
+| Console | Store → SQL band → **Performance**                                     |
 
 Default `postgres:18-alpine` does **not** ship `hypopg` / `index_advisor`. Pin the
 opt-in image when you want Suggest indexes:
@@ -137,8 +137,8 @@ set. Re-run `oke dev` so the stack writes `.env.local`, or export
 <Accordion title="PgStatStatementsNotPreloaded">
 
 The Console Performance view needs the library preloaded **and** the extension
-created. Recreate `store-sql` so the new `command` applies, then run
-`CREATE EXTENSION IF NOT EXISTS pg_stat_statements`.
+created. Recreate `store-sql` so the new `command` applies, then run `oke db push`
+(or open Performance again — it creates the extension when preload is already on).
 
 Existing clusters that started before this recipe change keep the old
 postmaster flags until recreate.
@@ -167,5 +167,9 @@ Postgres refusing auth.
 <Cards>
   <Card title="PgDog" description="Add pooling in front of Postgres." href="/docs/recipes/pgdog" />
   <Card title="Neon" description="A managed alternative." href="/docs/providers/neon" />
-  <Card title="Redis" description="The default store.kv image." href="/docs/recipes/redis" />
+  <Card
+    title="Dragonfly"
+    description="The default store.kv image."
+    href="/docs/recipes/dragonfly"
+  />
 </Cards>

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

@@ -1,13 +1,13 @@
 ---
 title: "Redis"
-description: "Default store.kv image — OKE_STORE_KV_PASSWORD, maxmemory policy, ephemeral data, REDIS_URL."
+description: "Opt-in store.kv image — OKE_STORE_KV_PASSWORD, maxmemory policy, ephemeral data, REDIS_URL."
 icon: "Zap"
 source: "docs/spec/unified-theory.md"
 ---
 
-Redis is the default `store.kv` image in `dev` and `prod`. `oke docker` matches image
-references containing `redis` or `keydb` and derives a password-required server — no
-unauthenticated instance.
+Redis is an opt-in `store.kv` image. The default pin is [Dragonfly](/docs/recipes/dragonfly).
+`oke docker` matches image references containing `redis` or `keydb` and derives a
+password-required server — no unauthenticated instance.
 
 <Callout title="The one rule">
   The driver id stays `redis` for every Redis-wire image — Redis, Valkey, Dragonfly, or a managed

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

@@ -134,7 +134,8 @@ Override app / console / mcp listen ports in `oke.config.ts` `ports` — see
 | `docker`     | Derive compose · clean leftover stacks                       | `--prod\|-p`, `--out`, `--config`, `--manifest`; sub `clean`                                                                                              |
 | `images`     | List / pin digests                                           | `list` · `pin`                                                                                                                                            |
 | `build`      | Tree-shaken bundle                                           | `--target\|-t bun\|node\|edge`, `--entry`, `--outdir`                                                                                                     |
-| `eval`       | Prompt eval sets (CI gate)                                   | `--manifest`                                                                                                                                              |
+| `eval`       | Prompt eval sets (CI gate)                                   | `--manifest`, `--certify` (decision seed certificate; prompt evals stay as they are)                                                                      |
+| `decide`     | Write a decision lockfile from the operator candidate        | `promote <name>` (`--origin`, `--lock`)                                                                                                                   |
 | `ai`         | Configure AI driver + models                                 | `setup` (`--provider`, `--chat`, `--vision`, `--embed`, `--yes`)                                                                                          |
 | `branch`     | Fork journaled state                                         | `<name>`, `--at\|-a`                                                                                                                                      |
 | `replay`     | Re-invoke a past Flow from Runs                              | `--request-id\|-r`, `--entry`, `--dry-run`, `--live`                                                                                                      |

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

@@ -136,11 +136,13 @@ sql: {
 },
 ```
 
-| Field      | Type              | Meaning                                     |
-| ---------- | ----------------- | ------------------------------------------- |
-| `url`      | connection string | Overrides the env-var resolution            |
-| `pool`     | `{ max?, min? }`  | SQL pool sizing                             |
-| `replicas` | `string[]`        | Read-only routing targets (read flows only) |
+| Field      | Type              | Meaning                                                                           |
+| ---------- | ----------------- | --------------------------------------------------------------------------------- |
+| `url`      | connection string | Overrides the env-var resolution                                                  |
+| `pool`     | `{ max?, min? }`  | `max` is the Bun.SQL pool size. Unset keeps 8. `min` is accepted and not applied  |
+| `replicas` | `string[]`        | Read-only flows use these URLs. Each replica opens its own pool at the same `max` |
+
+A store `max` of 20 does not share a pool another part of the process already opened at 8. Writes stay on the primary.
 
 ## images
 
@@ -150,18 +152,18 @@ Nested pins by element role — vendor choice lives here, never in driver ids:
 images: {
   store: {
     sql: "postgres:18-alpine",
-    kv: "redis:8-alpine",
+    kv: "docker.dragonflydb.io/dragonflydb/dragonfly:v2.0.0",
     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",
 },
 ```
 
 Omitted image keys mean no container for that role. When both `store.sql` and `pgdog` are pinned, `DATABASE_URL` points at PgDog — see [Store](/docs/elements/store#multiple-environments).
 
-For `store.kv`, pin Redis (default), Valkey, or Dragonfly — driver id stays `redis`.
+For `store.kv`, pin Dragonfly (default), Redis, or Valkey — driver id stays `redis`.
 `{ durable: true }` KV lives in SQL (`oke_kv` on `DATABASE_URL`), not a second Redis image.
 
 Compose does not manage AI inference — [OpenRouter](/docs/recipes/openrouter) or BYO

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.
@@ -233,12 +240,13 @@ elements.
 
 ## AI
 
-| Signature                                             | Records                   | Returns                                                                                                  |
-| ----------------------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `fx.ask(prompt, input?, { via?, tools?, maxSteps? })` | `ask` (+ `call` per tool) | Object validated against the prompt's `out`                                                              |
-| `fx.run(agent, input?)`                               | `ask`                     | Agent result                                                                                             |
-| `fx.stream(model, { prompt?, data?, via? })`          | `ask`                     | `AsyncIterable<string>` — real driver stream; cancels via ambient `fx.signal` (HTTP disconnect included) |
-| `fx.search(embed, query, { topK? })`                  | `read`                    | Matches from the index/embed                                                                             |
+| Signature                                             | Records                   | Returns                                                                                                                             |
+| ----------------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `fx.ask(prompt, input?, { via?, tools?, maxSteps? })` | `ask` (+ `call` per tool) | Object validated against the prompt's `out`                                                                                         |
+| `fx.run(agent, input?)`                               | `ask`                     | Agent result                                                                                                                        |
+| `fx.stream(model, { prompt?, data?, via? })`          | `ask`                     | `AsyncIterable<string>` — real driver stream; cancels via ambient `fx.signal` (HTTP disconnect included)                            |
+| `fx.search(embed, query, { topK? })`                  | `read`                    | Matches from the index/embed                                                                                                        |
+| `fx.decide(decision, input)`                          | `decide`                  | `$.<question>.how` is `auto`, `reviewed`, or `abstained`. `audited` is a boolean flag, not a `how`. Abstain makes the value `null`. |
 
 AI calls are nondeterministic: journaling is forced on and auto-cache disabled around them. `tools` are Flow refs — each model tool call goes through `fx.call` (same capability and Runs path).
 
@@ -340,9 +348,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>