okengine 0.19.3 → 0.19.4

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

@@ -7,12 +7,12 @@ 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 />
@@ -77,167 +77,8 @@ for the worker.
   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>
+type-check. Import the exported const.
 
 ## Progressive Patterns
 
@@ -451,14 +292,14 @@ Fix: `Use signal.broadcast if each flow should independently receive this event,
 
 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.
 
@@ -527,9 +368,13 @@ export default defineConfig({
 </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).
+  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">
@@ -557,11 +402,10 @@ 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) — OKE1070 · OKE1071 · OKE1240 · OKE1250 · OKE1210
+- [Errors](/docs/reference/errors) — OKE1070 · OKE1071 · OKE1072 · OKE1240 · OKE1250 · OKE1210
 
 ## Next
 

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

@@ -591,6 +591,11 @@ See [Durable Workflows](/docs/elements/flow/workflows).
   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">
   Wait for the 30s lease and the next drain/claim. There is no separate timeout daemon. A handler
   still running past the lease can overlap with a reclaim — shorten the work or journal it.
@@ -629,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) — OKE1071 · OKE1240 · OKE1250 · OKE1001
+- [Errors](/docs/reference/errors) — OKE1071 · OKE1072 · OKE1240 · OKE1250 · OKE1001
 
 ## Next
 

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

@@ -98,6 +98,7 @@ string. Custom app codes stay message-less until registered. Full catalogs:
 | `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`           |
@@ -173,6 +174,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="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

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/",
 ];
 

package/src/compiler/extract.test.ts

@@ -2069,21 +2069,21 @@ export const app = oke({
   });
 });
 
-describe("extractManifest — inline Signal/Clock + name inheritance", () => {
+describe("extractManifest — inline Signal/Clock + explicit / tree names", () => {
   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) => {
+  flow("hooks.linkClicked", { do: async (input, fx) => {
     await fx.store("sql:links").set("x", input);
   } }),
 );
 
 on(
   clock.every("cleanup", "10m"),
-  flow({ do: async (_input, fx) => {
+  flow("ops.cleanup", { do: async (_input, fx) => {
     await fx.store("sql:links").set("y", 1);
   } }),
 );
@@ -2095,16 +2095,16 @@ on(
       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" });
+    expect(manifest.flows?.["hooks.linkClicked"]?.trigger).toEqual({ signal: "link-clicked" });
+    expect(manifest.flows?.["ops.cleanup"]?.trigger).toEqual({ every: "10m" });
   });
 
-  test("nameless flow inherits the named trigger; explicit flow name wins", async () => {
+  test("explicit flow name is independent of the trigger name", async () => {
     const source = `
 import { on, flow, signal, clock } from "okengine";
 
 export const orderPlaced = signal.once("order-placed");
-on(orderPlaced, flow({ do: () => ({ ok: true }) }));
+on(orderPlaced, flow("orders.fulfill", { do: () => ({ ok: true }) }));
 
 on(
   clock.every("metrics.cleanup", "1h"),
@@ -2112,12 +2112,13 @@ on(
 );
 `;
     const manifest = await extractFromSources({ "workers.ts": source });
-    expect(manifest.flows?.["order-placed"]?.trigger).toEqual({ signal: "order-placed" });
+    expect(manifest.flows?.["orders.fulfill"]?.trigger).toEqual({ signal: "order-placed" });
     expect(manifest.flows?.["ops.sweep"]?.trigger).toEqual({ every: "1h" });
     expect(manifest.flows?.["metrics.cleanup"]).toBeUndefined();
+    expect(manifest.flows?.["order-placed"]).toBeUndefined();
   });
 
-  test("file-tree unit.export wins over trigger-name inheritance", async () => {
+  test("file-tree unit.export stamps a nameless Signal consumer", async () => {
     const source = `
 import { on, flow, signal } from "okengine";
 export const onCreated = on(
@@ -2132,15 +2133,189 @@ export const onCreated = on(
     expect(manifest.flows?.["note-created"]).toBeUndefined();
   });
 
-  test("two nameless inheritances of the same trigger name fail extract", async () => {
+  test("two differently-named flows on the same clock extract cleanly", async () => {
+    const source = `
+import { on, flow, clock } from "okengine";
+export const tick = clock.every("metrics.tick", "1h");
+on(tick, flow("ops.sweep", { do: () => ({ a: true }) }));
+on(tick, flow("ops.report", { do: () => ({ b: true }) }));
+`;
+    const manifest = await extractFromSources({ "clock-fanout.ts": source });
+    expect(manifest.clocks?.["metrics.tick"]).toMatchObject({ every: "1h" });
+    expect(manifest.flows?.["ops.sweep"]?.trigger).toEqual({ every: "1h" });
+    expect(manifest.flows?.["ops.report"]?.trigger).toEqual({ every: "1h" });
+  });
+
+  // Exact Clock docs Inline sample — explicit flow name, trigger written inline.
+  const clockInlineExplicitDocsSample = `
+import { on, flow, clock } from "okengine";
+
+export const pingExternal = on(
+  clock.every("health.pingExternal", "30s"),
+  flow("health.pingExternal", {
+    plane: "operator",
+    do: async (_, fx) => {
+      await fx.call(pingUpstream);
+    },
+  }),
+);
+`;
+
+  test("docs Clock Inline (explicit name) extracts outside src/flows/<unit>/", async () => {
+    const manifest = await extractFromSources({ "ping.ts": clockInlineExplicitDocsSample });
+    expect(manifest.clocks?.["health.pingExternal"]?.every).toBe("30s");
+    expect(manifest.flows?.["health.pingExternal"]?.trigger).toEqual({ every: "30s" });
+    expect(manifest.flows?.["pingExternal"]).toBeUndefined();
+  });
+
+  test("docs Clock named-export (shared schedule) extracts two explicit flows", async () => {
+    const clockSource = `
+import { clock } from "okengine";
+
+export const tickClock = clock.every("metrics.tick", "1h");
+`;
+    const flowsSource = `
+import { on, flow } from "okengine";
+import { tickClock } from "@/clocks/metrics";
+
+export const sweep = on(
+  tickClock,
+  flow("ops.sweep", {
+    plane: "operator",
+    do: async (_, fx) => {
+      await fx.call(sweepMetrics);
+    },
+  }),
+);
+
+export const report = on(
+  tickClock,
+  flow("ops.report", {
+    plane: "operator",
+    do: async (_, fx) => {
+      await fx.call(reportMetrics);
+    },
+  }),
+);
+`;
+    const manifest = await extractFromSources({
+      "src/clocks/metrics.ts": clockSource,
+      "src/flows/ops/metrics.ts": flowsSource,
+    });
+    expect(manifest.clocks?.["metrics.tick"]).toMatchObject({ every: "1h" });
+    expect(manifest.flows?.["ops.sweep"]?.trigger).toEqual({ every: "1h" });
+    expect(manifest.flows?.["ops.report"]?.trigger).toEqual({ every: "1h" });
+  });
+});
+
+describe("extractManifest — nameless Signal/Clock consumers fail OKE1072", () => {
+  test("nameless flow({ do }) on signal.once fails OKE1072", async () => {
+    const source = `
+import { on, flow, signal } from "okengine";
+on(signal.once("link-clicked"), flow({ do: () => ({ ok: true }) }));
+`;
+    await expect(extractFromSources({ "once.ts": source })).rejects.toThrow(/OKE1072/);
+  });
+
+  test("nameless flow({ do }) on signal.broadcast fails OKE1072", async () => {
+    const source = `
+import { on, flow, signal } from "okengine";
+on(signal.broadcast("catalog.changed"), flow({ do: () => ({ ok: true }) }));
+`;
+    await expect(extractFromSources({ "broadcast.ts": source })).rejects.toThrow(/OKE1072/);
+  });
+
+  test("nameless flow({ do }) on signal.live fails OKE1072", 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 }) }));
+on(signal.live("order-status", { optional: true }), flow({ do: () => ({ ok: true }) }));
+`;
+    await expect(extractFromSources({ "live.ts": source })).rejects.toThrow(/OKE1072/);
+  });
+
+  test("nameless flow({ do }) on clock.every fails OKE1072", async () => {
+    const source = `
+import { on, flow, clock } from "okengine";
+on(clock.every("cleanup", "10m"), flow({ do: () => ({ ok: true }) }));
 `;
-    await expect(extractFromSources({ "dup.ts": source })).rejects.toThrow(
-      /duplicate flow name "health.ping"/,
+    await expect(extractFromSources({ "clock.ts": source })).rejects.toThrow(/OKE1072/);
+  });
+
+  // Exact Signal docs Inline sample — tree path vs anywhere else.
+  const signalInlineDocsSample = `
+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 });
+    },
+  }),
+);
+`;
+
+  test("docs Inline sample at src/flows/hooks/inbound.ts stamps hooks.ingestWebhook", async () => {
+    const manifest = await extractFromSources({
+      "src/flows/hooks/inbound.ts": signalInlineDocsSample,
+    });
+    expect(manifest.flows?.["hooks.ingestWebhook"]?.trigger).toEqual({ signal: "hooks.inbound" });
+    expect(manifest.signals?.["hooks.inbound"]?.delivery).toBe("once");
+    expect(manifest.flows?.["ingestWebhook"]).toBeUndefined();
+    expect(manifest.flows?.["hooks.inbound"]).toBeUndefined();
+  });
+
+  test("docs Inline sample outside src/flows/<unit>/ fails OKE1072", async () => {
+    try {
+      await extractFromSources({ "inbound.ts": signalInlineDocsSample });
+      expect.unreachable("extract should throw OKE1072");
+    } catch (err) {
+      expect(err).toBeInstanceOf(Error);
+      const message = (err as Error).message;
+      expect(message).toMatch(/OKE1072/);
+      expect(message).toContain("hooks.inbound");
+      expect(message).toContain('flow("unit.export"');
+      expect(message).toContain("src/flows/<unit>/");
+    }
+  });
+
+  test("docs Inline sample under src/signals/ fails OKE1072", async () => {
+    await expect(
+      extractFromSources({ "src/signals/inbound.ts": signalInlineDocsSample }),
+    ).rejects.toThrow(/OKE1072/);
+  });
+
+  const clockInlineDocsSample = `
+import { on, flow, clock } from "okengine";
+
+export const pingExternal = on(
+  clock.every("health.pingExternal", "30s"),
+  flow({
+    plane: "operator",
+    do: async (_, fx) => {
+      await fx.call(pingUpstream);
+    },
+  }),
+);
+`;
+
+  test("docs Clock Inline sample at src/flows/health/ping.ts stamps health.pingExternal", async () => {
+    const manifest = await extractFromSources({
+      "src/flows/health/ping.ts": clockInlineDocsSample,
+    });
+    expect(manifest.flows?.["health.pingExternal"]?.trigger).toEqual({ every: "30s" });
+    expect(manifest.clocks?.["health.pingExternal"]?.every).toBe("30s");
+    expect(manifest.flows?.["pingExternal"]).toBeUndefined();
+  });
+
+  test("docs Clock Inline sample outside src/flows/<unit>/ fails OKE1072", async () => {
+    await expect(extractFromSources({ "ping.ts": clockInlineDocsSample })).rejects.toThrow(
+      /OKE1072/,
     );
   });
 });

package/src/compiler/extract.ts

@@ -55,7 +55,7 @@ import {
   type InferBinding,
   type Literal,
 } from "./effects-infer.ts";
-import { nameFromFlowFile, pathFromFlowFile } from "./flow-path.ts";
+import { isFlowsTreeFile, nameFromFlowFile, pathFromFlowFile } from "./flow-path.ts";
 import {
   defaultListInSchema,
   jsonSchemaFromAst,
@@ -1852,13 +1852,21 @@ function registerFlow(args: {
   const trigger = args.triggerNode
     ? parseTrigger(args.triggerNode, args.scope, args.file.path)
     : undefined;
-  const inherited = elementTriggerName(args.triggerNode, args.scope);
 
+  const signalOrClock = isSignalOrClockTrigger(trigger);
+  const treeName =
+    !signalOrClock || isFlowsTreeFile(args.file.path)
+      ? nameFromFlowFile(args.file.path, args.exportName)
+      : undefined;
+
+  // Signal / Clock: explicit `flow("name")` or a real `src/flows/<unit>/`
+  // tree stamp. A bare `export const` outside that folder is not a name —
+  // **OKE1072**, same as `oke()`. HTTP still falls through to exportName.
   const name =
     stringArg(args.flowCall.arguments[0]) ??
-    nameFromFlowFile(args.file.path, args.exportName) ??
+    treeName ??
+    (signalOrClock ? unnamedElementFlowName(args.triggerNode, args.scope, trigger) : undefined) ??
     args.exportName ??
-    inherited ??
     `flow_${Object.keys(args.scope.flows).length + 1}`;
 
   if (args.exportName) {
@@ -2414,10 +2422,22 @@ function assertOnceSignalSingleFlow(scope: ProjectScope): void {
   }
 }
 
+/**
+ * True when the parsed trigger is a Signal or Clock (cron / every).
+ *
+ * @param parsed - Parsed `on()` trigger
+ */
+function isSignalOrClockTrigger(parsed: ParsedTrigger | undefined): boolean {
+  const t = parsed?.trigger;
+  return Boolean(t && (t.signal || t.cron || t.every));
+}
+
 /**
  * Stable Signal / Clock name on `on()`'s first argument, when one exists.
  * HTTP has no inherent name of this kind — returns undefined.
  *
+ * Used only for **OKE1072** diagnostics — never as a Flow name.
+ *
  * @param node - Trigger AST
  * @param scope - Project scope
  */
@@ -2450,6 +2470,29 @@ function elementTriggerName(node: AstNode | undefined, scope: ProjectScope): str
   return undefined;
 }
 
+/**
+ * Fail loud when a Signal / Clock consumer has no explicit or tree-derived name.
+ * HTTP still falls through to the generic `flow_*` placeholder (OKE1045 at boot).
+ *
+ * @param triggerNode - Trigger AST
+ * @param scope - Project scope
+ * @param parsed - Parsed trigger
+ * @returns Never for Signal / Clock; `undefined` otherwise
+ */
+function unnamedElementFlowName(
+  triggerNode: AstNode | undefined,
+  scope: ProjectScope,
+  parsed: ParsedTrigger | undefined,
+): undefined {
+  if (!isSignalOrClockTrigger(parsed)) return undefined;
+  const triggerName = elementTriggerName(triggerNode, scope);
+  const kind = parsed?.trigger?.signal ? "signal" : "clock";
+  const target = triggerName ? `${kind} "${triggerName}"` : kind;
+  throw new Error(
+    `OKE1072: nameless flow({ do }) bound to ${target}. Use flow("unit.export", { do }) or export it from a src/flows/<unit>/ file so the tree can stamp unit.export.`,
+  );
+}
+
 /**
  * Inline `signal.once(…)` / `clock.every(…)` as `on()`'s first argument.
  *