okengine 0.19.2 → 0.19.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.19.2",
+  "version": "0.19.4",
   "description": "One law. Eight elements. One contract. The backend model stays small; operational surfaces are derived from it instead of maintained separately.",
   "license": "MIT",
   "repository": {

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

@@ -57,7 +57,7 @@ import { noteCreated } from "./signals";
 
 export const onCreated = on(
   noteCreated,
-  flow({
+  flow("notes.onCreated", {
     do: async (payload, fx) => {
       await fx.send(noteCreatedMail, {
         to: "you@localhost",

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

@@ -5,7 +5,7 @@ icon: "Clock"
 source: "docs/spec/unified-theory.md"
 ---
 
-Clock is how your backend **knows what time it is and when to run again**. A monthly invoice job, a 30s health ping, and a three-day trial reminder share one vocabulary: declare a named schedule, bind it with `on(clockDecl, flow)`, and read time only through `fx.clock`.
+Clock is how your backend **knows what time it is and when to run again**. A monthly invoice job, a 30s health ping, and a three-day trial reminder share one vocabulary: declare a named schedule, bind it with `on(clockDecl, flow("name", { do }))`, and read time only through `fx.clock`.
 
 For developers scheduling work on okengine — one handle shape; drivers swap by environment.
 
@@ -58,9 +58,8 @@ export const digest = on(
 ### See it tick
 
 With `oke dev`, the scheduler reconciles `notes.digest` into the Store and leader-elects
-before each fire. `do` receives no payload — read time with `fx.clock.now()` (epoch-ms for
-math). Map to ISO on the wire when the Flow returns a human-facing instant
-(`new Date(fx.clock.now()).toISOString()`).
+before each fire. `do` receives no payload — read time with `fx.clock.now()` (epoch-ms).
+Map to ISO on the wire with `new Date(fx.clock.now()).toISOString()`.
 
 Under `drivers.clock.test = "frozen"`, advance time in tests instead of waiting a day.
 
@@ -69,19 +68,88 @@ Under `drivers.clock.test = "frozen"`, advance time in tests instead of waiting
 </Steps>
 
 <Callout title="Jobs are Flows">
-  `on(clockDecl, flow)` is the same species as Signal consumers and HTTP handlers. There is no
-  separate job runner — see [Consumers · Clock Jobs](/docs/elements/flow/consumers#clock-jobs).
+  Write the schedule inline or export it — [Inline or named export](#inline-or-named-export).
+  Every consumer still uses `flow("name", { do })`. See
+  [Consumers · Clock Jobs](/docs/elements/flow/consumers#clock-jobs).
 </Callout>
 
 ## Inline or named export
 
-| Style                                         | When                                                              |
-| --------------------------------------------- | ----------------------------------------------------------------- |
-| `on(clock.every("name", "1h"), flow({ do }))` | Self-contained — nothing else needs the Clock handle              |
-| `export const x = clock.every("name", "1h")`  | Another file (or a second `on()`) must reuse the same declaration |
+| Style                                                     | When                              |
+| --------------------------------------------------------- | --------------------------------- |
+| `on(clock.every("name", "1h"), flow("ops.ping", { do }))` | One Flow owns this schedule       |
+| `export const x = clock.every("name", "1h")`              | Several Flows share this schedule |
 
-Nameless `flow({ do })` inherits the Clock's declared name. File-tree `unit.export` and explicit
-`flow("…")` win. Two nameless Flows inheriting the same name fail **OKE1070**.
+<Callout title="Why Clock can be inline">
+  `fx.clock` is now / sleep / offsets — not an emit. Signal stays an exported const so producers can
+  `fx.emit(handle, payload)`. Export a Clock const only to share one schedule across named Flows.
+</Callout>
+
+Both styles pass a real `flow("name", { do })`. Nameless `flow({ do })` fails
+**OKE1072** — the trigger's name is never the Flow's name.
+
+<Tabs items={["Inline", "Named"]}>
+
+<Tab value="Inline">
+
+One file — declare and bind together. The scheduler fires it; no other Flow
+binds this cadence:
+
+```typescript title="src/flows/health/ping.ts"
+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);
+    },
+  }),
+);
+```
+
+</Tab>
+
+<Tab value="Named">
+
+Export the handle when a second `on()` must reuse the same schedule. Each Flow
+keeps its own explicit name — **OKE1070** if they collide:
+
+```typescript title="src/clocks/metrics.ts"
+import { clock } from "okengine";
+
+export const tickClock = clock.every("metrics.tick", "1h");
+```
+
+```typescript title="src/flows/ops/metrics.ts"
+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);
+    },
+  }),
+);
+```
+
+</Tab>
+
+</Tabs>
 
 ## Progressive Patterns
 
@@ -93,12 +161,17 @@ Same `clock` + `fx.clock` from a calendar cron to an interval, a durable pause,
 
 Five-field cron plus helpers. Prefer an app-wide zone so schedules stay short:
 
-```typescript title="src/flows/reports/daily.ts"
-import { on, flow, clock } from "okengine";
+```typescript title="src/clocks/reports.ts"
+import { clock } from "okengine";
 
 export const dailyReportClock = clock.daily("reports.daily", {
   at: "06:00",
 });
+```
+
+```typescript title="src/flows/reports/daily.ts"
+import { on, flow } from "okengine";
+import { dailyReportClock } from "@/clocks/reports";
 
 export const runDailyReport = on(
   dailyReportClock,
@@ -121,10 +194,15 @@ see [Schedules](/docs/elements/clock/schedules).
 
 Human durations — integer + unit, no weeks: `"200ms"` · `"30s"` · `"5m"` · `"1h"` · `"7d"`:
 
-```typescript title="src/flows/health/ping.ts"
-import { on, flow, clock } from "okengine";
+```typescript title="src/clocks/health.ts"
+import { clock } from "okengine";
 
 export const pingClock = clock.every("health.pingExternal", "30s");
+```
+
+```typescript title="src/flows/health/ping.ts"
+import { on, flow } from "okengine";
+import { pingClock } from "@/clocks/health";
 
 export const pingExternal = on(
   pingClock,
@@ -279,6 +357,17 @@ export default defineConfig({
   declaration in source.
 </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. Clock allows several consumers on one schedule — each needs its own name.
+</Accordion>
+
+<Accordion title="OKE1072 — Clock flow unnamed">
+  Cause: `A clock flow on "{trigger}" has no name.`
+  Fix: pass an explicit name — `on(clockDecl, flow("notes.digest", { do }))`.
+  Inline `clock.every` still needs `flow("…")` — [Inline or named export](#inline-or-named-export).
+</Accordion>
+
 </Accordions>
 
 ## Learn more
@@ -288,7 +377,7 @@ export default defineConfig({
 - [Consumers · Clock Jobs](/docs/elements/flow/consumers#clock-jobs) — bind with `on(clockDecl, flow)`
 - [Workflows](/docs/elements/flow/workflows) — `durable: true` + `fx.step` around sleeps
 - [fx](/docs/reference/fx) — full `fx.clock` table
-- [Errors](/docs/reference/errors) — `ScheduleNotOverridableError` · `ClockResourceNotFoundError`
+- [Errors](/docs/reference/errors) — `ScheduleNotOverridableError` · `ClockResourceNotFoundError` · OKE1070 · OKE1072
 
 ## Next
 

package/site/content/docs/elements/clock/schedules.mdx

@@ -25,10 +25,15 @@ For developers running daily digests, health pings, and per-tenant billing loops
 <Step>
 ### Declare a schedule and bind a Flow
 
-```typescript title="src/flows/reports/daily.ts"
-import { on, flow, clock } from "okengine";
+```typescript title="src/clocks/reports.ts"
+import { clock } from "okengine";
 
 export const dailyReportClock = clock.daily("reports.daily", { at: "06:00" });
+```
+
+```typescript title="src/flows/reports/daily.ts"
+import { on, flow } from "okengine";
+import { dailyReportClock } from "@/clocks/reports";
 
 export const runDailyReport = on(
   dailyReportClock,
@@ -112,10 +117,15 @@ chosen programmatically: `clock("x", { cron: "0 6 * * *" })`, Bun nicknames
 
 Fixed duration loops — `"200ms"` · `"30s"` · `"5m"` · `"1h"` · `"7d"`:
 
-```typescript title="src/flows/health/ping.ts"
-import { on, flow, clock } from "okengine";
+```typescript title="src/clocks/health.ts"
+import { clock } from "okengine";
 
 export const pingClock = clock.every("health.pingExternal", "30s");
+```
+
+```typescript title="src/flows/health/ping.ts"
+import { on, flow } from "okengine";
+import { pingClock } from "@/clocks/health";
 
 export const pingExternal = on(
   pingClock,
@@ -146,9 +156,14 @@ Unknown duration strings parse as `0` ms and never become due. A `"d"` is exactl
 template name is never ticked:
 
 ```typescript title="src/clocks/invoices.ts"
-import { on, flow, clock } from "okengine";
+import { clock } from "okengine";
 
 export const invoicesClock = clock.perTenant("invoices", { every: "1h" });
+```
+
+```typescript title="src/flows/billing/invoices.ts"
+import { on, flow } from "okengine";
+import { invoicesClock } from "@/clocks/invoices";
 
 export const runInvoices = on(
   invoicesClock,
@@ -275,16 +290,22 @@ do not consult the zone for tick spacing; the zone still lands on the Store row.
 
 ## Binding & Input
 
-Bind the returned handle with `on(clockDecl, flow)`. The scheduler invokes `do` with **no
-payload** — destructure `_` and read time through `fx.clock`:
+Bind with `on(clockDecl, flow("name", { do }))`. One Flow can write `clock.every`
+inside `on()` — [Clock · Inline or named export](/docs/elements/clock#inline-or-named-export).
+`do` has no payload; read time through `fx.clock`:
+
+```typescript title="src/clocks/metrics.ts"
+import { clock } from "okengine";
+
+export const cleanupClock = clock.every("metrics.cleanup", "1h");
+```
 
 ```typescript title="src/flows/metrics/cleanup.ts"
-import { on, flow, clock } from "okengine";
+import { on, flow } from "okengine";
 import { lt } from "drizzle-orm";
+import { cleanupClock } from "@/clocks/metrics";
 import { db, metricLogs } from "@/schema";
 
-export const cleanupClock = clock.every("metrics.cleanup", "1h");
-
 export const cleanup = on(
   cleanupClock,
   flow("metrics.cleanup", {
@@ -470,6 +491,12 @@ forms; on overlap days crontab fires **once** (first occurrence).
   that is not in the reconciled Store — check spelling against your `clock()` declarations.
 </Accordion>
 
+<Accordion title="OKE1072 — Clock flow unnamed">
+  Cause: `A clock flow on "{trigger}" has no name.`
+  Fix: pass an explicit name — `on(clockDecl, flow("reports.runDaily", { do }))`.
+  Inline `clock.every` still needs `flow("…")` — [Clock · Inline or named export](/docs/elements/clock#inline-or-named-export).
+</Accordion>
+
 <Accordion title="DST gap / overlap warning on the row">
   Informational. Pick a UTC cron, a non-ambiguous local hour, or accept the warning. The job still
   schedules.
@@ -485,10 +512,11 @@ forms; on overlap days crontab fires **once** (first occurrence).
 ## Learn more
 
 - [Clock overview](/docs/elements/clock) — `fx.clock` helpers and drivers
+- [Clock · Inline or named export](/docs/elements/clock#inline-or-named-export) — one Flow vs shared schedule
 - [Durable Sleep](/docs/elements/clock/sleep) — `fx.clock.sleep(label, duration)`
 - [Consumers · Clock Jobs](/docs/elements/flow/consumers#clock-jobs) — bind with `on(clockDecl, flow)`
 - [fx](/docs/reference/fx) — `fx.clock.now` / `ago` / `fromNow` / `duration`
-- [Errors](/docs/reference/errors) — `ScheduleNotOverridableError` · `ClockResourceNotFoundError`
+- [Errors](/docs/reference/errors) — `ScheduleNotOverridableError` · `ClockResourceNotFoundError` · OKE1072
 
 ## Next