okengine 0.10.3 → 0.11.0

package/site/content/docs/deployment/kubernetes.mdx

@@ -31,7 +31,7 @@ sticky network id to preserve. Scale with `replicas: N`.
 <Step>
 ### Share backing services
 
-Pin docker/prod drivers to shared stores:
+Pin `dev`/`prod` drivers to shared stores:
 
 | Concern                       | Driver                       | Shared backend                                    |
 | ----------------------------- | ---------------------------- | ------------------------------------------------- |
@@ -59,7 +59,7 @@ Wire `readinessProbe` to `/_/ready` and `livenessProbe` to `/health`.
 Bun.SQL defaults to **10** connections per process — fine for one pod.
 Scale the Deployment and `N × pool` can exceed Postgres `max_connections`.
 
-When both `store.sql` and `pgdog` are pinned (docker/prod default in templates),
+When both `store.sql` and `pgdog` are pinned (`dev`/`prod` default in templates),
 `DATABASE_URL` points at PgDog on port `6432` — transaction pooling, wire-protocol
 transparent to Bun.SQL / Drizzle. Point the cluster Service at that pooler.
 
@@ -137,12 +137,12 @@ so traffic does not hit a pod mid-takeover.
 
 `drivers.store.kv` must be `redis` with `REDIS_URL` set. A missing URL now
 **fails boot** (no silent memory fallback). Declaring `memory` for local is fine;
-docker/prod should stay on redis.
+`dev`/`prod` should stay on redis.
 
 </Accordion>
 <Accordion title="Files uploaded on pod A are missing on pod B">
 
-`drivers.store.files: "fs"` is single-host. Switch docker/prod to `s3`
+`drivers.store.files: "fs"` is single-host. Switch `dev`/`prod` to `s3`
 (create-oke templates already do).
 
 </Accordion>

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

@@ -132,7 +132,7 @@ Use `keyBy: "ip"` on public unauthenticated AI edges. Cost caps stay on prompt/a
 
 ## Secrets stay out of prompts
 
-`Redacted` values (e.g. from `fx.vault`) stringify to `[redacted]` in provider-facing messages — the same placeholder as logs. Never cleartext to a model.
+`Redacted` values (e.g. from `fx.vault.get`) stringify to `[redacted]` in provider-facing messages — the same placeholder as logs. Never cleartext to a model.
 
 ## Streaming
 
@@ -176,8 +176,8 @@ oke ai setup --provider ollama --yes
 ```
 
 Writes `drivers.ai`, commented AI overrides in `.env.local` (so they do not
-shadow `docker/.env.docker`), and `src/core/ai.ts`. Uncomment `.env.local`
-lines only for a host-managed AI endpoint.
+shadow `docker/.env.docker`), and AI models into `src/core.ts`. Uncomment
+`.env.local` lines only for a host-managed AI endpoint.
 
 **Recommended** defaults to llama.cpp (lightest local footprint). Customize
 offers llama.cpp · Ollama · vLLM · SGLang · cloud providers.
@@ -209,7 +209,7 @@ import { defineConfig } from "okengine/config";
 
 export default defineConfig({
   drivers: {
-    ai: { local: "openai-compatible", docker: "openai-compatible", prod: "anthropic" },
+    ai: { dev: "openai-compatible", test: "mock", prod: "anthropic" },
   },
   images: {
     ai: "ghcr.io/ggml-org/llama.cpp:server-b10290", // ≥ b8146; never :latest
@@ -217,10 +217,10 @@ export default defineConfig({
 });
 ```
 
-```typescript title="src/core/ai.ts"
+```typescript title="src/core.ts"
 export const smart = ai.model("smart", {
   provider: "openai-compatible",
-  model: process.env.OKE_AI_MODEL ?? "smollm2", // Docker Hub ai/ id
+  model: process.env.OKE_AI_MODEL ?? "granite3.3:2b", // Docker Hub ai/ id
 });
 ```
 
@@ -270,7 +270,7 @@ The one you declared. There is no fallback or guess — if `prod` has no AI driv
 </Accordion>
 <Accordion title="oke boot: ollama driver needs OKE_AI_URL">
 
-Docker mode expects `OKE_AI_URL` from `docker/.env.docker` (written when `images.ai` is pinned). Keep `OKE_AI_*` in `.env.local` commented — an active `OKE_AI_URL` there wins and shadows the compose URL. Locally, the Ollama default is `http://127.0.0.1:11434`. If asks fail with `OllamaUnavailableError`, confirm the server answers at that URL and that the model is listed under `GET /api/tags` (boot pulls via `POST /api/pull` against the container — do not rely on a host `ollama pull`, which may talk to a different install). Prefer `oke ai setup` to wire driver, commented env overrides, and `src/core/ai.ts` in one pass.
+Docker mode expects `OKE_AI_URL` from `docker/.env.docker` (written when `images.ai` is pinned). Keep `OKE_AI_*` in `.env.local` commented — an active `OKE_AI_URL` there wins and shadows the compose URL. Locally, the Ollama default is `http://127.0.0.1:11434`. If asks fail with `OllamaUnavailableError`, confirm the server answers at that URL and that the model is listed under `GET /api/tags` (boot pulls via `POST /api/pull` against the container — do not rely on a host `ollama pull`, which may talk to a different install). Prefer `oke ai setup` to wire driver, commented env overrides, and AI models in `src/core.ts` in one pass.
 
 </Accordion>
 <Accordion title="A prompt edit made answers worse — how do I catch that pre-merge?">

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

@@ -54,7 +54,9 @@ do: async (input, fx) => {
 <Step>
 ### Read it in development
 
-Locally the `console` driver captures mail into an inbox instead of sending; in docker mode the stack runs **Mailpit**, a real SMTP catcher with a web UI — so you see the exact rendered message without ever touching a real mailbox.
+Under `oke test` the `console` driver captures mail into an inbox instead of sending; under `oke
+dev` Compose runs **Mailpit**, a real SMTP catcher with a web UI — so you see the exact rendered
+message without ever touching a real mailbox.
 
 </Step>
 
@@ -199,20 +201,20 @@ push drivers are passed via `BootOptions.channel.drivers` when you need them.
 ```typescript title="oke.config.ts"
 drivers: {
   channel: {
-    email: { local: "console", docker: "smtp", test: "console", prod: "smtp" },
+    email: { dev: "smtp", test: "console", prod: "smtp" },
     // optional — omit until you need SMS at boot
-    sms: { local: "console", docker: "taqnyat", test: "console", prod: "taqnyat" },
+    sms: { test: "console", prod: "taqnyat" },
   },
 },
 images: {
-  "channel.email": "axllent/mailpit:v1.22.3",
+  channel: { email: "axllent/mailpit:v1.22.3" },
 },
 ```
 
 | Driver         | Medium   | Behavior                                                            |
 | -------------- | -------- | ------------------------------------------------------------------- |
-| `console`      | any      | Captures into a readable inbox — local + tests                      |
-| `smtp`         | email    | Real SMTP — Mailpit in docker, your provider in prod                |
+| `console`      | any      | Captures into a readable inbox — tests                              |
+| `smtp`         | email    | Real SMTP — Mailpit under `oke dev`, your provider in prod          |
 | `resend`       | email    | Resend HTTP API (`RESEND_API_KEY`)                                  |
 | `sndr`         | email    | SNDR HTTP API (`SNDR_API_KEY`)                                      |
 | `taqnyat-mail` | email    | Taqnyat Mail API (`TAQNYAT_MAIL_TOKEN` + `TAQNYAT_CAMPAIGN`)        |
@@ -258,7 +260,7 @@ openWebPushChannel({
 <Accordions>
 <Accordion title="I sent an email in dev but nothing arrived">
 
-Nothing _should_ arrive — the `console` driver captures mail instead of sending. Read the dev inbox, or run `oke dev --docker` and open Mailpit's web UI to see the rendered message.
+Nothing _should_ arrive — the `console` driver captures mail instead of sending. Read the dev inbox, or run `oke dev` and open Mailpit's web UI to see the rendered message.
 
 </Accordion>
 <Accordion title="A user says they stopped receiving messages">

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

@@ -124,7 +124,7 @@ reclaimed after its lease expires and continues at the next unfinished step.
 
 **Leader election needs a shared store.** The default in-memory CronStore is per process. Multi-replica
 exclusivity holds when every instance opens the same durable CronStore — `postgres` (SKIP LOCKED +
-lease reclaim, docker/prod default) or `file` (shared volume, single-host / local).
+lease reclaim, `dev`/`prod` default) or `file` (shared volume, single-host).
 
 **Catch-up example:** an hourly clock down for five hours reports `missedRuns: 5` and
 `catchUp: "one"`, then a single tick runs the handler once.
@@ -141,16 +141,16 @@ Detection attaches `dstAmbiguity` on the cron row and the Console shows it. `oke
 
 ```typescript title="oke.config.ts"
 drivers: {
-  clock: { local: "memory", docker: "postgres", test: "frozen", prod: "postgres" },
+  clock: { dev: "postgres", test: "frozen", prod: "postgres" },
 },
 ```
 
-| Driver     | Behavior                                                                                       |
-| ---------- | ---------------------------------------------------------------------------------------------- |
-| `memory`   | In-process CronStore + timers — single process; lost on exit                                   |
-| `postgres` | Postgres CronStore (`oke_crons`) — multi-host leader election via SKIP LOCKED + lease reclaim  |
-| `file`     | On-disk CronStore (`.oke/crons.json`) — multi-process on a shared volume (local / single-host) |
-| `frozen`   | Deterministic test clock — time advances only when the test says so                            |
+| Driver     | Behavior                                                                                      |
+| ---------- | --------------------------------------------------------------------------------------------- |
+| `memory`   | In-process CronStore + timers — single process; lost on exit                                  |
+| `postgres` | Postgres CronStore (`oke_crons`) — multi-host leader election via SKIP LOCKED + lease reclaim |
+| `file`     | On-disk CronStore (`.oke/crons.json`) — multi-process on a shared volume (single-host)        |
+| `frozen`   | Deterministic test clock — time advances only when the test says so                           |
 
 `frozen` is why the no-`Date.now()` rule pays off: tests inject time travel through `fx.clock` and every flow obeys it automatically.
 

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

@@ -71,15 +71,15 @@ curl -X POST localhost:6530/orders -d '{"sku":"SKU-1","qty":2}' -H 'content-type
 
 ## Anatomy of a Flow
 
-| Part         | Role                                                            |
-| ------------ | --------------------------------------------------------------- |
-| trigger      | What starts the flow — `http`, a signal, `every`, a row change  |
-| `in`         | Input contract — validated before `do` runs; bad input is a 422 |
-| `out`        | Output contract — the return value is checked against it        |
-| `errors`     | Typed failures — **returned** with `fx.fail`, never thrown      |
-| `retry`      | Optional whole-`do` backoff on thrown errors (same journal)     |
-| `do`         | The work — every read, write, emit, and call goes through `fx`  |
-| `compensate` | Durable only — undo phase after terminal failure (same journal) |
+| Part         | Role                                                                       |
+| ------------ | -------------------------------------------------------------------------- |
+| trigger      | What starts the flow — `http`, a signal, `every`, a row change             |
+| `in`         | Input contract — validated before `do` runs; bad input is a 422            |
+| `out`        | Output contract — the return value is checked against it                   |
+| `errors`     | Typed failures — **returned** with `fx.fail`, never thrown                 |
+| `retry`      | Optional whole-`do` backoff on thrown errors (same journal)                |
+| `do`         | The work — every read, write, emit, and call goes through `fx`             |
+| `compensate` | Durable only — optional hook after auto per-step `{ undo }` (same journal) |
 
 Failures are values, not exceptions:
 
@@ -181,22 +181,22 @@ const order = await fx.call(getOrder, { id: orderId }); // from any other flow
 
 Everything a flow may touch, on one object:
 
-| Surface                                     | Effect recorded | What it does                                 |
-| ------------------------------------------- | --------------- | -------------------------------------------- |
-| `fx.store(db).select/insert/…`              | read / write    | SQL, KV, files, index sessions               |
-| `fx.emit(signal, payload)`                  | emit            | Publish a signal (transactional with writes) |
-| `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(contract)`                        | read            | Read a secret (`Redacted`; logs masked)      |
-| `fx.clock.now()` / `.sleep(…)`              | —               | Injected time / durable sleep                |
-| `fx.cache.get/set`                          | —               | Shared cache with effect-aware invalidation  |
-| `fx.step(name, fn)`                         | —               | Named durable step — never re-runs on replay |
-| `fx.all` / `fx.race` / `fx.retry`           | —               | Structured concurrency + backoff retry       |
-| `fx.signal`                                 | —               | Ambient `AbortSignal` for the current branch |
-| `fx.id()` · `fx.log` · `fx.t` · `fx.locale` | —               | UUIDs, redacting logger, ICU i18n            |
-| `fx.auth` · `fx.operator` · `fx.tenant`     | —               | Who is calling (user / operator / tenant)    |
+| Surface                                     | Effect recorded | What it does                                       |
+| ------------------------------------------- | --------------- | -------------------------------------------------- |
+| `fx.store(db).select/insert/…`              | read / write    | SQL, KV, files, index sessions                     |
+| `fx.emit(signal, payload)`                  | emit            | Publish a signal (transactional with writes)       |
+| `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.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             |
+| `fx.signal`                                 | —               | Ambient `AbortSignal` for the current branch       |
+| `fx.id()` · `fx.log` · `fx.t` · `fx.locale` | —               | UUIDs, redacting logger, ICU i18n                  |
+| `fx.auth` · `fx.operator` · `fx.tenant`     | —               | Who is calling (user / operator / tenant)          |
 
 <Callout title="Why this strictness pays off">
   Effects are inferred from `fx` usage, so the Manifest knows exactly which flows read `orders` or
@@ -216,28 +216,27 @@ export const chargeOrder = flow("payments.chargeOrder", {
   in: OrderRef,
   out: z.boolean(),
   do: async ({ orderId }, fx) => {
-    const intent = await fx.step("create-intent", () =>
-      stripe(fx.vault(stripeKey).reveal()).create(orderId),
-    );
+    const key = await fx.vault.get(stripeKey);
+    const intent = await fx.step("create-intent", () => stripe(key.reveal()).create(orderId));
 
     await fx.clock.sleep("verify-window", "2m"); // journals wakeAt in a durable flow
 
-    return fx.step("confirm", () => stripe(fx.vault(stripeKey).reveal()).confirm(intent));
+    return fx.step("confirm", () => stripe(key.reveal()).confirm(intent));
   },
 });
 ```
 
 **Consequence:** completed steps replay from the journal — on resume, `create-intent` does not re-run, so the card is not charged twice.
 
-**Crash recovery needs a shared journal.** Set `drivers.journal: "postgres"` (the docker/prod template default) and every run persists in `oke_journal_runs` under a per-run lease: boot scans for orphaned `running` / due `sleeping` runs and resumes them, and the lease lets exactly one instance execute a run at a time. The default `memory` journal is per process — replay holds for that process only.
+**Crash recovery needs a shared journal.** Set `drivers.journal: "postgres"` (the `dev`/`prod` template default) and every run persists in `oke_journal_runs` under a per-run lease: boot scans for orphaned `running` / `compensating` / due `sleeping` runs and resumes them, and the lease lets exactly one instance execute a run at a time. The default `memory` journal is per process — replay holds for that process only.
 
 Replay is **at-least-once** for a step whose body never persisted (crash mid-step, lease overrun): that step re-runs on reclaim, so keep step bodies short or internally idempotent. A client transport retry starts a _new_ run with a fresh `runId` — request-level idempotency is an application concern, not the journal's.
 
 For flaky sub-steps, wrap the work in `fx.retry` **inside** `fx.step` so a completed charge is never retried on resume. Coarse whole-body retry is also available as `flow(name, { retry: { retries, delay, backoff, jitter } })` and reuses the same journal session.
 
-After a **terminal** failure (`fx.fail` or exhausted retries / uncaught throw), optional
-`compensate` runs under the same journal. Undo work must use **new** step names
-(`undo:…`) — never rewind forward steps:
+After a **terminal** failure (`fx.fail` or exhausted retries / uncaught throw), declare
+undo next to each step. Only **persisted** steps undo (LIFO) — if `charge` throws before
+it journals, `undo:charge` does not run:
 
 ```typescript
 export const chargeOrder = flow("payments.chargeOrder", {
@@ -245,23 +244,23 @@ export const chargeOrder = flow("payments.chargeOrder", {
   in: OrderRef,
   out: z.boolean(),
   do: async ({ orderId }, fx) => {
-    await fx.step("reserve", () => reserve(orderId));
-    await fx.step("charge", () => charge(orderId));
+    await fx.step("reserve", () => reserve(orderId), {
+      undo: () => release(orderId),
+    });
+    await fx.step("charge", () => charge(orderId), {
+      undo: (intent) => refund(intent), // journaled value — resume-safe
+    });
     return true;
   },
-  compensate: async ({ input, completedSteps }, fx) => {
-    if (completedSteps.includes("charge")) {
-      await fx.step("undo:charge", () => refund(input.orderId));
-    }
-    if (completedSteps.includes("reserve")) {
-      await fx.step("undo:reserve", () => release(input.orderId));
-    }
-  },
 });
 ```
 
-Thrown errors on the durable execute path commit the journal as `failed` (and land on Runs).
-`JournalSuspend` (sleep) is park, not failure — compensate does not run.
+The runtime journals undos as `undo:<name>` under status `compensating`, then commits
+`failed`. Orphan reclaim resumes that phase without re-entering forward work.
+`flow.compensate` remains an optional hook after auto undos for cross-cutting cleanup.
+`JournalSuspend` (sleep) is park, not failure — undo does not run.
+Use `fx.using` for same-attempt cleanup; `{ undo }` for durable external effects — not both
+for the same release.
 
 ## Composition is just calls
 
@@ -298,9 +297,9 @@ Use `fx.all` (or `fx.race`) with thunks. The first rejection aborts siblings thr
 Put `fx.retry` **inside** `fx.step`, not around it. Completed steps replay from the journal and never re-run. `flow(name, { retry })` is for coarse whole-body retries on the same session.
 
 </Accordion>
-<Accordion title="When does compensate run?">
+<Accordion title="When does undo / compensate run?">
 
-Only after terminal failure for that journal attempt — not on sleep, not mid-retry, not on success. Undo bodies must be idempotent (`undo:*` steps resume like any other step). Irreversible effects (`send` / `ask`) need developer-declared undos or an explicit no-op.
+Only after terminal failure for that journal attempt — not on sleep, not mid-retry, not on success. Per-step `{ undo }` runs first (LIFO, only for persisted steps), then optional `flow.compensate`. The run stays `compensating` until undos finish so a crash mid-undo resumes the undo phase, not forward `do`. Undo bodies must be idempotent. Irreversible effects (`send` / `ask`) need developer-declared undos or an explicit no-op.
 
 </Accordion>
 <Accordion title="How do I share logic between flows — a private function?">

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

@@ -48,7 +48,7 @@ import { member, canBook, fair } from "./gates";
 
 export const app = oke({
   name: "shop",
-  env: "local",
+  env: "dev",
   gate: { policies: [member, canBook, fair] },
 });
 ```
@@ -166,7 +166,7 @@ Fine-grained authorization (`gate.scope`, roles) stays opt-in — attach it only
 
 All five run as atomic Lua on the kv driver — correct under concurrency, identical on the memory
 driver in tests. Boot opens a dedicated `oke:gates` namespace on **`drivers.store.kv`**
-(`memory` locally · `redis` in docker/prod) so multi-instance rate limits share counters.
+(`memory` in test · `redis` in `dev`/`prod`) so multi-instance rate limits share counters.
 
 ## Auth posture at boot
 
@@ -183,7 +183,7 @@ on(http.post("/bookings").gate(member, canBook), flow("bookings.create", {/* …
 posture but does **not** authenticate.
 
 `gate: { unguardedHttp: "allow" }` skips the audit **only** when `env === "test"`.
-In `local` / `prod` / `docker` migrate with per-trigger `gate.public`.
+In `dev` / `prod` migrate with per-trigger `gate.public`.
 
 ## Built-in auth (`gate.auth`)
 
@@ -196,7 +196,7 @@ import { member, canBook } from "./gates";
 
 export const app = oke({
   name: "shop",
-  env: "local",
+  env: "dev",
   gate: {
     auth: {
       emailAndPassword: { enabled: true },
@@ -248,7 +248,8 @@ gate: {
 }
 ```
 
-Customize tables, then run `oke schema generate` (supports `--check` in CI). Extra sign-in
+Customize tables, then run `oke schema generate` (writes `.oke/schema/oke.ts`;
+supports `--check` in CI). Extra sign-in
 shapes: [Plugins](/docs/plugins) (username, magic link, OTP, TOTP, passkeys). Call auth from
 [createClient](/docs/reference/client) — one client, helpers in `okengine/client/auth`.
 

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

@@ -238,13 +238,13 @@ When a signal disappears from code, reconciliation marks its config row `orphane
 
 ```typescript title="oke.config.ts"
 drivers: {
-  signal: { local: "memory", docker: "redis", test: "memory", prod: "redis" },
+  signal: { dev: "redis", test: "memory", prod: "redis" },
 },
 ```
 
 | Driver     | Runs as                              | Boot today                                                                  |
 | ---------- | ------------------------------------ | --------------------------------------------------------------------------- |
-| `memory`   | in-process                           | Local loop + tests — zero infrastructure                                    |
+| `memory`   | in-process                           | Tests — zero infrastructure                                                 |
 | `redis`    | Redis / Valkey / Dragonfly image pin | Boot-bound — **emit relay** via Streams / pub/sub; consume is process-local |
 | `postgres` | Postgres                             | Driver exists; boot **fails loud** until a LISTEN/NOTIFY SQL client binds   |
 | `nats`     | NATS                                 | Driver exists; boot **fails loud** until a production NATS client binds     |