okengine 0.2.6 → 0.3.2

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

@@ -0,0 +1,167 @@
+---
+title: "Channel"
+description: "Reaching humans — email, SMS, WhatsApp, and push with consent, locale, receipts, and fallback chains built in."
+icon: "Mail"
+source: "docs/spec/unified-theory.md"
+---
+
+Channel is how your app **reaches humans**: the order-confirmation email, the OTP text, the WhatsApp notification. Reaching a person is not the same problem as moving data between machines — it needs consent (did they opt out?), locale (which language?), receipts (did it land?), and fallback (email failed, try SMS). Those physics are built into the element, so every flow gets them for free.
+
+<Callout title="The one rule">
+  Sends go through `fx.send` and declared templates — never through a raw SMTP or provider client
+  inside a flow. That is what makes consent, locale, and receipts unavoidable rather than optional.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Declare a medium and a template
+
+A medium binder carries your defaults; a template names the message and types its data:
+
+```typescript title="src/channels.ts"
+import { channel } from "okengine";
+import { z } from "zod";
+
+export const mail = channel.email({ from: "Provisions <no-reply@provisions.sa>" });
+
+export const orderConfirmed = mail.template("order-confirmed", {
+  schema: z.object({ name: z.string(), orderId: z.string(), total: z.number() }),
+  locales: ["en", "ar"],
+});
+```
+
+</Step>
+
+<Step>
+### Send it from a Flow
+
+One call — consent, locale resolution, and the receipt happen around it:
+
+```typescript title="src/flows/orders/confirm.ts"
+do: async (input, fx) => {
+  await fx.send(orderConfirmed, {
+    to: input.email,
+    data: { name: input.name, orderId: input.id, total: input.total },
+  });
+};
+```
+
+</Step>
+
+<Step>
+### Read it in development
+
+Locally the `console` driver captures mail into an inbox instead of sending; in docker mode the stack runs **Mailpit**, a real SMTP catcher with a web UI — so you see the exact rendered message without ever touching a real mailbox.
+
+</Step>
+
+</Steps>
+
+## Mediums and templates
+
+| Declaration                    | Produces                                        |
+| ------------------------------ | ----------------------------------------------- |
+| `channel.email({ from })`      | Email binder (default sender)                   |
+| `channel.sms({ sender })`      | SMS binder (sender id)                          |
+| `channel.whatsapp()`           | WhatsApp binder                                 |
+| `channel.push()`               | Push binder                                     |
+| `binder.template(name, opts)`  | Typed template bound to that medium             |
+| `channel.template(name, opts)` | Medium-agnostic template (one body, any medium) |
+
+| Template option | Type                  | Meaning                                           |
+| --------------- | --------------------- | ------------------------------------------------- |
+| `schema`        | zod / Standard Schema | The data the template may reference — typed sends |
+| `locales`       | string[]              | Languages this template is rendered in            |
+
+## The human physics
+
+### Consent is checked before sending
+
+Opt-out is first-class: a subject who opted out of a medium is **suppressed** — the send resolves without contacting the provider, and the receipt says so. You never hand-roll "did they unsubscribe?" checks.
+
+### Locale resolves through a chain
+
+Templates render per recipient locale, falling back through your configured chain (`ar` → default `en`) instead of failing when a translation is missing. Locales and the default come from the `i18n` block in `oke.config.ts`.
+
+### Fallback chains are explicit
+
+`via` orders the mediums to try — first success wins, and **every** attempt is recorded:
+
+```typescript
+await fx.send(otpCode, { to: user.phone, data: { code }, via: [sms, wa] });
+// sms fails → whatsapp tried → receipt status "fallback" with both attempts
+```
+
+### Receipts for everything
+
+Each send records its attempts — driver, ok/error, timestamp, message id — so "did the user actually get it?" is a Console query, not a guess. In a dry run, sends are recorded as _would have fired_ and never contact a real provider.
+
+## Per-environment drivers
+
+```typescript title="oke.config.ts"
+drivers: {
+  channel: {
+    email: { local: "console", docker: "smtp", test: "console", prod: "smtp" },
+  },
+},
+images: {
+  "channel.email": "axllent/mailpit:v1.22.3", // SMTP catcher for the docker stack
+},
+```
+
+| Driver     | Medium | Behavior                                             |
+| ---------- | ------ | ---------------------------------------------------- |
+| `console`  | any    | Captures into a readable inbox — local + tests       |
+| `smtp`     | email  | Real SMTP — Mailpit in docker, your provider in prod |
+| `resend`   | email  | Resend API                                           |
+| `unifonic` | sms    | Unifonic SMS API                                     |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="I sent an email in dev but nothing arrived">
+
+Nothing _should_ arrive — the `console` driver captures mail instead of sending. Read the dev inbox, or run `oke dev --docker` and open Mailpit's web UI to see the rendered message.
+
+</Accordion>
+<Accordion title="A user says they stopped receiving messages">
+
+Check consent first: if they opted out, sends to them are suppressed by design. The Console shows the suppression on the receipt — it is a delivered-as-intended outcome, not a bug.
+
+</Accordion>
+<Accordion title="The Arabic version didn't render">
+
+Locale resolution falls back through the chain to your default locale when a translation is missing — the send still succeeds with the fallback body. Check that the template declares `locales: ["en", "ar"]` and that the Arabic body exists in the catalog.
+
+</Accordion>
+<Accordion title="How do I know which medium finally delivered?">
+
+The receipt keeps every attempt in order with its outcome. A send that succeeded on a later medium reports status `fallback` — you can see the full chain in Console → Channels.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Flow](/docs/elements/flow) — `fx.send` inside `do`
+- [Console · Channels](/docs/console/channels) — receipts, attempts, suppression
+- [Signal](/docs/elements/signal) — machine-to-machine messaging, the other side of the line
+
+## Next
+
+<Cards>
+  <Card title="AI" description="Continue to AI." href="/docs/elements/ai" />
+  <Card
+    title="Introduction"
+    description="Eight elements overview."
+    href="/docs/get-started/introduction"
+  />
+  <Card
+    title="Console"
+    description="Panels derived from the Manifest."
+    href="/docs/console/overview"
+  />
+</Cards>

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

@@ -0,0 +1,182 @@
+---
+title: "Clock"
+description: "Time — recurring schedules, intervals, and durable sleeps as first-class declarations, not a bolted-on cron library."
+icon: "Clock"
+source: "docs/spec/unified-theory.md"
+---
+
+Clock is how your app deals with **time**: cleanup jobs that run every hour, reports due at 9am Riyadh time, a flow that pauses for seven days and wakes up even after a deploy. There is no separate scheduler to install — a schedule is a trigger, and the flow it fires is the same species as every other flow.
+
+<Callout title="The one rule">
+  Flow code never calls `Date.now()` — it asks `fx.clock.now()`. Time is injected, which makes it
+  deterministic in tests and auditable in traces.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Fire a flow on an interval
+
+The simplest schedule is an anonymous interval trigger:
+
+```typescript title="src/flows/links/purge.ts"
+import { on, flow, every } from "okengine";
+
+export const purgeOld = on(
+  every("1h"),
+  flow({
+    do: async (_, fx) => {
+      const cutoff = fx.clock.now() - 30 * 24 * 60 * 60 * 1000; // 30 days
+      await fx.store(db).delete(links).where(lt(links.createdAt, cutoff));
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Or declare a named schedule
+
+A named `clock()` shows up in the Console, supports cron expressions and timezones, and can be paused or retuned at runtime:
+
+```typescript title="src/clocks.ts"
+import { clock } from "okengine";
+
+export const dailyReport = clock("daily-report", {
+  cron: "0 9 * * *", // 09:00
+  timezone: "Asia/Riyadh",
+  overridable: true, // the Console may edit this schedule
+});
+```
+
+```typescript title="src/flows/reports/daily.ts"
+export const sendDaily = on(
+  dailyReport,
+  flow({
+    do: async (_, fx) => {
+      /* … */
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Ask for time inside flows
+
+`fx.clock` is the only clock a flow knows:
+
+```typescript
+do: async (input, fx) => {
+  const now = fx.clock.now(); // epoch-ms, injectable
+  await fx.clock.sleep("wait-for-payment", "7d"); // durable — survives restarts
+};
+```
+
+</Step>
+
+</Steps>
+
+## Two kinds of schedules
+
+| Declaration         | Shows in Console | Cron + timezone | Runtime-editable   | Use for                           |
+| ------------------- | ---------------- | --------------- | ------------------ | --------------------------------- |
+| `every("1h")`       | no               | no              | no                 | Simple fixed intervals            |
+| `clock(name, opts)` | yes              | yes             | when `overridable` | Business schedules operators tune |
+
+Both are triggers consumed with the same `on(trigger, flow)` — the flow underneath does not know the difference.
+
+### `clock()` options
+
+| Option        | Type    | Default | Meaning                                                      |
+| ------------- | ------- | ------- | ------------------------------------------------------------ |
+| `cron`        | string  | —       | Cron expression `m h dom mon dow` (this or `every` required) |
+| `every`       | string  | —       | Fixed interval: `"30s"` · `"10m"` · `"1h"` · `"7d"`          |
+| `timezone`    | string  | `"UTC"` | IANA timezone for cron evaluation                            |
+| `overridable` | boolean | `false` | Allow the Console to edit / pause the schedule               |
+
+## Sleeping inside a flow
+
+`fx.clock.sleep(label, duration)` is a **durable** sleep: in a `durable: true` flow the wake time is journaled, so the flow resumes after restarts and deploys instead of losing its place. The `label` names the step in the journal — it is what the Console shows when you inspect a sleeping run.
+
+In a non-durable flow the same call resolves immediately, so code reads identically in tests.
+
+## What the runtime guarantees
+
+| Guarantee          | What it means                                                                               |
+| ------------------ | ------------------------------------------------------------------------------------------- |
+| Leader election    | With several replicas, only one instance fires each cron tick                               |
+| Catch-up `"one"`   | A schedule missed during downtime fires **once**, not once per missed tick                  |
+| Reconciled at boot | Named clocks are written into the store (`oke_crons`) — the scheduler reads state, not code |
+| DST-aware          | Ambiguous local times around DST transitions are detected and handled                       |
+
+## Per-environment drivers
+
+```typescript title="oke.config.ts"
+drivers: {
+  clock: { local: "memory", docker: "postgres", test: "frozen", prod: "postgres" },
+},
+```
+
+| Driver     | Behavior                                                            |
+| ---------- | ------------------------------------------------------------------- |
+| `memory`   | In-process timers — fast local loop, lost on exit                   |
+| `postgres` | Schedules and wakes persisted in your Postgres — survives restarts  |
+| `frozen`   | Deterministic test clock — time advances only when the test says so |
+
+`frozen` is why the no-`Date.now()` rule pays off: tests inject time travel through `fx.clock` and every flow obeys it automatically.
+
+## Operating schedules from the Console
+
+The Console (`:6533` → Clock) lists every named clock with a four-number health view — drift, past-due, next run, and which replica holds the leader lease. From there you can **pause**, **edit the schedule**, or **wake early** — but only for clocks declared with `overridable: true`. A non-overridable clock rejects edits with `ScheduleNotOverridableError`, so a mistyped production change cannot silently reshape your cadence.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="I used Date.now() and tests are flaky">
+
+Replace it with `fx.clock.now()`. Direct time calls bypass the injected clock, so the `frozen` test driver cannot control them — that is exactly the class of bug the rule exists to remove.
+
+</Accordion>
+<Accordion title="The server was down and the cron didn't catch up">
+
+That is by design: catch-up policy is `"one"` — the schedule fires a single time after downtime, never a storm of one-run-per-missed-tick. If you genuinely need backfill, trigger the flow from the Console.
+
+</Accordion>
+<Accordion title="Console won't let me edit a schedule">
+
+The clock was declared without `overridable: true`. Add it and redeploy — the restriction is deliberate, so only schedules you marked as operator-tunable can drift from code.
+
+</Accordion>
+<Accordion title="How do I run something once, later — not recurring?">
+
+Emit it from inside a flow with `fx.clock.sleep(label, duration)` before the work, in a `durable: true` flow. The sleep survives restarts, so "remind me in 7 days" is one line, not a cron row.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Flow](/docs/elements/flow) — `on(trigger, flow)` and the `fx` surface
+- [Console · Clock](/docs/console/clock) — health numbers, pause / edit / wake early
+- [Signal](/docs/elements/signal) — reacting to events instead of time
+
+## Next
+
+<Cards>
+  <Card title="Gate" description="Continue to Gate." href="/docs/elements/gate" />
+  <Card
+    title="Introduction"
+    description="Eight elements overview."
+    href="/docs/get-started/introduction"
+  />
+  <Card
+    title="Console"
+    description="Panels derived from the Manifest."
+    href="/docs/console/overview"
+  />
+</Cards>

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

@@ -0,0 +1,288 @@
+---
+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({
+    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      |
+| `do`     | The work — every read, write, emit, and call goes through `fx`  |
+
+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 } }` — so clients handle outcomes by `error.code`, not by parsing status text.
+
+## The five triggers
+
+| Trigger                      | Starts when                  | Replaces           |
+| ---------------------------- | ---------------------------- | ------------------ |
+| `http.post("/orders")`       | a request arrives            | endpoint · handler |
+| `orderPlaced` (a signal)     | another flow emits           | queue consumer     |
+| `every("1h")`                | time passes                  | cron job           |
+| `db.table(orders).changed()` | a row changes                | CDC pipeline       |
+| — none                       | another flow calls `fx.call` | "private" helper   |
+
+### http — a request arrives
+
+```typescript
+export const findOrder = on(
+  http.get("/orders/:id").gate(member), // gates evaluate before do runs
+  flow({
+    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` (transactionally with its writes); the consumer is the same species — no `subscribe()`, no listener registration:
+
+```typescript
+await fx.emit(orderPlaced, { orderId: id }); // inside the producing flow
+
+on(
+  orderPlaced,
+  flow({
+    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({
+    do: async (_, fx) => {
+      const cutoff = fx.clock.now() - 30 * 24 * 60 * 60 * 1000;
+      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({
+    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({
+  in: OrderRef,
+  out: Order,
+  do: async ({ id }, fx) => {
+    /* … */
+  },
+});
+
+const order = await fx.call(getOrder, { id: orderId }); // from any other flow
+```
+
+## 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.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(contract)`                    | read            | Read a secret (redacted from logs)           |
+| `fx.clock.now()` / `.sleep(…)`          | —               | Injected time / durable sleep                |
+| `fx.cache.get/set`                      | —               | Shared cache with effect-aware invalidation  |
+| `fx.step(name, fn)`                     | —               | Named durable step — never re-runs on replay |
+| `fx.id()` · `fx.log` · `fx.t`           | —               | UUIDs, redacting logger, 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>
+
+## Durability — flows that survive the process
+
+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({
+  durable: true, // every fx call below is journaled
+  in: OrderRef,
+  out: z.boolean(),
+  do: async ({ orderId }, fx) => {
+    const intent = await fx.step("create-intent", () =>
+      stripe(fx.vault(stripeKey)).create(orderId),
+    );
+
+    await fx.clock.sleep("verify-window", "2m"); // survives restart and deploy
+
+    return fx.step("confirm", () => stripe(fx.vault(stripeKey)).confirm(intent));
+  },
+});
+```
+
+**Consequence:** kill the process between the two steps and the run **resumes at `confirm`** — completed steps replay from the journal, so the card is not charged twice. This is verified by the engine's own test suite: after resume, `create-intent` has run exactly once.
+
+## 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="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="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 → Runs with its trace.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Signal](/docs/elements/signal) — delivery physics (`once` · `broadcast` · `live`)
+- [Clock](/docs/elements/clock) — schedules and durable sleep
+- [Console · Flows](/docs/console/flows) — the Manifest-derived panel
+- [Runs](/docs/console/runs) — how a flow execution is observed
+
+## 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"
+  />
+  <Card
+    title="Console"
+    description="Panels derived from the Manifest."
+    href="/docs/console/overview"
+  />
+</Cards>