okengine 0.19.2 → 0.19.4

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

@@ -7,22 +7,24 @@ source: "docs/spec/unified-theory.md"
 
 Signal is how your backend **moves data when the producer should not wait**. An email job, a cache bust across instances, and a browser status feed share one handle shape — only the helper changes: `signal.once`, `signal.broadcast`, or `signal.live`.
 
-For developers wiring async work on okengine — declare the physics, emit with `fx.emit`, bind workers with `on(signal, flow)`.
+For developers wiring async work on okengine — declare the physics, emit with `fx.emit`, bind workers with `on(handle, flow("name", { do }))`.
 
 <Callout title="The one rule">
-  Declare every signal with `signal.once`, `signal.broadcast`, or `signal.live` — same idea as
-  `http.get` / `http.post`. Physics and the **emit** `schema` live on the Signal; the Flow
-  worker is only `flow({ do })` — it inherits the payload type from the Signal, not `flow.in`.
+  Declare every signal with `signal.once`, `signal.broadcast`, or `signal.live` as an
+  exported const. Bind with `on(handle, flow("name", { do }))`. Physics and the **emit**
+  `schema` live on the Signal; the worker inherits the payload type, not `flow.in`.
 </Callout>
 
 <SignalDelivery />
 
 ## 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,28 +71,14 @@ 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 emits to this Signal                          |
-| `export const x = signal.once<Payload>(…)`    | Another file needs `fx.emit(x, payload)` with compile-time payload checking |
-
 A string `fx.emit("name", payload)` still runs (runtime `schema` still applies) but does not
-type-check the payload.
-
-Nameless `flow({ do })` inherits the Signal name; file-tree `unit.export` and explicit
-`flow("…")` win. Two nameless inheritances of the same name fail **OKE1070**.
+type-check. Import the exported const.
 
 ## Progressive Patterns
 
@@ -221,6 +208,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>
@@ -245,14 +292,14 @@ Fix: add `on(signal, …)` or mark `{ optional: true }`.
 
 Optional second argument to `signal.once` / `signal.broadcast` / `signal.live`. Delivery is the helper name — not an option.
 
-| Option        | Type                     | Default   | Meaning                                                                                                                              |
-| ------------- | ------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `schema`      | Standard Schema          | omitted   | **Emit** contract — enforced at `fx.emit` (**OKE1250** on mismatch). Workers inherit the payload; do not put `in` on `flow({ do })`. |
-| `retries`     | `number`                 | `3`       | Extra attempts after the first (`retries + 1` total) — `once` path                                                                   |
-| `deadLetter`  | `boolean`                | `true`    | Keep exhausted `once` messages; `false` marks them delivered                                                                         |
-| `optional`    | `boolean`                | `false`   | Allow emit with zero subscribers                                                                                                     |
-| `retention`   | `{ maxAge?, maxCount? }` | unbounded | **`signal.live` only** — type error on `once` / `broadcast`                                                                          |
-| `description` | `string`                 | the name  | Console / docs blurb                                                                                                                 |
+| Option        | Type                     | Default   | Meaning                                                                                                                        |
+| ------------- | ------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `schema`      | Standard Schema          | omitted   | **Emit** contract — enforced at `fx.emit` (**OKE1250** on mismatch). Workers inherit the payload; do not put `in` on `flow()`. |
+| `retries`     | `number`                 | `3`       | Extra attempts after the first (`retries + 1` total) — `once` path                                                             |
+| `deadLetter`  | `boolean`                | `true`    | Keep exhausted `once` messages; `false` marks them delivered                                                                   |
+| `optional`    | `boolean`                | `false`   | Allow emit with zero subscribers                                                                                               |
+| `retention`   | `{ maxAge?, maxCount? }` | unbounded | **`signal.live` only** — type error on `once` / `broadcast`                                                                    |
+| `description` | `string`                 | the name  | Console / docs blurb                                                                                                           |
 
 **Consequence:** `deadLetter` is a boolean flag, not a queue name string.
 
@@ -320,6 +367,22 @@ 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 `flow("…")` strings collide. Give at least one a
+  distinct name.
+</Accordion>
+
+<Accordion title="OKE1072 — Signal flow unnamed">
+  Cause: `A signal flow on "{trigger}" has no name.`
+  Fix: pass an explicit name — `on(handle, flow("orders.fulfill", { 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 [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.
@@ -342,7 +405,7 @@ export default defineConfig({
 - [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 · OKE1072 · 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,20 @@ 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="OKE1072 — Signal flow unnamed">
+  Cause: `A signal flow on "{trigger}" has no name.`
+  Fix: pass an explicit name — `on(handle, flow("workers.email", { do }))`.
 </Accordion>
 
 <Accordion title="Messages stuck inflight">
@@ -574,7 +634,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 · OKE1072 · OKE1240 · OKE1250 · OKE1001
 
 ## Next
 

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

@@ -78,33 +78,35 @@ 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             |
+| `1072` | flow unnamed           | Signal / Clock consumer still has no `unit.export`     | Export from `flows/<unit>/` or pass a named `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 +174,18 @@ 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="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 }))`. See
+  [Signal](/docs/elements/signal) · [Clock](/docs/elements/clock).
+</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/site/content/docs/understand/the-architecture.mdx

@@ -168,8 +168,8 @@ flow({
 ```
 
 Omit the name on tree files — the compiler stamps `unit.export` (e.g. `users.signup`).
-Pass `flow("users.signup", { … })` only for control: barrels, stable names across
-moves, or call-only Flows you `fx.call` by name.
+Pass `flow("users.signup", { … })` outside a unit folder, or for barrels / `fx.call`.
+Nameless Signal / Clock consumers outside a unit fail **OKE1072**.
 
 ### `do` — the code that actually runs
 

package/src/cli/competitor-mention-removal.test.ts

@@ -45,9 +45,9 @@ const EXPRESS_ALLOW = ["src/plugins/headers.test.ts:"];
 const OKID_PROMPT_ALLOW = [
   "okid.md:",
   "bun.lock:",
-  // Minified zod-core inside the vendored Console bundle registers string
-  // format validators whose names collide with peer library names — vendor
-  // identifiers, not authored comparisons. Hash changes on Console rebuilds.
+  // Minified zod-core inside a locally built Console bundle (gitignored)
+  // registers string-format validators whose names collide with peer library
+  // names — vendor identifiers, not authored comparisons.
   "src/console/ui-next/dist/",
 ];