okengine 0.19.2 → 0.19.3

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,10 +71,6 @@ 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
@@ -84,14 +81,163 @@ for the worker.
 
 | Style                                         | When                                                                        |
 | --------------------------------------------- | --------------------------------------------------------------------------- |
-| `on(signal.once("name", opts), flow({ do }))` | Self-contained — nothing else emits to this Signal                          |
+| `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 the payload.
+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 });
+    },
+  }),
+);
+```
 
-Nameless `flow({ do })` inherits the Signal name; file-tree `unit.export` and explicit
-`flow("…")` win. Two nameless inheritances of the same name fail **OKE1070**.
+```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
 
@@ -221,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>
@@ -320,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.
@@ -339,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).

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

@@ -21,10 +21,12 @@ For developers shipping jobs on okengine — declare the Signal, bind `on(signal
 
 ## Smallest Example
 
-<Steps>
+<Callout title="One handle, three independent uses">
+  `emailTask` is a shared const. Declare it, bind a worker, and emit — different files, any order.
+  Binding is not "step 2" after declare; emit is not "step 3".
+</Callout>
 
-<Step>
-### Define the once signal
+### Declare
 
 ```typescript title="src/signals/email.ts"
 import { signal } from "okengine";
@@ -37,10 +39,7 @@ export const emailTask = signal.once("tasks.email", {
 });
 ```
 
-</Step>
-
-<Step>
-### Attach a worker and emit
+### Bind a worker
 
 ```typescript title="src/flows/workers/email.ts"
 import { on, flow } from "okengine";
@@ -57,6 +56,8 @@ export const processEmail = on(
 );
 ```
 
+### Emit
+
 ```typescript
 await fx.emit(emailTask, { to: "alice@example.com", body: "Welcome" });
 ```
@@ -64,14 +65,67 @@ await fx.emit(emailTask, { to: "alice@example.com", body: "Welcome" });
 The emit resolves when the outbox commits. The worker runs asynchronously — the producer does not
 wait for `fx.send` to finish.
 
-</Step>
+## Competing consumers (once vs broadcast)
 
-</Steps>
+This is the most common mix-up. `signal.once` is a competing-consumer work queue: **exactly one**
+worker claims each message. It is not fan-out.
 
-<Callout title="Competing, not fan-out">
-  Two Flows bound to the same `once` Signal compete — exactly one claims each message. For every
-  subscriber to run, use [`broadcast`](/docs/elements/signal/broadcast).
-</Callout>
+Three differently-named Flows bound to the same `once` signal:
+
+```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, use
+[`signal.broadcast`](/docs/elements/signal/broadcast). 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}).`
+
+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.`
+
+Load-balancing competing consumers is the **same** Flow on many process replicas — still one
+`on()` in source. That case is not a second Flow definition.
 
 ## Progressive Patterns
 
@@ -251,12 +305,11 @@ The compiler records `emits: ["tasks.email"]` on producers that call `fx.emit(em
 
 <Tab value="Competing">
 
-Two Flows on the same `once` Signal share the pool — exactly one claims each message:
-
-```typescript title="src/flows/orders/fulfill-a.ts"
-import { on, flow } from "okengine";
-import { orderPlaced } from "@/signals/orders";
+Two different Flows on the same `once` Signal is the once-vs-broadcast mix-up — see
+[Competing consumers](#competing-consumers-once-vs-broadcast). The bus would let only one claim
+each message (race winner, not both, not a fixed Flow). The Manifest now fails **OKE1071**:
 
+```typescript
 export const fulfillA = on(
   orderPlaced,
   flow("orders.fulfillA", {
@@ -265,11 +318,6 @@ export const fulfillA = on(
     },
   }),
 );
-```
-
-```typescript title="src/flows/orders/fulfill-b.ts"
-import { on, flow } from "okengine";
-import { orderPlaced } from "@/signals/orders";
 
 export const fulfillB = on(
   orderPlaced,
@@ -281,7 +329,8 @@ export const fulfillB = on(
 );
 ```
 
-**Consequence:** this is not fan-out. For every Flow to run, use `signal.broadcast`.
+**Consequence:** bind one Flow (replicas of that process still compete for claims), or switch the
+declaration to [`signal.broadcast`](/docs/elements/signal/broadcast) so every Flow gets a copy.
 
 </Tab>
 
@@ -531,9 +580,15 @@ See [Durable Workflows](/docs/elements/flow/workflows).
 </Accordion>
 
 <Accordion title="Both of two Flows ran on one once message">
-  That is broadcast physics, not once. Confirm both files import the same `signal.once` handle —
-  competing workers share one claim. If you need fan-out, switch the declaration to
-  `signal.broadcast`.
+  That is broadcast physics, not once. Two different Flow definitions on one `once` signal now fail
+  **OKE1071** at boot. If you need every Flow to run, switch the declaration to
+  [`signal.broadcast`](/docs/elements/signal/broadcast).
+</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. Replicas of one Flow
+  are still one `on()` in source.
 </Accordion>
 
 <Accordion title="Messages stuck inflight">
@@ -574,7 +629,7 @@ See [Durable Workflows](/docs/elements/flow/workflows).
 - [Consumers](/docs/elements/flow/consumers) — `on(signal)` next to Clock / CDC
 - [Workflows](/docs/elements/flow/workflows) — `durable` + `fx.step` for idempotent side effects
 - [fx](/docs/reference/fx) — `fx.emit`, `fx.deadLetters`
-- [Errors](/docs/reference/errors) — OKE1240 · OKE1250 · OKE1001
+- [Errors](/docs/reference/errors) — OKE1071 · OKE1240 · OKE1250 · OKE1001
 
 ## Next
 

package/site/content/docs/reference/errors.mdx

@@ -78,33 +78,34 @@ string. Custom app codes stay message-less until registered. Full catalogs:
 
 ## OKE numeric codes
 
-| Code   | Name                 | Cause                                                  | Fix                                                       |
-| ------ | -------------------- | ------------------------------------------------------ | --------------------------------------------------------- |
-| `1001` | undeclared read      | Flow reads a resource not in `effects.reads`           | Add it to the flow's `effects.reads`                      |
-| `1002` | undeclared write     | Flow writes a resource not in `effects.writes`         | Add it to the flow's `effects.writes`                     |
-| `1003` | undeclared emit      | Flow emits a signal not in `effects.emits`             | Add it to the flow's `effects.emits`                      |
-| `1004` | undeclared send      | Flow sends a template not in `effects.sends`           | Add it to the flow's `effects.sends`                      |
-| `1005` | undeclared ask       | Flow asks a prompt not in `effects.asks`               | Add it to the flow's `effects.asks`                       |
-| `1006` | undeclared secret    | Flow reads a secret not in `effects.secrets`           | Add it to the flow's `effects.secrets`                    |
-| `1007` | undeclared call      | Flow calls a flow not in `effects.calls`               | Add it to the flow's `effects.calls`                      |
-| `1008` | undeclared fetch     | Flow fetches a host not in `effects.fetches`           | Add the hostname to the flow's `effects.fetches`          |
-| `1009` | undeclared embed     | Flow embeds with a model not in `effects.embeds`       | Add it to the flow's `effects.embeds`                     |
-| `1020` | no effects declared  | Flow has no `effects` and no Manifest to infer from    | Run `oke build` / `oke dev`, or declare effects           |
-| `1030` | adopt barrel stale   | A `src/flows/<unit>` folder was not adopted            | Run `oke dev` or `oke build` to regenerate `generated.ts` |
-| `1040` | HTTP path unresolved | Pathless `http.get()` never received a file-tree stamp | Import `@/flows/generated`, or pass `http.get("/…")`      |
-| `1041` | HTTP route clash     | Two HTTP flows share the same method + path            | Give each flow a unique method + path                     |
-| `1045` | HTTP flow unnamed    | Adopted HTTP flow still has no `unit.export`           | Export from `flows/<unit>/` or pass a named `flow`        |
-| `1050` | live exposure dup    | Same signal, gates, and match on two GET routes        | Change the gate or path-param filter                      |
-| `1060` | MCP tool duplicate   | Two MCP tool bindings share the same tool name         | Give each MCP tool exposure a unique name                 |
-| `1070` | flow name duplicate  | Two Flows share the same Manifest / `fx.call` name     | Give at least one an explicit `flow("…")` or tree export  |
-| `1110` | schema missing       | Domain table absent in `prod` — no auto-DDL            | Run `oke db migrate` against this environment             |
-| `1210` | live resume gap      | `Last-Event-ID` is not on the retained tape            | Reconnect without the cursor; remaining tape replays      |
-| `1240` | orphan emit          | Emit with zero subscribers and `optional` false        | Add `on(signal, …)` or declare `optional: true`           |
-| `1250` | signal schema        | Emit payload failed the signal's `schema`              | Pass a payload that matches `schema`, or remove it        |
-| `1605` | channel schema       | Send payload failed the template's `schema`            | Fix template `data` payload or the template `schema`      |
-| `1810` | tenant required      | Tenant-scoped op with no `fx.tenant.id`                | `switchTenant`, signed `tid`, or tenant header            |
-| `1820` | tenant not member    | Client-supplied tenant id is not a membership          | Pick from `listTenants` or add the user as a member       |
-| `1830` | tenant unknown scope | Tenant role used an invented or `console:*` scope      | Use a declared application scope                          |
+| Code   | Name                   | Cause                                                  | Fix                                                       |
+| ------ | ---------------------- | ------------------------------------------------------ | --------------------------------------------------------- |
+| `1001` | undeclared read        | Flow reads a resource not in `effects.reads`           | Add it to the flow's `effects.reads`                      |
+| `1002` | undeclared write       | Flow writes a resource not in `effects.writes`         | Add it to the flow's `effects.writes`                     |
+| `1003` | undeclared emit        | Flow emits a signal not in `effects.emits`             | Add it to the flow's `effects.emits`                      |
+| `1004` | undeclared send        | Flow sends a template not in `effects.sends`           | Add it to the flow's `effects.sends`                      |
+| `1005` | undeclared ask         | Flow asks a prompt not in `effects.asks`               | Add it to the flow's `effects.asks`                       |
+| `1006` | undeclared secret      | Flow reads a secret not in `effects.secrets`           | Add it to the flow's `effects.secrets`                    |
+| `1007` | undeclared call        | Flow calls a flow not in `effects.calls`               | Add it to the flow's `effects.calls`                      |
+| `1008` | undeclared fetch       | Flow fetches a host not in `effects.fetches`           | Add the hostname to the flow's `effects.fetches`          |
+| `1009` | undeclared embed       | Flow embeds with a model not in `effects.embeds`       | Add it to the flow's `effects.embeds`                     |
+| `1020` | no effects declared    | Flow has no `effects` and no Manifest to infer from    | Run `oke build` / `oke dev`, or declare effects           |
+| `1030` | adopt barrel stale     | A `src/flows/<unit>` folder was not adopted            | Run `oke dev` or `oke build` to regenerate `generated.ts` |
+| `1040` | HTTP path unresolved   | Pathless `http.get()` never received a file-tree stamp | Import `@/flows/generated`, or pass `http.get("/…")`      |
+| `1041` | HTTP route clash       | Two HTTP flows share the same method + path            | Give each flow a unique method + path                     |
+| `1045` | HTTP flow unnamed      | Adopted HTTP flow still has no `unit.export`           | Export from `flows/<unit>/` or pass a named `flow`        |
+| `1050` | live exposure dup      | Same signal, gates, and match on two GET routes        | Change the gate or path-param filter                      |
+| `1060` | MCP tool duplicate     | Two MCP tool bindings share the same tool name         | Give each MCP tool exposure a unique name                 |
+| `1070` | flow name duplicate    | Two Flows share the same Manifest / `fx.call` name     | Give at least one an explicit `flow("…")` or tree export  |
+| `1071` | once-signal multi-flow | Two different Flows bound to the same `signal.once`    | Use `signal.broadcast`, or bind only one Flow             |
+| `1110` | schema missing         | Domain table absent in `prod` — no auto-DDL            | Run `oke db migrate` against this environment             |
+| `1210` | live resume gap        | `Last-Event-ID` is not on the retained tape            | Reconnect without the cursor; remaining tape replays      |
+| `1240` | orphan emit            | Emit with zero subscribers and `optional` false        | Add `on(signal, …)` or declare `optional: true`           |
+| `1250` | signal schema          | Emit payload failed the signal's `schema`              | Pass a payload that matches `schema`, or remove it        |
+| `1605` | channel schema         | Send payload failed the template's `schema`            | Fix template `data` payload or the template `schema`      |
+| `1810` | tenant required        | Tenant-scoped op with no `fx.tenant.id`                | `switchTenant`, signed `tid`, or tenant header            |
+| `1820` | tenant not member      | Client-supplied tenant id is not a membership          | Pick from `listTenants` or add the user as a member       |
+| `1830` | tenant unknown scope   | Tenant role used an invented or `console:*` scope      | Use a declared application scope                          |
 
 <Callout title="Effects are usually inferred">
   The 1001–1007 · 1008 · 1009 family exists for flows that declare effects explicitly. Most apps
@@ -172,6 +173,12 @@ Thrown by specific subsystems — each names its own cause:
   A resource mount and a handwritten route share the same method + path. Drop one binding.
 </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 get a copy, or bind only one Flow. See [Once · Competing
+  consumers](/docs/elements/signal/once#competing-consumers-once-vs-broadcast).
+</Accordion>
+
 <Accordion title="OKE1110 in production">
   Domain tables missing — prod has no auto-DDL. Run `oke db migrate` against that environment
   ([CLI](/docs/reference/cli)).

package/src/compiler/extract.test.ts

@@ -2144,3 +2144,50 @@ on(ping, flow({ do: () => ({ b: true }) }));
     );
   });
 });
+
+describe("extractManifest — once-signal uniqueness OKE1071", () => {
+  test("two differently-named flows on the same once signal fail OKE1071", async () => {
+    const source = `
+import { on, flow, signal } from "okengine";
+export const orderPlaced = signal.once("orders.placed");
+on(orderPlaced, flow("orders.charge", { do: () => ({ a: true }) }));
+on(orderPlaced, flow("orders.ship", { do: () => ({ b: true }) }));
+`;
+    try {
+      await extractFromSources({ "dup-once.ts": source });
+      expect.unreachable("extract should throw OKE1071");
+    } catch (err) {
+      expect(err).toBeInstanceOf(Error);
+      const message = (err as Error).message;
+      expect(message).toMatch(/OKE1071/);
+      expect(message).toContain("orders.placed");
+      expect(message).toContain("orders.charge");
+      expect(message).toContain("orders.ship");
+      expect(message).toMatch(/signal\.broadcast/);
+    }
+  });
+
+  test("the same scenario with signal.broadcast does not fail", async () => {
+    const source = `
+import { on, flow, signal } from "okengine";
+export const catalogChanged = signal.broadcast("catalog.changed");
+on(catalogChanged, flow("cache.invalidate", { do: () => ({ a: true }) }));
+on(catalogChanged, flow("search.reindex", { do: () => ({ b: true }) }));
+`;
+    const manifest = await extractFromSources({ "fanout.ts": source });
+    expect(manifest.signals?.["catalog.changed"]?.delivery).toBe("broadcast");
+    expect(manifest.flows?.["cache.invalidate"]?.trigger).toEqual({ signal: "catalog.changed" });
+    expect(manifest.flows?.["search.reindex"]?.trigger).toEqual({ signal: "catalog.changed" });
+  });
+
+  test("a single flow bound to once extracts cleanly", async () => {
+    const source = `
+import { on, flow, signal } from "okengine";
+export const emailTask = signal.once("tasks.email");
+on(emailTask, flow("workers.email", { do: () => ({ ok: true }) }));
+`;
+    const manifest = await extractFromSources({ "once.ts": source });
+    expect(manifest.signals?.["tasks.email"]?.delivery).toBe("once");
+    expect(manifest.flows?.["workers.email"]?.trigger).toEqual({ signal: "tasks.email" });
+  });
+});