okengine 0.18.4 → 0.19.0

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

@@ -1,420 +0,0 @@
----
-title: "Flow"
-description: "Behavior — endpoints, jobs, consumers, and workflows as one species: a typed trigger, declared contracts, and a do that touches the world only through fx."
-icon: "Workflow"
-source: "docs/spec/unified-theory.md"
----
-
-Flow is how your backend **does anything**. An HTTP endpoint, a queue consumer, a cron job, a multi-step payment workflow — in other stacks these are four frameworks; here they are one species with one shape: `on(trigger, flow)`. Learn the shape once, and only the trigger ever changes.
-
-<Callout title="The one rule">
-  All world access goes through `fx`. A direct `fetch`, `Date.now()`, or `node:` import inside a
-  flow is a defect — effects are **inferred from what a flow touches through `fx`**, and that
-  inference is what powers the Manifest, the Console, caching, and durability.
-</Callout>
-
-## Quick start
-
-<Steps>
-
-<Step>
-### Write the flow
-
-Four declarations plus a `do`:
-
-```typescript title="src/flows/orders/create.ts"
-import { on, flow, http } from "okengine";
-import { z } from "zod";
-
-export const createOrder = on(
-  http.post("/orders"),
-  flow("orders.create", {
-    in: z.object({ sku: z.string(), qty: z.number().int().min(1) }),
-    out: z.object({ id: z.string() }),
-    errors: { OutOfStock: z.object({ left: z.number() }) },
-    do: async (input, fx) => {
-      const id = fx.id();
-      await fx
-        .store(db)
-        .insert(orders)
-        .values({ id, ...input, status: "pending" });
-      return { id };
-    },
-  }),
-);
-```
-
-</Step>
-
-<Step>
-### Run it
-
-`oke dev` picks up every exported flow — no route registration, no controller wiring:
-
-```bash
-oke dev
-```
-
-</Step>
-
-<Step>
-### Call it
-
-```bash
-curl -X POST localhost:6530/orders -d '{"sku":"SKU-1","qty":2}' -H 'content-type: application/json'
-# { "data": { "id": "…" }, "error": null }
-```
-
-</Step>
-
-</Steps>
-
-## 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)                          |
-| `cache`        | Optional — `false` opts out; `"30s"` adds a TTL. Read-only flows cache by default    |
-| `tenantScoped` | Default `true` when `gate.auth.tenant` is on — set `false` to skip tenant-role union |
-| `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:
-
-```typescript
-do: async (input, fx) => {
-  const [product] = await fx.store(db).select().from(products).where(eq(products.sku, input.sku));
-  if (!product || product.stock < input.qty) {
-    return fx.fail("OutOfStock", { left: product?.stock ?? 0 }); // declared in errors
-  }
-  // …
-};
-```
-
-Every response follows one envelope — success `{ data, error: null }`, failure
-`{ data: null, error: { code, data, message? } }` — clients switch on `error.code`.
-Built-in codes attach a localized `message` ([Errors](/docs/reference/errors)); custom codes stay message-less unless registered or `{ message }` is passed.
-
-<Callout title="List pages">
-  Prefer `out` as the item array and `return fx.json.withQuery(rows, input)` so the pager is
-  top-level `meta`. Do not put `{ data, meta }` on `out`. See
-  [Store](/docs/elements/store#handwritten-http-lists).
-</Callout>
-
-<Callout title="Helpers take the real Fx">
-  Type a helper's `fx` as the exported `Fx` (`import type { Fx } from
-  "okengine"`). A narrower `{ store: … }` will not match `store()` overloads
-  — that is the `as never` trap. See [fx](/docs/reference/fx).
-</Callout>
-
-## The triggers
-
-<FlowTriggers />
-
-### http — a request arrives
-
-`http.get` · `http.post` · `http.put` · `http.patch` · `http.delete` · `http.head` · `http.options` · `http.query`. QUERY (RFC 10008) is a safe, idempotent read with a JSON body.
-
-`http.get()` with no path is filled from the file tree (`flows/notes/[id]/get.ts` → `/notes/:id`). `flow({ do })` is named `unit.export`. Explicit `http.get("/me/tasks")` and `flow("notes.get")` still win. Folder conventions live on [Project structure](/docs/get-started/project-structure).
-
-`Content-Type: application/json` is required — missing → **400** `InvalidQuery`, anything else → **415** `UnsupportedMediaType` with `Accept-Query: "application/json"`. Invalid JSON is **400** (no sniffing). Responses advertise `Accept-Query`. okengine does not assign `Location` / `Content-Location` result URIs.
-
-A browser `GET` (`Accept` prefers `text/html`) paints the `{ data, error }` envelope in traces chrome — status, latency, and cache, Routes rail (static GET links), copy, line numbers, Pretty / Raw, Console on **6533**. `curl`, `Accept: application/json`, and `?format=json` stay JSON.
-
-```typescript
-export const findOrder = on(
-  http.get("/orders/:id").gate(member), // gates evaluate before do runs
-  flow("orders.find", {
-    in: z.object({ id: z.string() }),
-    out: Order,
-    errors: { NotFound: z.object({}) },
-    do: async ({ id }, fx) => (await fx.store(db).findById(orders, id)) ?? fx.fail("NotFound", {}),
-  }),
-);
-```
-
-### signal — another flow emits
-
-The producer emits through `fx`. For `once` and `broadcast` the consumer is the same species —
-`on(signal, flow)`, no `subscribe()` registration. `live` replay is HTTP SSE: `.live(signal)` on a
-GET trigger, `fx.live` as the stream carrier, `api.live` on the client.
-
-```typescript
-await fx.emit(orderPlaced, { orderId: id }); // inside the producing flow
-
-on(
-  orderPlaced,
-  flow("orders.sendReceipt", {
-    do: async ({ orderId }, fx) => {
-      /* … */
-    },
-  }),
-);
-```
-
-### clock — time passes
-
-`every("1h")` is a trigger value, not a registration with a scheduler library:
-
-```typescript
-on(
-  every("1h"),
-  flow("sessions.sweepExpired", {
-    do: async (_, fx) => {
-      const cutoff = fx.clock.ago("30d");
-      await fx.store(db).delete(sessions).where(lt(sessions.createdAt, cutoff));
-    },
-  }),
-);
-```
-
-### store change — a row changes
-
-CDC is built in; the flow receives `{ before, after }`:
-
-```typescript
-on(
-  db.table(orders).changed("status"),
-  flow("orders.reverify", {
-    do: ({ before, after }, fx) => fx.log.info("status", { from: before.status, to: after.status }),
-  }),
-);
-```
-
-### no trigger — a callable flow
-
-Drop `on()` and it is still a real Flow — contracts, Manifest entry, everything. Other flows call it through `fx.call`:
-
-```typescript
-export const getOrder = flow("orders.get", {
-  in: OrderRef,
-  out: Order,
-  do: async ({ id }, fx) => {
-    /* … */
-  },
-});
-
-const order = await fx.call(getOrder, { id: orderId }); // from any other flow
-```
-
-### mcp — an agent calls a tool
-
-`mcp.tool(name)` marks a flow for **OAuth-protected user-plane** exposure over MCP. Deny-by-default: a flow without this trigger is never listed over `tools/list`. A gate is required, exactly like a sensitive HTTP route:
-
-```typescript
-export const createBooking = on(
-  mcp.tool("bookings.create").gate(member), // gates required — deny-by-default
-  flow("bookings.create", {
-    plane: "user",
-    in: BookingRef,
-    out: Booking,
-    do: async ({ id }, fx) => {
-      /* … */
-    },
-  }),
-);
-```
-
-- The tool name is namespaced (`bookings.create`) and appears in the Manifest under `trigger.mcp.name` with its gates.
-- Binding the **same tool name** twice fails boot with **OKE1018** (`MCP tool "{tool}" is bound twice`).
-- Ungated `mcp.tool(...)` fails gate posture at boot (`GateBootError`) — the trigger never exposes an unauthenticated tool.
-
-This is one direction of [MCP](/docs/ai/mcp): exposing your flows as tools. The other is consuming external servers as `ai.mcpServer` tools via `fx.ask` / `ai.agent`.
-
-## fx — the only door
-
-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.deadLetters(signal)`                    | read            | Dead-lettered messages for that signal             |
-| `fx.live(signal, { match? })`               | read            | Live signal SSE carrier (`JsonStreamResult`)       |
-| `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/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             |
-| `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
-  send PII to a model — without you declaring any of it. That one graph drives the Console panels,
-  cache invalidation, least-privilege tokens, and durable replay.
-</Callout>
-
-## Cache — automatic for reads
-
-Read-only flows cache automatically from those inferred `reads`. A write to the same
-resource invalidates the entry. You do not declare `effects` or set `cache: "30s"`
-unless you want a TTL or to opt out.
-
-| On the flow      | What happens                            |
-| ---------------- | --------------------------------------- |
-| omitted / `true` | Tier-1 cache when the flow only `reads` |
-| `cache: "30s"`   | Same, plus a TTL                        |
-| `cache: false`   | Skip cache (live SQL every time)        |
-
-Mutations, `fx.ask`, and `durable: true` stay uncached. Console Traces shows **hit** /
-**miss** on cached reads, and **not applicable** only when the flow never used the cache.
-
-A hit records the cache lookup on the waterfall (`computed:…` reads), not a replay of
-the original store reads.
-
-## Durability — flows that survive the process
-
-<FlowDurable />
-
-Set `durable: true` and every `fx` call is journaled. Wrap side effects in `fx.step` and they never re-run on replay:
-
-```typescript
-export const chargeOrder = flow("payments.chargeOrder", {
-  durable: true, // every fx call below is journaled
-  in: OrderRef,
-  out: z.boolean(),
-  do: async ({ orderId }, fx) => {
-    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(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 `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), 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", {
-  durable: true,
-  in: OrderRef,
-  out: z.boolean(),
-  do: async ({ orderId }, fx) => {
-    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;
-  },
-});
-```
-
-The runtime journals undos as `undo:<name>` under `compensating`, then commits `failed`.
-Orphan reclaim resumes that phase; `flow.compensate` is optional after auto undos.
-`JournalSuspend` is park (no undo). Prefer `fx.using` or `{ undo }` — not both for one release.
-
-## Composition is just calls
-
-Wiring is values flowing between flows — declared in code, never configured in a dashboard:
-
-```typescript
-on(http.post("/orders"), createOrder); // ① a request arrives
-on(orderPlaced, sendReceipt); // ② its emit starts the consumer
-on(every("1h"), sweepExpired); // ③ time passes
-on(db.table(orders).changed("status"), reverify); // ④ a row changes
-// ⑤ getOrder — nothing starts it; every flow above can fx.call it
-```
-
-## Troubleshooting
-
-<Accordions>
-<Accordion title="My flow used fetch / Date.now directly and weird things happened">
-
-That bypasses the effect graph: the Manifest can't see the call, cache keys miss it, durable replay re-executes it, and tests can't freeze it. Move it behind `fx` — `fx.ask` / `fx.send` / `fx.clock.now()`, or a step inside a durable flow for true third-party calls.
-
-</Accordion>
-<Accordion title="Should I throw or fx.fail?">
-
-`fx.fail(code, data)` for expected outcomes — anything in `errors`. A throw is a crash: the run fails with a 500-shaped error and no typed code for the client. Expected failures are values so clients can switch on `error.code`.
-
-</Accordion>
-<Accordion title="Promise.all left orphan work running after one branch failed">
-
-Use `fx.all` (or `fx.race`) with thunks. The first rejection aborts siblings through `fx.signal`. Bare `Promise.all` / `Promise.race` do not cancel losers.
-
-</Accordion>
-<Accordion title="Durable flow retried a completed charge">
-
-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 undo / compensate run?">
-
-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?">
-
-Make it a plain flow with no trigger and `fx.call` it. You keep contracts, the Manifest entry, and tracing; a bare function would hide the work from the effect graph.
-
-</Accordion>
-<Accordion title="The browser shows a code block instead of JSON">
-
-That is the HTML view for a navigated `GET` when `Accept` prefers `text/html`. Send `Accept: application/json`, add `?format=json`, or use `curl` — the envelope is unchanged. `?raw=1` is the compact view of the same page.
-
-</Accordion>
-<Accordion title="GET on a POST-only path">
-
-The router returns **405 Method Not Allowed** with `Allow` listing every method bound to that path. A path that no flow owns is still 404. When QUERY is allowed, the 405 also carries `Accept-Query: "application/json"`.
-
-</Accordion>
-<Accordion title="QUERY without Content-Type">
-
-RFC 10008 forbids sniffing. Send `Content-Type: application/json` and a JSON body. Missing header → `InvalidQuery` **400**; `text/plain` (or any non-JSON type) → `UnsupportedMediaType` **415**.
-
-</Accordion>
-<Accordion title="What happens if a cron flow throws?">
-
-Only that run fails — the schedule keeps firing and the process does not exit. The failed run lands in Console → Flows (Traces) with its trace.
-
-</Accordion>
-<Accordion title="Console shows Cache not applicable on a GET">
-
-The flow is not a read-only cache candidate — it writes, asks a model, is durable, or set
-`cache: false`. Leave `cache` omitted. The first identical GET is a **miss**; the second is
-a **hit**. A matching write turns the next read into a miss.
-
-</Accordion>
-</Accordions>
-
-## Learn more
-
-- [Project structure](/docs/get-started/project-structure) — folders are the URL; `unit.export` is the name
-- [fx](/docs/reference/fx) — full `fx` surface, including ICU `fx.t` / `fx.locale`
-- [Signal](/docs/elements/signal) — delivery physics (`once` · `broadcast` · `live`)
-- [Clock](/docs/elements/clock) — schedules and durable sleep
-
-## Next
-
-<Cards>
-  <Card title="Signal" description="Continue to Signal." href="/docs/elements/signal" />
-  <Card
-    title="Introduction"
-    description="Eight elements overview."
-    href="/docs/get-started/introduction"
-  />
-</Cards>