okengine 0.19.3 → 0.19.5

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/cli.mdx

@@ -34,9 +34,11 @@ cd notes
 ### Run the dev loop
 
 ```bash
-oke dev
+bun run dev
 ```
 
+`bun run dev` is the portable form (`bunx oke dev` is the same). Bare `oke` needs `node_modules/.bin` on PATH — PowerShell does not add it.
+
 Compose comes up (pull / create / start progress streams into the boot status
 lines), the backend listens on **6530**, Console on **6533**, app MCP on **6535**,
 docs MCP on **6536**. Open `http://localhost:6533`. Quit with **Ctrl+C**.
@@ -177,6 +179,17 @@ oke db search-backfill notes --batch 500
 
 <Accordions>
 
+<Accordion title="oke is not recognized (Windows PowerShell)">
+  PowerShell has no local `oke` on PATH. Use `bun run dev` or `bunx oke dev`. New Cursor/VS Code
+  terminals inherit `node_modules/.bin` from `.vscode/settings.json`. Global: `bun install -g
+  okengine`.
+</Accordion>
+
+<Accordion title="OKE1020 on oke dev (Compose)">
+  The app child had no Manifest to stamp effects (`main.health`). `oke dev` now hands the parent
+  extract to the child. A failed extract appends `Manifest extract failed — …` (`oxc-parser`).
+</Accordion>
+
 <Accordion title="oke start: no entry found">
   Set `package.json` `okengine.entry` or `main`, pass `--entry`, or keep a conventional
   `src/app.ts`. Production imports that module; the app must call `createBunRuntime().serve` itself.

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/site/content/docs/understand/try-it.mdx

@@ -18,7 +18,7 @@ docker info
 ```bash
 bunx create-oke@latest my-app
 cd my-app
-oke dev
+bun run dev
 ```
 
 Open the Console at the address printed in the terminal and claim it with the code shown there. The Flows listed weren't configured anywhere — they were derived from the code you just scaffolded.

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/cli/dev-app-runner.ts

@@ -11,6 +11,9 @@
  * - `PORT` — listen port (`0` = ephemeral)
  * - `OKE_HOSTNAME` — listen hostname (default `127.0.0.1`)
  * - `OKE_READY_PATH` — when set, write bound port here once listening
+ * - `OKE_ROOT_DIR` — project root for Manifest extract (defaults to cwd)
+ * - `OKE_MANIFEST_PATH` — optional JSON Manifest from the parent `oke dev`
+ *   extract (avoids a second extract in the child; Windows-safe fallback)
  *
  * Soft reload must not clear the TTY — the parent `oke dev` board owns
  * Docker status and the first-admin claim code.
@@ -19,6 +22,7 @@
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { installGracefulShutdown, type GracefulShutdownApp } from "../kernel/graceful-shutdown.ts";
+import type { Manifest } from "../manifest/types.ts";
 import { createBunRuntime } from "../runtime/bun.ts";
 import { APP_PORT, type FetchApp } from "../runtime/types.ts";
 import { formatAppReadyLine } from "../term.ts";
@@ -28,7 +32,7 @@ export const DEV_APP_SERVE_ID = "oke-dev-app";
 
 /** App entry shape — FetchApp plus boot before serve. */
 type BootableApp = FetchApp & {
-  boot(): Promise<unknown>;
+  boot(overrides?: { readonly rootDir?: string; readonly manifest?: Manifest }): Promise<unknown>;
   stop(): Promise<void>;
   readonly bootResult?: GracefulShutdownApp["bootResult"];
 };
@@ -49,6 +53,20 @@ const readyPath = Bun.env["OKE_READY_PATH"];
 // already the project root here (Bun.spawn's `cwd` option in dev.ts).
 process.env["OKE_ROOT_DIR"] ??= process.cwd();
 
+const manifestPath = Bun.env["OKE_MANIFEST_PATH"];
+let manifest: Manifest | undefined;
+if (manifestPath !== undefined && manifestPath.length > 0) {
+  try {
+    manifest = (await Bun.file(manifestPath).json()) as Manifest;
+  } catch (err) {
+    console.error(
+      `oke dev-app-runner: OKE_MANIFEST_PATH unreadable — ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+}
+
 const absoluteEntry = resolve(entry);
 const mod = (await import(pathToFileURL(absoluteEntry).href)) as {
   app?: BootableApp;
@@ -63,7 +81,10 @@ if (
   process.exit(1);
 }
 
-await mod.app.boot();
+await mod.app.boot({
+  rootDir: process.env["OKE_ROOT_DIR"],
+  ...(manifest !== undefined ? { manifest } : {}),
+});
 const handle = createBunRuntime().serve(mod.app, {
   port,
   hostname,

package/src/cli/dev.test.ts

@@ -1070,8 +1070,55 @@ export const posts = store.schema.table("posts", {
 });
 
 describe("oke dev Console vault config", () => {
+  let session: DevSession | undefined;
+
+  afterEach(() => {
+    session?.stop();
+    session = undefined;
+  });
+
   test("hands loaded oke.config to Console so drivers.vault is not the env default", async () => {
     const src = await Bun.file(new URL("./dev.ts", import.meta.url)).text();
     expect(src).toMatch(/okeConfig:\s*loadedConfig/);
   });
+
+  test("writes OKE_MANIFEST_PATH for the app child when a Manifest is available", async () => {
+    const runner = await Bun.file(new URL("./dev-app-runner.ts", import.meta.url)).text();
+    expect(runner).toContain("OKE_MANIFEST_PATH");
+    expect(runner).toMatch(/mod\.app\.boot\(\{/);
+
+    const dir = await mkdtemp(join(tmpdir(), "oke-dev-manifest-handoff-"));
+    await Bun.write(join(dir, "src/app.ts"), "export {}\n");
+    await Bun.write(join(dir, "oke.manifest.json"), JSON.stringify(LIVE_MANIFEST));
+    let seen: Record<string, string> | undefined;
+    const result = await runDev({
+      stdinIsTTY: false,
+      cwd: dir,
+      silentClaim: true,
+      keepAlive: false,
+      appPort: 0,
+      consolePort: 0,
+      mcpPort: 0,
+      docsMcpPort: 0,
+      ...stubCompose(),
+      startApp: async (_entry, env) => {
+        seen = env;
+        return { stop() {} };
+      },
+      regenClient: async () => {},
+      write: () => {},
+      serveConsole: async () => ({ stop() {} }),
+      serveMcp: async () => ({ stop() {} }),
+      serveDocsMcp: async () => ({
+        stop() {},
+        port: 1,
+        url: new URL("http://127.0.0.1:1"),
+      }),
+    });
+    session = result.session;
+    expect(result.code).toBe(0);
+    expect(seen?.["OKE_MANIFEST_PATH"]).toBeTruthy();
+    const dumped = JSON.parse(await Bun.file(seen!["OKE_MANIFEST_PATH"]!).text()) as Manifest;
+    expect(dumped.app).toBe("dev-live");
+  });
 });

package/src/cli/dev.ts

@@ -1067,6 +1067,13 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
   const seedManifest =
     options.manifest !== undefined ? options.manifest : await tryLoadProjectManifest(cwd);
 
+  let seedManifestPath: string | undefined;
+  if (seedManifest) {
+    seedManifestPath = join(tmpdir(), `oke-dev-manifest-${crypto.randomUUID()}.json`);
+    await Bun.write(seedManifestPath, `${JSON.stringify(seedManifest)}\n`);
+    env.OKE_MANIFEST_PATH = seedManifestPath;
+  }
+
   async function refreshManifestInto(state: ConsoleState | null): Promise<void> {
     if (!state) return;
     try {
@@ -1401,6 +1408,10 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     consoleVite = null;
     void vite?.stop();
     void clearDevSessionLock(cwd);
+    if (seedManifestPath) {
+      void unlink(seedManifestPath).catch(() => {});
+      seedManifestPath = undefined;
+    }
     if (dockerStarted) {
       const started = dockerStarted;
       dockerStarted = null;

package/src/compiler/extract-skip.test.ts

@@ -0,0 +1,43 @@
+/**
+ * Manifest extract must not walk `node_modules` — Windows glob paths use `\`
+ * and a naive `includes("node_modules/")` miss lets framework fixtures throw
+ * during extract, which Docker-first `oke dev` surfaces as **OKE1020**.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { extractManifest } from "./extract.ts";
+
+describe("extractManifest — skip dependency trees", () => {
+  test("does not parse node_modules even when a poison file would fail extract", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-extract-skip-"));
+    try {
+      await mkdir(join(dir, "src/flows/main"), { recursive: true });
+      await writeFile(
+        join(dir, "src/flows/main/health.ts"),
+        `
+import { on, flow, http } from "okengine/http";
+export const health = on(
+  http.get("/health").public(),
+  flow({ do: () => ({ ok: true as const }) }),
+);
+`,
+      );
+      await mkdir(join(dir, "node_modules/okengine"), { recursive: true });
+      // Nameless Signal consumer — **OKE1072** if this file is scanned.
+      await writeFile(
+        join(dir, "node_modules/okengine/poison.ts"),
+        `
+import { on, flow, signal } from "okengine";
+export const inbound = on(signal.once("x"), flow({ do: () => ({}) }));
+`,
+      );
+      const manifest = await extractManifest({ rootDir: dir });
+      expect(manifest.flows?.["main.health"]).toBeDefined();
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});