okengine 0.10.1 → 0.10.2

package/README.md

@@ -74,7 +74,7 @@ import { z } from "zod";
 
 export const health = on(
   http.get("/health").gate(gate.public),
-  flow({
+  flow("health.check", {
     out: z.object({ ok: z.literal(true) }),
     do: () => ({ ok: true as const }),
   }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {

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

@@ -26,7 +26,7 @@ import { on, flow, every } from "okengine";
 
 export const purgeOld = on(
   every("1h"),
-  flow({
+  flow("links.purgeOld", {
     do: async (_, fx) => {
       const cutoff = fx.clock.now() - 30 * 24 * 60 * 60 * 1000; // 30 days
       await fx.store(db).delete(links).where(lt(links.createdAt, cutoff));
@@ -55,7 +55,7 @@ export const dailyReport = clock("daily-report", {
 ```typescript title="src/flows/reports/daily.ts"
 export const sendDaily = on(
   dailyReport,
-  flow({
+  flow("reports.sendDaily", {
     do: async (_, fx) => {
       /* … */
     },

package/site/content/docs/elements/flow.mdx

@@ -28,7 +28,7 @@ import { z } from "zod";
 
 export const createOrder = on(
   http.post("/orders"),
-  flow({
+  flow("orders.create", {
     in: z.object({ sku: z.string(), qty: z.number().int().min(1) }),
     out: z.object({ id: z.string() }),
     errors: { OutOfStock: z.object({ left: z.number() }) },
@@ -106,7 +106,7 @@ Built-in codes attach a localized `message` ([Errors](/docs/reference/errors));
 ```typescript
 export const findOrder = on(
   http.get("/orders/:id").gate(member), // gates evaluate before do runs
-  flow({
+  flow("orders.find", {
     in: z.object({ id: z.string() }),
     out: Order,
     errors: { NotFound: z.object({}) },
@@ -124,7 +124,7 @@ await fx.emit(orderPlaced, { orderId: id }); // inside the producing flow
 
 on(
   orderPlaced,
-  flow({
+  flow("orders.sendReceipt", {
     do: async ({ orderId }, fx) => {
       /* … */
     },
@@ -139,7 +139,7 @@ on(
 ```typescript
 on(
   every("1h"),
-  flow({
+  flow("sessions.sweepExpired", {
     do: async (_, fx) => {
       const cutoff = fx.clock.now() - 30 * 24 * 60 * 60 * 1000;
       await fx.store(db).delete(sessions).where(lt(sessions.createdAt, cutoff));
@@ -155,7 +155,7 @@ CDC is built in; the flow receives `{ before, after }`:
 ```typescript
 on(
   db.table(orders).changed("status"),
-  flow({
+  flow("orders.reverify", {
     do: ({ before, after }, fx) => fx.log.info("status", { from: before.status, to: after.status }),
   }),
 );
@@ -166,7 +166,7 @@ on(
 Drop `on()` and it is still a real Flow — contracts, Manifest entry, everything. Other flows call it through `fx.call`:
 
 ```typescript
-export const getOrder = flow({
+export const getOrder = flow("orders.get", {
   in: OrderRef,
   out: Order,
   do: async ({ id }, fx) => {
@@ -211,7 +211,7 @@ Everything a flow may touch, on one object:
 Set `durable: true` and every `fx` call is journaled. Wrap side effects in `fx.step` and they never re-run on replay:
 
 ```typescript
-export const chargeOrder = flow({
+export const chargeOrder = flow("payments.chargeOrder", {
   durable: true, // every fx call below is journaled
   in: OrderRef,
   out: z.boolean(),
@@ -233,14 +233,14 @@ export const chargeOrder = flow({
 
 Replay is **at-least-once** for a step whose body never persisted (crash mid-step, lease overrun): that step re-runs on reclaim, so keep step bodies short or internally idempotent. A client transport retry starts a _new_ run with a fresh `runId` — request-level idempotency is an application concern, not the journal's.
 
-For flaky sub-steps, wrap the work in `fx.retry` **inside** `fx.step` so a completed charge is never retried on resume. Coarse whole-body retry is also available as `flow({ retry: { retries, delay, backoff, jitter } })` and reuses the same journal session.
+For flaky sub-steps, wrap the work in `fx.retry` **inside** `fx.step` so a completed charge is never retried on resume. Coarse whole-body retry is also available as `flow(name, { retry: { retries, delay, backoff, jitter } })` and reuses the same journal session.
 
 After a **terminal** failure (`fx.fail` or exhausted retries / uncaught throw), optional
 `compensate` runs under the same journal. Undo work must use **new** step names
 (`undo:…`) — never rewind forward steps:
 
 ```typescript
-export const chargeOrder = flow({
+export const chargeOrder = flow("payments.chargeOrder", {
   durable: true,
   in: OrderRef,
   out: z.boolean(),
@@ -295,7 +295,7 @@ Use `fx.all` (or `fx.race`) with thunks. The first rejection aborts siblings thr
 </Accordion>
 <Accordion title="Durable flow retried a completed charge">
 
-Put `fx.retry` **inside** `fx.step`, not around it. Completed steps replay from the journal and never re-run. `flow({ retry })` is for coarse whole-body retries on the same session.
+Put `fx.retry` **inside** `fx.step`, not around it. Completed steps replay from the journal and never re-run. `flow(name, { retry })` is for coarse whole-body retries on the same session.
 
 </Accordion>
 <Accordion title="When does compensate run?">

package/site/content/docs/elements/gate.mdx

@@ -66,7 +66,7 @@ import { member, canBook, fair } from "../../gates";
 
 export const health = on(
   http.get("/health").gate(gate.public),
-  flow({
+  flow("health.check", {
     out: HealthOut,
     do: () => ({ ok: true as const }),
   }),
@@ -74,7 +74,7 @@ export const health = on(
 
 export const shorten = on(
   http.post("/links").gate(member, canBook, fair),
-  flow({
+  flow("links.shorten", {
     in: NewLink,
     out: LinkCode,
     errors: { Taken },
@@ -174,8 +174,8 @@ Every HTTP trigger must carry a gate or `gate.public`. Omitting both fails boot
 `GateBootError` — message starts with `gate boot failed —` and lists every gap.
 
 ```typescript
-on(http.get("/health").gate(gate.public), flow({/* … */}));
-on(http.post("/bookings").gate(member, canBook), flow({/* … */}));
+on(http.get("/health").gate(gate.public), flow("health.check", {/* … */}));
+on(http.post("/bookings").gate(member, canBook), flow("bookings.create", {/* … */}));
 ```
 
 **Consequence:** first `fetch` / `execute` auto-boots (`autoBoot` defaults to `true`).

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

@@ -58,7 +58,7 @@ A signal is a trigger like any other — the consumer is an ordinary Flow:
 ```typescript title="src/flows/orders/send-confirmation.ts"
 export const sendConfirmation = on(
   orderPlaced,
-  flow({
+  flow("orders.sendConfirmation", {
     in: z.object({ orderId: z.string(), total: z.number() }),
     do: async (input, fx) => {
       await fx.send(orderConfirmed, { to: "user-1", data: input });
@@ -131,8 +131,7 @@ export const orderStatus = signal("order-status", {
 ```typescript title="src/flows/fulfillment/on-order.ts"
 on(
   orderPlaced,
-  flow({
-    name: "fulfillment.onOrder",
+  flow("fulfillment.onOrder", {
     do: async ({ orderId }, fx) => {
       await fx.emit(orderChanged, { orderId, kind: "placed" });
       await fx.emit(orderStatus, { orderId, status: "fulfilling" });
@@ -147,8 +146,7 @@ on(
 ```typescript title="src/flows/orders/side-effects.ts"
 on(
   orderChanged,
-  flow({
-    name: "cache.onOrderChanged",
+  flow("cache.onOrderChanged", {
     do: async ({ orderId }, fx) => {
       /* invalidate order:{orderId} */
     },
@@ -157,8 +155,7 @@ on(
 
 on(
   orderChanged,
-  flow({
-    name: "notify.onOrderChanged",
+  flow("notify.onOrderChanged", {
     do: async ({ orderId }, fx) => {
       await fx.send(orderConfirmed, { to: "user-1", data: { orderId } });
     },

package/site/content/docs/elements/store.mdx

@@ -80,7 +80,7 @@ All data access goes through `fx.store(db)` — a typed session, one table at a
 ```typescript title="src/flows/notes/create.ts"
 export const createNote = on(
   http.post("/notes"),
-  flow({
+  flow("notes.create", {
     in: z.object({ title: z.string(), body: z.string() }),
     out: z.object({ id: z.string() }),
     do: async (input, fx) => {

package/site/content/docs/elements/vault.mdx

@@ -62,7 +62,7 @@ Call `.reveal()` once at the boundary that needs the real credential:
 ```typescript title="src/flows/billing/charge.ts"
 export const charge = on(
   http.post("/charge"),
-  flow({
+  flow("billing.charge", {
     in: ChargeInput,
     out: z.object({ id: z.string() }),
     do: async (input, fx) => {

package/site/content/docs/get-started/basic-usage.mdx

@@ -44,9 +44,7 @@ import { z } from "zod";
 
 export const health = on(
   http.get("/health").gate(gate.public),
-  flow({
-    name: "main.health",
-    unit: "main",
+  flow("main.health", {
     out: z.object({ ok: z.literal(true) }),
     do: () => ({ ok: true as const }),
   }),

package/site/content/docs/get-started/introduction.mdx

@@ -29,7 +29,7 @@ import { z } from "zod";
 
 export const health = on(
   http.get("/health"),
-  flow({
+  flow("health.check", {
     out: z.object({ ok: z.literal(true) }),
     do: () => ({ ok: true as const }),
   }),

package/site/content/docs/reference/cli.md

@@ -67,18 +67,18 @@ so ● updates live if you stop a container; AI ● tracks model phase while the
 AI container is up. Boot does not wait for the model to become ready.
 
 On a TTY with `-d`, keyboard controls stay active under Logs. Status ● for
-compose/AI live on the board **above** Logs (not as log lines). Press `c` to
-clear the log pane and reprint the latest board. `l` / `?` also refresh first
-so the services/help panel is not mixed into request logs.
-
-| Key                          | Action                              |
-| ---------------------------- | ----------------------------------- |
-| `?`                          | help                                |
-| `c`                          | refresh — clear logs, show latest ● |
-| `q`                          | quit `oke dev`                      |
-| `l`                          | list docker services                |
-| `u` / `x`                    | compose up / stop (whole stack)     |
-| `1`–`9` then `u` / `x` / `r` | start / stop / restart one service  |
+compose/AI live on the board **above** Logs (not as log lines) — it already
+lists every service, so refresh is enough to see the stack; there is no
+separate services panel. Press `r` to clear the log pane and reprint the
+latest board. `?` also refreshes first so the help panel is not mixed into
+request logs.
+
+| Key       | Action                              |
+| --------- | ----------------------------------- |
+| `?`       | help                                |
+| `r`       | refresh — clear logs, show latest ● |
+| `q`       | quit `oke dev`                      |
+| `u` / `x` | compose up / stop (whole stack)     |
 
 Compose stays quiet unless it fails. Process-local boot notices print once under
 the hero (not once per process).

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

@@ -7,7 +7,7 @@ icon: "Braces"
 `fx` is the second argument of every `do` — the single door to the world. This page is the whole surface; each entry notes the **effect it records**, which is what feeds the Manifest, caching, and capability checks.
 
 ```typescript
-flow({
+flow("orders.example", {
   do: async (input, fx) => {
     // everything below, on this one object
   },
@@ -51,8 +51,7 @@ Declare `effects: { reads: ["runs"] }`. Powers native SLO checkers (Clock + Chan
 ```typescript
 on(
   every("5m"),
-  flow({
-    name: "ops.slo-check",
+  flow("ops.slo-check", {
     effects: { reads: ["runs"], sends: ["slo-alert"] },
     do: async (_, fx) => {
       const breaches = await fx.runs.checkSlo(
@@ -133,7 +132,7 @@ const rows = await fx.using(
 );
 ```
 
-**Consequence:** put `fx.retry` inside `fx.step` on durable flows so a completed charge never re-runs on resume. Coarse whole-body retry is `flow({ retry: { … } })` on the same journal session.
+**Consequence:** put `fx.retry` inside `fx.step` on durable flows so a completed charge never re-runs on resume. Coarse whole-body retry is `flow(name, { retry: { … } })` on the same journal session.
 
 ## Channel
 

package/src/auth/auth.test.ts

@@ -177,8 +177,7 @@ describe("cross-plane compile error", () => {
         path: "src/flows/console/store.ts",
         flow: "console.store.query",
         source: `
-          export const query = flow({
-            name: "console.store.query",
+          export const query = flow("console.store.query", {
             plane: "operator",
             do: (_i, fx) => fx.auth.userId,
           });

package/src/auth/bindings.ts

@@ -205,9 +205,7 @@ export function createAuthHttpBindings(
 
   const base = config.basePath;
 
-  const refresh = flow({
-    name: "auth.refresh",
-    unit: "auth",
+  const refresh = flow("auth.refresh", {
     plane: "user",
     in: RefreshIn,
     out: SessionTokensOut,
@@ -231,9 +229,7 @@ export function createAuthHttpBindings(
     },
   });
 
-  const revoke = flow({
-    name: "auth.revoke",
-    unit: "auth",
+  const revoke = flow("auth.revoke", {
     plane: "user",
     in: RevokeIn,
     out: z.object({ ok: z.literal(true) }),
@@ -252,9 +248,7 @@ export function createAuthHttpBindings(
     },
   });
 
-  const me = flow({
-    name: "auth.me",
-    unit: "auth",
+  const me = flow("auth.me", {
     plane: "user",
     out: MeOut,
     errors: { AuthFailed },
@@ -289,9 +283,7 @@ export function createAuthHttpBindings(
   ];
 
   if (config.emailAndPassword.enabled) {
-    const signInEmail = flow({
-      name: "auth.signInEmail",
-      unit: "auth",
+    const signInEmail = flow("auth.signInEmail", {
       plane: "user",
       in: EmailPasswordIn,
       out: SessionTokensOut,
@@ -319,9 +311,7 @@ export function createAuthHttpBindings(
       },
     });
 
-    const signUpEmail = flow({
-      name: "auth.signUpEmail",
-      unit: "auth",
+    const signUpEmail = flow("auth.signUpEmail", {
       plane: "user",
       in: EmailPasswordIn,
       out: SessionTokensOut,

package/src/auth/gate-auth.test.ts

@@ -136,7 +136,7 @@ describe("gate.auth — autoBoot / posture", () => {
   });
 
   test(".needs(auth) satisfied by gate.auth without .plug(auth())", async () => {
-    on(http.get("/x").gate(AUTH_SESSION_GATE), flow({ name: "x", do: () => ({ ok: true }) }));
+    on(http.get("/x").gate(AUTH_SESSION_GATE), flow("x", { do: () => ({ ok: true }) }));
     const dependent = plugin("needs-auth", { version: "0.0.1" }).needs("auth");
     const app = oke({
       name: "needs-gate-auth",
@@ -309,7 +309,7 @@ describe("gate.auth — email Flows + security", () => {
   });
 
   test("missing gate on custom HTTP still GateBootError", async () => {
-    on(http.get("/open"), flow({ name: "open", do: () => ({ ok: true }) }));
+    on(http.get("/open"), flow("open", { do: () => ({ ok: true }) }));
     const app = oke({
       name: "gap",
       env: "local",

package/src/cli/ai-setup/apply.ts

@@ -5,6 +5,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { OLLAMA_IMAGE } from "../../docker/recipes/index.ts";
+import { DEFAULT_DOCKER_DIR } from "../../docker/types.ts";
 
 /** Choices applied to the project. */
 export type AiSetupApplyInput = {
@@ -91,6 +92,18 @@ export function applyAiSetup(
   }
   writeFileSync(envPath, env.endsWith("\n") ? env : `${env}\n`, "utf8");
 
+  // `docker/.env.docker` is regenerated from `.env.local` only on its first
+  // boot (existing values there are treated as durable, possibly hand-edited
+  // pins — see stack-id.ts). Once it exists, a later `oke ai setup` run must
+  // update it directly, or the docker profile keeps the old model forever.
+  if (input.chatModel) {
+    const dockerEnvPath = join(cwd, DEFAULT_DOCKER_DIR, ".env.docker");
+    if (existsSync(dockerEnvPath)) {
+      const dockerEnv = readFileSync(dockerEnvPath, "utf8");
+      writeFileSync(dockerEnvPath, upsertEnv(dockerEnv, "OKE_AI_MODEL", input.chatModel), "utf8");
+    }
+  }
+
   const aiTsPath = join(cwd, "src", "core", "ai.ts");
   mkdirSync(dirname(aiTsPath), { recursive: true });
   writeFileSync(aiTsPath, renderAiTs(input), "utf8");

package/src/cli/build.test.ts

@@ -0,0 +1,67 @@
+/**
+ * `oke build` regenerates `src/flows/generated.ts` before bundling — real
+ * before/after proof, not an assumption about the wiring.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runBuild } from "./build.ts";
+
+async function makeUnit(root: string, name: string): Promise<void> {
+  const dir = join(root, "src/flows", name);
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, "index.ts"), "export const nothing = 1;\n");
+}
+
+describe("oke build — .adopt() barrel regeneration", () => {
+  test("real before/after: no generated.ts before build, real barrel content after", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oke-build-adopt-"));
+    try {
+      await makeUnit(root, "main");
+      await makeUnit(root, "notes");
+
+      const generatedPath = join(root, "src/flows/generated.ts");
+      await expect(readFile(generatedPath, "utf8")).rejects.toThrow();
+
+      const code = await runBuild({
+        rootDir: root,
+        bundle: async () => ({ success: true, logs: "" }),
+      });
+      expect(code).toBe(0);
+
+      const after = await readFile(generatedPath, "utf8");
+      expect(after).toContain('export * as main from "./main/index.ts";');
+      expect(after).toContain('export * as notes from "./notes/index.ts";');
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("regeneration runs before bundling, using the injected syncAdoptBarrel", async () => {
+    const calls: string[] = [];
+    const code = await runBuild({
+      rootDir: "/fake/root",
+      syncAdoptBarrel: async (rootDir) => {
+        calls.push(`sync:${rootDir}`);
+        return ["main", "notes"];
+      },
+      bundle: async () => {
+        calls.push("bundle");
+        return { success: true, logs: "" };
+      },
+    });
+    expect(code).toBe(0);
+    expect(calls).toEqual(["sync:/fake/root", "bundle"]);
+  });
+
+  test("bundle failure still returns non-zero after a successful sync", async () => {
+    const code = await runBuild({
+      rootDir: "/fake/root",
+      syncAdoptBarrel: async () => [],
+      bundle: async () => ({ success: false, logs: "boom" }),
+    });
+    expect(code).toBe(1);
+  });
+});

package/src/cli/build.ts

@@ -2,18 +2,46 @@
  * `oke build --target edge` — tree-shaken kernel profile.
  */
 
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
 /** Options for {@link runBuild}. */
 export interface BuildOptions {
   readonly target?: "bun" | "node" | "edge";
   readonly entry?: string;
   readonly outdir?: string;
   readonly write?: (text: string) => void;
+  /** Project root for the `.adopt()` barrel sync (default `process.cwd()`). */
+  readonly rootDir?: string;
   /** Inject bun.build (tests). */
   readonly bundle?: (opts: {
     entry: string;
     outdir: string;
     target: "bun" | "node" | "browser";
   }) => Promise<{ success: boolean; logs: string }>;
+  /**
+   * Inject `.adopt()` barrel regeneration (tests). Default: real
+   * `generateAdoptBarrel` + write to `<rootDir>/src/flows/generated.ts`.
+   * Returns the unit names written, for the status line.
+   */
+  readonly syncAdoptBarrel?: (rootDir: string) => Promise<readonly string[]>;
+}
+
+/**
+ * Regenerate `src/flows/generated.ts` from every `src/flows/<unit>/index.ts`
+ * unit folder — pre-step for `oke build` (mirrors `oke db`'s `schema.generated.ts`
+ * pre-step). A real file on disk, not a virtual module: identical resolution
+ * under `oke dev`'s runtime `import()` and `oke build`'s `Bun.build()`
+ * (investigated — a virtual-module Bun plugin does not resolve consistently
+ * across those two paths).
+ *
+ * @param rootDir - Project root
+ */
+async function defaultSyncAdoptBarrel(rootDir: string): Promise<readonly string[]> {
+  const { generateAdoptBarrel } = await import("../compiler/generate-adopt.ts");
+  const { source, units } = await generateAdoptBarrel({ rootDir });
+  await writeFile(join(rootDir, "src/flows/generated.ts"), source);
+  return units;
 }
 
 /**
@@ -26,6 +54,7 @@ export async function runBuild(options: BuildOptions = {}): Promise<number> {
   const target = options.target ?? "bun";
   const entry = options.entry ?? "src/app.ts";
   const outdir = options.outdir ?? "dist";
+  const rootDir = options.rootDir ?? process.cwd();
   const bunTarget = target === "edge" ? "browser" : target === "node" ? "node" : "bun";
 
   const bundle =
@@ -43,8 +72,13 @@ export async function runBuild(options: BuildOptions = {}): Promise<number> {
         logs: result.logs.map((l) => String(l)).join("\n"),
       };
     });
+  const syncAdoptBarrel = options.syncAdoptBarrel ?? defaultSyncAdoptBarrel;
 
   try {
+    const units = await syncAdoptBarrel(rootDir);
+    write(
+      `oke build: .adopt() barrel → src/flows/generated.ts (${units.length} unit${units.length === 1 ? "" : "s"})\n`,
+    );
     const result = await bundle({ entry, outdir, target: bunTarget });
     if (!result.success) {
       console.error(result.logs || "oke build: failed");

package/src/cli/db-seed.ts

@@ -233,7 +233,7 @@ export async function bootSeedFx(
   if (!app) {
     throw new Error(`oke db seed: no oke() app export in ${entryAbs}`);
   }
-  await app.boot({ env, startScheduler: false, config: config ?? undefined });
+  await app.boot({ env, startScheduler: false, config: config ?? undefined, rootDir: cwd });
   const storeRuntime = app.elements?.store ?? app.bootResult?.store;
   if (!storeRuntime) {
     throw new Error(