okengine 0.19.1 → 0.19.3

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

@@ -179,14 +179,14 @@ const { chargeId } = await fx.call(chargeCard, { amount: 50 });
 
 <FlowTriggers />
 
-| Trigger   | Bind                                           | Starts when         | `do` input                 |
-| --------- | ---------------------------------------------- | ------------------- | -------------------------- |
-| HTTP      | `on(http.get(), flow)`                         | A request           | Merged path / query / body |
-| Signal    | `on(signalHandle, flow)`                       | `fx.emit`           | Payload (`schema`)         |
-| Clock     | `on(clockDecl, flow)`                          | Scheduler tick      | none (`_`)                 |
-| CDC       | `on(db.table(t).changed(), flow)`              | Committed SQL write | `{ before, after }`        |
-| Call-only | `call("name", { in, out, do, … })`             | `fx.call`           | Callee `in`                |
-| MCP       | `on(mcp.tool("x", { in, out }).gate(…), flow)` | MCP `tools/call`    | Tool args                  |
+| Trigger   | Bind                                           | Starts when         | `do` input                             |
+| --------- | ---------------------------------------------- | ------------------- | -------------------------------------- |
+| HTTP      | `on(http.get(), flow)`                         | A request           | Merged path / query / body             |
+| Signal    | `on(signalHandle, flow)`                       | `fx.emit`           | Payload (`schema`)                     |
+| Clock     | `on(clockDecl, flow)`                          | Scheduler tick      | none (`_`)                             |
+| CDC       | `on(db.table(t).changed(), flow)`              | Committed SQL write | `{ before, after, table, action, id }` |
+| Call-only | `call("name", { in, out, do, … })`             | `fx.call`           | Callee `in`                            |
+| MCP       | `on(mcp.tool("x", { in, out }).gate(…), flow)` | MCP `tools/call`    | Tool args                              |
 
 `signal.live` is an HTTP SSE tape — bind it with [`http.live`](/docs/elements/flow/http#live-streams), not as a worker.
 
@@ -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>
@@ -366,7 +366,7 @@ A bare `404` with body `Not Found` means **no route matched** — not `fx.fail("
 | `fx.ask(prompt, opts)`     | `asks`                     | AI prompt                                     |
 | `fx.vault.get(secret)`     | `secrets`                  | Declared secret (never a raw value in source) |
 | `fx.call(flow, input?)`    | `calls`                    | Another Flow — waits for return               |
-| `fx.id()`                  | —                          | UUID                                          |
+| `fx.id()`                  | —                          | OKID — 21-char native id from `okengine/okid` |
 | `fx.clock.now()`           | —                          | Deterministic time                            |
 | `fx.fail(code, data)`      | —                          | Typed failure value                           |
 | `fx.step(name, fn)`        | journal                    | Durable checkpoint                            |
@@ -524,9 +524,9 @@ Default is `true` once `gate.auth.tenant` is on.
 </Accordion>
 
 <Accordion title="TypeError: on() expected a trigger or signal handle">
-  First argument must be an HTTP trigger, Signal handle, Clock handle,
-  `db.table(…).changed()`, `internal`, or `mcp.tool(…)`. A bare interval string is not
-  a trigger — wrap it in `clock("name", { every: "1h" })`.
+  First argument must be an HTTP trigger, Signal handle, Clock handle, `db.table(…).changed()`,
+  `internal`, or `mcp.tool(…)`. A bare interval string is not a trigger — wrap it in
+  `clock.every("name", "1h")`.
 </Accordion>
 
 <Accordion title="TypeError: on() expected a flow() definition as the second argument">

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

@@ -455,7 +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.
 
-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
 
@@ -512,6 +523,11 @@ plus a handwritten `http.get("/notes")`.
   file so the tree can stamp `unit.export`. `export default` is not picked up.
 </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.
+</Accordion>
+
 <Accordion title="422 — path param missing from in">
   `[id]` stamps `:id`. `in` must declare `id` (same key). A schema that expects `userId` while the
   path is `:id` fails validation before `do`.
@@ -534,7 +550,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
+- [Errors](/docs/reference/errors) — OKE1040 · OKE1030 · OKE1041 · OKE1045 · OKE1070
 - [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.

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

@@ -19,10 +19,12 @@ For developers wiring async work on okengine — declare the physics, emit with
 
 ## Smallest Example
 
-<Steps>
+<Callout title="One handle, three independent uses">
+  `orderPlaced` is a shared const. Declare it, bind a worker, and emit from a producer — different
+  files, different people, any order. None of these is a prerequisite step for the others.
+</Callout>
 
-<Step>
-### Declare the signal
+### Declare
 
 ```typescript title="src/signals/orders.ts"
 import { signal } from "okengine";
@@ -39,10 +41,7 @@ export const orderPlaced = signal.once("orders.placed", {
 });
 ```
 
-</Step>
-
-<Step>
-### Bind a worker and emit
+### Bind a worker
 
 ```typescript title="src/flows/orders/fulfill.ts"
 import { on, flow } from "okengine";
@@ -58,8 +57,10 @@ export const fulfill = on(
 );
 ```
 
+### Emit
+
 ```typescript
-// Inside any Flow:
+// Inside any Flow — need not live next to the worker:
 await fx.emit(orderPlaced, {
   orderId: "ord_99",
   amount: 150,
@@ -70,16 +71,174 @@ await fx.emit(orderPlaced, {
 The compiler records `emits: ["orders.placed"]` on the producer. The HTTP request does not wait
 for the worker.
 
-</Step>
-
-</Steps>
-
 <Callout title="Live is not a worker">
   `signal.live` is an HTTP SSE tape. Expose it with
   [`http.live`](/docs/elements/flow/http#live-streams) — do not bind `on(liveSignal, flow)` as a
   competing consumer.
 </Callout>
 
+## Inline or named export
+
+| Style                                         | When                                                                        |
+| --------------------------------------------- | --------------------------------------------------------------------------- |
+| `on(signal.once("name", opts), flow({ do }))` | Self-contained — nothing else needs the Signal handle                       |
+| `export const x = signal.once<Payload>(…)`    | Another file needs `fx.emit(x, payload)` with compile-time payload checking |
+
+Both styles stamp the same Manifest `flow.trigger`. The choice is where the
+declaration lives, not two runtimes.
+
+A string `fx.emit("name", payload)` still runs (runtime `schema` still applies) but does not
+type-check. 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. Producers emit with the string name:
+
+```typescript title="src/flows/hooks/inbound.ts"
+import { on, flow, signal } from "okengine";
+import { z } from "zod";
+
+export const ingestWebhook = on(
+  signal.once("hooks.inbound", {
+    schema: z.object({ id: z.string() }),
+    retries: 3,
+    deadLetter: true,
+  }),
+  flow({
+    do: async ({ id }, fx) => {
+      await fx.call(persistHook, { id });
+    },
+  }),
+);
+```
+
+```typescript
+await fx.emit("hooks.inbound", { id: "h_1" });
+```
+
+</Tab>
+
+<Tab value="Named">
+
+Export the handle when another file must `fx.emit` with compile-time payload checking:
+
+```typescript title="src/signals/orders.ts"
+import { signal } from "okengine";
+import { z } from "zod";
+
+export const orderPlaced = signal.once("orders.placed", {
+  schema: z.object({ orderId: z.string() }),
+});
+```
+
+```typescript title="src/flows/orders/fulfill.ts"
+import { on, flow } from "okengine";
+import { orderPlaced } from "@/signals/orders";
+
+export const fulfill = on(
+  orderPlaced,
+  flow("orders.fulfill", {
+    do: async ({ orderId }, fx) => {
+      await fx.call(chargeAndShip, { orderId });
+    },
+  }),
+);
+```
+
+```typescript
+await fx.emit(orderPlaced, { orderId: "ord_99" });
+```
+
+</Tab>
+
+</Tabs>
+
+## Flow name
+
+| Style                         | When                                                                          |
+| ----------------------------- | ----------------------------------------------------------------------------- |
+| `flow({ do })`                | No unit folder — Flow name is the Signal name (`hooks.inbound`)               |
+| `flow("orders.fulfill")`      | Manifest / `fx.call` name must differ from the Signal                         |
+| Tree `export const onCreated` | `src/flows/notes/on-created.ts` stamps `notes.onCreated` — 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 `hooks.inbound` — same as the Signal:
+
+```typescript title="src/flows/hooks.ts"
+import { on, flow, signal } from "okengine";
+import { z } from "zod";
+
+export const ingestWebhook = on(
+  signal.once("hooks.inbound", {
+    schema: z.object({ id: z.string() }),
+    retries: 3,
+    deadLetter: true,
+  }),
+  flow({
+    do: async ({ id }, fx) => {
+      await fx.call(persistHook, { id });
+    },
+  }),
+);
+```
+
+</Tab>
+
+<Tab value="Explicit">
+
+The Signal stays `orders.placed`. The Flow is `orders.fulfill` — that is the
+Manifest / `fx.call` name:
+
+```typescript title="src/flows/fulfill.ts"
+import { on, flow } from "okengine";
+import { orderPlaced } from "@/signals/orders";
+
+export const fulfill = on(
+  orderPlaced,
+  flow("orders.fulfill", {
+    do: async ({ orderId }, fx) => {
+      await fx.call(chargeAndShip, { orderId });
+    },
+  }),
+);
+```
+
+</Tab>
+
+<Tab value="Tree">
+
+Unit folder + `export const` stamps `unit.export`. The Flow is `notes.onCreated`,
+not `note-created`:
+
+```typescript title="src/flows/notes/on-created.ts"
+import { on, flow } from "okengine";
+import { noteCreatedMail } from "@/core";
+import { noteCreated } from "./signals";
+
+export const onCreated = on(
+  noteCreated,
+  flow({
+    do: async ({ id }, fx) => {
+      await fx.send(noteCreatedMail, { to: "you@localhost", data: { id } });
+    },
+  }),
+);
+```
+
+</Tab>
+
+</Tabs>
+
 ## Progressive Patterns
 
 Same helpers + `fx.emit` from a queue job to a fan-out and a browser feed:
@@ -208,6 +367,66 @@ Fix: add `on(signal, …)` or mark `{ optional: true }`.
 | `signal.broadcast` | Pub/sub    | Every active subscriber       | None (miss if offline) | Cache invalidation, fan-out |
 | `signal.live`      | SSE tape   | HTTP clients via `http.live`  | `Last-Event-ID` resume | Status feeds, progress      |
 
+## Competing consumers (once vs broadcast)
+
+This is the most common mix-up. `signal.once` is a work queue: **exactly one** worker claims each
+message. It is not fan-out.
+
+Three differently-named Flows bound to the same `once` signal, then one emit:
+
+```typescript title="src/flows/orders/side-effects.ts"
+import { on, flow } from "okengine";
+import { orderPlaced } from "@/signals/orders";
+
+export const charge = on(
+  orderPlaced,
+  flow("orders.charge", {
+    do: async ({ orderId }, fx) => {
+      await fx.call(chargeOrder, { orderId });
+    },
+  }),
+);
+export const ship = on(
+  orderPlaced,
+  flow("orders.ship", {
+    do: async ({ orderId }, fx) => {
+      await fx.call(shipOrder, { orderId });
+    },
+  }),
+);
+export const notify = on(
+  orderPlaced,
+  flow("orders.notify", {
+    do: async ({ orderId }, fx) => {
+      await fx.call(notifyOrder, { orderId });
+    },
+  }),
+);
+```
+
+```typescript
+await fx.emit(orderPlaced, { orderId: "ord_99", amount: 150, userId: "usr_1" });
+```
+
+| Expectation                         | Real result                                                          |
+| ----------------------------------- | -------------------------------------------------------------------- |
+| All three Flows run                 | **No.** Exactly one of the three runs                                |
+| Always `orders.charge` (first `on`) | **No.** The winner is whichever claim lands first — not a fixed Flow |
+| A sticky assignment to one Flow     | **No.** There is no owner — only an exclusive claim per message      |
+
+**Consequence:** if every bound Flow should independently receive its own copy, that is
+[`signal.broadcast`](/docs/elements/signal/broadcast) — switch the declaration. That is the correct
+fix for this exact mistake.
+
+Two or more **different** Flow definitions on the same `once` signal fail **OKE1071**.
+
+Cause: `Once signal "{signal}" is bound to more than one Flow ({flows}).`
+
+Load-balancing competing consumers is the **same** Flow on many process replicas — still one
+`on()` in source.
+
+Fix: `Use signal.broadcast if each flow should independently receive this event, or bind only one flow if these should compete for the same work.`
+
 ## The Capabilities of Signal
 
 <Cards>
@@ -307,6 +526,18 @@ export default defineConfig({
   on the Signal. The consumer never ran.
 </Accordion>
 
+<Accordion title="OKE1070 — flow name defined twice">
+  Cause: `Flow "{flow}" is defined twice.` Two nameless consumers inherited the same Signal name, or
+  two explicit `flow("…")` calls collide. Give at least one a distinct `flow("…")` or tree export —
+  [Flow name](#flow-name).
+</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 [Competing
+  consumers](#competing-consumers-once-vs-broadcast).
+</Accordion>
+
 <Accordion title='oke boot: signal driver "postgres" / "nats"'>
   Those ids are reserved but not bound for production yet. Use `"memory"` or `"redis"`, or inject a
   custom `elements.signal` runtime.
@@ -326,10 +557,11 @@ export default defineConfig({
 - [Broadcast](/docs/elements/signal/broadcast) — ephemeral fan-out
 - [Live](/docs/elements/signal/live) — SSE tapes and retention
 - [Consumers](/docs/elements/flow/consumers) — `on(signal)` workers next to Clock / CDC
+- [Routing](/docs/elements/flow/routing#names) — tree `unit.export` vs inherit
 - [HTTP · Live Streams](/docs/elements/flow/http#live-streams) — `http.live` exposure
 - [fx](/docs/reference/fx) — `fx.emit`, `fx.deadLetters`, `fx.live`
 - [Client](/docs/client/live) — `api.live` for browsers
-- [Errors](/docs/reference/errors) — OKE1240 · OKE1250 · OKE1210
+- [Errors](/docs/reference/errors) — OKE1070 · OKE1071 · OKE1240 · OKE1250 · OKE1210
 
 ## Next
 

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

@@ -21,10 +21,12 @@ from the typed client.
 
 ## Smallest Example
 
-<Steps>
+<Callout title="One handle, three independent uses">
+  `orderStatus` is a shared const. Declare it, expose SSE, and emit — different files, any order.
+  The firehose is not "step 2"; emit is not "step 3".
+</Callout>
 
-<Step>
-### Declare the live signal
+### Declare
 
 ```typescript title="src/signals/orders.ts"
 import { signal } from "okengine";
@@ -39,9 +41,6 @@ export const orderStatus = signal.live("order-status", {
 });
 ```
 
-</Step>
-
-<Step>
 ### Expose SSE
 
 ```typescript title="src/flows/orders/firehose.ts"
@@ -52,9 +51,6 @@ import { orderStatus } from "@/signals/orders";
 export const firehose = on(http.live(orderStatus).gate(member));
 ```
 
-</Step>
-
-<Step>
 ### Emit and subscribe
 
 ```typescript
@@ -71,10 +67,6 @@ curl -N http://localhost:6530/_oke/live/order-status \
 Response `Content-Type` is `text/event-stream`. Frames are JSON `data:` lines
 (optional `id:` for resume), then `data: [DONE]`.
 
-</Step>
-
-</Steps>
-
 <Callout title="Pathless firehose">
   `on(http.live(signal))` always mounts `GET /_oke/live/{name}` — there is no pathless file-tree
   stamp for live. Custom paths use `http.get(path).live(signal)`. See [Exposure](#exposure).