okengine 0.19.9 → 0.21.0

package/AGENTS.md

@@ -84,7 +84,7 @@ After changing `src/kernel/`, `src/client/`, `src/compiler/`, `src/validation/`,
 Published packages:
 
 - `okengine` — framework. Subpath exports: `.`, `./client`, `./test`, `./config`, `./auth`, `./plugins`, `./drivers/*`. `"sideEffects": false`. CLI binary: `oke`.
-- `create-oke` — scaffold CLI (`bunx create-oke@latest <name>`). Lives in `packages/create-oke` and ships Notes starters from `packages/create-oke/templates/{standard,advanced}`.
+- `create-oke` — scaffold CLI (`bunx create-oke@latest <name>`). Lives in `packages/create-oke` and ships starters from `packages/create-oke/templates/{blank,shorter}`.
 
 Engine: Bun `>=1.4.2`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.19.9",
+  "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/auth.mdx

@@ -171,8 +171,7 @@ auth.bind(api);
 | `Forbidden`    | 403  | Wrong scopes / CSRF — read `error.data.reason` |
 | `RateLimited`  | 429  | Wait `retryAfterMs`                            |
 
-Also see [CORS](/docs/plugins/cors) and [CSRF](/docs/plugins/csrf). Advanced create-oke starter
-demos cookie + passkey + `<Can>`.
+Also see [CORS](/docs/plugins/cors) and [CSRF](/docs/plugins/csrf).
 
 ## Troubleshooting
 

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
@@ -81,11 +81,11 @@ export const publicApiUrl = vault.config("PUBLIC_API_URL", {
 });
 ```
 
-| Runtime                                    | Base URL for `createClient`                                     |
-| ------------------------------------------ | --------------------------------------------------------------- |
-| Browser / Bun (create-oke web)             | `vault.env("PUBLIC_API_URL") ?? ""` — empty = same-origin proxy |
-| Node / worker / CLI                        | `vault.env.required("PUBLIC_API_URL")`                          |
-| Separate storefront after `oke client add` | Same `vault.env("PUBLIC_API_URL") ?? ""`                        |
+| Runtime                                    | Base URL for `createClient`                               |
+| ------------------------------------------ | --------------------------------------------------------- |
+| Browser / Bun                              | `vault.env("PUBLIC_API_URL") ?? ""` — empty = same origin |
+| Node / worker / CLI                        | `vault.env.required("PUBLIC_API_URL")`                    |
+| Separate storefront after `oke client add` | Same `vault.env("PUBLIC_API_URL") ?? ""`                  |
 
 Set `PUBLIC_API_URL` via environment or `oke vault set`. Prefer `vault.env` over raw
 `process.env` — same helpers as the rest of the measure. See
@@ -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 —
@@ -362,8 +433,8 @@ const api = createClient(import.meta.env.PUBLIC_API_URL ?? "", { $routes: routes
 
 Ambient `.d.ts` types `in` / `out` / live / stream stamps. The routes module supplies wire REST.
 
-create-oke starters ship `web/`: Vite proxies Flow paths plus `/auth` and `/_oke` to the app.
-Leave `PUBLIC_API_URL` unset in local web so `createClient("")` stays same-origin.
+Point `createClient` at your app origin (`PUBLIC_API_URL`), or leave it empty when the
+browser page is same-origin with the API.
 
 CLI details: [CLI Reference](/docs/reference/cli).
 
@@ -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                    |
@@ -387,7 +459,7 @@ Budget: the `./client` export stays under the measured client-runtime cap (hard
 <Accordions>
 
 <Accordion title="api.bookings.get is not a function / type error">
-  Confirm the Flow is `export`ed from a generated unit (`import "@/flows/generated"` then
+  Confirm the Flow is `export`ed from a generated unit (`import "@/flows"` then
   `oke({ name })`), or from a module you still `.adopt({ bookings })`.
 
 Type `createClient` with that `App` (or ambient `Register` after `oke-client.d.ts` regenerates).
@@ -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

@@ -27,7 +27,7 @@ the envelope.
 
 ```typescript title="src/app.ts"
 import "@/core";
-import "@/flows/generated";
+import "@/flows";
 import { oke } from "okengine/http";
 
 export const app = oke({ name: "commerce" });
@@ -46,12 +46,12 @@ import { createClient } from "okengine/client";
 import { vault } from "okengine/vault";
 import { app } from "../../src/app";
 
-// Base URL via vault.env (empty = same-origin proxy in create-oke web)
+// Base URL via vault.env (empty = same origin as the page)
 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;
 }
 
@@ -128,8 +128,8 @@ const api = createClient(vault.env("PUBLIC_API_URL") ?? "");
 ```
 
 Declare the origin on the server with [Vault · Config](/docs/elements/vault/config)
-(`PUBLIC_API_URL`), then set it via env or `oke vault set`. Leave it unset in local web
-dev so `createClient("")` stays same-origin behind the Vite proxy.
+(`PUBLIC_API_URL`), then set it via env or `oke vault set`. Leave it unset in local frontend
+dev so `createClient("")` stays same-origin behind your proxy.
 
 </Tab>
 
@@ -160,7 +160,7 @@ dev so `createClient("")` stays same-origin behind the Vite 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 the Vite 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/client/react.mdx

@@ -221,6 +221,11 @@ Prefer [`createAuthClient`](/docs/client/auth) for cookie/Bearer sessions and me
   Without a token, status becomes `"unauthenticated"`.
 </Accordion>
 
+<Accordion title="Vite SPA is a blank page">
+  The console shows `node:async_hooks` / `AsyncLocalStorage` from `okengine/client-react`. Upgrade
+  okengine — `Can` / `useLiveQuery` must not import the server realtime binder.
+</Accordion>
+
 <Accordion title="useLiveQuery never connects">
   Pass `live: { method, path }` from `app.$routes` for the resource’s `/live` route. Set
   `enabled: true` (or omit). See [Live](/docs/client/live) for exposure and resume errors.

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

@@ -6,14 +6,14 @@ source: "docs/spec/unified-theory.md"
 ---
 
 Email (`channel.email`) is the default Channel medium. Declare a binder with a From address,
-register templates, put bodies in the catalog, and send with `fx.send`.
+put `{{field}}` bodies on `.template({ catalog })`, and send with `fx.send`.
 
 For developers who need local catchers and production HTTP MTAs — same `fx.send` path, swap the
 driver.
 
 <Callout title="The one rule">
-  Use `channel.email({ from }).template(name, { schema, locales })` — never
-  `channel.email("name", { subject, body })`. Subject and body live in the catalog.
+  Use `channel.email({ from }).template(name, { schema, locales, catalog })`. Subject and body
+  live on the template — not on `oke()`.
 </Callout>
 
 ## Smallest Example
@@ -33,32 +33,20 @@ export const passwordReset = mail.template("auth.resetPassword", {
   description: "Password reset link",
   locales: ["en"],
   schema: z.object({ resetLink: z.string().url() }),
+  catalog: {
+    en: {
+      subject: "Reset your password",
+      text: "Open {{resetLink}} to choose a new password.",
+      html: '<p><a href="{{resetLink}}">Reset your password</a></p>',
+    },
+  },
 });
 ```
 
 </Step>
 
 <Step>
-### Catalog + send
-
-```typescript title="src/app.ts"
-import { oke } from "okengine";
-
-oke({
-  name: "app",
-  channel: {
-    catalog: {
-      "auth.resetPassword": {
-        en: {
-          subject: "Reset your password",
-          text: "Open {{resetLink}} to choose a new password.",
-          html: '<p><a href="{{resetLink}}">Reset your password</a></p>',
-        },
-      },
-    },
-  },
-});
-```
+### Send from a Flow
 
 ```typescript title="src/flows/auth/reset.ts"
 import { on, flow, http } from "okengine";
@@ -118,13 +106,13 @@ Per-locale `subject` / `text` / `html` with `{{field}}` interpolation from `data
 
 ```typescript
 catalog: {
-  "auth.resetPassword": {
-    en: { subject: "Reset", text: "{{resetLink}}", html: "<a href=\"{{resetLink}}\">Reset</a>" },
-    ar: { subject: "إعادة التعيين", text: "{{resetLink}}" },
-  },
+  en: { subject: "Reset", text: "{{resetLink}}", html: "<a href=\"{{resetLink}}\">Reset</a>" },
+  ar: { subject: "إعادة التعيين", text: "{{resetLink}}" },
 }
 ```
 
+Put that object on `.template({ catalog })`. Do not nest the template name again.
+
 </Tab>
 
 <Tab value="Failover">
@@ -146,8 +134,8 @@ Receipt status `fallback` means an earlier attempt failed and a later one succee
 
 <Tab value="Plugin catalog">
 
-Official plugins contribute catalogs with `.channelCatalog(…)` (e.g. OTP, magic link). App
-`channel.catalog` merges with plugin contributions at boot.
+Official plugins put copy on `.template({ catalog })` (OTP, magic link, two-factor). App
+`oke({ channel.catalog })` and plugin `.channelCatalog(…)` overlay those bodies at boot.
 
 </Tab>
 
@@ -164,11 +152,12 @@ Official plugins contribute catalogs with `.channelCatalog(…)` (e.g. OTP, magi
 
 ### `.template(name, options?)`
 
-| Option        | Type       | Meaning                     |
-| ------------- | ---------- | --------------------------- |
-| `description` | `string`   | Console label               |
-| `locales`     | `string[]` | Declared locales            |
-| `schema`      | Schema     | Payload contract for `data` |
+| Option        | Type       | Meaning                                |
+| ------------- | ---------- | -------------------------------------- |
+| `description` | `string`   | Console label                          |
+| `locales`     | `string[]` | Declared locales                       |
+| `schema`      | Schema     | Payload contract for `data`            |
+| `catalog`     | object     | Per-locale `subject` / `text` / `html` |
 
 Default From when neither binder nor template sets one: `"oke@localhost.test"`.
 
@@ -229,8 +218,8 @@ Channel catalogs are **not** ICU — do not use `fx.t` for email bodies ([i18n](
 </Accordion>
 
 <Accordion title="Message in Mailpit has JSON body / template name as subject">
-  No catalog entry for that template + locale. Add `channel.catalog` (or a plugin catalog) with
-  `subject` / `text` / `html`.
+  No catalog entry for that template + locale. Add `catalog` on `.template(…)` (or overlay with
+  `oke({channel.catalog})` / plugin `.channelCatalog`) with `subject` / `text` / `html`.
 </Accordion>
 
 <Accordion title="suppressed/opted-out or prior-bounce — no provider call">