okengine 0.20.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "One law. Eight elements. One contract. The backend model stays small; operational surfaces are derived from it instead of maintained separately.",
   "license": "MIT",
   "repository": {
@@ -70,6 +70,7 @@
     },
     "./client": "./src/client/index.ts",
     "./client/auth": "./src/client/auth.ts",
+    "./client/explain": "./src/client/explain.ts",
     "./client-react": "./src/client-react/index.ts",
     "./test": "./src/test/index.ts",
     "./testing": {

package/site/content/docs/client/calling.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Calling"
-description: "createClient forms, REST vs RPC, options, result envelopes, store resources, and remote types."
+description: "createClient forms, REST vs RPC, match/explain for unknown errors, options, envelopes, and remote types."
 icon: "Braces"
 source: "docs/spec/unified-theory.md"
 ---
@@ -13,8 +13,8 @@ For developers wiring a storefront, mobile app, or partner service to an okengin
 **6530**).
 
 <Callout title="The one rule">
-  Treat every call as a result envelope: `{ data, error }`. Switch on `error.code`. Only transport
-  / protocol problems use `code: "TransportError"`.
+  Treat every call as `{ data, error }`. Use `match` from `okengine/client/explain` for success plus
+  unknown failures. Name a code only when this screen has special recovery.
 </Callout>
 
 ## Smallest Example
@@ -125,7 +125,7 @@ if (isOk(result)) {
 <Tab value="Failures">
 
 ```typescript
-import { isOk, isErrorCode } from "okengine/client";
+import { match } from "okengine/client/explain";
 
 const result = await api.bookings.create({
   flightId: "SK481",
@@ -133,16 +133,18 @@ const result = await api.bookings.create({
   cabin: "economy",
 });
 
-if (isOk(result)) {
-  result.data.confirmationCode;
-} else if (result.error.code === "FlightFull") {
-  offerWaitlist(result.error.data.seatsLeft);
-} else if (isErrorCode(result.error, "NotFound")) {
-  // shared helper narrowing
-}
+match(result, {
+  ok: (data) => show(data.confirmationCode),
+  FlightFull: (data) => offerWaitlist(data.seatsLeft),
+  auth: () => goSignIn(),
+  invalid: (e) => setForm(e.fields),
+  _: (e) => toast(e.message),
+});
 ```
 
-Prefer `error?.code === "FlightFull"` for inference; use `isErrorCode` in shared helpers.
+One import. Named codes narrow `data`. Kind arms (`auth`, `invalid`) cover chrome. `_` is required
+— store auto-map, transport, and unknown domain codes land there. Full table: [`match` /
+`explain`](#match--explain).
 
 </Tab>
 
@@ -154,13 +156,13 @@ import { isTransportError } from "okengine/client";
 const result = await api.orders.list({ limit: 20, status: "shipped" });
 
 if (result.error && isTransportError(result.error)) {
-  showOfflineBanner(result.error.data.message);
+  showOfflineBanner(result.error.message); // === error.data.message
   // optional: result.error.data.status
 }
 ```
 
 Network failure, abort (`timeout`), non-JSON body, or HTTP status without a `{ data, error }`
-envelope — never a declared Flow code.
+envelope — never a declared Flow code. Prefer `error.message`; it always matches `error.data.message`.
 
 </Tab>
 
@@ -180,6 +182,80 @@ JSON envelopes.
 
 </Tabs>
 
+## `match` / `explain`
+
+A `create` can return `ValidationError`, store auto-map (`Conflict`, `DatabaseError`), gates,
+`TransportError`, plus any domain code. Do not switch on every `error.code`.
+
+```typescript
+import { match } from "okengine/client/explain";
+
+const result = await api.bookings.create({ flightId: "SK481", seats: 2 });
+
+match(result, {
+  ok: (data) => show(data.confirmationCode),
+  FlightFull: (data) => offerWaitlist(data.seatsLeft),
+  auth: () => goSignIn(),
+  invalid: (e) => setForm(e.fields),
+  _: (e) => toast(e.message),
+});
+```
+
+<Callout title="Dispatch order">
+  `ok` → named code (`FlightFull`) → UX kind (`auth`, `invalid`) → required `_`. Kind names are
+  reserved — do not use `auth` or `failed` as domain codes.
+</Callout>
+
+Import from `okengine/client/explain` so the 5 kB `okengine/client` graph stays small. `isOk` /
+`isFail` stay on `okengine/client` when you only need a predicate.
+
+| Helper                        | When                      |
+| ----------------------------- | ------------------------- |
+| `match(result, { ok, …, _ })` | Whole envelope — one call |
+| `matchError(error, { …, _ })` | You already have `error`  |
+| `explain(error)`              | Chrome only — no matcher  |
+
+### Kinds
+
+| `kind`        | Codes                                                                                  | Typical UI                  |
+| ------------- | -------------------------------------------------------------------------------------- | --------------------------- |
+| `auth`        | `Unauthorized`, `AuthFailed`                                                           | Sign-in                     |
+| `permission`  | `Forbidden`                                                                            | “You can’t do that”         |
+| `missing`     | `NotFound`; `TransportError` HTTP 404                                                  | Empty state                 |
+| `conflict`    | `Conflict`, `ForeignKey`                                                               | Retry or pick another value |
+| `invalid`     | `ValidationError`, `InvalidQuery`, `UnsupportedMediaType`; `DatabaseError` 422 reasons | Form fields                 |
+| `limited`     | `RateLimited`, `AuthRateLimited`                                                       | Wait / retry (`retryable`)  |
+| `unavailable` | `ServiceUnavailable`; `DatabaseError` `retryable`; other `TransportError`              | Offline / retry             |
+| `failed`      | `InternalError`, unknown `DatabaseError`, unnamed domain codes                         | Toast `message`             |
+
+Named code arms receive typed `data`. Kind arms and `_` receive `{ kind, code, message, retryable,
+fields? }`. `_` is required even if you listed every kind.
+
+`explain(error).fields` maps `ValidationError` issues to `{ email: "Required" }` (`.`-joined
+path; empty path is `_`). `retryable` is true for `limited` and `unavailable`; `retryAfterMs` is
+set when the payload has `retryAfterMs` or `retryAfter` (seconds).
+
+```typescript
+import { explain, matchError } from "okengine/client/explain";
+
+if (result.error) {
+  matchError(result.error, {
+    FlightFull: (data) => offerWaitlist(data.seatsLeft),
+    _: (e) => toast(e.message),
+  });
+}
+
+explain(result.error!); // { kind, code, message, retryable, fields? }
+```
+
+`error.code === "FlightFull"` still narrows `error.data` if you prefer an `if`. HTTP status is on
+the response, not on `error`.
+
+Domain codes with no `{ message }` toast the code name (`OutOfStock`). Pass
+`fx.fail("OutOfStock", data, { message })` on the Flow, or name that code in `match`.
+
+See [Errors](/docs/reference/errors) for `fx.fail` helpers and store auto-map.
+
 ## `createClient` forms
 
 | Form                            | Types from                             | Wire                                             |
@@ -324,24 +400,19 @@ See [Store](/docs/elements/store) for the list query language. Handwritten lists
 ## Result envelopes
 
 Success may include optional top-level `meta` (for example pagination). Declared flow errors and
-transport failures share the failure arm:
+transport failures share the failure arm. Handle them with [`match`](#match--explain).
 
 ```typescript
-import { isOk, isFail, isErrorCode, isTransportError } from "okengine/client";
-
-const result = await api.bookings.create({ flightId: "SK481", seats: 2 });
-
-if (isOk(result)) {
-  result.data.confirmationCode;
-} else if (result.error.code === "FlightFull") {
-  result.error.data.seatsLeft;
-} else if (isTransportError(result.error)) {
-  result.error.data.message;
-}
+import { isOk, isFail, isTransportError } from "okengine/client";
 
 isFail(result); // true when error !== null
+isOk(result); // narrows to success `data`
+isTransportError(result.error); // network / non-envelope HTTP
 ```
 
+`error.code === "FlightFull"` still narrows `error.data`. HTTP status is on the response, not on
+`error`.
+
 ## Remote types
 
 `oke dev` regenerates `oke-client.d.ts` from `GET /_oke/client.json`. A separate storefront repo —
@@ -376,6 +447,7 @@ CLI details: [CLI Reference](/docs/reference/cli).
 | `createTransport`                         | function  | Low-level HTTP transport (timeout / retry / auth)   |
 | `isOk` / `isFail`                         | function  | Envelope predicates                                 |
 | `isErrorCode` / `isTransportError`        | function  | Error narrowing                                     |
+| `match` / `matchError` / `explain`        | function  | `okengine/client/explain` — `ok`, codes, kinds, `_` |
 | `Client`, `ClientCall`, `ClientResult`, … | types     | Contracts, `page.next()` / `for await` of `list()`  |
 | `Register`                                | interface | Module-augmentation slot for ambient App types      |
 | `AppOf`                                   | type      | Brand a bare route map as an App                    |
@@ -402,8 +474,24 @@ Restart `oke dev` after renaming exports.
 
 <Accordion title='error.code is "TransportError"'>
   Network failure, abort (`timeout`), non-JSON body, empty error response, or HTTP status without a
-  `{ data, error }` envelope. Declared flow codes (`NotFound`, `FlightFull`, …) never use this code.
-  Message text lives in `error.data.message`; HTTP status may appear as `error.data.status`.
+  `{ data, error }` envelope. Built-in and domain flow codes never use this code.
+  Prefer `error.message` — it always equals `error.data.message`. `explain` maps HTTP 404 transport
+  to kind `missing`.
+</Accordion>
+
+<Accordion title="Why import from okengine/client/explain?">
+  `match` / `explain` stay off the measured `okengine/client` gzip cap. Predicates (`isOk`,
+  `isTransportError`) stay on `okengine/client`.
+</Accordion>
+
+<Accordion title="Toast showed OutOfStock / FlightFull">
+  Domain codes with no `{message}` use the code name as `explain.message`. Handle the named arm, or
+  pass `fx.fail("OutOfStock", data, {message})` on the Flow.
+</Accordion>
+
+<Accordion title="404 — route miss or NotFound?">
+  Bare body `Not Found` means no HTTP route — `TransportError` (kind `missing`). JSON
+  `{ error: { code: "NotFound" } }` is `fx.fail.notFound`. Distinguish by envelope, not status.
 </Accordion>
 
 <Accordion title="Failed to fetch …/_oke/client.json">
@@ -427,7 +515,7 @@ Restart `oke dev` after renaming exports.
 - [Vault · Config](/docs/elements/vault/config) — `PUBLIC_API_URL`, `vault.env`
 - [Routing](/docs/elements/flow/routing) — `$routes` stamps
 - [HTTP](/docs/elements/flow/http) — verbs and envelopes on the server
-- [Errors](/docs/reference/errors) — framework codes vs failure values
+- [Errors](/docs/reference/errors) — `fx.fail` helpers, store auto-map, `match` on the client
 - [CLI](/docs/reference/cli) — `oke client add`, `oke dev`
 
 ## Next

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

@@ -51,7 +51,7 @@ const api = createClient(app, vault.env("PUBLIC_API_URL") ?? "");
 const { data, error } = await api.bookings.get({ id: "bkg_7f3a" });
 
 if (error) {
-  // TransportError or a declared flow code (NotFound, …)
+  // TransportError or a flow code (NotFound, …)
   return;
 }
 
@@ -160,7 +160,7 @@ dev so `createClient("")` stays same-origin behind your proxy.
 <Cards>
   <Card
     title="Calling"
-    description="createClient forms, REST vs RPC, options, envelopes, resources, remote types."
+    description="createClient forms, REST vs RPC, match/explain, envelopes, remote types."
     href="/docs/client/calling"
   />
   <Card
@@ -192,7 +192,7 @@ dev so `createClient("")` stays same-origin behind your proxy.
 <Cards>
   <Card
     title="Calling"
-    description="REST vs RPC, options, helpers, and remote types."
+    description="REST vs RPC, match/explain, options, and remote types."
     href="/docs/client/calling"
   />
   <Card

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

@@ -110,7 +110,7 @@ export const create = on(
 
 <Tab value="Failures">
 
-Declare typed domain errors and return clean failure responses using `fx.fail`:
+Declare typed domain errors on `errors:`. Built-in codes use helpers (`fx.fail.notFound`) with no bag:
 
 ```typescript title="src/flows/orders/[id]/get.ts"
 import { on, flow, http } from "okengine";
@@ -120,12 +120,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;
     },
   }),
@@ -287,12 +286,11 @@ export const get = on(
   http.get({
     in: z.object({ id: z.string() }),
     out: z.object({ id: z.string(), title: z.string() }),
-    errors: { NotFound: z.object({ id: z.string() }) },
   }),
   flow({
     do: async ({ id }, fx) => {
       const [note] = await fx.store(db).select().from(notes).where(eq(notes.id, id));
-      if (!note) return fx.fail("NotFound", { id });
+      if (!note) return fx.fail.notFound({ id });
       return note;
     },
   }),
@@ -378,7 +376,6 @@ export const update = on(
       title: z.string().min(1).optional(),
     }),
     out: z.object({ id: z.string(), title: z.string() }),
-    errors: { NotFound: z.object({ id: z.string() }) },
   }),
   flow({
     do: async ({ id, title }, fx) => {
@@ -386,7 +383,7 @@ export const update = on(
         await fx.store(db).update(notes).set({ title }).where(eq(notes.id, id));
       }
       const [note] = await fx.store(db).select().from(notes).where(eq(notes.id, id));
-      if (!note) return fx.fail("NotFound", { id });
+      if (!note) return fx.fail.notFound({ id });
       return note;
     },
   }),
@@ -465,7 +462,6 @@ import { db, notes } from "@/schema";
 export const head = on(
   http.head("/notes/:id", {
     in: z.object({ id: z.string() }),
-    errors: { NotFound: z.object({ id: z.string() }) },
   }),
   flow({
     do: async ({ id }, fx) => {
@@ -474,7 +470,7 @@ export const head = on(
         .select({ id: notes.id })
         .from(notes)
         .where(eq(notes.id, id));
-      if (!note) return fx.fail("NotFound", { id });
+      if (!note) return fx.fail.notFound({ id });
       return;
     },
   }),
@@ -577,7 +573,7 @@ pathless `http.resource()` — pass an explicit base path.
 | `out`      | Schema    | _(required)_                     | Item shape (get / list / update return)                                  |
 | `update`   | Schema    | `in`                             | Patch fields. Wire body is `{ id, ...patch }`                            |
 | `idSchema` | Schema    | `update`/`in` + `{ id: string }` | Replaces the update Flow `in` when set (include the id key)              |
-| `errors`   | error map | `{ NotFound }`                   | Typed failures on get / update / remove                                  |
+| `errors`   | error map | —                                | Extra domain codes. Built-in `NotFound` is always on                     |
 | `id`       | column    | table PK                         | Column bound to `:id`                                                    |
 | `list`     | object    | see List Options                 | List query grammar (`GET /notes`)                                        |
 | `breaking` | `boolean` | `false`                          | Marks the five Flows `breaking: true` (handwritten → resource migration) |
@@ -965,10 +961,11 @@ return fx.json.ok({ id: "ord_1" }, { meta: { traceId: fx.runId } });
 return new Response(null, { status: 302, headers: { Location: url } });
 ```
 
-**Typed failures** — `fx.fail(code, data)` formats the error envelope and maps status:
+**Typed failures** — built-in helpers need no `errors:` bag. Domain codes still go on `errors:`:
 
 ```typescript
-return fx.fail("NotFound", { id: "123" });
+return fx.fail.notFound({ id: "123" });
+return fx.fail("OutOfStock", { available: 0 });
 ```
 
 ```json
@@ -976,7 +973,7 @@ return fx.fail("NotFound", { id: "123" });
   "data": null,
   "error": {
     "code": "NotFound",
-    "message": "Resource not found",
+    "message": "The requested resource was not found.",
     "data": { "id": "123" }
   }
 }
@@ -987,8 +984,14 @@ Standard status code mappings:
 - `ValidationError` → `422 Unprocessable Entity`
 - `Unauthorized` → `401 Unauthorized`
 - `Forbidden` → `403 Forbidden`
-- `RateLimited` → `429 Too Many Requests`
-- Custom error codes → `400 Bad Request`
+- `NotFound` → `404 Not Found` (JSON envelope — router miss is plain-text `404`)
+- `Conflict` / `ForeignKey` → `409 Conflict`
+- `UnsupportedMediaType` → `415 Unsupported Media Type`
+- `RateLimited` / `AuthRateLimited` → `429 Too Many Requests`
+- `DatabaseError` → `422` (`not_null` / `check` / `invalid` / `too_long` / `out_of_range`), `503` (`retryable`), else `500`
+- `ServiceUnavailable` → `503 Service Unavailable`
+- `InternalError` → `500 Internal Server Error` (catalog message only)
+- Domain codes (`OutOfStock`, `FlightFull`, `Duplicate`) → `400 Bad Request`
 
 ## Troubleshooting
 

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

@@ -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;
     },
   }),
@@ -318,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>
 
@@ -386,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)">
@@ -546,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">
@@ -556,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">

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

@@ -64,7 +64,7 @@ export const list = on(
   flow({
     do: async (_, fx) => {
       const tenantId = fx.tenant.id;
-      if (!tenantId) return fx.fail("Forbidden", { reason: "tenant_required" });
+      if (!tenantId) return fx.fail.forbidden({ reason: "tenant_required" });
       return await fx.store(db).select().from(invoices).where(eq(invoices.tenantId, tenantId));
     },
   }),

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

@@ -318,13 +318,12 @@ import { uploads } from "@/core";
 export const get = on(
   http.get({
     in: z.object({ id: z.string(), name: z.string() }),
-    errors: { NotFound: z.object({ key: z.string() }) },
   }),
   flow({
     do: async ({ id, name }, fx) => {
       const key = `notes/${id}/${name}`;
       const bytes = await fx.store(uploads).get(key);
-      if (!bytes) return fx.fail("NotFound", { key });
+      if (!bytes) return fx.fail.notFound({ key });
       return { key, size: bytes.byteLength };
     },
   }),
@@ -582,7 +581,7 @@ export default defineConfig({
   },
   images: {
     store: {
-      files: "rustfs/rustfs:1.0.0-rc.5",
+      files: "rustfs/rustfs:1.0.0",
     },
   },
 });
@@ -607,8 +606,14 @@ For `s3`, Compose / env typically supply `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`,
 </Accordion>
 
 <Accordion title="Invalid object key">
-  Cause: `Invalid object key: …` on the `fs` driver when the key starts with `/` or contains `..`.
-  Use relative, non-escaping keys.
+  The `fs` driver rejects keys that start with `/` or contain `..`. HTTP is `Forbidden` **403**
+  (`reason: invalid_key`) — the key is not copied. Use relative, non-escaping keys.
+</Accordion>
+
+<Accordion title="S3 AccessDenied / disk full is InternalError">
+  `AccessDenied` / `EACCES` map to `Forbidden` **403**. Missing `get` stays `null`. `SlowDown` stays
+  thrown until `flow.retry` exhausts, then **503**. `NoSuchBucket` / `ENOSPC` are **503** — see
+  [Errors · Files auto-map](/docs/reference/errors#files-auto-map).
 </Accordion>
 
 <Accordion title="ERR_IMAGE_TOO_MANY_PIXELS">
@@ -644,6 +649,7 @@ For `s3`, Compose / env typically supply `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`,
 - [HTTP](/docs/elements/flow/http) — routes that accept uploads
 - [Vault](/docs/elements/vault) — credentials for S3 when you configure bindings
 - [fx](/docs/reference/fx) — `fx.store(decl)`
+- [Errors](/docs/reference/errors) — Files auto-map
 - [Configuration](/docs/reference/configuration) — `drivers.store.files`
 
 ## Next

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

@@ -117,12 +117,11 @@ import { db, notes } from "@/schema";
 export const get = on(
   http.get({
     in: z.object({ id: z.string() }),
-    errors: { NotFound: z.object({ id: z.string() }) },
   }),
   flow({
     do: async ({ id }, fx) => {
       const [note] = await fx.store(db).select().from(notes).where(eq(notes.id, id));
-      if (!note) return fx.fail("NotFound", { id });
+      if (!note) return fx.fail.notFound({ id });
       return note;
     },
   }),
@@ -228,7 +227,7 @@ export default defineConfig({
     store: {
       sql: "postgres:18-alpine",
       kv: "redis:8-alpine",
-      files: "rustfs/rustfs:1.0.0-rc.5",
+      files: "rustfs/rustfs:1.0.0",
     },
   },
 });

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

@@ -262,7 +262,7 @@ export const get = on(
     do: async ({ token }, fx) => {
       const userId = await fx.store(sessions).get(`session:${token}`);
       if (userId === undefined || userId === null) {
-        return fx.fail("NotFound", { token });
+        return fx.fail.notFound({ token });
       }
       return { userId };
     },
@@ -599,6 +599,12 @@ Gate rate strategies inherit `drivers.store.kv` (no separate `drivers.gate`).
   does). Prefer prefix filters in admin Flows.
 </Accordion>
 
+<Accordion title="Redis down returns InternalError">
+  Connection / `CLUSTERDOWN` / `READONLY` map to `ServiceUnavailable` **503**. `BUSY` / `TRYAGAIN`
+  stay thrown until `flow.retry` exhausts, then **503**. `WRONGTYPE` stays `InternalError` — see
+  [Errors · KV auto-map](/docs/reference/errors#kv-auto-map).
+</Accordion>
+
 <Accordion title="I expected incr / setNx / fx.store.kv">
   Those helpers are not on the public handle. Use `get` / `set` / `delete` / `list` / `ttlMs` via
   `fx.store(decl)`. Gate rates use Redis Lua internally.
@@ -614,7 +620,7 @@ Gate rate strategies inherit `drivers.store.kv` (no separate `drivers.gate`).
 - [Gate](/docs/elements/gate) — rate buckets use Redis internally
 - [fx](/docs/reference/fx) — `fx.store(decl)`
 - [Configuration](/docs/reference/configuration) — `drivers.store.kv`
-- [Errors](/docs/reference/errors) — OKE1810
+- [Errors](/docs/reference/errors) — OKE1810 · KV auto-map
 
 ## Next
 

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

@@ -344,12 +344,11 @@ export const get = on(
   http.get({
     in: z.object({ id: z.string() }),
     out: z.object({ id: z.string(), title: z.string() }),
-    errors: { NotFound: z.object({ id: z.string() }) },
   }),
   flow({
     do: async ({ id }, fx) => {
       const [note] = await fx.store(db).select().from(notes).where(eq(notes.id, id));
-      if (!note) return fx.fail("NotFound", { id });
+      if (!note) return fx.fail.notFound({ id });
       return note;
     },
   }),
@@ -404,7 +403,6 @@ export const update = on(
       id: z.string(),
       title: z.string().min(1).optional(),
     }),
-    errors: { NotFound: z.object({ id: z.string() }) },
   }),
   flow({
     do: async ({ id, title }, fx) => {
@@ -412,7 +410,7 @@ export const update = on(
         await fx.store(db).update(notes).set({ title }).where(eq(notes.id, id));
       }
       const row = await fx.store(db).findById(notes, id);
-      if (!row) return fx.fail("NotFound", { id });
+      if (!row) return fx.fail.notFound({ id });
       return row;
     },
   }),
@@ -591,7 +589,7 @@ The URL id segment is always `:id`. Update is **PATCH**, not PUT.
 | `out`      | Schema    | _(required)_                     | Item shape (get / list / update return)                                  |
 | `update`   | Schema    | `in`                             | Patch fields. Wire body is `{ id, …patch }`                              |
 | `idSchema` | Schema    | `update`/`in` + `{ id: string }` | Replaces the update Flow `in` when set (include the id key)              |
-| `errors`   | error map | `{ NotFound }`                   | Typed failures on get / update / remove                                  |
+| `errors`   | error map | —                                | Extra domain codes. Built-in `NotFound` is always on                     |
 | `id`       | column    | table PK                         | Column bound to `:id`                                                    |
 | `list`     | object    | see List Options                 | List query grammar (`GET /notes`)                                        |
 | `breaking` | `boolean` | `false`                          | Marks the five Flows `breaking: true` (handwritten → resource migration) |
@@ -917,6 +915,11 @@ export default defineConfig({
   `oke db migrate` in that environment.
 </Accordion>
 
+<Accordion title="Unique insert is 500 InternalError">
+  Unique / exclusion maps to `Conflict` **409**; missing FK to `ForeignKey` **409**. See [Errors ·
+  SQL auto-map](/docs/reference/errors#sql-auto-map).
+</Accordion>
+
 <Accordion title="update().set().where(): condition required">
   Updates and deletes without a `where` are rejected (`delete().where(): condition required`). Pass
   a Drizzle condition or equality map — or use `delete(table, id)` for PK deletes.
@@ -976,7 +979,7 @@ export default defineConfig({
 - [HTTP · Resources](/docs/elements/flow/http#resources) — mount, live SSE, verb table
 - [Consumers · CDC](/docs/elements/flow/consumers#cdc) — `db.table(…).changed()`
 - [fx](/docs/reference/fx) — `fx.store` session
-- [Errors](/docs/reference/errors) — OKE1110 · OKE1041
+- [Errors](/docs/reference/errors) — OKE1110 · OKE1041 · SQL auto-map
 
 ## Next