okengine 0.19.9 → 0.21.0

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

@@ -96,19 +96,19 @@ export const ping = on(
 
 `in` / `out` live on the HTTP bag. Invalid input never enters `do`:
 
-```typescript title="src/flows/notes/create.ts"
+```typescript title="src/flows/links/create.ts"
 import { on, flow, http } from "okengine";
 import { z } from "zod";
 
 export const create = on(
   http.post({
-    in: z.object({ title: z.string().min(1) }),
-    out: z.object({ id: z.string(), title: z.string() }),
+    in: z.object({ url: z.string().url() }),
+    out: z.object({ id: z.string(), url: z.string() }),
   }),
   flow({
-    do: async ({ title }, fx) => {
+    do: async ({ url }, fx) => {
       const id = fx.id();
-      return { id, title };
+      return { id, url };
     },
   }),
 );
@@ -118,7 +118,7 @@ export const create = on(
 
 <Tab value="Failures">
 
-Declare domain errors on the exposure bag and return `fx.fail` — do not throw for expected failures:
+Declare domain errors on the exposure bag. Built-in codes (`NotFound`, `Forbidden`, …) need no `errors:` — use the helpers:
 
 ```typescript title="src/flows/orders/[id]/get.ts"
 import { on, flow, http } from "okengine";
@@ -130,12 +130,11 @@ export const get = on(
   http.get({
     in: z.object({ id: z.string() }),
     out: z.object({ id: z.string(), sku: z.string(), qty: z.number() }),
-    errors: { NotFound: z.object({ id: z.string() }) },
   }),
   flow({
     do: async ({ id }, fx) => {
       const [order] = await fx.store(db).select().from(orders).where(eq(orders.id, id));
-      if (!order) return fx.fail("NotFound", { id });
+      if (!order) return fx.fail.notFound({ id });
       return order;
     },
   }),
@@ -238,11 +237,14 @@ Invoke contracts (`in` / `out` / `errors` / `breaking`) belong on the exposure
 ## Contracts
 
 <Callout title="Detailed section">
-  Invoke contracts live on the **exposure** — `http.post({ in, out, errors })`, `call("name", {
-  in, out, do })`, or `mcp.tool("x", { in, out })`. The Manifest still shows flat
-  `flows.*.{in,out,errors,breaking}` as a projection from that exposure. `in` runs before `do`;
-  `out` runs after a successful return. `fx.fail` skips `out`. Signal / Channel `schema` is a
-  separate **emit** contract (validated at `fx.emit` / `fx.send`).
+  Invoke contracts live on the **exposure** (`http.post({ in, out, errors })`, `call("name", { in,
+  out, do })`, `mcp.tool("x", { in, out })`). Manifest `flows.*` is a projection from that bag.
+
+`in` validates before `do`. After success, `out` projects the reply (Date → ISO-8601, extra keys
+strip); a miss is not a client error. `fx.fail` skips `out`.
+
+Signal / Channel `schema` is a separate **emit** contract (validated at `fx.emit` / `fx.send`).
+
 </Callout>
 
 <Tabs items={["Standard Schema", "Failures", "Envelope"]}>
@@ -315,15 +317,22 @@ HTTP success from a returned value is `200` + `{ data, error: null }`. `undefine
 
 Status for `error.code`:
 
-| Code                                                  | Status |
-| ----------------------------------------------------- | ------ |
-| `ValidationError`                                     | `422`  |
-| `Unauthorized`                                        | `401`  |
-| `Forbidden`                                           | `403`  |
-| `RateLimited`                                         | `429`  |
-| Any other declared code (`NotFound`, `OutOfStock`, …) | `400`  |
-
-A bare `404` with body `Not Found` means **no route matched** — not `fx.fail("NotFound")`.
+| Code                                                   | Status |
+| ------------------------------------------------------ | ------ |
+| `ValidationError`                                      | `422`  |
+| `Unauthorized`                                         | `401`  |
+| `Forbidden`                                            | `403`  |
+| `NotFound`                                             | `404`  |
+| `Conflict` / `ForeignKey`                              | `409`  |
+| `UnsupportedMediaType`                                 | `415`  |
+| `RateLimited` / `AuthRateLimited`                      | `429`  |
+| `DatabaseError` (`not_null` / `check`)                 | `422`  |
+| `DatabaseError` (`retryable`) / `ServiceUnavailable`   | `503`  |
+| `DatabaseError` (else) / `InternalError`               | `500`  |
+| Domain codes (`OutOfStock`, `FlightFull`, `Duplicate`) | `400`  |
+
+A bare `404` with body `Not Found` means **no route matched** — not `fx.fail.notFound`. Clients
+distinguish router miss (plain text) from domain miss (JSON envelope).
 
 </Tab>
 
@@ -344,8 +353,8 @@ A bare `404` with body `Not Found` means **no route matched** — not `fx.fail("
 </Accordion>
 
 <Accordion title="Name stamping">
-  Prefer nameless `flow({ do })` on HTTP tree files — `src/flows/notes/[id]/get.ts` +
-  `export const get` stamps `notes.get`. Signal / Clock workers pass `flow("name", { do })`
+  Prefer nameless `flow({ do })` on HTTP tree files — `src/flows/links/[code]/get.ts` +
+  `export const get` stamps `links.get`. Signal / Clock workers pass `flow("name", { do })`
   (**OKE1072**; Clock inline is [Clock · Inline or named export](/docs/elements/clock#inline-or-named-export)).
 </Accordion>
 
@@ -383,7 +392,9 @@ A bare `404` with body `Not Found` means **no route matched** — not `fx.fail("
 
 <Accordion title="fx.call identity">
   `fx.call` starts the callee with an **empty** `fx.auth` (fail-closed). `fx.tenant.id` propagates.
-  For audit only, read `fx.principal` — gates never consult it. See [fx](/docs/reference/fx).
+  For audit only, read `fx.principal` — gates never consult it. Controlled `return fx.fail(...)`
+  comes back as a `FlowFailure` value; an unhandled `throw` rethrows to the caller (never silent
+  `undefined`). See [fx](/docs/reference/fx).
 </Accordion>
 
 <Accordion title="Undeclared effects (OKE1001–1007)">
@@ -543,8 +554,8 @@ Default is `true` once `gate.auth.tenant` is on.
 </Accordion>
 
 <Accordion title="Thrown Error becomes a mystery 500 instead of a typed envelope">
-  Uncaught exceptions are defects. Declare the code in `errors` on the exposure and `return
-  fx.fail("OutOfStock", payload)` from `do`.
+  Uncaught exceptions become `InternalError` (catalog message only — the thrown `message` is not
+  copied). For expected misses use `fx.fail.notFound` / domain `fx.fail("OutOfStock", payload)`.
 </Accordion>
 
 <Accordion title="422 ValidationError — path param missing from in">
@@ -553,9 +564,9 @@ Default is `true` once `gate.auth.tenant` is on.
   Parsing](/docs/elements/flow/http#request-parsing).
 </Accordion>
 
-<Accordion title="fx.fail('NotFound') is 400, not 404">
-  Custom domain codes map to **400**. A bare `404` `Not Found` means the router found no method +
-  path. Use `fx.fail` for domain misses; fix the route for missing bindings.
+<Accordion title="Router 404 vs domain NotFound">
+  A bare `404` with body `Not Found` means **no route matched**. `fx.fail.notFound` is a JSON
+  envelope at **404** with `error.code: "NotFound"`. Clients distinguish by envelope, not status.
 </Accordion>
 
 <Accordion title="Read-only Flow never cache-hits">