okengine 0.10.1 → 0.10.3

package/src/docker/images-config.test.ts

@@ -0,0 +1,168 @@
+/**
+ * `ImagesConfig` (config surface, nested) → internal flat role map.
+ *
+ * Two guarantees:
+ * 1. Every built-in image recipe is reachable through the nested shape,
+ *    correctly placed under its owning element (or flat, for roles with no
+ *    driver counterpart) — the type-safety gap this closes.
+ * 2. A nested config produces byte-identical `deriveInfrastructure()` output
+ *    (Dockerfile / compose / stack env) to the flat-shape equivalent it
+ *    replaces — nesting is a config-surface change only, never an internal
+ *    representation change.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { flattenImagesConfig, type ImagesConfig } from "../config/index.ts";
+import { deriveInfrastructure } from "./derive.ts";
+import { builtinRecipes, recipeFor } from "./recipes/index.ts";
+import type { ServiceCredentials } from "./types.ts";
+
+describe("ImagesConfig nesting — recipe coverage", () => {
+  test("every built-in recipe id is reachable, correctly nested/flat by role", () => {
+    const cases: ReadonlyArray<{ images: ImagesConfig; role: string; image: string }> = [
+      // store.sql — postgres-family
+      {
+        images: { store: { sql: "postgres:18-alpine" } },
+        role: "store.sql",
+        image: "postgres:18-alpine",
+      },
+      {
+        images: { store: { sql: "cockroachdb/cockroach:v24.1.0" } },
+        role: "store.sql",
+        image: "cockroachdb/cockroach:v24.1.0",
+      },
+      {
+        images: { store: { sql: "yugabytedb/yugabyte:2024.1.0.0-b1" } },
+        role: "store.sql",
+        image: "yugabytedb/yugabyte:2024.1.0.0-b1",
+      },
+      {
+        images: { store: { sql: "timescale/timescaledb:2.15.0-pg16" } },
+        role: "store.sql",
+        image: "timescale/timescaledb:2.15.0-pg16",
+      },
+      {
+        images: { store: { sql: "supabase/postgres:15.1.0.117" } },
+        role: "store.sql",
+        image: "supabase/postgres:15.1.0.117",
+      },
+      // store.kv — redis-family
+      { images: { store: { kv: "redis:8-alpine" } }, role: "store.kv", image: "redis:8-alpine" },
+      {
+        images: { store: { kv: "valkey/valkey:8-alpine" } },
+        role: "store.kv",
+        image: "valkey/valkey:8-alpine",
+      },
+      {
+        images: { store: { kv: "docker.dragonflydb.io/dragonflydb/dragonfly:v1.24.0" } },
+        role: "store.kv",
+        image: "docker.dragonflydb.io/dragonflydb/dragonfly:v1.24.0",
+      },
+      // store.files / store.index
+      {
+        images: { store: { files: "rustfs/rustfs:1.0.0-beta.11" } },
+        role: "store.files",
+        image: "rustfs/rustfs:1.0.0-beta.11",
+      },
+      {
+        images: { store: { index: "getmeili/meilisearch:v1.37" } },
+        role: "store.index",
+        image: "getmeili/meilisearch:v1.37",
+      },
+      // channel.email
+      {
+        images: { channel: { email: "axllent/mailpit:v1.22.3" } },
+        role: "channel.email",
+        image: "axllent/mailpit:v1.22.3",
+      },
+      // flat roles — no driver counterpart in DriversConfig
+      {
+        images: { vault: "openbao/openbao:2.6.1" },
+        role: "vault",
+        image: "openbao/openbao:2.6.1",
+      },
+      {
+        images: { ai: "ghcr.io/ggml-org/llama.cpp:server-b10290" },
+        role: "ai",
+        image: "ghcr.io/ggml-org/llama.cpp:server-b10290",
+      },
+      { images: { ai: "vllm/vllm-openai:v0.26.0" }, role: "ai", image: "vllm/vllm-openai:v0.26.0" },
+      {
+        images: { ai: "lmsysorg/sglang:v0.5.16-runtime" },
+        role: "ai",
+        image: "lmsysorg/sglang:v0.5.16-runtime",
+      },
+      { images: { ai: "ollama/ollama:0.32.6" }, role: "ai", image: "ollama/ollama:0.32.6" },
+      {
+        images: { pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.51" },
+        role: "pgdog",
+        image: "ghcr.io/pgdogdev/pgdog:v0.1.51",
+      },
+      { images: { proxy: "caddy:2-alpine" }, role: "proxy", image: "caddy:2-alpine" },
+      { images: { proxy: "traefik:v3.1" }, role: "proxy", image: "traefik:v3.1" },
+    ];
+
+    const matchedIds = new Set<string>();
+    for (const { images, role, image } of cases) {
+      // The nested literal flattens to exactly the dotted/flat role key the
+      // rest of the pipeline (buildSpecs, credentials, env prefixes) expects.
+      expect(flattenImagesConfig(images)).toEqual({ [role]: image });
+      matchedIds.add(recipeFor(image).id);
+    }
+
+    expect(matchedIds).toEqual(new Set(builtinRecipes.map((r) => r.id)));
+  });
+});
+
+describe("ImagesConfig nesting — compose output parity", () => {
+  test("nested config derives byte-identical output to its flat-shape equivalent", () => {
+    const flatImages: Readonly<Record<string, string>> = {
+      "store.sql": "postgres:18-alpine",
+      pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.51",
+      "store.kv": "redis:8-alpine",
+      "store.files": "rustfs/rustfs:1.0.0-beta.11",
+      "channel.email": "axllent/mailpit:v1.22.3",
+      vault: "openbao/openbao:2.6.1",
+    };
+
+    const nestedImages: ImagesConfig = {
+      store: {
+        sql: "postgres:18-alpine",
+        kv: "redis:8-alpine",
+        files: "rustfs/rustfs:1.0.0-beta.11",
+      },
+      channel: { email: "axllent/mailpit:v1.22.3" },
+      vault: "openbao/openbao:2.6.1",
+      pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.51",
+    };
+
+    // Same nested→flat set, written in a different field order — proves the
+    // parity holds independent of source object key order.
+    expect(flattenImagesConfig(nestedImages)).toEqual(flatImages);
+
+    const credentials: Readonly<Record<string, ServiceCredentials>> = {
+      "store.sql": { user: "oke", password: "fixed-pw-sql", database: "oke" },
+      "store.kv": { user: "oke", password: "fixed-pw-kv", database: "oke" },
+      "store.files": { user: "oke", password: "fixed-pw-files", database: "oke" },
+      "channel.email": { user: "oke", password: "fixed-pw-email", database: "oke" },
+      vault: { user: "oke", password: "fixed-pw-vault", database: "oke" },
+      pgdog: { user: "oke", password: "fixed-pw-pgdog", database: "oke" },
+    };
+
+    const fromFlat = deriveInfrastructure({
+      images: flatImages,
+      app: "images-nesting-parity",
+      credentials,
+    });
+    const fromNested = deriveInfrastructure({
+      images: flattenImagesConfig(nestedImages),
+      app: "images-nesting-parity",
+      credentials,
+    });
+
+    expect(fromNested.specs).toEqual(fromFlat.specs);
+    expect(fromNested.files).toEqual(fromFlat.files);
+    expect(fromNested.stackEnv).toEqual(fromFlat.stackEnv);
+    expect(fromNested.composeFiles).toEqual(fromFlat.composeFiles);
+  });
+});

package/src/docker/recipes/llama-cpp.ts

@@ -221,7 +221,14 @@ def ensure_model(model: str) -> str:
 def main() -> None:
     model = (os.environ.get("OKE_AI_MODEL") or "smollm2").strip() or "smollm2"
     gguf = ensure_model(model)
-    print(f"oke ai: serving {model} from {gguf}", flush=True)
+    # Without an explicit --ctx-size, llama-server defaults to the model's
+    # full native training context (32K-256K+ for many current models). The
+    # KV cache for that is allocated up front and can be many times the
+    # model's own file size, OOM-killing the container even with generous
+    # Docker memory — independent of how small the model itself is.
+    # OKE_AI_CTX_SIZE (docker/.env.docker) overrides this default.
+    ctx_size = (os.environ.get("OKE_AI_CTX_SIZE") or "4096").strip() or "4096"
+    print(f"oke ai: serving {model} from {gguf} (ctx={ctx_size})", flush=True)
     os.execv(
         "/app/llama-server",
         [
@@ -234,6 +241,8 @@ def main() -> None:
             gguf,
             "--alias",
             model,
+            "--ctx-size",
+            ctx_size,
         ],
     )
 

package/src/docker/stack-id.ts

@@ -128,6 +128,7 @@ export const STACK_CONTROL_KEYS = [
   "MP_SMTP_AUTH_ACCEPT_ANY",
   "MP_SMTP_AUTH_ALLOW_INSECURE",
   "OKE_AI_MODEL",
+  "OKE_AI_CTX_SIZE",
   "OKE_PROXY_HOST",
   "OKE_PROXY_ACME_EMAIL",
   // OpenBao app token — minted by bootstrap, must survive `writeDerivedFiles`.

package/src/elements/channel/declare.ts

@@ -5,6 +5,7 @@
  */
 
 import type { ChannelMedium } from "../../manifest/types.ts";
+import { channelTemplateRegistry } from "../../kernel/element-registries.ts";
 
 /** Options for a medium binder (`channel.email`, …). */
 export interface ChannelMediumOptions {
@@ -49,6 +50,29 @@ export interface ChannelMediumBinder {
   ): ChannelTemplateDecl;
 }
 
+/**
+ * Medium binders' `.template()` (email / sms / whatsapp / push) push into
+ * the shared {@link channelTemplateRegistry} (`src/kernel/element-registries.ts`)
+ * so {@link oke} can auto-populate `channel.templates` with zero explicit
+ * array — mirrors the {@link on} trigger-drain registry
+ * (`src/kernel/on.ts`). The medium-agnostic `channel.template()` is
+ * intentionally not auto-registered (out of scope).
+ *
+ * Snapshot of every medium-binder template declared since the last reset.
+ */
+export function listChannelTemplates(): readonly ChannelTemplateDecl[] {
+  return channelTemplateRegistry.slice();
+}
+
+/**
+ * Clear the channel-template registry (tests / fresh app adopt).
+ *
+ * @internal
+ */
+export function resetChannelTemplates(): void {
+  channelTemplateRegistry.length = 0;
+}
+
 /**
  * Create a medium binder.
  *
@@ -64,7 +88,7 @@ function mediumBinder(
     medium,
     ...(from !== undefined ? { from } : {}),
     template(name, opts = {}) {
-      return {
+      const decl: ChannelTemplateDecl = {
         kind: "template",
         name,
         medium,
@@ -73,6 +97,8 @@ function mediumBinder(
         ...(opts.schema !== undefined ? { schema: opts.schema } : {}),
         ...(from !== undefined ? { from } : {}),
       };
+      channelTemplateRegistry.push(decl);
+      return decl;
     },
   };
 }

package/src/elements/clock/chaos-child.ts

@@ -169,8 +169,7 @@ if (mode === "tick-loop") {
   }
 
   const journalStore = createFileJournalStore(join(journalPath));
-  const charge = flow({
-    name: "chaos.charge",
+  const charge = flow("chaos.charge", {
     durable: true,
     do: async (_input, fx) => {
       const intent = await fx.step("create-intent", async () => {
@@ -329,8 +328,7 @@ async function logHasStep(path: string, step: string, instanceId: string): Promi
 
 /** Durable charge flow: step 1 → block → step 2 (both logged). */
 function chargeFlow(instanceId: string, stepLogPath: string, blockMs: number): AnyFlowDef {
-  return flow({
-    name: "chaos.journal.charge",
+  return flow("chaos.journal.charge", {
     durable: true,
     do: async (_input, fx) => {
       const intent = await fx.step("create-intent", async () => {
@@ -349,8 +347,7 @@ function chargeFlow(instanceId: string, stepLogPath: string, blockMs: number): A
 
 /** Durable sleeper flow: step 1 → sleep → confirm (steps logged). */
 function sleeperFlow(instanceId: string, stepLogPath: string, wakeMs: number): AnyFlowDef {
-  return flow({
-    name: "chaos.journal.sleeper",
+  return flow("chaos.journal.sleeper", {
     durable: true,
     do: async (_input, fx) => {
       await fx.step("create-intent", async () => {

package/src/elements/clock/chaos.test.ts

@@ -173,8 +173,7 @@ describe("chaos — SIGKILL durable mid-step", () => {
 
       const calls: string[] = [];
       const journalStore = createFileJournalStore(journalPath);
-      const charge = flow({
-        name: "chaos.charge",
+      const charge = flow("chaos.charge", {
         durable: true,
         do: async (_input, fx) => {
           const intent = await fx.step("create-intent", () => {

package/src/elements/clock.test.ts

@@ -67,8 +67,7 @@ describe("durable journal", () => {
     const tt = createTimeTravel(0);
     let crashAfterFirstStep = true;
 
-    const charge = flow({
-      name: "payments.charge",
+    const charge = flow("payments.charge", {
       durable: true,
       do: async (_input, fx) => {
         const intent = await fx.step("create-intent", () => {
@@ -118,8 +117,7 @@ describe("durable journal", () => {
     const tt = createTimeTravel(0);
 
     try {
-      const sleepy = flow({
-        name: "trial.wait",
+      const sleepy = flow("trial.wait", {
         durable: true,
         do: async (_input, fx) => {
           await fx.step("start", () => "begun");

package/src/elements/signal/declare.ts

@@ -6,6 +6,7 @@
  */
 
 import type { SignalDelivery } from "../../manifest/types.ts";
+import { signalRegistry } from "../../kernel/element-registries.ts";
 
 /** Options for {@link signal}. */
 export interface SignalOptions {
@@ -54,6 +55,27 @@ export interface SignalDecl<T = unknown> {
   readonly _payload?: T;
 }
 
+/**
+ * `signal()` pushes into the shared {@link signalRegistry}
+ * (`src/kernel/element-registries.ts`) so {@link oke} can auto-populate
+ * `signals` with zero explicit array — mirrors the {@link on} trigger-drain
+ * registry (`src/kernel/on.ts`).
+ *
+ * Snapshot of every signal declared since the last reset.
+ */
+export function listSignals(): readonly SignalDecl[] {
+  return signalRegistry.slice();
+}
+
+/**
+ * Clear the signal registry (tests / fresh app adopt).
+ *
+ * @internal
+ */
+export function resetSignals(): void {
+  signalRegistry.length = 0;
+}
+
 /**
  * Declare a signal. `delivery` is mandatory — omitting it is a type error.
  *
@@ -68,7 +90,7 @@ export function signal<T = unknown>(name: string, options: SignalOptions): Signa
   ) {
     throw new TypeError(`signal("${name}"): delivery is mandatory (once | broadcast | live)`);
   }
-  return {
+  const decl: SignalDecl<T> = {
     name,
     delivery: options.delivery,
     ...(options.description !== undefined ? { description: options.description } : {}),
@@ -77,4 +99,6 @@ export function signal<T = unknown>(name: string, options: SignalOptions): Signa
     schema: options.schema,
     optional: options.optional ?? false,
   };
+  signalRegistry.push(decl as SignalDecl);
+  return decl;
 }

package/src/elements/store/declare.ts

@@ -5,6 +5,7 @@
  */
 
 import type { ColumnClassification, ResourceRef, StoreFacet } from "../../manifest/types.ts";
+import { storeRegistry } from "../../kernel/element-registries.ts";
 import { resource } from "./resource.ts";
 import { schema } from "./schema-decl.ts";
 import { resolveTableName, type TableHandle } from "./table.ts";
@@ -114,6 +115,28 @@ export interface IndexStoreDecl extends StoreDeclBase {
 /** Any store declaration. */
 export type StoreDecl = SqlStoreDecl | KvStoreDecl | FilesStoreDecl | IndexStoreDecl;
 
+/**
+ * `store.sql` / `store.files` push into the shared {@link storeRegistry}
+ * (`src/kernel/element-registries.ts`) so {@link oke} can auto-populate
+ * `stores` with zero explicit array — mirrors the {@link on} trigger-drain
+ * registry (`src/kernel/on.ts`). `store.kv` / `store.index` are
+ * intentionally not auto-registered (out of scope).
+ *
+ * Snapshot of every `store.sql` / `store.files` declared since the last reset.
+ */
+export function listStores(): readonly StoreDecl[] {
+  return storeRegistry.slice();
+}
+
+/**
+ * Clear the store registry (tests / fresh app adopt).
+ *
+ * @internal
+ */
+export function resetStores(): void {
+  storeRegistry.length = 0;
+}
+
 /**
  * Declare a SQL store.
  *
@@ -140,6 +163,7 @@ export function sql(name: string, options: SqlStoreOptions = {}): SqlStoreDecl {
       };
     },
   };
+  storeRegistry.push(decl);
   return decl;
 }
 
@@ -165,12 +189,14 @@ export function kv(name: string, options: KvStoreOptions = {}): KvStoreDecl {
  * @param options - Options
  */
 export function files(name: string, options: FilesStoreOptions = {}): FilesStoreDecl {
-  return {
+  const decl: FilesStoreDecl = {
     facet: "files",
     name,
     ref: `files:${name}`,
     ...(options.description !== undefined ? { description: options.description } : {}),
   };
+  storeRegistry.push(decl);
+  return decl;
 }
 
 /**

package/src/elements/store/resource.ts

@@ -1,7 +1,7 @@
 /**
  * `store.resource(db, table, opts)` — a CRUD + list resource factory.
  *
- * Declarative sugar, never new physics: every op is an ordinary `flow({…})`
+ * Declarative sugar, never new physics: every op is an ordinary `flow(name, {…})`
  * whose body composes `fx.store(db)` (select/insert/update/findById/delete +
  * `page`/`count`) through the existing Drizzle-condition compiler. Wire
  * binding stays in `on(http.resource(path, resource.all()))` — the factory
@@ -649,8 +649,7 @@ export function resource(db: SqlStoreDecl, table: unknown, options: ResourceOpti
     return { data, meta };
   }
 
-  const listFlow = flow({
-    name: "list",
+  const listFlow = flow("list", {
     unit,
     ...(breaking ? { breaking: true as const } : {}),
     // Loose record so the HTTP AoT infers `query` and lets every list URL
@@ -664,8 +663,7 @@ export function resource(db: SqlStoreDecl, table: unknown, options: ResourceOpti
     },
   });
 
-  const createFlow = flow({
-    name: "create",
+  const createFlow = flow("create", {
     unit,
     ...(breaking ? { breaking: true as const } : {}),
     in: options.in as never,
@@ -682,8 +680,7 @@ export function resource(db: SqlStoreDecl, table: unknown, options: ResourceOpti
     },
   });
 
-  const getFlow = flow({
-    name: "get",
+  const getFlow = flow("get", {
     unit,
     ...(breaking ? { breaking: true as const } : {}),
     errors,
@@ -709,8 +706,7 @@ export function resource(db: SqlStoreDecl, table: unknown, options: ResourceOpti
       : patchSchema instanceof z.ZodObject
         ? patchSchema.extend({ [idKey]: z.string() })
         : patchSchema;
-  const updateFlow = flow({
-    name: "update",
+  const updateFlow = flow("update", {
     unit,
     ...(breaking ? { breaking: true as const } : {}),
     in: updateIn as never,
@@ -736,8 +732,7 @@ export function resource(db: SqlStoreDecl, table: unknown, options: ResourceOpti
     },
   });
 
-  const removeFlow = flow({
-    name: "remove",
+  const removeFlow = flow("remove", {
     unit,
     ...(breaking ? { breaking: true as const } : {}),
     errors,

package/src/elements/store/upsert-app.test.ts

@@ -46,8 +46,7 @@ describe("fx.store(db).upsert via app.fetch (real boot)", () => {
 
     const seed = on(
       http.post("/seed").gate(gate.public),
-      flow({
-        name: "notes.seed",
+      flow("notes.seed", {
         in: UpsertIn,
         out: UpsertOut,
         effects: { writes: ["sql:app"], reads: ["sql:app"] },

package/src/elements/vault/declare.ts

@@ -4,6 +4,8 @@
  * Physics: secrets · config · environment.
  */
 
+import { secretRegistry } from "../../kernel/element-registries.ts";
+
 /** Options for {@link vault} / {@link vault.secret} / {@link vault.config}. */
 export interface VaultSecretOptions {
   /** Human description shown in boot-gap listings. */
@@ -35,6 +37,30 @@ export interface VaultSecretDecl {
   readonly sensitive: boolean;
 }
 
+/**
+ * `vault.secret` (only) pushes into the shared {@link secretRegistry}
+ * (`src/kernel/element-registries.ts`) so {@link oke} can auto-populate
+ * `secrets` with zero explicit array — mirrors the {@link on} trigger-drain
+ * registry (`src/kernel/on.ts`). `vault.config` is intentionally not
+ * auto-registered (out of scope).
+ */
+
+/**
+ * Snapshot of every `vault.secret` declared since the last reset.
+ */
+export function listSecrets(): readonly VaultSecretDecl[] {
+  return secretRegistry.slice();
+}
+
+/**
+ * Clear the vault-secret registry (tests / fresh app adopt).
+ *
+ * @internal
+ */
+export function resetSecrets(): void {
+  secretRegistry.length = 0;
+}
+
 /**
  * Declare a vault secret contract (fingerprinted — never revealed).
  *
@@ -45,7 +71,7 @@ function declareSecret(name: string, options: VaultSecretOptions = {}): VaultSec
   if (!name) {
     throw new TypeError("vault.secret: name is required");
   }
-  return {
+  const decl: VaultSecretDecl = {
     kind: "secret",
     name,
     sensitive: options.sensitive ?? true,
@@ -54,6 +80,8 @@ function declareSecret(name: string, options: VaultSecretOptions = {}): VaultSec
     ...(options.schema !== undefined ? { schema: options.schema } : {}),
     ...(options.dev !== undefined ? { dev: options.dev } : {}),
   };
+  secretRegistry.push(decl);
+  return decl;
 }
 
 /**

package/src/kernel/adopt-barrel-fresh.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Boot-level proof: a `src/flows/<unit>` folder on disk with no adopted
+ * flow under that unit — the stale/missing `.adopt()` barrel case.
+ *
+ * Mirrors `effects-stamping.test.ts`'s OKE1008 shape exactly: opt-in only
+ * via `rootDir`, `local`/`test` warn once (dev-loop stays unbroken),
+ * `docker`/`prod` hard-fail (`OKE1009`) — never a silently-incomplete route
+ * table in a deploy-shaped environment.
+ */
+
+import { afterEach, 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 { gate } from "../elements/gate.ts";
+import { assertAdoptBarrelFresh, resetStaleAdoptBarrelWarnForTests } from "./boot.ts";
+import { flow, resetFlowSeq } from "./flow.ts";
+import { on, resetBindings } from "./on.ts";
+import { http } from "./triggers.ts";
+import { oke } from "./app.ts";
+
+afterEach(() => {
+  resetBindings();
+  resetFlowSeq();
+  resetStaleAdoptBarrelWarnForTests();
+});
+
+async function makeUnitDir(root: string, unit: string): Promise<void> {
+  const dir = join(root, "src/flows", unit);
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, "index.ts"), "export const nothing = 1;\n");
+}
+
+describe("assertAdoptBarrelFresh — direct", () => {
+  test("no rootDir: no-op, never reads the filesystem", async () => {
+    await expect(assertAdoptBarrelFresh([], "prod", undefined)).resolves.toBeUndefined();
+  });
+
+  test("fresh: every disk unit has an adopted flow — no warn, no throw, any env", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oke-adopt-fresh-"));
+    try {
+      await makeUnitDir(root, "notes");
+      const notesFlow = flow("notes.create", { do: () => ({ ok: true as const }) });
+      await expect(assertAdoptBarrelFresh([notesFlow], "docker", root)).resolves.toBeUndefined();
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("stale: unit on disk, zero adopted flows for it — docker hard-fails OKE1009", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oke-adopt-fresh-"));
+    try {
+      await makeUnitDir(root, "notes");
+      await expect(assertAdoptBarrelFresh([], "docker", root)).rejects.toThrow(/OKE1009/);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("stale: prod — same posture as docker", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oke-adopt-fresh-"));
+    try {
+      await makeUnitDir(root, "notes");
+      await expect(assertAdoptBarrelFresh([], "prod", root)).rejects.toThrow(/OKE1009/);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("stale: local — warns, never throws (dev-loop stays unbroken)", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oke-adopt-fresh-"));
+    try {
+      await makeUnitDir(root, "notes");
+      await expect(assertAdoptBarrelFresh([], "local", root)).resolves.toBeUndefined();
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("boot-level: stale barrel through a real oke() boot", () => {
+  test("docker: real app.boot() hard-fails OKE1009 when a unit folder was never adopted", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oke-adopt-fresh-"));
+    try {
+      // "notes" exists on disk but this app only ever adopted "main" —
+      // exactly what a stale `src/flows/generated.ts` after adding a unit
+      // (and forgetting to rerun `oke dev` / `oke build`) looks like.
+      await makeUnitDir(root, "notes");
+      const mainFlow = flow("main.health", {
+        effects: {},
+        do: () => ({ ok: true as const }),
+      });
+      on(http.get("/health").gate(gate.public), mainFlow);
+      const app = oke({ name: "stale-barrel", gate: { unguardedHttp: "allow" } });
+
+      await expect(
+        app.boot({ env: "docker", rootDir: root, unguardedHttp: "allow", startScheduler: false }),
+      ).rejects.toThrow(/OKE1009/);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});