okengine 0.19.9 → 0.21.0

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

@@ -6,16 +6,16 @@ source: "docs/spec/unified-theory.md"
 ---
 
 Channel is how your backend **reaches a person** — the order-confirmation email, the SMS
-sign-in code, a WhatsApp notice, or a device push. You declare a template on a medium, fill a
-`{{field}}` body catalog, and send from a Flow with `fx.send`.
+sign-in code, a WhatsApp notice, or a device push. You declare a template on a medium with
+per-locale `{{field}}` bodies, then send from a Flow with `fx.send`.
 
 For developers wiring Mailpit locally and Resend / Taqnyat / FCM in production — templates and
 drivers first, never vendor SDKs inside `do`.
 
 <Callout title="The one rule">
-  Declare a template (`channel.email(…).template(…)`), then `fx.send(template, { to, data })`.
-  Bodies live in the catalog (`subject` / `text` / `html`), not on the declare call. Consent and
-  prior bounces suppress before any driver runs.
+  Declare a template (`channel.email(…).template({ catalog })`), then `fx.send(template, { to, data })`.
+  Bodies live on the declare (`subject` / `text` / `html` per locale). Consent and prior bounces
+  suppress before any driver runs.
 </Callout>
 
 <ChannelPhysics />
@@ -27,18 +27,28 @@ drivers first, never vendor SDKs inside `do`.
 <Step>
 ### Declare an email template
 
-```typescript title="src/core/channel.ts"
+```typescript title="src/core/email.ts"
 import { channel } from "okengine";
 import { z } from "zod";
 
-const mail = channel.email({ from: "Notes <notes@localhost>" });
+const mail = channel.email({ from: "Shorter <shorter@localhost>" });
 
-export const noteCreatedMail = mail.template("note-created", {
+export const linkCreatedMail = mail.template("link-created", {
+  description: "Short URL delivered to the demo inbox",
   locales: ["en"],
   schema: z.object({
     id: z.string(),
-    title: z.string(),
+    code: z.string(),
+    url: z.string(),
+    shortUrl: z.string(),
   }),
+  catalog: {
+    en: {
+      subject: "Short link {{code}}",
+      text: "{{shortUrl}} → {{url}}",
+      html: '<p><a href="{{shortUrl}}">{{code}}</a> → {{url}}</p>',
+    },
+  },
 });
 ```
 
@@ -50,26 +60,42 @@ Import this module before `oke()` so auto-registry adopts the template (or pass
 <Step>
 ### Send from a Flow
 
-```typescript title="src/flows/notes/on-created.ts"
-import { on, flow } from "okengine";
-import { noteCreatedMail } from "@/core/channel";
-import { noteCreated } from "./signals";
+```typescript title="src/flows/links/signals.ts"
+import { on, flow, signal } from "okengine";
+import { z } from "zod";
+import { linkCreatedMail } from "@/core";
+
+export const linkCreated = signal.once("link-created", {
+  retries: 3,
+  deadLetter: true,
+  schema: z.object({
+    id: z.string(),
+    code: z.string(),
+    url: z.string(),
+    shortUrl: z.string(),
+  }),
+});
 
 export const onCreated = on(
-  noteCreated,
-  flow("notes.onCreated", {
+  linkCreated,
+  flow("links.onCreated", {
     do: async (payload, fx) => {
-      await fx.send(noteCreatedMail, {
+      await fx.send(linkCreatedMail, {
         to: "you@localhost",
-        data: { id: payload.id, title: payload.title },
+        data: {
+          id: payload.id,
+          code: payload.code,
+          url: payload.url,
+          shortUrl: payload.shortUrl,
+        },
       });
     },
   }),
 );
 ```
 
-The compiler stamps `sends: ["note-created"]` on the Flow’s effects (template name — not
-`email:note-created`).
+The compiler stamps `sends: ["link-created"]` on the Flow’s effects (template name — not
+`email:link-created`). Declaration and subscriber share `signals.ts`.
 
 </Step>
 
@@ -77,8 +103,8 @@ The compiler stamps `sends: ["note-created"]` on the Flow’s effects (template
 ### See it locally
 
 With `drivers.channel.email.dev: "smtp"` and Mailpit pinned, open the Mailpit UI
-(`MAILPIT_UI_URL`). Missing catalog bodies fall back to `subject: note-created` and
-`text: JSON.stringify(data)`.
+(`MAILPIT_UI_URL`). Subject and HTML come from the template `catalog`. Omit `catalog` and the
+runtime falls back to `subject: link-created` and `text: JSON.stringify(data)`.
 
 </Step>
 
@@ -95,9 +121,14 @@ From a bare send to catalog bodies, locale, and same-medium failover:
 Template handle + recipient — catalog optional for local smoke tests:
 
 ```typescript
-await fx.send(noteCreatedMail, {
+await fx.send(linkCreatedMail, {
   to: "alice@example.com",
-  data: { id: "n1", title: "Hello" },
+  data: {
+    id: "lnk_1",
+    code: "ok",
+    url: "https://example.com",
+    shortUrl: "http://localhost:6530/ok",
+  },
 });
 ```
 
@@ -105,23 +136,22 @@ await fx.send(noteCreatedMail, {
 
 <Tab value="Catalog">
 
-Bodies are `{{field}}` strings per locale — not ICU, not React. Pass them on boot or via a
-plugin `.channelCatalog(…)`:
-
-```typescript title="src/app.ts"
-import { oke } from "okengine";
-
-export const app = oke({
-  name: "notes",
-  channel: {
-    catalog: {
-      "note-created": {
-        en: {
-          subject: "Note created",
-          text: "Your note {{title}} ({{id}}) is ready.",
-          html: "<p>Your note <strong>{{title}}</strong> is ready.</p>",
-        },
-      },
+Bodies are `{{field}}` strings per locale — not ICU, not React. Put them on the template.
+`oke({ channel.catalog })` and plugin `.channelCatalog(…)` are overlays (later locale wins):
+
+```typescript title="src/core/email.ts"
+export const linkCreatedMail = mail.template("link-created", {
+  locales: ["en"],
+  schema: z.object({
+    code: z.string(),
+    url: z.string(),
+    shortUrl: z.string(),
+  }),
+  catalog: {
+    en: {
+      subject: "Short link {{code}}",
+      text: "{{shortUrl}} → {{url}}",
+      html: '<p><a href="{{shortUrl}}">{{code}}</a> → {{url}}</p>',
     },
   },
 });
@@ -136,9 +166,14 @@ Precedence: explicit `locale` → `profileLocale` → `Accept-Language` →
 `fx.locale`.
 
 ```typescript
-await fx.send(noteCreatedMail, {
+await fx.send(linkCreatedMail, {
   to: "alice@example.com",
-  data: { id: "n1", title: "مرحبا" },
+  data: {
+    id: "lnk_1",
+    code: "ok",
+    url: "https://example.com",
+    shortUrl: "http://localhost:6530/ok",
+  },
   locale: "ar",
 });
 ```
@@ -154,9 +189,14 @@ Order same-medium drivers for failover. Provider / 5xx errors advance; permanent
 (400, invalid address) do **not**:
 
 ```typescript
-await fx.send(noteCreatedMail, {
+await fx.send(linkCreatedMail, {
   to: "alice@example.com",
-  data: { id: "n1", title: "Hello" },
+  data: {
+    id: "lnk_1",
+    code: "ok",
+    url: "https://example.com",
+    shortUrl: "http://localhost:6530/ok",
+  },
   via: ["smtp", "resend"],
 });
 ```
@@ -193,12 +233,14 @@ succeeded — every attempt is kept on the receipt.
 | `description` | `string`   | name      | Console / docs label                                |
 | `locales`     | `string[]` | —         | Declared locale tags for the template               |
 | `schema`      | Schema     | —         | Payload shape (Zod / Standard Schema)               |
+| `catalog`     | object     | —         | Per-locale `subject` / `text` / `html`              |
 | `from`        | `string`   | binder’s  | Override sender on agnostic `channel.template` only |
 | `medium`      | medium     | `"email"` | Only on `channel.template()`                        |
 
 Empty name throws `TypeError: channel.template: name is required`.
 
-There is **no** `subject` / `body` / `html` on declare — those belong in the catalog.
+`oke({ channel.catalog })` overlays bodies after template catalogs (tests / plugin copy
+overrides). Manifest stays free of copy.
 
 ## `fx` surface
 
@@ -295,7 +337,7 @@ Env knobs: [Environment variables](/docs/reference/environment-variables). Local
 
 <Accordion title="OKE1004 — UNDECLARED_SEND">
   Cause: `Flow "{flow}" sends "{resource}" without declaring it.` Touch the template handle
-  inside `do` (inference) or list `effects: { sends: ["note-created"] }`.
+  inside `do` (inference) or list `effects: { sends: ["link-created"] }`.
 </Accordion>
 
 <Accordion title="channel: no email transport in driver chain">

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

@@ -37,6 +37,9 @@ export const orderPush = push.template("order.status", {
     title: z.string(),
     body: z.string(),
   }),
+  catalog: {
+    en: { subject: "{{title}}", text: "{{body}}" },
+  },
 });
 ```
 
@@ -59,11 +62,6 @@ export const app = oke({
         privateKey: process.env.FCM_PRIVATE_KEY,
       }),
     ],
-    catalog: {
-      "order.status": {
-        en: { subject: "{{title}}", text: "{{body}}" },
-      },
-    },
   },
 });
 ```
@@ -128,13 +126,13 @@ Web Push where the subscription is supplied on the runtime path.
 <Tab value="Catalog">
 
 ```typescript
-"order.status": {
+catalog: {
   en: { subject: "{{title}}", text: "{{body}}" },
 }
 ```
 
-`subject` becomes the notification title on FCM; `text` is the body. Extra `data` fields pass
-through as FCM data payload when present.
+Put that on `push.template({ catalog })`. `subject` becomes the notification title on FCM; `text`
+is the body. Extra `data` fields pass through as FCM data payload when present.
 
 </Tab>
 
@@ -163,7 +161,7 @@ Config key `drivers.channel.push` exists for Manifest / tooling ids (`console`
 
 ### `.template(name, options?)`
 
-`description` · `locales` · `schema` — same as other mediums.
+`description` · `locales` · `schema` · `catalog` — same as other mediums.
 
 ## Troubleshooting
 

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

@@ -52,6 +52,7 @@ const sms = channel.sms({ sender: "ACME" });
 export const orderShippedSms = sms.template("order.shipped", {
   locales: ["en"],
   schema: z.object({ tracking: z.string() }),
+  catalog: { en: { text: "Shipped — track {{tracking}}" } },
 });
 ```
 
@@ -62,7 +63,7 @@ await fx.send(orderShippedSms, {
 });
 ```
 
-Add a catalog body (`text: "Shipped — track {{tracking}}"`) or accept the JSON fallback.
+Missing `catalog` falls back to `subject: templateName` and `text: JSON.stringify(data)`.
 
 </Step>
 
@@ -102,6 +103,7 @@ Transactional SMS through the same `fx.send` path as email:
 const sms = channel.sms({ from: "ACME" });
 export const alertSms = sms.template("ops.alert", {
   schema: z.object({ message: z.string() }),
+  catalog: { en: { text: "{{message}}" } },
 });
 
 await fx.send(alertSms, { to: phone, data: { message: "Disk 90%" } });
@@ -202,7 +204,7 @@ Same medium options as email: `from` / `sender`.
 
 ### `.template(name, options?)`
 
-`description` · `locales` · `schema` — bodies in the catalog (`text` is typical for SMS).
+`description` · `locales` · `schema` · `catalog` — `text` is typical for SMS.
 
 ## Troubleshooting
 
@@ -229,8 +231,8 @@ Same medium options as email: `from` / `sender`.
 </Accordion>
 
 <Accordion title="channel: otp delivery failed on all channels">
-  Every medium in the failover list failed. Check driver credentials, suppression, and template
-  catalog entries.
+  Every medium in the failover list failed. Check driver credentials, suppression, and `catalog` on
+  each `.template()`.
 </Accordion>
 
 </Accordions>

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

@@ -53,6 +53,10 @@ const wa = channel.whatsapp();
 export const bookingReminder = wa.template("booking.reminder", {
   locales: ["en", "ar"],
   schema: z.object({ when: z.string(), place: z.string() }),
+  catalog: {
+    en: { text: "Reminder: {{when}} at {{place}}" },
+    ar: { text: "تذكير: {{when}} — {{place}}" },
+  },
 });
 ```
 
@@ -85,14 +89,12 @@ and SMS.
 Catalog typically supplies `text` (and optional `subject` where the transport uses it):
 
 ```typescript
-oke({
-  channel: {
-    catalog: {
-      "booking.reminder": {
-        en: { text: "Reminder: {{when}} at {{place}}" },
-        ar: { text: "تذكير: {{when}} — {{place}}" },
-      },
-    },
+export const bookingReminder = wa.template("booking.reminder", {
+  locales: ["en", "ar"],
+  schema: z.object({ when: z.string(), place: z.string() }),
+  catalog: {
+    en: { text: "Reminder: {{when}} at {{place}}" },
+    ar: { text: "تذكير: {{when}} — {{place}}" },
   },
 });
 ```
@@ -165,7 +167,7 @@ oke boot: unknown whatsapp channel driver "…"
 
 ### `.template(name, options?)`
 
-`description` · `locales` · `schema` — same as other mediums.
+`description` · `locales` · `schema` · `catalog` — same as other mediums.
 
 ## Troubleshooting
 

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

@@ -21,32 +21,19 @@ For developers scheduling work on okengine — one handle shape; drivers swap by
 <Steps>
 
 <Step>
-### Declare a named clock
+### Declare and bind in the unit
 
-```typescript title="src/clocks/digest.ts"
-import { clock } from "okengine";
-
-export const digestClock = clock.every("notes.digest", "1d");
-```
-
-</Step>
-
-<Step>
-### Bind a Flow
+```typescript title="src/flows/links/expire.ts"
+import { on, flow, clock } from "okengine/http";
 
-```typescript title="src/flows/notes/digest.ts"
-import { on, flow } from "okengine";
-import { digestClock } from "@/clocks/digest";
-import { db, notes } from "@/schema";
-import { isNull } from "drizzle-orm";
+const expireClock = clock.every("links.expire", "1h");
 
-export const digest = on(
-  digestClock,
-  flow("notes.digest", {
-    plane: "operator",
-    do: async (_, fx) => {
-      const rows = await fx.store(db).select().from(notes).where(isNull(notes.archivedAt));
-      return { active: rows.length, at: new Date(fx.clock.now()).toISOString() };
+export const expire = on(
+  expireClock,
+  flow({
+    do: async (_input, fx) => {
+      const now = fx.clock.now();
+      return { archived: 0, at: new Date(now).toISOString() };
     },
   }),
 );
@@ -57,9 +44,11 @@ export const digest = on(
 <Step>
 ### See it tick
 
-With `oke dev`, the scheduler reconciles `notes.digest` into the Store and leader-elects
+With `oke dev`, the scheduler reconciles `links.expire` into the Store and leader-elects
 before each fire. `do` receives no payload — read time with `fx.clock.now()` (epoch-ms).
-Map to ISO on the wire with `new Date(fx.clock.now()).toISOString()`.
+
+Pass that number into SQL `timestamp` columns as-is — insert, update, and WHERE binds
+coerce to `Date`. For a hand-built ISO reply, use `new Date(fx.clock.now()).toISOString()`.
 
 Under `drivers.clock.test = "frozen"`, advance time in tests instead of waiting a day.
 

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,24 +286,26 @@ 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;
     },
   }),
 );
 ```
 
+Declared `out` projects the row — return it as-is (Date or `fx.clock.now()` epoch-ms → ISO-8601; extra columns strip).
+
 </Tab>
 
 <Tab value="POST">
 
-Create a resource or run a command. `fx.json.create(value)` returns `201 Created` with
-`{ data: value, error: null }`:
+Create a resource or run a command. `fx.json.create(row)` returns `201 Created` with
+`{ data: value, error: null }`. Declared `out` projects the store row (Date / epoch-ms → ISO).
+HTTP `in` timestamps are ISO (`z.iso.datetime()`); store writes coerce them to `Date`.
 
 ```typescript title="src/flows/notes/create.ts"
 import { on, flow, http } from "okengine";
@@ -319,8 +320,8 @@ export const create = on(
   flow({
     do: async ({ title }, fx) => {
       const id = fx.id();
-      await fx.store(db).insert(notes).values({ id, title });
-      return fx.json.create({ id, title });
+      const [row] = await fx.store(db).insert(notes).values({ id, title }).returning();
+      return fx.json.create(row);
     },
   }),
 );
@@ -375,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) => {
@@ -383,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;
     },
   }),
@@ -462,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) => {
@@ -471,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;
     },
   }),
@@ -574,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) |
@@ -934,8 +933,9 @@ Every HTTP flow returns the same envelope shape. You choose status and optional
 custom wrapper.
 
 <Callout title="Envelope is fixed">
-  Success and failure always use `{ data, error }` (optional top-level `meta`). There is no API to
-  replace that shape. Use `fx.json.*` for status codes and `meta`; use `fx.fail` for typed errors.
+  Success and failure always use `{ data, error }` (optional top-level `meta`). Use `fx.json.*` for
+  status and `meta`; use `fx.fail` for typed errors. A raw `Response` from `do` is the exception —
+  `302` + `Location` for redirects.
 </Callout>
 
 **Success** — returning a value from `do` produces `200 OK`:
@@ -946,18 +946,26 @@ custom wrapper.
 
 Returning `undefined` produces a `204 No Content` response with an empty body.
 
-**Custom status** — `fx.json.create` for `201 Created`, or `fx.json.ok` with optional `meta`:
+**Custom status** — `fx.json.create` for `201 Created`, or `fx.json.ok` with optional `meta`.
+When `out` is set, pass the store row — the kernel projects it (Date → ISO-8601; extra keys strip):
 
 ```typescript
-return fx.json.create({ id: "ord_1" });
+return fx.json.create(row);
 // or
 return fx.json.ok({ id: "ord_1" }, { meta: { traceId: fx.runId } });
 ```
 
-**Typed failures** — `fx.fail(code, data)` formats the error envelope and maps status:
+**Redirects** — return a raw `Response` so the kernel does not wrap `{ data, error }`:
 
 ```typescript
-return fx.fail("NotFound", { id: "123" });
+return new Response(null, { status: 302, headers: { Location: url } });
+```
+
+**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("OutOfStock", { available: 0 });
 ```
 
 ```json
@@ -965,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" }
   }
 }
@@ -976,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
 
@@ -1004,6 +1018,11 @@ Standard status code mappings:
   `error.data.issues` array for the specific field validation failure.
 </Accordion>
 
+<Accordion title="I mapped Date columns to ISO by hand">
+  Declared `out` already projects store rows. `fx.json.create(row)`, `return row`, and
+  `fx.json.withQuery(rows, input)` are enough — extra columns strip. A miss is not a client error.
+</Accordion>
+
 <Accordion title="Browser blocked by CORS / missing Access-Control-*">
   Cross-origin access is closed until you plug the [`cors`](/docs/plugins/cors) plugin with an
   explicit `origin`. Same-origin calls need no CORS headers. Preflight `OPTIONS` is answered by the