okengine 0.19.2 → 0.19.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.19.2",
+  "version": "0.19.3",
   "description": "One law. Eight elements. One contract. The backend model stays small; operational surfaces are derived from it instead of maintained separately.",
   "license": "MIT",
   "repository": {

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

@@ -80,8 +80,142 @@ Under `drivers.clock.test = "frozen"`, advance time in tests instead of waiting
 | `on(clock.every("name", "1h"), flow({ do }))` | Self-contained — nothing else needs the Clock handle              |
 | `export const x = clock.every("name", "1h")`  | Another file (or a second `on()`) must reuse the same declaration |
 
-Nameless `flow({ do })` inherits the Clock's declared name. File-tree `unit.export` and explicit
-`flow("…")` win. Two nameless Flows inheriting the same name fail **OKE1070**.
+Both styles stamp the same Manifest `flow.trigger`. The choice is where the
+declaration lives, not two runtimes.
+
+What the Flow is called is a separate choice — [Flow name](#flow-name).
+
+<Tabs items={["Inline", "Named"]}>
+
+<Tab value="Inline">
+
+One file — declare and bind together. The scheduler fires it; no other file
+imports the handle:
+
+```typescript title="src/flows/health/ping.ts"
+import { on, flow, clock } from "okengine";
+
+export const pingExternal = on(
+  clock.every("health.pingExternal", "30s"),
+  flow({
+    plane: "operator",
+    do: async (_, fx) => {
+      await fx.call(pingUpstream);
+    },
+  }),
+);
+```
+
+</Tab>
+
+<Tab value="Named">
+
+Export the handle when another file (or a second `on()`) must reuse the same
+declaration:
+
+```typescript title="src/clocks/digest.ts"
+import { clock } from "okengine";
+
+export const digestClock = clock.every("notes.digest", "1d");
+```
+
+```typescript title="src/flows/notes/digest.ts"
+import { on, flow } from "okengine";
+import { digestClock } from "@/clocks/digest";
+
+export const digest = on(
+  digestClock,
+  flow("notes.digest", {
+    plane: "operator",
+    do: async (_, fx) => {
+      await fx.call(buildDigest, { at: fx.clock.now() });
+    },
+  }),
+);
+```
+
+</Tab>
+
+</Tabs>
+
+## Flow name
+
+| Style                     | When                                                             |
+| ------------------------- | ---------------------------------------------------------------- |
+| `flow({ do })`            | No unit folder — Flow name is the Clock name (`metrics.cleanup`) |
+| `flow("ops.sweep")`       | Manifest / `fx.call` name must differ from the Clock             |
+| Tree `export const sweep` | `src/flows/ops/sweep.ts` stamps `ops.sweep` — overwrites inherit |
+
+Explicit `flow("…")` and the file tree overwrite inherit. HTTP does not inherit a
+name from the path — nameless HTTP stays for the tree or fails **OKE1045**. Two
+Flows that land on the same name fail **OKE1070** (`Flow "{flow}" is defined twice.`).
+
+<Tabs items={["Inherit", "Explicit", "Tree"]}>
+
+<Tab value="Inherit">
+
+A file directly in `src/flows/` (no unit folder) has nothing to stamp. The Flow
+is named `metrics.cleanup` — same as the Clock:
+
+```typescript title="src/flows/cleanup.ts"
+import { on, flow, clock } from "okengine";
+
+export const cleanupMetrics = on(
+  clock.every("metrics.cleanup", "1h"),
+  flow({
+    plane: "operator",
+    do: async (_, fx) => {
+      await fx.call(sweepMetrics);
+    },
+  }),
+);
+```
+
+</Tab>
+
+<Tab value="Explicit">
+
+The Clock stays `metrics.cleanup`. The Flow is `ops.sweep` — that is the
+Manifest / `fx.call` name:
+
+```typescript title="src/flows/sweep.ts"
+import { on, flow, clock } from "okengine";
+
+export const sweep = on(
+  clock.every("metrics.cleanup", "1h"),
+  flow("ops.sweep", {
+    plane: "operator",
+    do: async (_, fx) => {
+      await fx.call(sweepMetrics);
+    },
+  }),
+);
+```
+
+</Tab>
+
+<Tab value="Tree">
+
+Unit folder + `export const` stamps `unit.export`. The Flow is `ops.sweep`, not
+the Clock name `cleanup`:
+
+```typescript title="src/flows/ops/sweep.ts"
+import { on, flow, clock } from "okengine";
+
+export const sweep = on(
+  clock.every("cleanup", "10m"),
+  flow({
+    plane: "operator",
+    do: async (_, fx) => {
+      await fx.call(sweepMetrics);
+    },
+  }),
+);
+```
+
+</Tab>
+
+</Tabs>
 
 ## Progressive Patterns
 
@@ -279,6 +413,12 @@ export default defineConfig({
   declaration in source.
 </Accordion>
 
+<Accordion title="OKE1070 — flow name defined twice">
+  Cause: `Flow "{flow}" is defined twice.` Two nameless consumers inherited the same Clock name, or
+  two explicit `flow("…")` calls collide. Give at least one a distinct `flow("…")` or tree export —
+  [Flow name](#flow-name).
+</Accordion>
+
 </Accordions>
 
 ## Learn more
@@ -288,7 +428,8 @@ export default defineConfig({
 - [Consumers · Clock Jobs](/docs/elements/flow/consumers#clock-jobs) — bind with `on(clockDecl, flow)`
 - [Workflows](/docs/elements/flow/workflows) — `durable: true` + `fx.step` around sleeps
 - [fx](/docs/reference/fx) — full `fx.clock` table
-- [Errors](/docs/reference/errors) — `ScheduleNotOverridableError` · `ClockResourceNotFoundError`
+- [Routing](/docs/elements/flow/routing#names) — tree `unit.export` vs inherit
+- [Errors](/docs/reference/errors) — `ScheduleNotOverridableError` · `ClockResourceNotFoundError` · OKE1070
 
 ## Next
 

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).
@@ -195,8 +190,9 @@ Omit `key` for competing consumers with no ordering.
 `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**.
+One-file inline vs exported handle: [Signal](/docs/elements/signal#inline-or-named-export) ·
+[Clock](/docs/elements/clock#inline-or-named-export). Flow name (inherit / explicit / tree):
+[Signal](/docs/elements/signal#flow-name) · [Clock](/docs/elements/clock#flow-name). Collision is **OKE1070**.
 
 ## Signal Consumers
 
@@ -212,8 +208,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";
@@ -489,49 +489,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 +538,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 +595,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">
@@ -665,6 +679,12 @@ Clock drivers: **postgres** in `dev`/`prod`, **frozen** in `test`. Signal driver
   explicit `flow("…")` or a distinct tree export.
 </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">
   Cause: `Flow "{flow}" emits signal "{resource}" with no subscriber.` Add `on(signal, flow)` or
   set `{ optional: true }` on the Signal (live firehoses, unused hooks).
@@ -716,7 +736,7 @@ Clock drivers: **postgres** in `dev`/`prod`, **frozen** in `test`. Signal driver
 - [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 · OKE1240 · OKE1250
 - [Workflows](/docs/elements/flow/workflows) — `durable: true` + `fx.step` on a consumer
 
 ## Next

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

@@ -345,8 +345,8 @@ A bare `404` with body `Not Found` means **no route matched** — not `fx.fail("
 
 <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).
+  Signal / Clock inherit the trigger name only outside a unit folder
+  ([Signal · Flow name](/docs/elements/signal#flow-name)). Nameless HTTP after adopt fails **OKE1045**.
 </Accordion>
 
 </Accordions>

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

@@ -455,11 +455,18 @@ 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**.
+Nameless Signal / Clock consumers take the trigger name only when the tree does
+not stamp `unit.export`:
+
+| Style                           | Flow name               |
+| ------------------------------- | ----------------------- |
+| `flow({ do })` (no unit folder) | the Signal / Clock name |
+| `flow("orders.fulfill")`        | the string you passed   |
+| `src/flows/notes/on-created.ts` | `notes.onCreated`       |
+
+Worked examples: [Signal · Flow name](/docs/elements/signal#flow-name) ·
+[Clock · Flow name](/docs/elements/clock#flow-name). Collision fails **OKE1070**.
+HTTP has no trigger name of this kind — nameless HTTP stays for the tree or **OKE1045**.
 
 ## Runtime Matching
 

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.