okengine 0.19.2 → 0.19.4

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

@@ -17,9 +17,11 @@ For developers wiring background work on okengine — bind the trigger, keep `do
 
 ## Smallest Example
 
-<Steps>
+<Callout title="Bind and emit are independent">
+  The consumer and the producer share one Signal handle. They can live in different files, written
+  in any order — emit is not "step 2" after bind.
+</Callout>
 
-<Step>
 ### Bind a Signal consumer
 
 ```typescript title="src/flows/notifications/welcome.ts"
@@ -40,9 +42,6 @@ export const sendWelcome = on(
 );
 ```
 
-</Step>
-
-<Step>
 ### Emit from any Flow
 
 ```typescript
@@ -52,10 +51,6 @@ await fx.emit(userSignedUp, { userId: "usr_123", email: "alice@example.com" });
 The compiler records `emits: ["users.signed-up"]` on the producer. The consumer runs after the
 emit commits — the HTTP request does not wait for the welcome mail.
 
-</Step>
-
-</Steps>
-
 <Callout title="Jobs are consumers">
   A named Clock bound with `on(clockDecl, flow)` is the same species — an asynchronous Flow. There
   is no separate job runner. See [Clock jobs](#clock-jobs).
@@ -101,15 +96,21 @@ export const processEmail = on(
 
 <Tab value="Clock">
 
-Name the schedule, then bind it. Omit `timezone` for `"UTC"`:
+Name the schedule, then bind it. One Flow can write `clock.every` inside `on()` —
+[Clock · Inline or named export](/docs/elements/clock#inline-or-named-export).
+
+```typescript title="src/clocks/metrics.ts"
+import { clock } from "okengine";
+
+export const cleanupClock = clock.every("metrics.cleanup", "1h");
+```
 
 ```typescript title="src/flows/metrics/cleanup.ts"
-import { on, flow, clock } from "okengine";
+import { on, flow } from "okengine";
 import { lt } from "drizzle-orm";
+import { cleanupClock } from "@/clocks/metrics";
 import { db, metricLogs } from "@/schema";
 
-export const cleanupClock = clock.every("metrics.cleanup", "1h");
-
 export const cleanupMetrics = on(
   cleanupClock,
   flow("metrics.cleanup", {
@@ -185,18 +186,19 @@ Omit `key` for competing consumers with no ordering.
 
 ## Trigger Reference
 
-| Trigger    | Signature                                           | Purpose                                     | `do` input                             |
-| ---------- | --------------------------------------------------- | ------------------------------------------- | -------------------------------------- |
-| Signal     | `on(signalHandle, flow)` or inline `signal.once(…)` | Queue (`once`) or fan-out (`broadcast`)     | Payload (`schema`)                     |
-| Clock      | `on(clockDecl, flow)` or inline `clock.every(…)`    | Interval or cron tick                       | none (`_`)                             |
-| CDC any    | `on(db.table(t).changed(), flow)`                   | Every insert / update / delete              | `{ before, after, table, action, id }` |
-| CDC column | `on(db.table(t).changed("col"), flow)`              | Same writes; column stamped on the Manifest | `{ before, after, table, action, id }` |
+| Trigger    | Signature                                                        | Purpose                                     | `do` input                             |
+| ---------- | ---------------------------------------------------------------- | ------------------------------------------- | -------------------------------------- |
+| Signal     | `on(handle, flow("name", { do }))`                               | Queue (`once`) or fan-out (`broadcast`)     | Payload (`schema`)                     |
+| Clock      | `on(clockDecl, flow("name", { do }))` or inline `clock.every(…)` | Interval or cron tick                       | none (`_`)                             |
+| CDC any    | `on(db.table(t).changed(), flow)`                                | Every insert / update / delete              | `{ before, after, table, action, id }` |
+| CDC column | `on(db.table(t).changed("col"), flow)`                           | Same writes; column stamped on the Manifest | `{ before, after, table, action, id }` |
 
 `signal.live` is an HTTP SSE tape — bind it with [`http.live`](/docs/elements/flow/http#live-streams),
 not as a worker. A Flow with no trigger is [call-only](/docs/elements/flow).
 
-Inline `on(signal.once("…"), flow({ do }))` is supported; export the handle for typed `fx.emit`.
-Nameless `flow({ do })` inherits the trigger name; a second nameless inherit fails **OKE1070**.
+Signal is always an exported const (`fx.emit` needs the handle). Clock may write
+`clock.every(…)` inside `on()` — [Clock · Inline or named
+export](/docs/elements/clock#inline-or-named-export). **OKE1072** if nameless.
 
 ## Signal Consumers
 
@@ -212,8 +214,12 @@ Each emit is handled according to the Signal helper you declared. The Flow is th
 
 <Tab value="Once">
 
-Competing workers — exactly one consumer processes each message. Failed attempts retry, then
-dead-letter when `deadLetter` is true (default):
+Competing workers — exactly one consumer claims each message. Failed attempts retry, then
+dead-letter when `deadLetter` is true (default).
+
+Two different Flows on one `once` signal fail **OKE1071** — see
+[Once · Competing consumers](/docs/elements/signal/once#competing-consumers-once-vs-broadcast).
+For every bound Flow to run, use [`signal.broadcast`](/docs/elements/signal/broadcast).
 
 ```typescript title="src/signals/orders.ts"
 import { signal } from "okengine";
@@ -336,10 +342,9 @@ Broadcast does not use the `once` lease / DLQ path. Live uses the retained tape,
 </Accordion>
 
 <Accordion title="Schema at emit">
-  Invalid payloads fail at `fx.emit` with **OKE1250** (`"{resource}": {detail}`) before any
-  consumer runs. Fix the payload or the Signal's `schema`. This is an **emit** contract — not
-  an HTTP invoke contract on `flow()`. Workers inherit the typed payload from the Signal
-  declaration; they do not declare `in` on `flow({ do })`.
+  Invalid payloads fail at `fx.emit` with **OKE1250** (`"{resource}": {detail}`) before any consumer
+  runs. This is an **emit** contract — workers inherit the payload from the Signal; they do not
+  declare `in` on `flow()`.
 </Accordion>
 
 </Accordions>
@@ -347,11 +352,9 @@ Broadcast does not use the `once` lease / DLQ path. Live uses the retained tape,
 ## Clock Jobs
 
 <Callout title="Detailed section">
-  Prefer `clock.every` / `clock.daily` / `clock.cron` (and the other named helpers) for fixed
-  schedules — they compile to the same decl as the bare callable. The lower-level bare `clock(name,
-  options)` form still works when you need a raw expression or a schedule chosen programmatically;
-  missing both `cron` and `every` throws `clock("name"): require cron or every`. Bind the returned
-  handle with `on(clockDecl, flow)`.
+  Prefer named helpers (`clock.every` / `daily` / `cron`). Bind with
+  `on(clockDecl, flow("name", { do }))`, or write `clock.every` inside `on()` —
+  [Clock · Inline or named export](/docs/elements/clock#inline-or-named-export).
 </Callout>
 
 Named clocks reconcile into the Store at boot. The scheduler leader-elects so N instances do not
@@ -363,10 +366,15 @@ double-fire. `do` receives no payload — read time through `fx.clock`.
 
 Human durations: `"200ms"` · `"30s"` · `"5m"` · `"1h"` · `"7d"` (integer + unit, no weeks):
 
-```typescript title="src/flows/health/ping.ts"
-import { on, flow, clock } from "okengine";
+```typescript title="src/clocks/health.ts"
+import { clock } from "okengine";
 
 export const pingClock = clock.every("health.pingExternal", "30s");
+```
+
+```typescript title="src/flows/health/ping.ts"
+import { on, flow } from "okengine";
+import { pingClock } from "@/clocks/health";
 
 export const pingExternal = on(
   pingClock,
@@ -385,13 +393,18 @@ export const pingExternal = on(
 
 Five-field cron (`m h dom mon dow`) plus an IANA `timezone` (default `"UTC"`):
 
-```typescript title="src/flows/reports/daily.ts"
-import { on, flow, clock } from "okengine";
+```typescript title="src/clocks/reports.ts"
+import { clock } from "okengine";
 
 export const dailyReportClock = clock.daily("reports.daily", {
   at: "06:00",
   timezone: "Asia/Riyadh",
 });
+```
+
+```typescript title="src/flows/reports/daily.ts"
+import { on, flow } from "okengine";
+import { dailyReportClock } from "@/clocks/reports";
 
 export const runDailyReport = on(
   dailyReportClock,
@@ -415,9 +428,14 @@ trigger when both are present.
 is never ticked:
 
 ```typescript title="src/clocks/invoices.ts"
-import { on, flow, clock } from "okengine";
+import { clock } from "okengine";
 
 export const invoicesClock = clock.perTenant("invoices", { every: "1h" });
+```
+
+```typescript title="src/flows/billing/invoices.ts"
+import { on, flow } from "okengine";
+import { invoicesClock } from "@/clocks/invoices";
 
 export const runInvoices = on(
   invoicesClock,
@@ -489,49 +507,34 @@ do not fire.
 ## CDC
 
 <Callout title="Detailed section">
-  If you only need any-write, jump to the example below. The handle is
+  If you only need any-write, jump to Bare or enriched below. The handle is
   `db.table(table).changed(column?)` — `db` is a `store.sql` declaration, `table` is a schema
   handle. `changed("insert")` is **not** an op filter; it stamps a column named `insert`.
 </Callout>
 
 SQL writes through `fx.store` notify CDC after commit. The Flow input is always
-`{ before, after }` plus `table`, `action`, and `id` (`CdcPayload`). Destructure
-only `{ before, after }` when that's all you need.
+`{ before, after, table, action, id }` (`CdcPayload`).
 
-<Tabs items={["Audit log", "Bare", "Images"]}>
+### Bare or enriched
 
-<Tab value="Audit log">
+| Style                     | When                                                                   |
+| ------------------------- | ---------------------------------------------------------------------- |
+| `({ before, after })`     | Bound to one table — images are enough (search reindex, listing cache) |
+| `({ table, action, id })` | Log, route, or branch — kind of change and which record (audit log)    |
 
-`table` is the real table name. `action` is `"created"` / `"updated"` / `"deleted"`.
-`id` is the declared primary-key value — not a hardcoded `"id"` column:
+Both styles receive the same object. There is no second dispatch path, no
+performance difference, and no correctness difference — the choice is which
+fields this handler destructures.
 
-```typescript title="src/flows/audit/users.ts"
-import { on, flow } from "okengine";
-import { db } from "@/core";
-import { users, auditLogs } from "@/schema";
-
-export const onUserWrite = on(
-  db.table(users).changed(),
-  flow("audit.users", {
-    do: async ({ table, action, id, before, after }, fx) => {
-      await fx
-        .store(db)
-        .insert(auditLogs)
-        .values({
-          table,
-          recordId: String(id),
-          action,
-        });
-    },
-  }),
-);
-```
+`{ table, action, id }` are always populated; omitting them from `do` does not
+drop them from the payload.
 
-</Tab>
+<Tabs items={["Bare", "Enriched", "Images"]}>
 
 <Tab value="Bare">
 
-Omit `table` / `action` / `id` when you only need the row images:
+Bound to `notes` — the table is already in the trigger. Images decide upsert vs
+drop; the row's `id` is on the surviving image:
 
 ```typescript title="src/flows/search/reindex.ts"
 import { on, flow } from "okengine";
@@ -553,25 +556,30 @@ export const reindexNotes = on(
 );
 ```
 
-`changed("status")` stamps `trigger.cdc.column` on the Manifest. Still receive the
-same payload — filter in `do` when you only care about that field:
+</Tab>
 
-```typescript title="src/flows/tasks/on-status.ts"
+<Tab value="Enriched">
+
+`table` is the real table name. `action` is `"created"` / `"updated"` / `"deleted"`.
+`id` is the declared primary-key value — not a hardcoded `"id"` column:
+
+```typescript title="src/flows/audit/users.ts"
 import { on, flow } from "okengine";
 import { db } from "@/core";
-import { tasks } from "@/schema";
+import { users, auditLogs } from "@/schema";
 
-export const onStatus = on(
-  db.table(tasks).changed("status"),
-  flow("tasks.onStatus", {
-    plane: "operator",
-    do: async ({ before, after, id }, fx) => {
-      if (before?.status === after?.status) return;
-      await fx.emit(taskStatusChanged, {
-        id,
-        from: before?.status ?? null,
-        to: after?.status ?? null,
-      });
+export const onUserWrite = on(
+  db.table(users).changed(),
+  flow("audit.users", {
+    do: async ({ table, action, id }, fx) => {
+      await fx
+        .store(db)
+        .insert(auditLogs)
+        .values({
+          table,
+          recordId: String(id),
+          action,
+        });
     },
   }),
 );
@@ -605,6 +613,30 @@ do: async ({ before, after, action }, fx) => {
 
 </Tabs>
 
+`changed("status")` stamps `trigger.cdc.column` on the Manifest. Still the same
+payload — filter in `do` when you only care about that field:
+
+```typescript title="src/flows/tasks/on-status.ts"
+import { on, flow } from "okengine";
+import { db } from "@/core";
+import { tasks } from "@/schema";
+
+export const onStatus = on(
+  db.table(tasks).changed("status"),
+  flow("tasks.onStatus", {
+    plane: "operator",
+    do: async ({ before, after, id }, fx) => {
+      if (before?.status === after?.status) return;
+      await fx.emit(taskStatusChanged, {
+        id,
+        from: before?.status ?? null,
+        to: after?.status ?? null,
+      });
+    },
+  }),
+);
+```
+
 <Accordions>
 
 <Accordion title="CDC payload">
@@ -660,9 +692,19 @@ Clock drivers: **postgres** in `dev`/`prod`, **frozen** in `test`. Signal driver
 </Accordion>
 
 <Accordion title="OKE1070 — flow name defined twice">
-  Cause: `Flow "{flow}" is defined twice.` Two nameless `flow({ do })` bindings inherited the same
-  Signal or Clock name, or two explicit `flow("…")` calls share a name. Give at least one an
-  explicit `flow("…")` or a distinct tree export.
+  Cause: `Flow "{flow}" is defined twice.` Two `flow("…")` strings share a name. Give at least one a
+  distinct name.
+</Accordion>
+
+<Accordion title="OKE1072 — Signal or Clock flow unnamed">
+  Cause: `A {kind} flow on "{trigger}" has no name.`
+  Fix: pass an explicit name — `on(handle, flow("unit.export", { do }))`.
+</Accordion>
+
+<Accordion title="OKE1071 — once signal bound to more than one Flow">
+  Cause: `Once signal "{signal}" is bound to more than one Flow ({flows}).` Use `signal.broadcast`
+  if each Flow should independently receive this event, or bind only one Flow. See [Once · Competing
+  consumers](/docs/elements/signal/once#competing-consumers-once-vs-broadcast).
 </Accordion>
 
 <Accordion title="OKE1240 — emit with no subscriber">
@@ -713,10 +755,11 @@ Clock drivers: **postgres** in `dev`/`prod`, **frozen** in `test`. Signal driver
 - [Signal](/docs/elements/signal) — `once` / `broadcast` / `live` physics
 - [Signal · Once](/docs/elements/signal/once) — leases, retries, partition keys
 - [Clock](/docs/elements/clock) — schedules, `fx.clock.sleep`
+- [Clock · Inline or named export](/docs/elements/clock#inline-or-named-export) — one Flow vs shared schedule
 - [Store · SQL](/docs/elements/store/sql) — tables CDC watches
 - [HTTP · Live Streams](/docs/elements/flow/http#live-streams) — `signal.live` SSE
 - [fx](/docs/reference/fx) — `fx.emit`, `fx.deadLetters`, `fx.clock`
-- [Errors](/docs/reference/errors) — OKE1070 · OKE1240 · OKE1250
+- [Errors](/docs/reference/errors) — OKE1070 · OKE1071 · OKE1072 · OKE1240 · OKE1250
 - [Workflows](/docs/elements/flow/workflows) — `durable: true` + `fx.step` on a consumer
 
 ## Next

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

@@ -344,9 +344,9 @@ A bare `404` with body `Not Found` means **no route matched** — not `fx.fail("
 </Accordion>
 
 <Accordion title="Name stamping">
-  Prefer nameless `flow({ do })` on tree files — the file stamps `unit.export`.
-  Pass `flow("notes.create", { … })` only for control. Nameless HTTP after adopt
-  fails **OKE1045** — see [Routing](/docs/elements/flow/routing#when-to-omit--when-to-pass).
+  Prefer nameless `flow({ do })` on HTTP tree files — `src/flows/notes/[id]/get.ts` +
+  `export const get` stamps `notes.get`. Signal / Clock workers pass `flow("name", { do })`
+  (**OKE1072**; Clock inline is [Clock · Inline or named export](/docs/elements/clock#inline-or-named-export)).
 </Accordion>
 
 </Accordions>

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

@@ -455,11 +455,9 @@ prefix). Wrong-unit prefixes fail generate.
 Non-HTTP files still join the unit. A signal consumer in `notes/on-created.ts`
 is `api.notes.onCreated` over RPC (`POST /_oke/notes/onCreated`), not HTTP.
 
-Outside the tree, nameless `flow({ do })` inherits a named Signal or Clock trigger.
-File-tree `unit.export` still wins. Two nameless inheritances fail **OKE1070**. HTTP has no
-inherent trigger name — those Flows stay on the tree stamp or **OKE1045**.
-
-HTTP flows that remain nameless after adopt fail **OKE1045**.
+Signal / Clock consumers pass an explicit `flow("…")` name (**OKE1072** if nameless
+outside `src/flows/<unit>/`; **OKE1070** on collision). Clock may write `clock.every(…)`
+inside `on()` — [Clock · Inline or named export](/docs/elements/clock#inline-or-named-export).
 
 ## Runtime Matching
 
@@ -517,8 +515,13 @@ plus a handwritten `http.get("/notes")`.
 </Accordion>
 
 <Accordion title="OKE1070 — flow name defined twice">
-  Cause: `Flow "{flow}" is defined twice.` Two nameless Signal/Clock consumers inherited the same
-  name, or two explicit `flow("…")` calls collide. Give at least one a distinct name or tree export.
+  Cause: `Flow "{flow}" is defined twice.` Two explicit `flow("…")` calls collide, or two tree
+  exports stamp the same `unit.export`. Give at least one a distinct name or tree export.
+</Accordion>
+
+<Accordion title="OKE1072 — Signal or Clock flow unnamed">
+  Cause: `A {kind} flow on "{trigger}" has no name.`
+  Fix: pass an explicit name — `on(handle, flow("unit.export", { do }))`.
 </Accordion>
 
 <Accordion title="422 — path param missing from in">
@@ -543,7 +546,7 @@ plus a handwritten `http.get("/notes")`.
 
 - [HTTP](/docs/elements/flow/http) — verbs, envelopes, `http.resource`, live SSE
 - [Client](/docs/client/calling) — `api.notes.get`, REST vs RPC, `$routes`
-- [Errors](/docs/reference/errors) — OKE1040 · OKE1030 · OKE1041 · OKE1045 · OKE1070
+- [Errors](/docs/reference/errors) — OKE1040 · OKE1030 · OKE1041 · OKE1045 · OKE1070 · OKE1072
 - [The Architecture](/docs/understand/the-architecture) — derived routes, no hand-written table
 - [Gate](/docs/elements/gate) — `.gate(...)` / `.public()` on the same trigger
 

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

@@ -21,10 +21,12 @@ more `on(signal, flow)` subscribers, emit with `fx.emit`.
 
 ## Smallest Example
 
-<Steps>
+<Callout title="One handle, three independent uses">
+  `cacheInvalidated` is a shared const. Declare it, bind any number of subscribers, and emit —
+  different files, any order. Bind and emit do not have a required sequence.
+</Callout>
 
-<Step>
-### Define the broadcast signal
+### Declare
 
 ```typescript title="src/signals/cache.ts"
 import { signal } from "okengine";
@@ -35,9 +37,6 @@ export const cacheInvalidated = signal.broadcast("cache.invalidated", {
 });
 ```
 
-</Step>
-
-<Step>
 ### Bind a subscriber
 
 ```typescript title="src/flows/cache/purge.ts"
@@ -54,10 +53,11 @@ export const purgeLocalCache = on(
 );
 ```
 
-</Step>
+Multiple Flows may bind the same handle — every one gets a copy. That is fan-out, not a race.
+See [Once · Competing consumers](/docs/elements/signal/once#competing-consumers-once-vs-broadcast)
+when you meant a work queue instead.
 
-<Step>
-### Emit from any Flow
+### Emit
 
 ```typescript title="src/flows/skus/[sku]/update.ts"
 import { on, flow, http } from "okengine";
@@ -81,10 +81,6 @@ export const update = on(
 The compiler records `emits: ["cache.invalidated"]` on the producer. Emit resolves when the
 outbox commits — the HTTP request does not wait for every subscriber to finish.
 
-</Step>
-
-</Steps>
-
 <Callout title="Same handle everywhere">
   Import the declared Signal handle (or the same name) in every subscriber and producer. A typo in
   the name creates a different Manifest entry — fan-out never crosses names.
@@ -470,6 +466,11 @@ dead-letter queue for exhausted retries in the queue sense — see
   Cause: `"{resource}": {detail}`. Align the payload with `schema` — no subscriber started.
 </Accordion>
 
+<Accordion title="OKE1072 — Signal flow unnamed">
+  Cause: `A signal flow on "{trigger}" has no name.`
+  Fix: pass an explicit name — `on(handle, flow("cache.purgeLocal", { do }))`.
+</Accordion>
+
 <Accordion title="Expecting retries / DLQ like a queue">
   Use `signal.once`. Broadcast fan-out is not the lease + DLQ path documented under
   [Once](/docs/elements/signal/once).
@@ -496,7 +497,7 @@ dead-letter queue for exhausted retries in the queue sense — see
 - [Consumers](/docs/elements/flow/consumers) — binding `on(signal)`
 - [HTTP · Live Streams](/docs/elements/flow/http#live-streams) — when the consumer is a browser
 - [fx](/docs/reference/fx) — `fx.emit`
-- [Errors](/docs/reference/errors) — OKE1240 · OKE1250
+- [Errors](/docs/reference/errors) — OKE1072 · OKE1240 · OKE1250
 
 ## Next