okengine 0.19.1 → 0.19.3

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/elements/store/sql.mdx

@@ -807,8 +807,8 @@ Default is insert-once; pass `{ onExisting: "update" }` to overwrite.
 </Callout>
 
 `db.table(orders).changed(column?)` builds a CDC trigger for `on(…)`. Input is
-always `{ before, after }`. `changed("status")` stamps a **column** name on the
-Manifest — it is not an op filter.
+`{ before, after }` plus `table` / `action` / `id`. `changed("status")` stamps a
+**column** name on the Manifest — it is not an op filter.
 
 ```typescript title="src/flows/orders/on-status.ts"
 import { on, flow } from "okengine";

package/site/content/docs/plugins/anonymous.mdx

@@ -38,7 +38,7 @@ export const app = oke({
 
 ```typescript
 const { data } = await api.auth.signInAnonymous();
-// data.userId is a fresh UUID; store tokens like any other session
+// data.userId is a fresh OKID; store tokens like any other session
 ```
 
 `POST /auth/sign-in/anonymous` — no body.

package/site/content/docs/plugins/cors.mdx

@@ -71,7 +71,7 @@ const origins = configSource({
   db: { store: db },
   kv: cache,
 });
-const corsSyncClock = clock("cors.sync", { every: "30s" });
+const corsSyncClock = clock.every("cors.sync", "30s");
 on(corsSyncClock, origins.sync());
 export const app = oke({ name: "shop", env: "dev" }).plug(cors(origins));
 ```

package/site/content/docs/plugins/csrf.mdx

@@ -75,7 +75,7 @@ const rules = configSource({
   db: { store: db },
   kv: cache,
 });
-const csrfSyncClock = clock("csrf.sync", { every: "30s" });
+const csrfSyncClock = clock.every("csrf.sync", "30s");
 on(csrfSyncClock, rules.sync());
 export const app = oke({ name: "shop", env: "dev" }).plug(csrf(rules));
 ```

package/site/content/docs/plugins/headers.mdx

@@ -103,7 +103,7 @@ const headerConfig = configSource({
   db: { store: db },
   kv: cache,
 });
-const headerSyncClock = clock("headers.sync", { every: "30s" });
+const headerSyncClock = clock.every("headers.sync", "30s");
 on(headerSyncClock, headerConfig.sync());
 export const app = oke({ name: "shop", env: "dev" }).plug(headers(headerConfig));
 ```

package/site/content/docs/plugins/ip-allowlist.mdx

@@ -69,7 +69,7 @@ const rules = configSource({
   db: { store: db },
   kv: cache,
 });
-const ipRulesSyncClock = clock("ip-allowlist.sync", { every: "30s" });
+const ipRulesSyncClock = clock.every("ip-allowlist.sync", "30s");
 on(ipRulesSyncClock, rules.sync());
 export const app = oke({ name: "shop", env: "dev" }).plug(ipAllowlist(rules));
 ```

package/site/content/docs/plugins/maintenance-mode.mdx

@@ -78,7 +78,7 @@ const maintenance = configSource({
   db: { store: db },
   kv: cache,
 });
-const maintenanceSyncClock = clock("maintenance.sync", { every: "30s" });
+const maintenanceSyncClock = clock.every("maintenance.sync", "30s");
 on(maintenanceSyncClock, maintenance.sync());
 export const app = oke({ name: "shop", env: "dev" }).plug(maintenanceMode(maintenance));
 ```

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

@@ -78,32 +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                 |
-| `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
@@ -171,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/site/content/docs/reference/fx.mdx

@@ -90,11 +90,11 @@ See [Store](/docs/elements/store) for the query-builder surface.
 
 ## Signals
 
-| Signature                             | Records                | Notes                                                                                                                                                                                                     |
-| ------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `fx.emit(signal, payload?, { key? })` | `emit`                 | Commits the signal outbox when the call resolves; optional `key` serializes `once` per key; stamps producer run id as `parentRunId` for trace chains; throws **OKE1240** (orphan) or **OKE1250** (schema) |
-| `fx.deadLetters(signal)`              | `read` `signal:<name>` | Dead-lettered messages for that signal. Payload typed from `SignalDecl<T>`. Page with `fx.json.withQuery`. Cross-signal throws **OKE1001**.                                                               |
-| `fx.live(signal, { match? })`         | `read` `signal:<name>` | Live tape as SSE. Returns `JsonStreamResult` (object chunks, `id:` on the wire). Cross-signal throws **OKE1001**. Do not wrap with `fx.json.stream`.                                                      |
+| Signature                             | Records                | Notes                                                                                                                                                                                                                                                                                                                            |
+| ------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fx.emit(signal, payload?, { key? })` | `emit`                 | Pass a `SignalDecl<T>` handle to type-check `payload`; a string name stays `unknown` (runtime `schema` still applies). Commits the signal outbox when the call resolves; optional `key` serializes `once` per key; stamps producer run id as `parentRunId` for trace chains; throws **OKE1240** (orphan) or **OKE1250** (schema) |
+| `fx.deadLetters(signal)`              | `read` `signal:<name>` | Dead-lettered messages for that signal. Payload typed from `SignalDecl<T>`. Page with `fx.json.withQuery`. Cross-signal throws **OKE1001**.                                                                                                                                                                                      |
+| `fx.live(signal, { match? })`         | `read` `signal:<name>` | Live tape as SSE. Returns `JsonStreamResult` (object chunks, `id:` on the wire). Cross-signal throws **OKE1001**. Do not wrap with `fx.json.stream`.                                                                                                                                                                             |
 
 ## Runs (observability read)
 
@@ -108,7 +108,7 @@ Declare `effects: { reads: ["runs"] }`. Powers native SLO checkers (Clock + Chan
 | `fx.runs.checkSlo(flow, slo, windowMs?)` | `read` `runs` | Availability / latency breaches                                                          |
 
 ```typescript
-const sloCheckClock = clock("ops.slo-check", { every: "5m" });
+const sloCheckClock = clock.every("ops.slo-check", "5m");
 
 on(
   sloCheckClock,

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

@@ -150,7 +150,7 @@ The default alphabet order is not lexicographic; `_` sorts between uppercase and
 ## Learn more
 
 - [Store](/docs/elements/store) — `defaultFn(id)` in table declarations delegates to `okid()`
-- [fx](/docs/reference/fx) — `fx.id()` in the runtime uses `okid()`
+- [fx](/docs/reference/fx) — `fx.id()` returns an OKID; options live here
 - [Clock](/docs/elements/clock) — process `instanceId` (`inst-<okid>`) is an OKID
 
 ## Next

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

@@ -146,7 +146,7 @@ const maintenance = configSource({
   kv: cache, // read-through cache (optional)
 });
 
-const maintenanceSyncClock = clock("maintenance.sync", { every: "30s" });
+const maintenanceSyncClock = clock.every("maintenance.sync", "30s");
 on(maintenanceSyncClock, maintenance.sync()); // one clock flow refreshes the box
 
 export const app = oke({ name: "shop", env: "dev" }).plug(maintenanceMode(maintenance));

package/site/content/docs/understand/the-architecture.mdx

@@ -239,7 +239,7 @@ None of that required new code beyond what's above. It required the four lines t
 | Trigger                                             | Element | Starts When                      |
 | --------------------------------------------------- | ------- | -------------------------------- |
 | `http.post()` (path from file tree)                 | Flow    | A request arrives                |
-| `clock("name", { every: "10m" })`                   | Clock   | A time interval elapses          |
+| `clock.every("name", "10m")`                        | Clock   | A time interval elapses          |
 | `signal.once("name", {…})` / `.broadcast` / `.live` | Signal  | Another flow announces something |
 | `db.table(users).changed("email")`                  | Store   | A database row changes           |
 | `mcp.tool("name")`                                  | AI      | An AI agent calls it             |

package/src/compiler/extract.test.ts

@@ -530,7 +530,6 @@ export const live = on(
 );
 `;
     const manifest = await extractFromSources({
-      "src/schema.decl.ts": source,
       "src/flows/live.ts": source,
     });
     expect(manifest.flows?.["tasks.live"]).toBeDefined();
@@ -2069,3 +2068,126 @@ export const app = oke({
     );
   });
 });
+
+describe("extractManifest — inline Signal/Clock + name inheritance", () => {
+  test("inline signal.once / clock.every stamp element maps and flow.trigger", async () => {
+    const source = `
+import { on, flow, signal, clock } from "okengine";
+
+on(
+  signal.once("link-clicked", { retries: 3, deadLetter: true }),
+  flow({ do: async (input, fx) => {
+    await fx.store("sql:links").set("x", input);
+  } }),
+);
+
+on(
+  clock.every("cleanup", "10m"),
+  flow({ do: async (_input, fx) => {
+    await fx.store("sql:links").set("y", 1);
+  } }),
+);
+`;
+    const manifest = await extractFromSources({ "inline.ts": source });
+    expect(manifest.signals?.["link-clicked"]).toMatchObject({
+      delivery: "once",
+      retries: 3,
+      deadLetter: true,
+    });
+    expect(manifest.clocks?.cleanup).toMatchObject({ every: "10m" });
+    expect(manifest.flows?.["link-clicked"]?.trigger).toEqual({ signal: "link-clicked" });
+    expect(manifest.flows?.cleanup?.trigger).toEqual({ every: "10m" });
+  });
+
+  test("nameless flow inherits the named trigger; explicit flow name wins", async () => {
+    const source = `
+import { on, flow, signal, clock } from "okengine";
+
+export const orderPlaced = signal.once("order-placed");
+on(orderPlaced, flow({ do: () => ({ ok: true }) }));
+
+on(
+  clock.every("metrics.cleanup", "1h"),
+  flow("ops.sweep", { do: () => ({ ok: true }) }),
+);
+`;
+    const manifest = await extractFromSources({ "workers.ts": source });
+    expect(manifest.flows?.["order-placed"]?.trigger).toEqual({ signal: "order-placed" });
+    expect(manifest.flows?.["ops.sweep"]?.trigger).toEqual({ every: "1h" });
+    expect(manifest.flows?.["metrics.cleanup"]).toBeUndefined();
+  });
+
+  test("file-tree unit.export wins over trigger-name inheritance", async () => {
+    const source = `
+import { on, flow, signal } from "okengine";
+export const onCreated = on(
+  signal.once("note-created"),
+  flow({ do: () => ({ ok: true }) }),
+);
+`;
+    const manifest = await extractFromSources({
+      "src/flows/notes/on-created.ts": source,
+    });
+    expect(manifest.flows?.["notes.onCreated"]?.trigger).toEqual({ signal: "note-created" });
+    expect(manifest.flows?.["note-created"]).toBeUndefined();
+  });
+
+  test("two nameless inheritances of the same trigger name fail extract", async () => {
+    const source = `
+import { on, flow, signal } from "okengine";
+const ping = signal.once("health.ping");
+on(ping, flow({ do: () => ({ a: true }) }));
+on(ping, flow({ do: () => ({ b: true }) }));
+`;
+    await expect(extractFromSources({ "dup.ts": source })).rejects.toThrow(
+      /duplicate flow name "health.ping"/,
+    );
+  });
+});
+
+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" });
+  });
+});