okengine 0.10.1 → 0.10.3

package/src/cli/dev.test.ts

@@ -7,9 +7,14 @@
  */
 
 import { afterEach, describe, expect, test } from "bun:test";
-import { mkdtemp } from "node:fs/promises";
+import { mkdir, mkdtemp, readdir } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
+import {
+  ADOPT_BARREL_FILE,
+  generateAdoptBarrel,
+  writeAdoptBarrel,
+} from "../compiler/generate-adopt.ts";
 import type { Manifest } from "../manifest/types.ts";
 import type { WideEvent } from "../runs/types.ts";
 import { isDataEnvelope, MCP_DATA_KIND } from "../mcp/data.ts";
@@ -398,13 +403,11 @@ async function writePingApp(dir: string, version: string): Promise<void> {
     join(dir, "src/flows/ping.ts"),
     `import { on, flow, http, gate } from ${JSON.stringify(OKE_INDEX)};
 
-export const ping = on(http.get("/ping").gate(gate.public), flow({
-  name: "ping",
+export const ping = on(http.get("/ping").gate(gate.public), flow("ping", {
   do: () => ({ version: ${JSON.stringify(version)} as const }),
 }));
 
-export const slow = on(http.get("/slow").gate(gate.public), flow({
-  name: "slow",
+export const slow = on(http.get("/slow").gate(gate.public), flow("slow", {
   do: async () => {
     const started = ${JSON.stringify(version)};
     await Bun.sleep(800);
@@ -546,6 +549,88 @@ describe("oke dev hot reload", () => {
   }, 60_000);
 });
 
+describe("oke dev syncAdoptBarrel atomic write", () => {
+  test("default path regenerates generated.ts and leaves no .tmp behind", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-dev-adopt-atomic-"));
+    await mkdir(join(dir, "src/flows/notes"), { recursive: true });
+    await Bun.write(join(dir, "src/flows/notes/index.ts"), "export {};\n");
+    await Bun.write(join(dir, "src/app.ts"), "export {};\n");
+    await Bun.write(join(dir, "src/flows", ADOPT_BARREL_FILE), "// stale stub\n");
+
+    const { code } = await runDev({
+      cwd: dir,
+      dryRun: true,
+      stdinIsTTY: false,
+      write: () => {},
+    });
+    expect(code).toBe(0);
+
+    const barrelPath = join(dir, "src/flows", ADOPT_BARREL_FILE);
+    const text = await Bun.file(barrelPath).text();
+    expect(text).toContain('export * as notes from "./notes/index.ts";');
+    expect(text).not.toContain("stale stub");
+    expect(await Bun.file(`${barrelPath}.tmp`).exists()).toBe(false);
+    const leftovers = (await readdir(join(dir, "src/flows"))).filter((f) => f.includes(".tmp"));
+    expect(leftovers).toEqual([]);
+  });
+
+  test("writeAdoptBarrel uses temp then rename — concurrent readers never see a torn file", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-dev-adopt-race-"));
+    const flowsDir = join(dir, "src/flows");
+    await mkdir(flowsDir, { recursive: true });
+    const target = join(flowsDir, ADOPT_BARREL_FILE);
+
+    // Two complete, same-length payloads so a mid-write truncate would yield
+    // mixed or short content that fails both equality checks.
+    const markerA = "A";
+    const markerB = "B";
+    const body = (marker: string) => `// ${marker}\n` + `${marker.repeat(64)}\n`.repeat(2_000);
+    const payloadA = body(markerA);
+    const payloadB = body(markerB);
+    expect(payloadA.length).toBe(payloadB.length);
+    expect(payloadA).not.toBe(payloadB);
+
+    await writeAdoptBarrel(dir, payloadA);
+    expect(await Bun.file(target).text()).toBe(payloadA);
+
+    const reads: string[] = [];
+    let stop = false;
+    const reader = (async () => {
+      while (!stop) {
+        try {
+          reads.push(await Bun.file(target).text());
+        } catch {
+          // Target briefly missing only if rename races a delete — ignore.
+        }
+        // Yield so writers interleave; Bun.sleep(0) is enough on this loop.
+        await Bun.sleep(0);
+      }
+    })();
+
+    for (let i = 0; i < 80; i++) {
+      await writeAdoptBarrel(dir, i % 2 === 0 ? payloadB : payloadA);
+    }
+    stop = true;
+    await reader;
+
+    expect(reads.length).toBeGreaterThan(10);
+    for (const sample of reads) {
+      // Every observation is a complete prior or complete next payload —
+      // never a truncated prefix, never a mix of A/B markers.
+      const ok = sample === payloadA || sample === payloadB;
+      expect(ok).toBe(true);
+      expect(sample.length).toBe(payloadA.length);
+      expect(sample.includes(markerA) && sample.includes(markerB)).toBe(false);
+    }
+    expect(await Bun.file(`${target}.tmp`).exists()).toBe(false);
+
+    // Same helper the default `oke dev` path uses end-to-end.
+    const { source } = await generateAdoptBarrel({ rootDir: dir });
+    await writeAdoptBarrel(dir, source);
+    expect(await Bun.file(target).text()).toBe(source);
+  });
+});
+
 describe("oke dev mode resolution", () => {
   test("non-TTY + unset mode → local, zero ask, zero docker, no save", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-dev-mode-nontty-"));

package/src/cli/dev.ts

@@ -47,7 +47,6 @@ import { clientAdd } from "./client-add.ts";
 import { resolveDriverId } from "../config/index.ts";
 import { askDevMode, type AskDevModeFn } from "./ask-dev-mode.ts";
 import {
-  controlServicesFromStack,
   formatDevControlsHint,
   startDevControls,
   type DevComposeControlAction,
@@ -177,6 +176,19 @@ export interface DevOptions {
    * @param filename - Relative path from the watcher
    */
   readonly onDbAutoPush?: (filename: string) => void;
+  /**
+   * Injectable `.adopt()` barrel regeneration (tests). Default: real
+   * `generateAdoptBarrel` + atomic write to `<cwd>/src/flows/generated.ts`
+   * (`generated.ts.tmp` → rename). Runs once per `oke dev` session, before
+   * the entry is resolved/imported — a real file on disk, so `oke dev`'s
+   * runtime `import()` and `oke build`'s `Bun.build()` resolve it
+   * identically (unlike a virtual-module Bun plugin, which does not — see
+   * `compiler/generate-adopt.ts`). Atomic so a concurrent import during
+   * `bun --hot` never sees a torn mid-write file.
+   *
+   * @param cwd - Project root
+   */
+  readonly syncAdoptBarrel?: (cwd: string) => Promise<readonly string[]>;
   /** Watch project source changes (injectable for tests). */
   readonly watchFs?: DevWatchFn;
   readonly images?: Readonly<Record<string, string>>;
@@ -334,6 +346,28 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     console.warn = previousWarn;
   };
   const cwd = options.cwd ?? process.cwd();
+
+  // One-shot `.adopt()` barrel regen for the session — real file on disk
+  // (`src/flows/generated.ts`), written atomically (tmp → rename) before the
+  // entry is resolved/imported below so a freshly-added flows unit is
+  // adoptable without a hand edit. Best-effort like `syncDevSchema` below:
+  // a project with no `src/flows` yet (or a synthetic test tree) never
+  // blocks the dev session.
+  const syncAdoptBarrel =
+    options.syncAdoptBarrel ??
+    (async (root: string) => {
+      const { generateAdoptBarrel, writeAdoptBarrel } =
+        await import("../compiler/generate-adopt.ts");
+      const { source, units } = await generateAdoptBarrel({ rootDir: root });
+      await writeAdoptBarrel(root, source);
+      return units;
+    });
+  try {
+    await syncAdoptBarrel(cwd);
+  } catch {
+    /* best-effort — boot-time assertAdoptBarrelFresh (rootDir opt-in) is the real gate */
+  }
+
   const preferredApp = options.appPort ?? Number(Bun.env.PORT ?? APP_PORT);
   const preferredConsole = options.consolePort ?? CONSOLE_PORT;
   const preferredMcp = options.mcpPort ?? MCP_PORT;
@@ -1388,29 +1422,18 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
         process.exit(0);
       },
       onRefresh: () => refreshChrome(),
-      // Refresh first so help/services never sit in the middle of request logs.
+      // Refresh first so help never sits in the middle of request logs.
       onShowPanel: async (body) => {
         await refreshChrome();
         write(body);
       },
       onComposeSettled: () => syncComposeBoard(),
-      services: () => controlServicesFromStack(pendingStackSummary?.services ?? []),
-      statusOf: (serviceName) => liveComposeHealth.get(serviceName),
-      composeAction: async (action: DevComposeControlAction, serviceNames) => {
+      composeAction: async (action: DevComposeControlAction) => {
         const files = started.files;
         const finalArgs =
-          action === "up" && serviceNames.length === 0
+          action === "up"
             ? ["compose", ...files.flatMap((f) => ["-f", f]), "up", "-d"]
-            : action === "up"
-              ? [
-                  "compose",
-                  ...files.flatMap((f) => ["-f", f]),
-                  "up",
-                  "-d",
-                  "--no-deps",
-                  ...serviceNames,
-                ]
-              : ["compose", ...files.flatMap((f) => ["-f", f]), action, ...serviceNames];
+            : ["compose", ...files.flatMap((f) => ["-f", f]), action];
         const proc = Bun.spawn(["docker", ...finalArgs], {
           cwd: started.cwd,
           stdout: "pipe",

package/src/cli/doctor.ts

@@ -3,17 +3,70 @@
  */
 
 import { resolve } from "node:path";
+import type { ConfigEnv, DriverRef, DriversConfig, EnvDriverMap } from "../config/index.ts";
+import { resolveEffectiveDrivers, type EffectiveDriversConfig } from "../config/driver-defaults.ts";
 import type { Manifest } from "../manifest/types.ts";
 import { APP_PORT, CONSOLE_PORT, MCP_PORT } from "../runtime/types.ts";
 import { hasFlag, wantsJson } from "./args.ts";
 import { checkManifestPiiAsks } from "./doctor-pii.ts";
 import { EXIT_OK, EXIT_RUNTIME } from "./exit.ts";
-import { loadManifest } from "./load-config.ts";
+import { loadManifest, loadOkeConfig } from "./load-config.ts";
 import { isPortInUse } from "./ports.ts";
 import { schemaFingerprint, readSchemaFingerprint } from "./schema.ts";
 
 export { isPortInUse } from "./ports.ts";
 
+/**
+ * `label → merged EnvDriverMap` pairs, in the fixed order shown by
+ * {@link formatDriversSummary} / the `drivers` JSON key.
+ *
+ * @param drivers - Fully-resolved drivers config
+ */
+function flattenEffectiveDrivers(
+  drivers: EffectiveDriversConfig,
+): ReadonlyArray<readonly [string, EnvDriverMap]> {
+  return [
+    ["store.sql", drivers.store.sql],
+    ["store.kv", drivers.store.kv],
+    ["store.files", drivers.store.files],
+    ["signal", drivers.signal],
+    ["clock", drivers.clock],
+    ["journal", drivers.journal],
+    ["vault", drivers.vault],
+    ["channel.email", drivers.channel.email],
+    ["channel.sms", drivers.channel.sms],
+  ];
+}
+
+/**
+ * @param ref - Driver ref (string id, rich `{ driver }` object, or unset)
+ */
+function driverRefId(ref: DriverRef | undefined): string {
+  if (ref === undefined) return "—";
+  return typeof ref === "string" ? ref : ref.driver;
+}
+
+/**
+ * Render the fully-resolved drivers config as aligned text lines — every
+ * default plus every override, per env, for a developer whose own
+ * `oke.config.ts` only pins a handful of keys.
+ *
+ * @param drivers - Fully-resolved drivers config
+ * @param configEnv - Active env (marked in the active-driver column)
+ */
+function formatDriversSummary(drivers: EffectiveDriversConfig, configEnv: ConfigEnv): string {
+  const rows = flattenEffectiveDrivers(drivers);
+  const nameWidth = Math.max(...rows.map(([name]) => name.length));
+  const activeWidth = Math.max(...rows.map(([, map]) => driverRefId(map[configEnv]).length));
+  const lines = [`drivers (env=${configEnv}):`];
+  for (const [name, map] of rows) {
+    const active = driverRefId(map[configEnv]);
+    const full = `local=${driverRefId(map.local)} docker=${driverRefId(map.docker)} test=${driverRefId(map.test)} prod=${driverRefId(map.prod)}`;
+    lines.push(`  ${name.padEnd(nameWidth)}  ${active.padEnd(activeWidth)}  { ${full} }`);
+  }
+  return lines.join("\n");
+}
+
 /** One doctor finding. */
 export interface DoctorFinding {
   readonly code:
@@ -55,6 +108,19 @@ export interface DoctorOptions {
   }>;
   /** Skip live DB drift probe (default false). */
   readonly skipDbDrift?: boolean;
+  /**
+   * Inject the `drivers` block directly (tests) — skips loading
+   * `oke.config.ts` from disk. When omitted, `oke doctor` best-effort loads
+   * `oke.config.ts` from {@link cwd}; a project without one just gets the
+   * real, untouched defaults in the drivers summary.
+   */
+  readonly driversConfig?: DriversConfig;
+  /**
+   * Active {@link ConfigEnv} for the drivers summary. Default: `docker` when
+   * `OKE_DOCKER=1` (via {@link env}), else `local` — the same resolution
+   * `oke boot` uses without an explicit `env`.
+   */
+  readonly configEnv?: ConfigEnv;
   readonly write?: (text: string) => void;
   /** Write hints / progress (defaults to stderr). */
   readonly writeErr?: (text: string) => void;
@@ -92,6 +158,20 @@ export async function runDoctor(options: DoctorOptions = {}): Promise<{
   const env = options.env ?? ((k) => Bun.env[k] ?? process.env[k]);
   const secretNames = options.secrets ?? (manifest?.vault ? Object.keys(manifest.vault) : []);
 
+  // Fully-resolved `drivers.*` — real defaults + every override merged, so
+  // the picture is complete even when `oke.config.ts` only pins one key.
+  let driversConfig = options.driversConfig;
+  if (driversConfig === undefined) {
+    try {
+      driversConfig = (await loadOkeConfig(cwd)).config.drivers;
+    } catch {
+      // No oke.config.ts (or it failed to load) — show real defaults only.
+    }
+  }
+  const configEnv: ConfigEnv =
+    options.configEnv ?? (env("OKE_DOCKER") === "1" ? "docker" : "local");
+  const effectiveDrivers = resolveEffectiveDrivers(driversConfig);
+
   for (const name of secretNames) {
     const value = env(name);
     if (value === undefined || value.length === 0) {
@@ -177,7 +257,9 @@ export async function runDoctor(options: DoctorOptions = {}): Promise<{
   const code = ok ? EXIT_OK : EXIT_RUNTIME;
 
   if (json) {
-    write(`${JSON.stringify({ ok, findings }, null, 2)}\n`);
+    write(
+      `${JSON.stringify({ ok, findings, drivers: { env: configEnv, resolved: effectiveDrivers } }, null, 2)}\n`,
+    );
     if (!ok) {
       writeErr("Hint: fix error-severity findings, then re-run oke doctor.\n");
     }
@@ -186,6 +268,7 @@ export async function runDoctor(options: DoctorOptions = {}): Promise<{
 
   if (findings.length === 0) {
     write("oke doctor: ok\n");
+    write(`${formatDriversSummary(effectiveDrivers, configEnv)}\n`);
     return { code: EXIT_OK, findings };
   }
 
@@ -193,6 +276,7 @@ export async function runDoctor(options: DoctorOptions = {}): Promise<{
   for (const f of findings) {
     write(`  [${f.severity}] ${f.code}: ${f.message}\n`);
   }
+  write(`${formatDriversSummary(effectiveDrivers, configEnv)}\n`);
   return { code, findings };
 }
 
@@ -208,16 +292,25 @@ export async function doctorCli(args: readonly string[]): Promise<number> {
   }
 
   let manifestPath: string | undefined;
+  let configEnv: ConfigEnv | undefined;
   const json = wantsJson(args);
   for (let i = 0; i < args.length; i++) {
     const a = args[i]!;
     if (a === "--manifest" || a === "-m") manifestPath = args[++i];
-    else if (a === "--help" || a === "-h") {
-      console.log(`oke doctor [--manifest|-m path] [--json|-j]
+    else if (a === "--env" || a === "-e") {
+      const value = args[++i];
+      if (value === "local" || value === "docker" || value === "test" || value === "prod") {
+        configEnv = value;
+      }
+    } else if (a === "--help" || a === "-h") {
+      console.log(`oke doctor [--manifest|-m path] [--env|-e local|docker|test|prod] [--json|-j]
 oke doctor --diff|-d [--before|-b <path> --after|-a <path>] [--base|-B <branch>]
 
 Verify secrets, ports, schema drift, and PII→model egress before serving.
+Also prints drivers.* fully resolved (every default + every override merged)
+for the active env, from oke.config.ts.
 
+--env   Env to resolve drivers for (default: docker when OKE_DOCKER=1, else local).
 --diff  CI gate: block undeclared contract breaks (Manifest Diff).
         Default baseline is git merge-base (main/master) vs the working
         tree; pass --before/--after for an explicit comparison.
@@ -227,6 +320,6 @@ Verify secrets, ports, schema drift, and PII→model egress before serving.
       return EXIT_OK;
     }
   }
-  const { code } = await runDoctor({ manifestPath, json });
+  const { code } = await runDoctor({ manifestPath, configEnv, json });
   return code;
 }

package/src/cli/load-config.images.test.ts

@@ -3,12 +3,42 @@
  */
 
 import { describe, expect, test } from "bun:test";
+import { flattenImagesConfig } from "../config/index.ts";
 import {
   defaultImagesFromConfig,
   resolveImages,
   dockerDevDriverMismatches,
 } from "./load-config.ts";
 
+describe("flattenImagesConfig", () => {
+  test("flattens store/channel nesting to dotted keys; flat roles pass through", () => {
+    expect(
+      flattenImagesConfig({
+        store: { sql: "postgres:18-alpine", kv: "redis:8-alpine", files: "rustfs/rustfs:1.0.0" },
+        channel: { email: "axllent/mailpit:v1.22.3" },
+        vault: "openbao/openbao:2.6.1",
+        ai: "ollama/ollama:0.32.6",
+        pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.51",
+        proxy: "caddy:2-alpine",
+      }),
+    ).toEqual({
+      "store.sql": "postgres:18-alpine",
+      "store.kv": "redis:8-alpine",
+      "store.files": "rustfs/rustfs:1.0.0",
+      "channel.email": "axllent/mailpit:v1.22.3",
+      vault: "openbao/openbao:2.6.1",
+      ai: "ollama/ollama:0.32.6",
+      pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.51",
+      proxy: "caddy:2-alpine",
+    });
+  });
+
+  test("undefined / empty input yields empty map", () => {
+    expect(flattenImagesConfig(undefined)).toEqual({});
+    expect(flattenImagesConfig({})).toEqual({});
+  });
+});
+
 describe("defaultImagesFromConfig", () => {
   test("maps postgres + redis prod drivers", () => {
     const images = defaultImagesFromConfig({
@@ -82,7 +112,7 @@ describe("resolveImages", () => {
           kv: { prod: "redis" },
         },
       },
-      images: { "store.sql": "pgvector/pgvector:pg17" },
+      images: { store: { sql: "pgvector/pgvector:pg17" } },
     });
     expect(images).toEqual({ "store.sql": "pgvector/pgvector:pg17" });
   });

package/src/cli/load-config.ts

@@ -3,7 +3,7 @@
  */
 
 import { resolve } from "node:path";
-import type { DriverRef, OkeConfig } from "../config/index.ts";
+import { flattenImagesConfig, type DriverRef, type OkeConfig } from "../config/index.ts";
 import type { Manifest } from "../manifest/types.ts";
 
 /** Default image pins when `images` is omitted but prod drivers need containers. */
@@ -145,7 +145,7 @@ export function resolveImages(
   config?: OkeConfig,
   manifest?: Manifest,
 ): Readonly<Record<string, string>> {
-  const explicit = config?.images ?? manifest?.images;
+  const explicit = config?.images ? flattenImagesConfig(config.images) : manifest?.images;
   if (explicit && Object.keys(explicit).length > 0) return explicit;
   if (config) return defaultImagesFromConfig(config);
   return {};

package/src/cli/safe-defaults.test.ts

@@ -16,7 +16,7 @@ describe("oke safe-default overrides", () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-safe-docker-"));
     await Bun.write(
       join(dir, "oke.config.ts"),
-      `export default { images: { "store.sql": "postgres:18-alpine" } }\n`,
+      `export default { images: { store: { sql: "postgres:18-alpine" } } }\n`,
     );
     // Without --prod, derive still runs but prod overlays are not requested.
     // We assert the parser default by calling runDockerDerive via dockerCli

package/src/client/notes-contract.test.ts

@@ -37,7 +37,7 @@ const NotFound = z.object({});
 
 const create = on(
   http.post("/notes"),
-  flow({
+  flow("notes.create", {
     in: NewNote,
     out: NoteId,
     do: (input) => ({ id: `n_${input.title}` }),
@@ -46,7 +46,7 @@ const create = on(
 
 const get = on(
   http.get("/notes/:id"),
-  flow({
+  flow("notes.get", {
     in: NoteId,
     out: Note,
     errors: { NotFound },
@@ -250,8 +250,7 @@ describe("Notes — typeof app carries contracts", () => {
   });
 
   test("untriggered adopted flow is RPC-only on the client", async () => {
-    const stats = flow({
-      name: "notes.stats",
+    const stats = flow("notes.stats", {
       in: NoteId,
       out: z.object({ clicks: z.number() }),
       do: () => ({ clicks: 7 }),

package/src/compiler/aot.test.ts

@@ -120,8 +120,7 @@ describe("typed error narrowing end-to-end", () => {
 
     on(
       http.post("/bookings").gate(gate.public),
-      flow({
-        name: "bookings.create",
+      flow("bookings.create", {
         in: Booking,
         out: z.object({ id: z.string() }),
         errors: { FlightFull },

package/src/compiler/extract.test.ts

@@ -123,8 +123,7 @@ describe("extractManifest — performance", () => {
       parts.push(`
 export const flow_${i} = on(
   http.get("/f/${i}"),
-  flow({
-    name: "synth.flow_${i}",
+  flow("synth.flow_${i}", {
     do: async (input, fx) => {
       await fx.store(db).insert(items).values(input);
       const rows = await fx.store(db).select().from(items);
@@ -166,8 +165,7 @@ export const daily = { name: "daily" };
 
 export const listLinks = on(
   http.get("/links"),
-  flow({
-    name: "rel.root",
+  flow("rel.root", {
     do: async (_input, fx) => {
       return fx.store(db).select().from(links);
     },
@@ -178,8 +176,7 @@ export const listLinks = on(
 // relations, so the related table must NOT appear in effects.
 export const withDaily = on(
   http.get("/links/with-daily"),
-  flow({
-    name: "rel.with",
+  flow("rel.with", {
     do: async (_input, fx) => {
       return fx.store(db).findMany({ with: { daily: true } });
     },
@@ -354,9 +351,7 @@ export const files = store.files("uploads");
 
 export const attach = on(
   http.post("/attach").gate(gate.public),
-  flow({
-    name: "notes.attach",
-    unit: "notes",
+  flow("notes.attach", {
     do: async (input, fx) => {
       await fx.store(files).put("key", input.text);
       return { ok: true };
@@ -377,9 +372,7 @@ export const files = store.files("uploads");
 
 export const attach = on(
   http.post("/attach").gate(gate.public),
-  flow({
-    name: "notes.attachImage",
-    unit: "notes",
+  flow("notes.attachImage", {
     do: async (input, fx) => {
       await fx.store(files).putImage("key", input.bytes);
       return { ok: true };
@@ -400,9 +393,7 @@ export const files = store.files("uploads");
 
 export const sweep = on(
   every("1d"),
-  flow({
-    name: "notes.sweep",
-    unit: "notes",
+  flow("notes.sweep", {
     do: async (_input, fx) => {
       const keys = await fx.store(files).list();
       return { count: keys.length };
@@ -429,9 +420,7 @@ export const noteCreatedMail = mail.template("note-created", {
 
 export const onCreated = on(
   http.post("/hook").gate(gate.public),
-  flow({
-    name: "notes.onCreated",
-    unit: "notes",
+  flow("notes.onCreated", {
     do: async (payload, fx) => {
       await fx.send(noteCreatedMail, { to: "you@localhost", data: payload });
     },
@@ -454,9 +443,7 @@ export const otpTemplate = otp.template("otp-code", {});
 
 export const send = on(
   http.post("/otp").gate(gate.public),
-  flow({
-    name: "notes.sendOtp",
-    unit: "notes",
+  flow("notes.sendOtp", {
     do: async (payload, fx) => {
       await fx.send(otpTemplate, { to: "+10000000000", data: payload });
     },
@@ -469,3 +456,71 @@ export const send = on(
     expect(manifest.channels?.["otp-code"]?.medium).toBe("sms");
   });
 });
+
+describe("extractManifest — flow(name, options) positional signature", () => {
+  test("bare flow(name, {...}) extracts name, in, out, effects", async () => {
+    const source = `
+import { flow } from "okengine";
+
+export const chargeOrder = flow("checkout.chargeOrder", {
+  in: ChargeIn,
+  out: ChargeOut,
+  effects: { reads: ["sql:orders"], writes: ["sql:orders"] },
+  do: async (input, fx) => {
+    return { ok: true };
+  },
+});
+`;
+    const manifest = await extractFromSources({ "src/flows/checkout.ts": source });
+
+    expect(manifest.flows?.["checkout.chargeOrder"]).toBeDefined();
+    expect(manifest.flows?.["checkout.chargeOrder"]?.in).toBeDefined();
+    expect(manifest.flows?.["checkout.chargeOrder"]?.out).toBeDefined();
+    expect(manifest.flows?.["checkout.chargeOrder"]?.effects?.reads).toEqual(["sql:orders"]);
+    expect(manifest.flows?.["checkout.chargeOrder"]?.effects?.writes).toEqual(["sql:orders"]);
+  });
+
+  test("on(trigger, flow(name, {...})) extracts the same shape as bare flow()", async () => {
+    const source = `
+import { on, http, flow } from "okengine";
+
+export const getOrder = on(
+  http.get("/orders/:id"),
+  flow("checkout.getOrder", {
+    out: OrderOut,
+    effects: { reads: ["sql:orders"] },
+    do: async (input, fx) => {
+      return { id: input.id };
+    },
+  }),
+);
+`;
+    const manifest = await extractFromSources({ "src/flows/checkout.ts": source });
+
+    expect(manifest.flows?.["checkout.getOrder"]).toBeDefined();
+    expect(manifest.flows?.["checkout.getOrder"]?.trigger?.http?.method).toBe("GET");
+    expect(manifest.flows?.["checkout.getOrder"]?.out).toBeDefined();
+    expect(manifest.flows?.["checkout.getOrder"]?.effects?.reads).toEqual(["sql:orders"]);
+  });
+
+  test("a stray `name:` key inside the options object is ignored — the positional arg wins", async () => {
+    // Regression guard for the exact class of AST-shape assumption that broke
+    // silently before (channel-alias tracking, `.put()` inference): the
+    // compiler must read the flow's identity from the first positional
+    // argument, never from a `name` property on the options object, even
+    // when one happens to be present.
+    const source = `
+import { flow } from "okengine";
+
+export const decoy = flow("checkout.realName", {
+  name: "checkout.decoyName",
+  effects: { reads: ["sql:orders"] },
+  do: async () => ({ ok: true }),
+});
+`;
+    const manifest = await extractFromSources({ "src/flows/checkout.ts": source });
+
+    expect(manifest.flows?.["checkout.realName"]).toBeDefined();
+    expect(manifest.flows?.["checkout.decoyName"]).toBeUndefined();
+  });
+});