okengine 0.6.1 → 0.7.0

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

@@ -85,52 +85,79 @@ do: async (input, fx) => {
 
 <ClockSchedules />
 
-Both are triggers consumed with the same `on(trigger, flow)` — the flow underneath does not know the difference.
+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               |
-| `description` | string  | —       | Human title in the Console (falls back to the clock name)    |
+| 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** the schedule (pause is separate) |
+| `description` | string  | —       | Human title in the Console (falls back to the clock name)      |
 
 ## 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.
+<ClockSleep />
+
+`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.
 
+Completed journal steps never re-run on resume — a process killed mid-flow continues at the next
+unfinished step.
+
 ## 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                       |
+<ClockCatchUp />
+
+| Guarantee          | What it means                                                                                      |
+| ------------------ | -------------------------------------------------------------------------------------------------- |
+| Leader election    | Instances that share one CronStore fire a given tick once (lease TTL, default 30s)                 |
+| Catch-up `"one"`   | Health counts every missed slot; the runtime still fires **once** when overdue — not once per miss |
+| Reconciled at boot | Named clocks land in `oke_crons`; the scheduler reads the Store, not the source                    |
+| DST detection      | Ambiguous local times get a Console warning — schedules are not rewritten or blocked               |
+
+**Leader election needs a shared store.** The default in-memory CronStore is per process. Multi-replica
+exclusivity only holds when every instance opens the same durable CronStore (file-backed store is
+available for that; a Postgres cron driver is not wired yet).
+
+**Catch-up example:** an hourly clock down for five hours reports `missedRuns: 5` and
+`catchUp: "one"`, then a single tick runs the handler once.
+
+## DST warnings (detect only)
+
+Simple daily crons (`M H * * *`) in a DST-observing zone can hit a **gap** (spring forward — local time skipped) or an **overlap** (fall back — local time occurs twice).
+
+Detection attaches `dstAmbiguity` on the cron row and the Console shows it. `oke doctor` does not check DST. The scheduler does not rewrite the expression.
+
+**Consequence:** fall-back days can list two civil instants an hour apart. The default leader lease (30s) is shorter than that gap, so a lease alone is not a “fire once on overlap” policy. Prefer UTC, or a wall time outside the transition window, when double-fire would hurt.
 
 ## Per-environment drivers
 
 ```typescript title="oke.config.ts"
 drivers: {
-  clock: { local: "memory", docker: "postgres", test: "frozen", prod: "postgres" },
+  clock: { local: "memory", docker: "file", test: "frozen", prod: "file" },
 },
 ```
 
-| 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 |
+| Driver   | Behavior                                                                                 |
+| -------- | ---------------------------------------------------------------------------------------- |
+| `memory` | In-process CronStore + timers — single process; lost on exit                             |
+| `file`   | On-disk CronStore (`.oke/crons.json`) — multi-process leader election on a shared volume |
+| `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.
+The Console (`:6533` → Clock) lists every named clock with health — drift, overdue, missed runs + catch-up `"one"`, and which replica holds the leader lease.
+
+From there you can **pause** any cron, **wake early** a sleeping durable run, or **edit the schedule** when `overridable: true`. Edit on a locked clock throws `ScheduleNotOverridableError` (`clock "…" is not overridable`).
 
 ## Troubleshooting
 
@@ -142,18 +169,23 @@ Replace it with `fx.clock.now()`. Direct time calls bypass the injected clock, s
 </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.
+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. Health still shows how many slots were missed. 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.
+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. Pause does not require `overridable`.
 
 </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>
+<Accordion title="Two replicas both ran my cron">
+
+They are not sharing one CronStore. In-memory leases are per process. Point every replica at the same durable cron store, or run a single scheduler instance until the Postgres clock driver ships.
+
 </Accordion>
 </Accordions>
 

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

@@ -205,6 +205,8 @@ Everything a flow may touch, on one object:
 
 ## Durability — flows that survive the process
 
+<FlowDurable />
+
 Set `durable: true` and every `fx` call is journaled. Wrap side effects in `fx.step` and they never re-run on replay:
 
 ```typescript

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

@@ -104,8 +104,14 @@ A denied request never reaches `do`. It returns one of three typed failures:
 
 </Steps>
 
+## First denial wins
+
 <GatePipeline />
 
+`.gate(member, canBook, fair)` evaluates left to right — first denial wins
+(`Unauthorized` · `Forbidden` · `RateLimited`); later gates are skipped. `do`
+runs only when every gate passed.
+
 ## `oke({ gate })` bag
 
 | Option          | Type                    | Default  | Meaning                                                         |
@@ -159,7 +165,8 @@ Fine-grained authorization (`gate.scope`, roles) stays opt-in — attach it only
 | `leaky-bucket`           | Smooths output to a constant rate                      |
 
 All five run as atomic Lua on the kv driver — correct under concurrency, identical on the memory
-driver in tests.
+driver in tests. Boot opens a dedicated `oke:gates` namespace on **`drivers.store.kv`**
+(`memory` locally · `redis` in docker/prod) so multi-instance rate limits share counters.
 
 ## Auth posture at boot
 

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

@@ -43,9 +43,8 @@ Producers never touch a broker client — they call `fx.emit`:
 ```typescript title="src/flows/orders/place.ts"
 do: async (input, fx) => {
   await fx.store(db).insert(orders).values({ id: input.id /* … */ });
-  await fx.emit(orderPlaced, { orderId: input.id, total: input.total });
-  // With the postgres driver this enrols in the same transaction as the insert —
-  // the message is only ever sent if the row is committed.
+  await fx.emit(orderPlaced, { orderId: input.id, total: input.total }, { key: input.id });
+  // optional `key` keeps same-order events serialized under `once`
 };
 ```
 
@@ -62,7 +61,7 @@ export const sendConfirmation = on(
   flow({
     in: z.object({ orderId: z.string(), total: z.number() }),
     do: async (input, fx) => {
-      await fx.channel(email).send(/* … */);
+      await fx.send(orderConfirmed, { to: "user-1", data: input });
     },
   }),
 );
@@ -82,14 +81,105 @@ The declaration is identical in shape for all three — switching physics later
 
 ### Options
 
-| Option        | Type                              | Default          | Meaning                                                        |
-| ------------- | --------------------------------- | ---------------- | -------------------------------------------------------------- |
-| `delivery`    | `"once" \| "broadcast" \| "live"` | — (**required**) | Delivery physics                                               |
-| `description` | string                            | —                | Human title in the Console (falls back to the signal name)     |
-| `schema`      | zod / Standard Schema             | —                | Payload contract; typed emits and Manifest docs                |
-| `retries`     | number                            | `3`              | Max delivery attempts before dead-letter (`once`)              |
-| `deadLetter`  | boolean                           | `true`           | Preserve exhausted messages in the DLQ (`once`)                |
-| `optional`    | boolean                           | `false`          | Allow emitting while nobody subscribes (skip the orphan check) |
+| Option        | Type                              | Default          | Meaning                                                                                           |
+| ------------- | --------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------- |
+| `delivery`    | `"once" \| "broadcast" \| "live"` | — (**required**) | Delivery physics                                                                                  |
+| `description` | string                            | —                | Human title in the Console (falls back to the signal name)                                        |
+| `schema`      | zod / Standard Schema             | —                | Payload contract — validated at emit (**OKE1043** on failure); Manifest docs                      |
+| `retries`     | number                            | `3`              | Retry budget for `once` — dead-letter when `attempts > retries` (`retries + 1` total invocations) |
+| `deadLetter`  | boolean                           | `true`           | Preserve exhausted messages in the DLQ (`once`)                                                   |
+| `optional`    | boolean                           | `false`          | Allow emitting while nobody subscribes (skip the orphan check)                                    |
+
+## One order, three modes
+
+One placed order can need all three physics at once — pick a signal per job, not one signal stretched across modes:
+
+| Signal          | Mode        | Job                                                         |
+| --------------- | ----------- | ----------------------------------------------------------- |
+| `order-placed`  | `once`      | Fulfillment job — competing workers, retries, DLQ           |
+| `order-changed` | `broadcast` | Fan-out — cache invalidation **and** customer notification  |
+| `order-status`  | `live`      | Status feed — retained history a late subscriber can replay |
+
+```typescript title="src/signals.ts"
+import { signal } from "okengine";
+import { z } from "zod";
+
+export const orderPlaced = signal("order-placed", {
+  schema: z.object({ orderId: z.string(), total: z.number() }),
+  delivery: "once",
+  retries: 2,
+  deadLetter: true,
+});
+
+export const orderChanged = signal("order-changed", {
+  schema: z.object({ orderId: z.string(), kind: z.literal("placed") }),
+  delivery: "broadcast",
+});
+
+export const orderStatus = signal("order-status", {
+  schema: z.object({
+    orderId: z.string(),
+    status: z.enum(["placed", "fulfilling", "shipped"]),
+  }),
+  delivery: "live",
+  optional: true, // clients may not be connected yet
+});
+```
+
+`once` — two fulfillment workers compete; **exactly one** claims each message (at-least-once; make the handler idempotent):
+
+```typescript title="src/flows/fulfillment/on-order.ts"
+on(
+  orderPlaced,
+  flow({
+    name: "fulfillment.onOrder",
+    do: async ({ orderId }, fx) => {
+      await fx.emit(orderChanged, { orderId, kind: "placed" });
+      await fx.emit(orderStatus, { orderId, status: "fulfilling" });
+      await fx.emit(orderStatus, { orderId, status: "shipped" });
+    },
+  }),
+);
+```
+
+`broadcast` — every subscriber gets its own copy of the same domain event:
+
+```typescript title="src/flows/orders/side-effects.ts"
+on(
+  orderChanged,
+  flow({
+    name: "cache.onOrderChanged",
+    do: async ({ orderId }, fx) => {
+      /* invalidate order:{orderId} */
+    },
+  }),
+);
+
+on(
+  orderChanged,
+  flow({
+    name: "notify.onOrderChanged",
+    do: async ({ orderId }, fx) => {
+      await fx.send(orderConfirmed, { to: "user-1", data: { orderId } });
+    },
+  }),
+);
+```
+
+`live` — retain status updates and replay the **full history** to a late `bus.live()` subscriber (tracking UI, ops feed).
+
+Today that subscription is a **server-side** bus API. `createClient` does not yet expose SSE / WebSocket / `client.live` — see [Client](/docs/reference/client#signal-and-live-queries).
+
+```typescript
+await fx.emit(orderStatus, { orderId, status: "placed" });
+
+// Late subscriber (server / test harness) receives placed → fulfilling → shipped.
+const unsub = await bus.live("order-status", (payload) => {
+  /* push to UI */
+});
+```
+
+**Why separate signals:** delivery is fixed per declaration. Competing work stays on `once`; fan-out stays on `broadcast`; the client-visible timeline stays on `live`. Switching a word later is cheap; mixing physics on one name is not.
 
 ## When delivery fails
 
@@ -97,50 +187,104 @@ The declaration is identical in shape for all three — switching physics later
 
 The **Console** (`:6533` → Signals) shows the topology (which flows emit and consume each signal), per-subscriber delivery stats, and the DLQ contents with replay / discard controls — no separate broker UI to run.
 
-<Callout title="Orphan emits fail loudly">
-  Emitting a signal with zero subscribers is normally an error — it almost always means a typo or a
-  forgotten consumer. Set `optional: true` on the declaration only when zero-subscriber emits are
-  genuinely expected (e.g. an integration hook).
+<Callout title="Orphan emits and schema fail loudly">
+  Zero subscribers throws **OKE1042** unless `optional: true`. A payload that fails the signal's
+  Standard Schema throws **OKE1043** before the message is staged — same `validate()` path as Flow
+  `in`.
+</Callout>
+
+## Per-key ordering (`once`)
+
+`fx.emit(signal, payload, { key })` is optional and additive. When `key` is set, no two messages
+sharing the same `(signal, key)` are claimed concurrently — a per-key serialization lock, not a
+partitioned log.
+
+The lock **is** the in-flight message's visibility lease: while that row is `inflight` with an
+unexpired `leaseExpiresAt`, same-key siblings stay unclaimable. Crash → lease expiry → reclaim
+(same clock as unkeyed `once`). Omit `key` for pure competing-consumer behavior.
+
+```typescript
+await fx.emit(orderPlaced, { orderId, total }, { key: orderId });
+await fx.emit(orderPlaced, { orderId, total: total + fee }, { key: orderId });
+// Same key → never concurrent; complete in emission order across competing workers.
+```
+
+## Durability and leases (`once`)
+
+<SignalOnceLease />
+
+Committed `once` messages survive process death. A claim sets `lockedBy` and a visibility lease (`leaseExpiresAt`, default **30s**). There is no background sweeper: the next consumer reclaim query takes `pending` rows **or** `inflight` rows whose lease has expired. Per-key locks reuse this same lease — no second timeout.
+
+<Callout title="At-least-once, not exactly-once">
+  Delivery is **at-least-once** — finish side effects then die before ack, and the message may run
+  again; make consumers idempotent. Handlers must finish within `leaseMs` (default 30s): a healthy
+  but slower handler can be reclaimed while still running. Lease heartbeat is not offered yet.
+</Callout>
+
+## Live replay
+
+<SignalLiveReplay />
+
+`live` retains every delivered message and replays the **full history** to a late `bus.live()` subscriber. There is no TTL or max-count window on that retention today (the Console payload monitor shows only the newest 50 for display).
+
+<Callout title="Client subscription is not shipped yet">
+  `delivery: "live"` means the **driver** retains and replays. `createClient` has no SSE / WebSocket
+  / `client.live` yet — poll an HTTP Flow or use `bus.live()` server-side. See [Client · Signal and
+  live queries](/docs/reference/client#signal-and-live-queries).
 </Callout>
 
+## Orphaned signal config
+
+When a signal disappears from code, reconciliation marks its config row `orphaned` — it is never deleted. Pending and DLQ messages for that name stay in storage. Drain and replay require an active declaration again: restore the `signal(…)` (and a consumer), then replay from the Console or bus.
+
 ## Per-environment drivers
 
 ```typescript title="oke.config.ts"
 drivers: {
-  signal: { local: "memory", docker: "postgres", test: "memory", prod: "postgres" },
+  signal: { local: "memory", docker: "redis", test: "memory", prod: "redis" },
 },
 ```
 
-| Driver     | Runs as                          | Best for                                                                  |
-| ---------- | -------------------------------- | ------------------------------------------------------------------------- |
-| `memory`   | in-process                       | Local loop + tests — zero infrastructure                                  |
-| `postgres` | your existing Postgres container | Default for docker/prod — emits join your DB transaction (outbox pattern) |
-| `redis`    | Redis container                  | Explicit alternative when throughput outgrows Postgres                    |
-| `nats`     | NATS container                   | High-throughput fan-out                                                   |
+| Driver     | Runs as        | Boot today                                                                |
+| ---------- | -------------- | ------------------------------------------------------------------------- |
+| `memory`   | in-process     | Local loop + tests — zero infrastructure                                  |
+| `redis`    | Redis / Valkey | Default for docker/prod — Streams + pub/sub via `Bun.redis`               |
+| `postgres` | Postgres       | Driver exists; boot **fails loud** until a LISTEN/NOTIFY SQL client binds |
+| `nats`     | NATS           | Driver exists; boot **fails loud** until a production NATS client binds   |
 
-`postgres` is the default outside local dev for a reason: `fx.emit` enrols in the caller's transaction, so "write row + emit event" commits or rolls back **atomically** — the classic dual-write bug is designed out.
+`redis` is the honestly boot-bound durable path today. Pairing an arbitrary Store insert with emit inside **one** shared SQL transaction is not what `fx.emit` does — keep consumers idempotent (at-least-once).
 
 ## Troubleshooting
 
 <Accordions>
-<Accordion title="Emit fails with a 'no subscribers' error">
+<Accordion title="Emit fails with OKE1042 (no subscriber)">
+
+You emitted a signal that nobody currently subscribes to. Wire a consumer with `on(signal, flow)` before emit, or set `optional: true` when zero-subscriber emits are intentional.
+
+</Accordion>
+<Accordion title="Emit fails with OKE1043 (schema)">
 
-You emitted a signal that no flow consumes. Either wire a consumer with `on(signal, flow)`, or set `optional: true` on the declaration if zero-subscriber emits are intentional.
+The payload failed the signal's Standard Schema at emit time — nothing was staged. Fix the payload shape, or remove `schema` if the contract was intentional.
 
 </Accordion>
 <Accordion title="A message keeps retrying and then disappears">
 
-After `retries` attempts the message moves to the DLQ — it is not lost. Open Console → Signals, inspect the typed failure reasons on each attempt, fix the consumer, then replay.
+When `attempts > retries` the message moves to the DLQ (if `deadLetter: true`) — it is not lost. Open Console → Signals, inspect the typed failure reasons, fix the consumer, then replay.
 
 </Accordion>
 <Accordion title="once vs broadcast vs live — how do I choose?">
 
-Ask: _how many consumers should process each message?_ One → `once`. All of them → `broadcast`. Clients over time, with replay → `live`. If you need retries and a DLQ, you want `once`.
+Ask: _how many consumers should process each message?_ One → `once`. All of them → `broadcast`. Clients over time, with full retained replay → `live`. Retries and a DLQ are `once` only.
 
 </Accordion>
 <Accordion title="My emit happened but the row didn't (or vice versa)">
 
-That is the dual-write problem, and it means the signal driver is not `postgres`. With the `postgres` driver the emit joins your SQL transaction; with `redis` / `nats` an outbox relay keeps the guarantee, but `postgres` is the only mode where atomicity is literal.
+`fx.emit` commits the signal outbox when it resolves; it does not wrap your Store insert. Treat delivery as at-least-once and make the consumer idempotent (or check the row before acting). Prefer `redis` (or a future LISTEN-capable postgres bind) when you want durable delivery rather than in-process memory.
+
+</Accordion>
+<Accordion title="The same once message ran twice">
+
+At-least-once: crash-after-claim reclaims when the lease expires, and a handler slower than `leaseMs` can be reclaimed while still running. Idempotent consumers are required; there is no lease heartbeat yet.
 
 </Accordion>
 </Accordions>