okengine 0.10.0 → 0.10.2

package/src/kernel/auto-registry.test.ts

@@ -0,0 +1,198 @@
+/**
+ * `oke({...})` auto-populates `stores` / `secrets` / `signals` /
+ * `channel.templates` from the same kind of module-evaluation registry
+ * already proven for `on()`'s trigger drain (`registry-isolation.test.ts`).
+ *
+ * `store.sql` / `store.files`, `vault.secret`, `signal()`, and medium-binder
+ * `.template()` push into a shared registry (`src/kernel/element-registries.ts`)
+ * at call time — zero change to how developers call them. `oke()` drains it
+ * at construction under the same `registry: "consume" | "keep" | "ignore"`
+ * switch that already governs bindings.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { channel } from "../elements/channel/declare.ts";
+import { signal } from "../elements/signal/declare.ts";
+import { store } from "../elements/store/declare.ts";
+import { vault } from "../elements/vault/declare.ts";
+import { oke } from "./app.ts";
+import { flow } from "./flow.ts";
+import { on, resetBindings } from "./on.ts";
+import { http } from "./triggers.ts";
+
+describe("oke() auto-registry — stores/secrets/signals/channel.templates", () => {
+  test("before/after: zero explicit arrays boots identically to the explicit-array form", async () => {
+    resetBindings();
+
+    // "before" — today's explicit-array form (registry: "ignore" so this
+    // app cannot see anything auto-drained; proves the old path is unchanged).
+    const dbBefore = store.sql("before-app", { schema: {} });
+    const filesBefore = store.files("before-uploads");
+    const secretBefore = vault.secret("BEFORE_WEBHOOK_SECRET", { dev: "dev-secret-before" });
+    const signalBefore = signal("before-note-created", { delivery: "once", optional: true });
+    const mailBefore = channel.email({ from: "Before <before@localhost>" });
+    const templateBefore = mailBefore.template("before-note-created");
+
+    const beforeFlow = flow("before.onCreated", {
+      effects: {
+        secrets: ["BEFORE_WEBHOOK_SECRET"],
+        emits: ["before-note-created"],
+        sends: ["before-note-created"],
+      },
+      do: async (_input, fx) => {
+        const secret = fx.vault(secretBefore);
+        await fx.emit(signalBefore, {});
+        await fx.send(templateBefore, { to: "you@localhost", data: {} });
+        return { secret };
+      },
+    });
+    on(http.post("/before"), beforeFlow);
+
+    const appBefore = oke({
+      name: "before-app",
+      registry: "ignore",
+      bindings: [{ trigger: http.post("/before"), flow: beforeFlow }],
+      gate: { unguardedHttp: "allow" },
+      vault: { allowDevFallbacks: true },
+      stores: [dbBefore, filesBefore],
+      secrets: [secretBefore],
+      signals: [signalBefore],
+      channel: { templates: [templateBefore] },
+      startScheduler: false,
+    });
+
+    // "after" — same shape, zero explicit arrays; registry auto-populates.
+    // Declared (and registered) for their side effect only — never passed
+    // to `oke()` directly, proving the registry alone carries them.
+    store.sql("after-app", { schema: {} });
+    store.files("after-uploads");
+    const secretAfter = vault.secret("AFTER_WEBHOOK_SECRET", { dev: "dev-secret-after" });
+    const signalAfter = signal("after-note-created", { delivery: "once", optional: true });
+    const mailAfter = channel.email({ from: "After <after@localhost>" });
+    const templateAfter = mailAfter.template("after-note-created");
+
+    const afterFlow = flow("after.onCreated", {
+      effects: {
+        secrets: ["AFTER_WEBHOOK_SECRET"],
+        emits: ["after-note-created"],
+        sends: ["after-note-created"],
+      },
+      do: async (_input, fx) => {
+        const secret = fx.vault(secretAfter);
+        await fx.emit(signalAfter, {});
+        await fx.send(templateAfter, { to: "you@localhost", data: {} });
+        return { secret };
+      },
+    });
+    resetBindings();
+    on(http.post("/after"), afterFlow);
+
+    const appAfter = oke({
+      name: "after-app",
+      gate: { unguardedHttp: "allow" },
+      vault: { allowDevFallbacks: true },
+      startScheduler: false,
+      // No stores / secrets / signals / channel — registry supplies them.
+    });
+
+    await appBefore.boot({ env: "test", unguardedHttp: "allow" });
+    await appAfter.boot({ env: "test", unguardedHttp: "allow" });
+
+    // Both boots resolved the same shape from stores → secrets → signals → channel.
+    expect(appBefore.bootResult?.store?.declarations.has("sql:before-app")).toBe(true);
+    expect(appBefore.bootResult?.store?.declarations.has("files:before-uploads")).toBe(true);
+    expect(appAfter.bootResult?.store?.declarations.has("sql:after-app")).toBe(true);
+    expect(appAfter.bootResult?.store?.declarations.has("files:after-uploads")).toBe(true);
+
+    expect(appBefore.bootResult?.vault?.contracts.has("BEFORE_WEBHOOK_SECRET")).toBe(true);
+    expect(appAfter.bootResult?.vault?.contracts.has("AFTER_WEBHOOK_SECRET")).toBe(true);
+    expect(appBefore.bootResult?.vault?.read("BEFORE_WEBHOOK_SECRET")).toBe("dev-secret-before");
+    expect(appAfter.bootResult?.vault?.read("AFTER_WEBHOOK_SECRET")).toBe("dev-secret-after");
+
+    expect(appBefore.bootResult?.signal?.declarations.has("before-note-created")).toBe(true);
+    expect(appAfter.bootResult?.signal?.declarations.has("after-note-created")).toBe(true);
+
+    expect(appBefore.bootResult?.channel?.templates.has("before-note-created")).toBe(true);
+    expect(appAfter.bootResult?.channel?.templates.has("after-note-created")).toBe(true);
+
+    // Same flow execution shape through the real HTTP path either way —
+    // both resolve, emit, and send successfully; the secret value itself
+    // comes back redacted (fx output redaction), same on both sides.
+    const resBefore = await appBefore.fetch(
+      new Request("http://localhost/before", { method: "POST" }),
+    );
+    const resAfter = await appAfter.fetch(
+      new Request("http://localhost/after", { method: "POST" }),
+    );
+    expect(resBefore.status).toBe(200);
+    expect(resAfter.status).toBe(200);
+    const bodyBefore = (await resBefore.json()) as { data: { secret: string } };
+    const bodyAfter = (await resAfter.json()) as { data: { secret: string } };
+    expect(bodyBefore.data.secret).toBe(bodyAfter.data.secret);
+  });
+
+  test("explicit passing is additive, never silently ignored — same object via both paths is deduped, not doubled", async () => {
+    const db = store.sql("dedup-app", { schema: {} });
+
+    // `db` is already sitting in the registry from the call above *and*
+    // passed explicitly — must not double-register / conflict.
+    const app = oke({
+      name: "dedup-app",
+      autoBoot: false,
+      stores: [db],
+      startScheduler: false,
+    });
+
+    await app.boot({ env: "test", unguardedHttp: "allow" });
+    expect(app.bootResult?.store?.declarations.has("sql:dedup-app")).toBe(true);
+  });
+
+  test('registry: "ignore" does not auto-populate', async () => {
+    vault.secret("IGNORED_SECRET", { description: "never passed, never auto-read" });
+
+    const app = oke({
+      name: "ignore-mode-app",
+      registry: "ignore",
+      startScheduler: false,
+    });
+    // Nothing requires the secret, so boot succeeds — but it must not have
+    // silently picked up IGNORED_SECRET from the registry either way.
+    await app.boot({ env: "test", unguardedHttp: "allow" });
+    expect(app.bootResult?.vault?.contracts.has("IGNORED_SECRET")).toBeFalsy();
+  });
+
+  test('registry: "consume" (default) drains stores/secrets/signals/channel.templates — a later app does not inherit them', async () => {
+    store.sql("leak-app", { schema: {} });
+    vault.secret("LEAK_SECRET", { dev: "dev-leak" });
+    signal("leak-signal", { delivery: "once" });
+    channel.email().template("leak-template");
+
+    const appA = oke({
+      name: "leak-app-a",
+      autoBoot: false,
+      vault: { allowDevFallbacks: true },
+      startScheduler: false,
+    });
+    await appA.boot({ env: "test", unguardedHttp: "allow" });
+    expect(appA.bootResult?.store?.declarations.has("sql:leak-app")).toBe(true);
+    expect(appA.bootResult?.vault?.contracts.has("LEAK_SECRET")).toBe(true);
+
+    // Second app, constructed after the first drained the registry.
+    const appB = oke({
+      name: "leak-app-b",
+      autoBoot: false,
+      startScheduler: false,
+    });
+    await appB.boot({ env: "test", unguardedHttp: "allow" });
+    // Nothing was passed and nothing was left in the registry (App A drained
+    // it) — App B needed store/vault/signal not at all, so no runtime was
+    // built for them. Channel boots unconditionally regardless of registry
+    // content (pre-existing, unrelated to this feature — `resolveElementNeeds`
+    // gates channel on object *presence*, not template count) — assert its
+    // template map, not runtime absence.
+    expect(appB.bootResult?.store).toBeUndefined();
+    expect(appB.bootResult?.vault).toBeUndefined();
+    expect(appB.bootResult?.signal).toBeUndefined();
+    expect(appB.bootResult?.channel?.templates.has("leak-template") ?? false).toBe(false);
+  });
+});

package/src/kernel/boot-bind/honor-config.test.ts

@@ -157,7 +157,7 @@ describe("boot binders honour drivers.* config", () => {
     const result = await bootApplication({
       env: "local",
       startScheduler: false,
-      flows: [flow({ name: "charge", durable: true, do: () => ({ ok: true }) })],
+      flows: [flow("charge", { durable: true, do: () => ({ ok: true }) })],
     });
     try {
       expect(result.journal?.driverId).toBe("memory");
@@ -172,7 +172,7 @@ describe("boot binders honour drivers.* config", () => {
     const result = await bootApplication({
       env: "local",
       startScheduler: false,
-      flows: [flow({ name: "plain", do: () => ({ ok: true }) })],
+      flows: [flow("plain", { do: () => ({ ok: true }) })],
     });
     try {
       expect(result.journal).toBeUndefined();
@@ -187,7 +187,7 @@ describe("boot binders honour drivers.* config", () => {
     const result = await bootApplication({
       env: "local",
       startScheduler: false,
-      flows: [flow({ name: "charge", durable: true, do: () => ({ ok: true }) })],
+      flows: [flow("charge", { durable: true, do: () => ({ ok: true }) })],
       config: {
         drivers: {
           journal: { local: "file", docker: "postgres", test: "memory", prod: "postgres" },
@@ -211,7 +211,7 @@ describe("boot binders honour drivers.* config", () => {
         bootApplication({
           env: "local",
           startScheduler: false,
-          flows: [flow({ name: "charge", durable: true, do: () => ({ ok: true }) })],
+          flows: [flow("charge", { durable: true, do: () => ({ ok: true }) })],
           config: {
             drivers: {
               journal: { local: "postgres" },
@@ -232,7 +232,7 @@ describe("boot binders honour drivers.* config", () => {
       bootApplication({
         env: "local",
         startScheduler: false,
-        flows: [flow({ name: "charge", durable: true, do: () => ({ ok: true }) })],
+        flows: [flow("charge", { durable: true, do: () => ({ ok: true }) })],
         config: {
           drivers: {
             journal: { local: "neon" },

package/src/kernel/boot.test.ts

@@ -79,7 +79,7 @@ describe("boot — lazy element needs", () => {
     expect(needs.signal).toBe(false);
   });
 
-  test("oke() Store-only graph stays under the prior 54 kB baseline", async () => {
+  test("oke() Store-only graph stays under the prior 54.3 kB baseline", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-store-only-"));
     const entry = join(dir, "entry.ts");
     const appPath = join(import.meta.dir, "app.ts");
@@ -120,8 +120,18 @@ describe("boot — lazy element needs", () => {
       // gzip), durable-journal lease surface (~51.2 kB), fx.deliverOtp +
       // unified otp() (~50.9 kB → 53 kB), then fx.runs / SLO window on the
       // shared surface (~53.3 kB → 54 kB cap). Clock/channel/journal drivers
-      // stay lazy-bound; far below eager bind.
-      expect(total).toBeLessThan(54_000);
+      // stay lazy-bound; far below eager bind. Rebased again for the
+      // store/vault/signal/channel auto-registry drain (`element-registries.ts`
+      // + the `oke()` merge/dedup logic) — every app now carries this
+      // regardless of which elements it uses, since the drain must run
+      // synchronously at construction (same isolation guarantee as the
+      // `on()` binding registry) and can't be deferred behind a lazy import
+      // (~54.0 kB → 54.3 kB cap). Rebased again for `assertAdoptBarrelFresh`
+      // + `tryListFlowsUnits` in `boot.ts` (`.adopt()` barrel staleness
+      // check, OKE1009) — part of the already-lazily-loaded boot graph, not
+      // the `oke()` construction path, but `Bun.build` still traces and
+      // sums the dynamic-import chunk (~54.3 kB → 54.7 kB cap).
+      expect(total).toBeLessThan(54_700);
     } finally {
       await rm(dir, { recursive: true, force: true });
     }
@@ -130,8 +140,7 @@ describe("boot — lazy element needs", () => {
 
 describe("boot — capabilities from Manifest effects", () => {
   test("tokens cover declared effects only", async () => {
-    const charge = flow({
-      name: "payments.charge",
+    const charge = flow("payments.charge", {
       effects: { secrets: ["STRIPE_KEY"], writes: ["sql:orders"] },
       do: () => ({ ok: true }),
     });
@@ -158,8 +167,7 @@ describe("boot — cron fires without manual dispatch", () => {
     let ran = 0;
     on(
       every("1h"),
-      flow({
-        name: "cleanup.expire",
+      flow("cleanup.expire", {
         do: () => {
           ran += 1;
         },
@@ -200,8 +208,7 @@ describe("boot — HTTP gate wiring on the default path", () => {
     resetFlowSeq();
     on(
       http.get("/ping"),
-      flow({
-        name: "ping",
+      flow("ping", {
         do: () => ({ ok: true }),
       }),
     );
@@ -217,8 +224,7 @@ describe("boot — HTTP gate wiring on the default path", () => {
     const { GateBootError } = await import("../elements/gate/boot.ts");
     on(
       http.get("/ping"),
-      flow({
-        name: "ping",
+      flow("ping", {
         do: () => ({ ok: true }),
       }),
     );
@@ -235,8 +241,7 @@ describe("boot — HTTP gate wiring on the default path", () => {
     const { gate } = await import("../elements/gate.ts");
     on(
       http.get("/ping").gate(gate.public),
-      flow({
-        name: "ping-public",
+      flow("ping-public", {
         do: () => ({ ok: true }),
       }),
     );
@@ -261,8 +266,7 @@ describe("boot — cron autostart via real timer loop", () => {
     let ran = 0;
     on(
       every("10m"),
-      flow({
-        name: "cleanup.autostart",
+      flow("cleanup.autostart", {
         do: () => {
           ran += 1;
         },

package/src/kernel/boot.ts

@@ -17,7 +17,10 @@
  * Element runtimes are loaded via `new URL("./boot-bind/"+name+".ts", …)` so
  * unused binders stay out of the `oke()` bundle (semantic tree-shaking).
  * Vault still loads whenever secrets are declared and lists every gap in one
- * failure; capability minting uses flow effect refs only — no element modules.
+ * failure; capability minting uses flow effect refs only — no element modules,
+ * except a lazy `extractManifest` import when a flow has no hand-declared
+ * `effects` and neither {@link BootOptions.manifest} nor
+ * {@link BootOptions.rootDir} / `OKE_ROOT_DIR` are set to derive one.
  *
  * The scheduler reads the effective state from the Store after reconciliation,
  * never the code directly (console §5).
@@ -38,8 +41,11 @@ import type {
 import type { JournalRuntime } from "./boot-bind/journal.ts";
 import type { CreateRunsRuntimeOptions, RunsRuntime } from "../runs/index.ts";
 import { createCapabilityToken, type CapabilityToken } from "./capability.ts";
+import { throwOke } from "./errors.ts";
 import type { AnyFlowDef } from "./flow.ts";
 import type { Binding } from "./on.ts";
+import type { Manifest } from "../manifest/types.ts";
+import { emitBootWarn } from "../runtime/boot-warn.ts";
 
 /** Pre-built or partially-built element runtimes. */
 export interface ElementRuntimes {
@@ -104,6 +110,21 @@ export interface BootOptions {
   readonly bindings?: readonly Binding[];
   /** Flows known to the app (for capability minting). */
   readonly flows?: readonly AnyFlowDef[];
+  /**
+   * Compiled Manifest to derive capability tokens from for flows with no
+   * hand-declared `effects` (highest priority — build tooling / bundler
+   * import, never a filesystem read the kernel performs itself).
+   */
+  readonly manifest?: Manifest;
+  /**
+   * Project root for a lazy, best-effort `extractManifest` when a flow has
+   * no hand-declared `effects` and no {@link manifest} was given. Explicit
+   * opt-in only — never defaults to `process.cwd()` — so the existing test
+   * suite (hundreds of boots against synthetic flows, not a real source
+   * tree) never pays extraction cost. Falls back to `OKE_ROOT_DIR` when
+   * unset (the CLI sets this for `oke dev` / `oke start`).
+   */
+  readonly rootDir?: string;
   /**
    * Dispatch a cron / every interval when the scheduler fires.
    *
@@ -264,7 +285,7 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
     input.docker === true || (input.docker !== false && process.env.OKE_DOCKER === "1");
   // `-d` always selects the `docker` driver profile — not a mix of local/test +
   // prod store overrides when `$options.env` is unset.
-  const env: ConfigEnv = docker ? "docker" : (input.env ?? "local");
+  const env: ConfigEnv = input.env ?? (docker ? "docker" : "local");
   let config = input.config;
   if (config === undefined) {
     try {
@@ -457,8 +478,16 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
     }
   }
 
-  // 8. Caps — effect refs only; no element modules.
-  const capabilities = mintCapabilities(options.flows ?? []);
+  // 8. Caps — effect refs only; no element modules (unless a lazy extract is needed).
+  const capabilities = await mintCapabilities(options.flows ?? [], env, {
+    manifest: options.manifest,
+    rootDir: options.rootDir,
+  });
+
+  // 9. `.adopt()` barrel freshness — opt-in only (same `rootDir` gate as
+  // capability minting above; never a filesystem read the kernel performs
+  // on its own).
+  await assertAdoptBarrelFresh(options.flows ?? [], env, options.rootDir);
 
   return {
     vault,
@@ -491,20 +520,169 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   };
 }
 
+/** Per-process guard so the "no effects" boot warning fires once, not per-flow. */
+let noEffectsWarned = false;
+
+/** Reset the once-per-process "no effects" warn latch (tests only). */
+export function resetNoEffectsWarnForTests(): void {
+  noEffectsWarned = false;
+}
+
+/**
+ * Best-effort AoT extraction from `rootDir` — mirrors the CLI's own lazy,
+ * defensive `extractManifest` use (`oke dev`'s `tryLoadProjectManifest`).
+ * Never throws: a broken or mid-edit source tree just means "no Manifest
+ * available," handled by the caller like any other missing Manifest.
+ *
+ * `new URL` (not a literal specifier) so `oxc-parser` / the whole compiler
+ * never enters the bundler graph for apps that never hit this path — same
+ * trick as {@link loadBind} for the element binders.
+ *
+ * @param rootDir - Project root to extract from
+ */
+async function tryAutoExtractManifest(rootDir: string): Promise<Manifest | undefined> {
+  try {
+    const url = new URL("../compiler/extract.ts", import.meta.url);
+    const { extractManifest } = (await import(url.href)) as typeof import("../compiler/extract.ts");
+    return await extractManifest({ rootDir });
+  } catch {
+    return undefined;
+  }
+}
+
 /**
- * Mint capability tokens from each flow's declared effects.
- * Tokens come from the Manifest / flow contract — never hand-passed sets.
+ * Mint capability tokens from each flow's declared effects, falling back to
+ * a Manifest-derived stamp when a flow declares no `effects` of its own —
+ * an explicit {@link BootOptions.manifest}, or a lazy AoT extract from
+ * {@link BootOptions.rootDir} / `OKE_ROOT_DIR`.
+ *
+ * When neither is available: `local` / `test` stay open (today's dev-loop
+ * behavior, unbroken) with a once-per-process `oke boot:` warning; `docker`
+ * / `prod` fail loud (`OKE1008`) — docker mirrors prod's posture, never a
+ * silent open door in a deploy-shaped environment.
  *
  * @param flows - Adopted flows
+ * @param env - Resolved {@link ConfigEnv}
+ * @param options - Manifest / rootDir sources for the fallback stamp
  */
-export function mintCapabilities(flows: readonly AnyFlowDef[]): Map<string, CapabilityToken> {
+export async function mintCapabilities(
+  flows: readonly AnyFlowDef[],
+  env: ConfigEnv = "local",
+  options: { readonly manifest?: Manifest; readonly rootDir?: string } = {},
+): Promise<Map<string, CapabilityToken>> {
   const map = new Map<string, CapabilityToken>();
+
+  let manifest = options.manifest;
+  const needsManifest = manifest === undefined && flows.some((f) => f.effects === undefined);
+  if (needsManifest) {
+    const rootDir = options.rootDir ?? process.env["OKE_ROOT_DIR"];
+    if (rootDir) manifest = await tryAutoExtractManifest(rootDir);
+  }
+
   for (const f of flows) {
-    map.set(f.name, createCapabilityToken(f.name, f.effects));
+    if (f.effects !== undefined) {
+      map.set(f.name, createCapabilityToken(f.name, f.effects));
+      continue;
+    }
+
+    const stamped = manifest?.flows?.[f.name]?.effects;
+    if (stamped !== undefined) {
+      map.set(f.name, createCapabilityToken(f.name, stamped));
+      continue;
+    }
+
+    if (env === "docker" || env === "prod") {
+      throwOke("NO_EFFECTS_DECLARED", { flow: f.name });
+    }
+    if (!noEffectsWarned) {
+      noEffectsWarned = true;
+      emitBootWarn(
+        `oke boot: flow "${f.name}" (and possibly others) has no declared effects and no ` +
+          "Manifest-derived effects — running with an OPEN capability token (every access " +
+          "allowed, ledgered but not gated). Run `oke build`, or boot with `manifest` / " +
+          "`rootDir`, before deploying — docker/prod refuse to boot this way.",
+      );
+    }
+    map.set(f.name, createCapabilityToken(f.name, undefined));
   }
   return map;
 }
 
+/** Per-process guard so the stale-barrel boot warning fires once. */
+let staleAdoptBarrelWarned = false;
+
+/** Reset the once-per-process stale-barrel warn latch (tests only). */
+export function resetStaleAdoptBarrelWarnForTests(): void {
+  staleAdoptBarrelWarned = false;
+}
+
+/**
+ * Best-effort disk scan for `<rootDir>/src/flows/*` unit folders — mirrors
+ * {@link tryAutoExtractManifest}'s lazy, defensive, never-throws posture and
+ * the same `new URL` trick so the generator never enters the bundler graph
+ * for apps that never opt into `rootDir`.
+ *
+ * @param rootDir - Project root to scan
+ */
+async function tryListFlowsUnits(rootDir: string): Promise<readonly string[] | undefined> {
+  try {
+    const url = new URL("../compiler/generate-adopt.ts", import.meta.url);
+    const { generateAdoptBarrel } = (await import(
+      url.href
+    )) as typeof import("../compiler/generate-adopt.ts");
+    return (await generateAdoptBarrel({ rootDir })).units;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Confirm every `src/flows/<unit>` folder on disk actually reached this
+ * boot's adopted flows — the disk-file counterpart of a stale/missing
+ * generated `.adopt()` barrel (`src/flows/generated.ts`). A folder present
+ * on disk with zero adopted flows under that unit means the barrel wasn't
+ * regenerated (or was hand-edited) after the folder was added.
+ *
+ * Opt-in only via {@link BootOptions.rootDir} / `OKE_ROOT_DIR` (same gate as
+ * {@link mintCapabilities}'s Manifest fallback) — never a filesystem read
+ * the kernel performs on its own. `local` / `test` warn once per process;
+ * `docker` / `prod` fail loud (`OKE1009`) — same class as `NO_EFFECTS_DECLARED`,
+ * never a silently-incomplete route table in a deploy-shaped environment.
+ *
+ * @param flows - Adopted flows
+ * @param env - Resolved {@link ConfigEnv}
+ * @param rootDir - Explicit project root (falls back to `OKE_ROOT_DIR`)
+ */
+export async function assertAdoptBarrelFresh(
+  flows: readonly AnyFlowDef[],
+  env: ConfigEnv = "local",
+  rootDir?: string,
+): Promise<void> {
+  const dir = rootDir ?? process.env["OKE_ROOT_DIR"];
+  if (!dir) return;
+
+  const diskUnits = await tryListFlowsUnits(dir);
+  if (diskUnits === undefined || diskUnits.length === 0) return;
+
+  const adoptedUnits = new Set(
+    flows.map((f) => f.unit).filter((u): u is string => u !== undefined),
+  );
+  const missing = diskUnits.filter((u) => !adoptedUnits.has(u));
+  if (missing.length === 0) return;
+
+  if (env === "docker" || env === "prod") {
+    throwOke("ADOPT_BARREL_STALE", { unit: missing[0]! });
+  }
+  if (!staleAdoptBarrelWarned) {
+    staleAdoptBarrelWarned = true;
+    emitBootWarn(
+      `oke boot: src/flows/${missing[0]} exists on disk but adopted no flows — the ` +
+        '.adopt() barrel ("src/flows/generated.ts") is stale. Run `oke dev` or `oke build` ' +
+        "to regenerate it — docker/prod refuse to boot this way.",
+    );
+  }
+}
+
 function isRunsRuntime(value: RunsRuntime | CreateRunsRuntimeOptions): value is RunsRuntime {
   return (
     typeof value === "object" &&

package/src/kernel/call.test.ts

@@ -11,15 +11,13 @@ beforeEach(() => {
 
 describe("fx.call — untriggered flows", () => {
   test("untriggered flow is callable via app.call and fx.call", async () => {
-    const stats = flow({
-      name: "links.stats",
+    const stats = flow("links.stats", {
       do: ({ code }: { code: string }) => ({ code, clicks: 7 }),
     });
 
     const parent = on(
       http.post("/run"),
-      flow({
-        name: "links.run",
+      flow("links.run", {
         effects: { calls: ["links.stats"] },
         do: async ({ code }: { code: string }, fx) => {
           const result = await fx.call("links.stats", { code });
@@ -54,8 +52,7 @@ describe("fx.call — untriggered flows", () => {
   });
 
   test("fx.call propagates fx.principal without filling fx.auth", async () => {
-    const audit = flow({
-      name: "audit.log",
+    const audit = flow("audit.log", {
       do: (_input: { event: string }, fx) => ({
         authUserId: fx.auth.userId,
         principalUserId: fx.principal.userId,
@@ -65,8 +62,7 @@ describe("fx.call — untriggered flows", () => {
 
     const act = on(
       http.post("/act"),
-      flow({
-        name: "act",
+      flow("act", {
         effects: { calls: ["audit.log"] },
         do: async (_input: Record<string, never>, fx) => {
           return fx.call("audit.log", { event: "act" });
@@ -99,8 +95,7 @@ describe("fx.call — untriggered flows", () => {
 
   test("http and signal invocations of the same flow execute identically", async () => {
     let runs = 0;
-    const work = flow({
-      name: "work",
+    const work = flow("work", {
       do: (input: { v: number }) => {
         runs += 1;
         return { out: input.v + 1 };

package/src/kernel/compensate.test.ts

@@ -24,8 +24,7 @@ describe("durable compensate", () => {
     const store = createMemoryJournalStore();
     const undos: string[] = [];
 
-    const pay = flow({
-      name: "pay.charge",
+    const pay = flow("pay.charge", {
       durable: true,
       do: async (_input: { amount: number }, fx) => {
         await fx.step("reserve", async () => "reserved");
@@ -72,8 +71,7 @@ describe("durable compensate", () => {
   test("compensate does not run on successful path", async () => {
     let compensated = 0;
     const store = createMemoryJournalStore();
-    const ok = flow({
-      name: "pay.ok",
+    const ok = flow("pay.ok", {
       durable: true,
       do: async (_input, fx) => {
         await fx.step("a", () => "done");
@@ -103,8 +101,7 @@ describe("durable compensate", () => {
     await runs.open();
     const store = createMemoryJournalStore();
 
-    const boom = flow({
-      name: "pay.boom",
+    const boom = flow("pay.boom", {
       durable: true,
       do: async () => {
         throw new Error("boom");