okengine 0.12.0 → 0.14.1

package/manifest.v1.schema.json

@@ -111,6 +111,11 @@
       "type": "string",
       "pattern": "^(sql|kv|files|index):.+$"
     },
+    "SignalResourceRef": {
+      "description": "Dead-letter read via fx.deadLetters — signal:<name>, not a store facet.",
+      "type": "string",
+      "pattern": "^signal:.+$"
+    },
     "SignalRef": {
       "type": "string",
       "minLength": 1
@@ -145,7 +150,8 @@
               {
                 "const": "runs",
                 "description": "Runs wide-event store via fx.runs (observability read)."
-              }
+              },
+              { "$ref": "#/$defs/SignalResourceRef" }
             ]
           },
           "uniqueItems": true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.12.0",
+  "version": "0.14.1",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {
@@ -271,6 +271,6 @@
     "react": "^19.2.8"
   },
   "engines": {
-    "bun": ">=1.3.14"
+    "bun": ">=1.4.0"
   }
 }

package/site/content/docs/ai/mcp.mdx

@@ -1,11 +1,13 @@
 ---
 title: "MCP"
-description: "The runtime MCP server on :6535 — read tools for Manifest, schemas, effects, and traces, write actions gated by per-call human confirmation — plus the read-only docs MCP on :6536."
+description: "OKE serves MCP on :6535 so agents can operate a running app, and apps consume external MCP servers as allowlisted tools on the same fx.call path."
 icon: "Plug"
 source: "docs/spec/unified-theory.md"
 ---
 
-OKE serves an [MCP](https://modelcontextprotocol.io) endpoint on port **6535** so an AI agent can operate your running app: read its Manifest and traces, and take a small set of safe actions. It speaks JSON-RPC over HTTP (MCP protocol `2024-11-05`), requires a Bearer token **even on localhost**, and never forwards that token upstream — adapters receive structured operator ids instead.
+Two directions, same protocol. **Serve:** OKE exposes your running app on port **6535** so an agent can read the Manifest and take confirmed actions. **Consume:** your Flows call _external_ MCP servers as tools — declared on `ai.mcpServer`, dispatched through `fx.call`.
+
+The server on **6535** speaks JSON-RPC over HTTP (MCP protocol `2024-11-05`), requires a Bearer token **even on localhost**, and never forwards that token upstream — adapters receive structured operator ids instead.
 
 <Callout title="The one rule">
   MCP inherits the operator's capability and can never exceed it. Server-level controls alone are
@@ -96,6 +98,29 @@ Consumed tokens cannot be replayed; the next write needs a new confirmation. A m
 
 The docs content ships inside the `okengine` package, so the index your agent searches is exactly the version you have installed. If the surface cannot boot (missing content, busy port), `oke dev` prints `Docs MCP skipped — …` and continues — docs search never takes your dev session down.
 
+## Consume — `ai.mcpServer`
+
+Your app can _call_ other MCP servers. Those tools are not a second loop — they join `fx.ask` / `ai.agent` the same way a Flow tool does.
+
+```typescript
+export const github = ai.mcpServer("github", {
+  url: "https://mcp.example/github",
+  auth: { bearer: githubToken },
+  tools: ["create_issue"], // required allowlist
+});
+
+await fx.ask(triage, input, { tools: [github.tool("create_issue")] });
+```
+
+| Rule       | Meaning                                                                                           |
+| ---------- | ------------------------------------------------------------------------------------------------- |
+| Allowlist  | `tools` is required. Extra names from `tools/list` are dropped.                                   |
+| Capability | `mcp:<server>/<tool>` on `effects.calls` — undeclared throws **OKE1007**.                         |
+| Transport  | `url` (Streamable HTTP) **or** `command` + `args` (stdio). Not both.                              |
+| Cancel     | HTTP aborts the fetch / SSE stream. stdio sends `notifications/cancelled` then kills the process. |
+
+Console draws each declared server as one **AI** node on the flow graph; Units chips read `Call github → create_issue`; traces label the effect **MCP call**. There is no separate MCP page or connect UI.
+
 ## Learn more
 
 - [Agent contracts](/docs/ai/skills) — what agents are taught about the system they operate

package/site/content/docs/elements/ai.mdx

@@ -68,14 +68,15 @@ export const triage = smart.prompt("ticket-triage", {
 
 </Steps>
 
-## The four building blocks
+## The building blocks
 
-| Declaration                | Produces                                                           |
-| -------------------------- | ------------------------------------------------------------------ |
-| `ai.model(name, opts)`     | Logical model binding — provider / tier / concrete model id        |
-| `model.prompt(name, opts)` | Versioned prompt with typed in/out, evals, budget                  |
-| `ai.embed(name, opts)`     | Embedding pipeline into a `store.index` (searched via `fx.search`) |
-| `ai.agent(name, opts)`     | Bounded agent whose tools are **your own flows**                   |
+| Declaration                | Produces                                                                        |
+| -------------------------- | ------------------------------------------------------------------------------- |
+| `ai.model(name, opts)`     | Logical model binding — provider / tier / model id / optional `driverId`        |
+| `model.prompt(name, opts)` | Versioned prompt with typed in/out, evals, budget                               |
+| `ai.embed(name, opts)`     | Embedding pipeline into a `store.index` (searched via `fx.search`)              |
+| `ai.agent(name, opts)`     | Bounded agent whose tools are **your own flows**                                |
+| `ai.mcpServer(name, opts)` | External MCP server — allowlisted tools join `fx.call` as `mcp:<server>/<tool>` |
 
 <AiBlocks />
 
@@ -105,9 +106,11 @@ const out = await fx.ask(summarizeNote, { title, body });
 // out.via is the logical model that answered
 ```
 
-Resolution: `fx.ask(…, { via })` overrides `prompt.via`, else the prompt’s bound model. On each model the runtime retries **once** for retryable failures (timeout / 429 / 5xx / network), then advances. Permanent failures (401 / other 4xx / schema invalid) stop the chain. When every eligible attempt fails, `fx.ask` throws — map that to a typed error in the flow (no silent text excerpt).
+Resolution: `fx.ask(…, { via })` overrides `prompt.via`, else the prompt’s bound model. On each model the runtime retries **once** for retryable failures (timeout / 429 / 5xx / network), then advances.
 
-`timeout` uses the same duration vocabulary as Clock (`"30s"`, `"2m"`, or a millisecond number). Ask-time `fx.ask(…, { timeout: "10s" })` overrides the prompt. Omit = no artificial cap. Cost caps stay on `budget`.
+Permanent failures (401 / other 4xx / schema invalid / client disconnect / `maxCostPerCall` exceeded) stop the chain. When every eligible attempt fails, `fx.ask` throws — map that to a typed error in the flow (no silent text excerpt).
+
+`timeout` uses the same duration vocabulary as Clock (`"30s"`, `"2m"`, or a millisecond number). Ask-time `fx.ask(…, { timeout: "10s" })` overrides the prompt. Omit = no artificial cap. `budget.maxCostPerCall` is enforced at runtime (not just observed). Set `driverId` on a model to open a different protocol than the app default.
 
 ## Declared guardrails
 
@@ -126,6 +129,22 @@ const result = await fx.ask(triage, input, {
 });
 ```
 
+External MCP tools take the same path. Declare a server with a **required** allowlist, then pass `server.tool("…")` — never whatever `tools/list` happens to expose:
+
+```typescript
+export const github = ai.mcpServer("github", {
+  url: "https://mcp.example/github",
+  auth: { bearer: githubToken },
+  tools: ["create_issue"],
+});
+
+await fx.ask(triage, input, {
+  tools: [github.tool("create_issue")],
+});
+```
+
+Capability refs are `mcp:<server>/<tool>`. An undeclared call throws **OKE1007**. See [MCP](/docs/ai/mcp).
+
 ## Agents with real guardrails
 
 An agent's tools are your flows — each carrying its own gates, effects, and typed errors, so the agent can never do anything a flow couldn't:
@@ -139,7 +158,7 @@ export const support = ai.agent("support", {
 });
 ```
 
-`maxSteps` bounds the loop; `budget.maxCostPerRun` bounds the spend. Both are declared, so "the agent ran away" is a violated contract, not a surprise. `fx.run(support, { message })` uses the same tool loop and the same `fx.call` dispatch as `fx.ask(…, { tools })`.
+`maxSteps` bounds the loop; `budget.maxCostPerRun` is enforced after the run. Both are declared, so "the agent ran away" is a violated contract, not a surprise. `fx.run(support, { message })` uses the same tool loop and the same `fx.call` dispatch as `fx.ask(…, { tools })`.
 
 ## Rate limits via Gate
 
@@ -157,7 +176,20 @@ Use `keyBy: "ip"` on public unauthenticated AI edges. Cost caps stay on prompt/a
 
 ## Streaming
 
-`fx.stream(model, { prompt })` yields real provider tokens (Ollama NDJSON, OpenAI-compatible SSE). Cancel by aborting the ambient signal — the same one `fx.all` / `fx.race` already use. Drivers without `stream` fail loud (no stub echo).
+`fx.stream(model, { prompt, via? })` yields real provider tokens (Ollama NDJSON, OpenAI-compatible SSE). Cancel by aborting the ambient signal — the same one `fx.all` / `fx.race` already use. Drivers without `stream` fail loud (no stub echo).
+
+Return those chunks on HTTP with `fx.json.stream(...)`. The kernel answers `text/event-stream` (`data:` frames, then `data: [DONE]`). JSON flows stay buffered `{ data, error }`.
+
+```typescript
+on(
+  http.post("/complete").gate.public,
+  flow("chat.complete", {
+    do: (input, fx) => fx.json.stream(fx.stream(smart, { prompt: input.prompt })),
+  }),
+);
+```
+
+Disconnect cancels the provider call automatically (`request.signal` → ambient abort). An `AbortError` from hang-up does not retry or advance `via`. Console Traces stay empty until the stream closes — then the run is one completed row whose duration covers the open stream, not just time-to-first-byte.
 
 ## PII cannot leak by accident
 
@@ -305,6 +337,11 @@ Capability pins and Call API pass `name@version`. `fx.ask` resolves the bare
 prompt id. A pin that does not match `prompt.version` throws
 `ai: unknown prompt "name@version"`.
 
+</Accordion>
+<Accordion title="OKE1007 when the model calls an MCP tool">
+
+Add `mcp:<server>/<tool>` to that flow’s `effects.calls` — the same token as `fx.call`. The allowlist on `ai.mcpServer` is not a capability grant.
+
 </Accordion>
 <Accordion title="An agent looped and burned budget">
 
@@ -313,6 +350,15 @@ Bound it at declaration: `maxSteps` caps iterations, `budget.maxCostPerRun` caps
 `fx.ask` stamps `promptVersion` on the run. Cost is recorded only when the
 driver reports `usage.cost` — tokens land on the ask journal either way.
 
+</Accordion>
+<Accordion title="The client hung up but the model kept generating">
+
+HTTP flows install `request.signal` as the ambient abort. `fx.ask` / `fx.stream` /
+`fx.run` cancel the provider fetch. Return tokens with `fx.json.stream(fx.stream(...))`
+so disconnect is observable.
+
+A hang-up is `AbortError` — it does not retry or advance `via`.
+
 </Accordion>
 </Accordions>
 
@@ -320,6 +366,7 @@ driver reports `usage.cost` — tokens land on the ask journal either way.
 
 - [Flow](/docs/elements/flow) — `fx.ask` and `fx.search` inside `do`
 - [Store](/docs/elements/store) — `store.index`, the home of embeddings
+- [MCP](/docs/ai/mcp) — serve the app to agents, or consume external servers as tools
 
 ## Next
 

package/site/content/docs/elements/clock.mdx

@@ -28,7 +28,7 @@ export const purgeOld = on(
   every("1h"),
   flow("links.purgeOld", {
     do: async (_, fx) => {
-      const cutoff = fx.clock.now() - 30 * 24 * 60 * 60 * 1000; // 30 days
+      const cutoff = fx.clock.ago("30d");
       await fx.store(db).delete(links).where(lt(links.createdAt, cutoff));
     },
   }),
@@ -68,12 +68,15 @@ export const sendDaily = on(
 <Step>
 ### Ask for time inside flows
 
-`fx.clock` is the only clock a flow knows:
+`fx.clock` is the only clock a flow knows. Instants stay epoch-ms; spans use the same
+duration strings as `every()` and `sleep()`:
 
 ```typescript
 do: async (input, fx) => {
-  const now = fx.clock.now(); // epoch-ms, injectable
-  await fx.clock.sleep("wait-for-payment", "7d"); // durable — survives restarts on a shared journal
+  const cutoff = fx.clock.ago("30d");
+  const expiresAt = fx.clock.fromNow("14d");
+  const window = input.createdAt + fx.clock.duration("7d");
+  await fx.clock.sleep("wait-for-payment", "7d");
 };
 ```
 
@@ -90,13 +93,25 @@ difference.
 
 ### `clock()` options
 
-| Option        | Type    | Default | Meaning                                                        |
-| ------------- | ------- | ------- | -------------------------------------------------------------- |
-| `cron`        | string  | —       | Cron expression `m h dom mon dow` (this or `every` required)   |
-| `every`       | string  | —       | Fixed interval: `"30s"` · `"10m"` · `"1h"` · `"7d"`            |
-| `timezone`    | string  | `"UTC"` | IANA timezone for cron evaluation                              |
-| `overridable` | boolean | `false` | Allow the Console to **edit** the schedule (pause is separate) |
-| `description` | string  | —       | Human title in the Console (falls back to the clock name)      |
+| Option        | Type    | Default | Meaning                                                                                                                  |
+| ------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `cron`        | string  | —       | Five-field crontab (`m h dom mon dow`), plus steps, ranges, lists, names, `@hourly`, `@daily` (this or `every` required) |
+| `every`       | string  | —       | Fixed interval: `"30s"` · `"10m"` · `"1h"` · `"7d"`                                                                      |
+| `timezone`    | string  | `"UTC"` | IANA timezone for cron evaluation                                                                                        |
+| `overridable` | boolean | `false` | Allow the Console to **edit** the schedule (pause is separate)                                                           |
+| `description` | string  | —       | Human title in the Console (falls back to the clock name)                                                                |
+
+### `fx.clock`
+
+| Call                 | Returns | Meaning                                          |
+| -------------------- | ------- | ------------------------------------------------ |
+| `now()`              | instant | Injected epoch-ms                                |
+| `ago("30d")`         | instant | now − duration                                   |
+| `fromNow("14d")`     | instant | now + duration                                   |
+| `duration("7d")`     | span ms | Offset a stored instant (`createdAt + duration`) |
+| `sleep(label, "7d")` | —       | Durable sleep                                    |
+
+Same duration strings as `every()`: `"200ms"` · `"30s"` · `"2m"` · `"1h"` · `"7d"`. A `"d"` is 86_400_000 ms, not a calendar day. Unknown strings parse as `0`.
 
 ## Sleeping inside a flow
 
@@ -136,7 +151,7 @@ Simple daily crons (`M H * * *`) in a DST-observing zone can hit a **gap** (spri
 
 Detection attaches `dstAmbiguity` on the cron row and the Console shows it. `oke doctor` does not check DST. The scheduler does not rewrite the expression.
 
-**Consequence:** fall-back days can list two civil instants an hour apart. The default leader lease (30s) is shorter than that gap, so a lease alone is not a “fire once on overlap” policy. Prefer UTC, or a wall time outside the transition window, when double-fire would hurt.
+**Consequence:** firing follows crontab. A spring gap runs at the next valid instant (shifted). A fall overlap fires **once** (first occurrence). Prefer UTC when a shifted spring fire would hurt.
 
 ## Per-environment drivers
 

package/site/content/docs/elements/flow.mdx

@@ -130,7 +130,9 @@ export const findOrder = on(
 
 ### signal — another flow emits
 
-The producer emits through `fx` (transactionally with its writes); the consumer is the same species — no `subscribe()`, no listener registration:
+The producer emits through `fx`. For `once` and `broadcast` the consumer is the same species —
+`on(signal, flow)`, no `subscribe()` registration. `live` replay is the exception: `bus.live()` on
+the server, not a Flow.
 
 ```typescript
 await fx.emit(orderPlaced, { orderId: id }); // inside the producing flow
@@ -154,7 +156,7 @@ on(
   every("1h"),
   flow("sessions.sweepExpired", {
     do: async (_, fx) => {
-      const cutoff = fx.clock.now() - 30 * 24 * 60 * 60 * 1000;
+      const cutoff = fx.clock.ago("30d");
       await fx.store(db).delete(sessions).where(lt(sessions.createdAt, cutoff));
     },
   }),
@@ -198,12 +200,13 @@ Everything a flow may touch, on one object:
 | ------------------------------------------- | --------------- | -------------------------------------------------- |
 | `fx.store(db).select/insert/…`              | read / write    | SQL, KV, files, index sessions                     |
 | `fx.emit(signal, payload)`                  | emit            | Publish a signal (transactional with writes)       |
+| `fx.deadLetters(signal)`                    | read            | Dead-lettered messages for that signal             |
 | `fx.send(template, opts)`                   | send            | Reach a human (email · SMS · …)                    |
 | `fx.ask(prompt, input)`                     | ask             | Call a versioned AI prompt                         |
 | `fx.run(agent, input)`                      | ask             | Run a bounded agent                                |
 | `fx.call(flow, input)`                      | call            | Invoke another flow                                |
 | `fx.vault.get(contract)`                    | secret          | Read a secret (`Redacted`; logs masked)            |
-| `fx.clock.now()` / `.sleep(…)`              | —               | Injected time / durable sleep                      |
+| `fx.clock.now/ago/fromNow/duration/sleep`   | —               | Injected instants, spans, durable sleep            |
 | `fx.cache.get/set`                          | —               | Shared cache with effect-aware invalidation        |
 | `fx.step(name, fn, { undo? })`              | —               | Named durable step — optional LIFO undo on failure |
 | `fx.all` / `fx.race` / `fx.retry`           | —               | Structured concurrency + backoff retry             |

package/site/content/docs/elements/signal.mdx

@@ -71,7 +71,8 @@ export const sendConfirmation = on(
 
 </Steps>
 
-That's the loop: declare → `fx.emit` → `on(signal, flow)`. The runtime handles routing, retries, and dead-lettering.
+That's the loop for `once` and `broadcast`: declare → `fx.emit` → `on(signal, flow)`.
+`live` keeps the same emit; the listener is `bus.live()`, not a Flow.
 
 ## The three delivery physics
 
@@ -96,7 +97,7 @@ One placed order can need all three physics at once — pick a signal per job, n
 
 | Signal          | Mode        | Job                                                         |
 | --------------- | ----------- | ----------------------------------------------------------- |
-| `order-placed`  | `once`      | Fulfillment job — competing workers, retries, DLQ           |
+| `order-placed`  | `once`      | One job — competing workers, retries, DLQ                   |
 | `order-changed` | `broadcast` | Fan-out — cache invalidation **and** customer notification  |
 | `order-status`  | `live`      | Status feed — retained history a late subscriber can replay |
 
@@ -107,7 +108,7 @@ import { z } from "zod";
 export const orderPlaced = signal("order-placed", {
   schema: z.object({ orderId: z.string(), total: z.number() }),
   delivery: "once",
-  retries: 2,
+  retries: 3,
   deadLetter: true,
 });
 
@@ -126,25 +127,43 @@ export const orderStatus = signal("order-status", {
 });
 ```
 
-`once` — two fulfillment workers compete; **exactly one** claims each message (at-least-once; make the handler idempotent):
+A Flow **writes** all three tapes. `once` / `broadcast` **listen** with `on(signal, flow)`. `live` does not.
 
-```typescript title="src/flows/fulfillment/on-order.ts"
-on(
+```typescript title="src/flows/orders/place.ts"
+export const placeOrder = on(
+  http.post("/orders").gate.public,
+  flow("orders.place", {
+    in: z.object({ id: z.string(), total: z.number() }),
+    do: async (input, fx) => {
+      await fx.emit(orderPlaced, { orderId: input.id, total: input.total });
+      await fx.emit(orderChanged, { orderId: input.id, kind: "placed" });
+      await fx.emit(orderStatus, { orderId: input.id, status: "placed" });
+      await fx.emit(orderStatus, { orderId: input.id, status: "fulfilling" });
+      await fx.emit(orderStatus, { orderId: input.id, status: "shipped" });
+    },
+  }),
+);
+```
+
+Stacked status emits are so replay is visible in one request. A real app emits as the order moves.
+
+`once` — the listener is `on(orderPlaced, flow)`. Two workers compete; **exactly one** claims each message (at-least-once; make the handler idempotent):
+
+```typescript title="src/flows/orders/send-confirmation.ts"
+export const sendConfirmation = on(
   orderPlaced,
-  flow("fulfillment.onOrder", {
-    do: async ({ orderId }, fx) => {
-      await fx.emit(orderChanged, { orderId, kind: "placed" });
-      await fx.emit(orderStatus, { orderId, status: "fulfilling" });
-      await fx.emit(orderStatus, { orderId, status: "shipped" });
+  flow("orders.sendConfirmation", {
+    do: async (input, fx) => {
+      await fx.send(orderConfirmed, { to: "user-1", data: input });
     },
   }),
 );
 ```
 
-`broadcast` — every subscriber gets its own copy of the same domain event:
+`broadcast` — every `on(orderChanged, flow)` gets its own copy. Neither Flow knows the other exists:
 
 ```typescript title="src/flows/orders/side-effects.ts"
-on(
+export const invalidateCache = on(
   orderChanged,
   flow("cache.onOrderChanged", {
     do: async ({ orderId }, fx) => {
@@ -153,7 +172,7 @@ on(
   }),
 );
 
-on(
+export const notifyCustomer = on(
   orderChanged,
   flow("notify.onOrderChanged", {
     do: async ({ orderId }, fx) => {
@@ -163,27 +182,38 @@ on(
 );
 ```
 
-`live` — retain status updates and replay the **full history** to a late `bus.live()` subscriber (tracking UI, ops feed).
+`live` — retain the tape. A late subscriber replays **full history** (`placed → fulfilling → shipped`), then keeps going.
 
-Today that subscription is a **server-side** bus API. `createClient` does not yet expose SSE / WebSocket / `client.live` — see [Client](/docs/reference/client#signal-and-live-queries).
+The listener is **`bus.live()`**, not `on(orderStatus, flow)`. `on(signal, flow)` does not replay retained live payloads. Today that API is server-side; `createClient` has no SSE / WebSocket / `client.live` yet — see [Client](/docs/reference/client#signal-and-live-queries).
 
 ```typescript
-await fx.emit(orderStatus, { orderId, status: "placed" });
+const bus = app.bootResult?.signal?.bus;
+if (!bus) throw new Error("signal runtime not booted");
 
-// Late subscriber (server / test harness) receives placed → fulfilling → shipped.
 const unsub = await bus.live("order-status", (payload) => {
-  /* push to UI */
+  /* placed → fulfilling → shipped */
 });
 ```
 
-**Why separate signals:** delivery is fixed per declaration. Competing work stays on `once`; fan-out stays on `broadcast`; the client-visible timeline stays on `live`. Switching a word later is cheap; mixing physics on one name is not.
+**Why separate signals:** delivery is fixed per declaration. Competing work stays on `once`; fan-out stays on `broadcast`; the timeline stays on `live`. Switching a word later is cheap; mixing physics on one name is not.
 
 ## When delivery fails
 
 `once` signals retry automatically. Every attempt keeps a **typed failure reason**, and the full attempt history survives into the DLQ — so when a message lands there you see _why_ each attempt failed, not just that it did.
 
+Query that queue from a Flow with `fx.deadLetters(signal)` — same handle as `fx.emit`. The compiler stamps `reads: ["signal:<name>"]`; another signal throws **OKE1001**.
+
 The **Console** (`:6533` → `/overview`) shows emit and consume on the graph, and delivery attempts in Traces — no separate broker UI to run.
 
+```typescript
+on(
+  http.get("/notifications/failed"),
+  flow("notifications.failed", {
+    do: async (input, fx) => fx.json.withQuery(await fx.deadLetters(orderPlaced), input),
+  }),
+);
+```
+
 <Callout title="Orphan emits and schema fail loudly">
   Zero subscribers throws **OKE1042** unless `optional: true`. A payload that fails the signal's
   Standard Schema throws **OKE1043** before the message is staged — same `validate()` path as Flow
@@ -225,9 +255,10 @@ Committed `once` messages survive process death. A claim sets `lockedBy` and a v
 `live` retains every delivered message and replays the **full history** to a late `bus.live()` subscriber. There is no TTL or max-count window on that retention today (the Console payload monitor shows only the newest 50 for display).
 
 <Callout title="Client subscription is not shipped yet">
-  `delivery: "live"` means the **driver** retains and replays. `createClient` has no SSE / WebSocket
-  / `client.live` yet — poll an HTTP Flow or use `bus.live()` server-side. See [Client · Signal and
-  live queries](/docs/reference/client#signal-and-live-queries).
+  `delivery: "live"` means the **driver** retains and replays. Listen with `bus.live()` on the
+  server — not `on(signal, flow)`. `createClient` has no SSE / WebSocket / `client.live` yet — poll
+  an HTTP Flow. See [Client · Signal and live
+  queries](/docs/reference/client#signal-and-live-queries).
 </Callout>
 
 ## Orphaned signal config
@@ -258,7 +289,10 @@ Pairing an arbitrary Store insert with emit inside **one** shared SQL transactio
 <Accordions>
 <Accordion title="Emit fails with OKE1042 (no subscriber)">
 
-You emitted a signal that nobody currently subscribes to. Wire a consumer with `on(signal, flow)` before emit, or set `optional: true` when zero-subscriber emits are intentional.
+You emitted a signal that nobody currently subscribes to. For `once` and `broadcast`, wire
+`on(signal, flow)` before emit.
+
+`live` listeners are `bus.live()`, not a Flow — set `optional: true` when they may connect later.
 
 </Accordion>
 <Accordion title="Emit fails with OKE1043 (schema)">
@@ -268,7 +302,18 @@ The payload failed the signal's Standard Schema at emit time — nothing was sta
 </Accordion>
 <Accordion title="A message keeps retrying and then disappears">
 
-When `attempts > retries` the message moves to the DLQ (if `deadLetter: true`) — it is not lost. Open Console → Flows, inspect the typed failure on the trace, fix the consumer, then replay.
+When `attempts > retries` the message moves to the DLQ (if `deadLetter: true`) — it is not lost. List it from a Flow with `fx.deadLetters(signal)`, or open Console → Flows, inspect the typed failure, fix the consumer, then replay.
+
+</Accordion>
+<Accordion title="fx.deadLetters throws OKE1001">
+
+The flow read a signal it did not declare. The compiler infers `reads: ["signal:<name>"]` from `fx.deadLetters(signal)`. A different handle needs its own read.
+
+</Accordion>
+<Accordion title="on(liveSignal, flow) never replays history">
+
+`on(signal, flow)` listens for `once` and `broadcast`. `live` replay is `bus.live()` on the Signal
+bus — a Flow trigger does not replay retained payloads.
 
 </Accordion>
 <Accordion title="once vs broadcast vs live — how do I choose?">
@@ -291,6 +336,7 @@ At-least-once: crash-after-claim reclaims when the lease expires, and a handler
 ## Learn more
 
 - [Flow](/docs/elements/flow) — `on(trigger, flow)` and `fx.emit`
+- [fx](/docs/reference/fx) — `fx.emit` and `fx.deadLetters`
 - [Clock](/docs/elements/clock) — scheduled and delayed work
 
 ## Next

package/site/content/docs/elements/store.mdx

@@ -632,6 +632,26 @@ images: {
 
 Missing Redis URL fails boot loudly: `oke boot: redis driver needs REDIS_URL`.
 
+### Durable KV
+
+Default `store.kv("sessions")` is cache-shaped — a Redis recreate drops keys.
+
+`{ durable: true }` persists that namespace in your SQL database (`oke_kv` JSONB on
+`DATABASE_URL`). Not a per-key Redis flag, not Flow `durable`, not tier-1 auto-cache.
+
+```typescript
+export const sessions = store.kv("sessions", { description: "Session cache" });
+export const ledger = store.kv("ledger", { durable: true, description: "Idempotency keys" });
+```
+
+Gate rates and Signal stay on `REDIS_URL`. Missing `DATABASE_URL` with the postgres driver
+fails boot: `oke boot: durable store.kv needs DATABASE_URL`.
+
+<Callout title="Not per-key, not Flow durable, not auto-cache">
+  Durable KV is a JSONB table on the same Postgres as `store.sql`. Flow `durable` journals steps.
+  Tier-1 auto-cache is an in-process Map and never reads `store.kv`.
+</Callout>
+
 Driver id stays `redis` for every image below — same `REDIS_URL`, zero Flow changes.
 Redis is the default because it is the most mature and battle-tested; Valkey and
 Dragonfly are equally legitimate opt-in pins.
@@ -757,7 +777,7 @@ images: {
 
 ### Images — `image` / `putImage`
 
-For photos, use Bun's built-in `Bun.Image` pipeline on the same handle (requires Bun `>=1.3.14`).
+For photos, use Bun's built-in `Bun.Image` pipeline on the same handle (requires Bun `>=1.4.0`).
 `putImage` is one write that fans into several keys:
 
 <StoreFilesVariants />

package/site/content/docs/get-started/installation.mdx

@@ -6,7 +6,7 @@ icon: Download
 ---
 
 This page gets you from zero to a running app on Bun. The engine targets
-**Bun ≥ 1.3.14** — prefer it for install, scaffold, and `oke dev`.
+**Bun ≥ 1.4.0** — prefer it for install, scaffold, and `oke dev`.
 
 <Callout title="The one rule">
   The npm package is `okengine`; the CLI binary is `oke`. Use `bun add` in a project or `bun install
@@ -20,7 +20,7 @@ This page gets you from zero to a running app on Bun. The engine targets
 <Step>
 ### Prerequisites
 
-- [Bun](https://bun.sh) ≥ 1.3.14 (`bun --version`)
+- [Bun](https://bun.sh) ≥ 1.4.0 (`bun --version`)
 - [Docker](https://docs.docker.com/get-docker/) with a running daemon (`docker info`)
 - A terminal and a code editor
 

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

@@ -43,6 +43,7 @@ Managed Postgres-wire databases — set `DATABASE_URL`, driver stays `postgres`.
 ## Redis providers
 
 Managed Redis-wire caches — set `REDIS_URL`, driver stays `redis`.
+`{ durable: true }` KV lives in your SQL database, not a second Redis.
 
 <Cards>
   <Card

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

@@ -66,9 +66,10 @@ If the host forbids unlimited memlock, the container may fail to start.
 
 ## Data and backup
 
-No named volume — ephemeral by default, same as Redis/Valkey. **Backup means:** do not
-treat this container as durable storage until you add a volume and Dragonfly persistence
-settings; rebuild from SQL/files, or use [Dragonfly Cloud](/docs/providers/dragonfly-cloud).
+The default `store.kv` recipe declares **no named volume** — ephemeral, same as Redis/Valkey.
+
+Keys that must survive go on `{ durable: true }` — a JSONB table on your SQL database.
+Dragonfly snapshots are not involved. See [Store · Durable KV](/docs/elements/store#durable-kv).
 
 ## Production note
 

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

@@ -66,12 +66,11 @@ The recipe runs:
 
 ## Data and backup
 
-The Redis recipe declares **no named volume**. Process memory is the source of truth;
-a container recreate loses keys unless you add persistence yourself
-(`compose.override.yml` + Redis AOF/RDB).
+The default `store.kv` recipe declares **no named volume**. Process memory is the source of truth;
+a container recreate loses those keys.
 
-**Backup means (default recipe):** treat KV as a cache — rebuild from SQL / files, or
-add an explicit volume + `SAVE`/`BGSAVE` policy before you rely on durability.
+Keys that must survive go on `{ durable: true }` — a JSONB table on your SQL database, not a
+second Redis. See [Store · Durable KV](/docs/elements/store#durable-kv).
 
 ## Production note
 

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

@@ -61,9 +61,11 @@ Same knobs as Redis: `OKE_STORE_KV_MAXMEMORY`, `OKE_STORE_KV_MAXMEMORY_POLICY`.
 
 ## Data and backup
 
-No named volume in the recipe — same ephemeral default as [Redis](/docs/recipes/redis).
-**Backup means:** do not assume durability until you add a volume + persistence config;
-treat the default as a shared cache rebuilt from durable stores.
+The default `store.kv` recipe declares **no named volume** — same ephemeral default as
+[Redis](/docs/recipes/redis).
+
+Keys that must survive go on `{ durable: true }` — a JSONB table on your SQL database.
+See [Store · Durable KV](/docs/elements/store#durable-kv).
 
 ## Production note
 

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

@@ -162,7 +162,9 @@ images: {
 
 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 `ai`, see [Recipes · AI](/docs/recipes#ai-local--self-hosted). For `proxy`, see [Reverse proxy](/docs/deployment/reverse-proxy).
+For `store.kv`, pin Redis (default), Valkey, or Dragonfly — driver id stays `redis`.
+`{ durable: true }` KV lives in SQL (`oke_kv` on `DATABASE_URL`), not a second Redis image.
+For `ai`, see [Recipes · AI](/docs/recipes#ai-local--self-hosted). For `proxy`, see [Reverse proxy](/docs/deployment/reverse-proxy).
 
 ## i18n