okengine 0.10.3 → 0.11.0

package/src/docker/index.ts

@@ -3,12 +3,14 @@
  *
  * Recipes translate a normalised {@link ServiceSpec} into image-specific
  * env / command / healthcheck and expose {@link ImageRecipe.url} so the
- * kernel never learns an env-var name. Four compose override layers end
- * in an untouched `compose.override.yml`. Credentials never enter YAML.
+ * kernel never learns an env-var name. Default layout is a single
+ * production-grade `docker-compose.yml` (opt-in `--split` / `--stack`).
+ * Credentials never enter YAML.
  */
 
 export type {
   ComposeHealthcheck,
+  ComposeLayout,
   DeriveOptions,
   DeriveResult,
   GeneratedFile,
@@ -26,7 +28,11 @@ export { DEFAULT_DOCKER_DIR } from "./types.ts";
 
 export {
   COMPOSE_ALL,
+  COMPOSE_BASE,
   COMPOSE_OVERRIDE,
+  DOCKER_COMPOSE,
+  DOCKER_COMPOSE_OVERRIDE,
+  DOCKER_STACK,
   assertNoCredentialsInYaml,
   buildSpecs,
   buildStackEnv,
@@ -36,9 +42,24 @@ export {
   formatStackEnv,
 } from "./compose.ts";
 
+export {
+  DEFAULT_SERVER_BUDGET,
+  allocateServiceResources,
+  mergeDeployResources,
+  resolveServerBudget,
+  type ServerBudget,
+  type ServiceResourceLimit,
+} from "./resources.ts";
+
 export { deriveInfrastructure, writeDerivedFiles } from "./derive.ts";
 export { emitDockerfile } from "./dockerfile.ts";
-export { credEnv, envPrefix, serviceNameFor } from "./helpers.ts";
+export {
+  composeToYaml,
+  credEnv,
+  envPrefix,
+  serviceNameFor,
+  type ComposeYamlOptions,
+} from "./helpers.ts";
 export { generateCredentials } from "./credentials.ts";
 export {
   ensureOllamaModel,
@@ -92,7 +113,6 @@ export {
   ollama,
   OLLAMA_IMAGE,
   OLLAMA_MIN_SAFE_VERSION,
-  openbao,
   pgdog,
   postgres,
   recipeFor,
@@ -108,7 +128,12 @@ export {
   yugabyte,
 } from "./recipes/index.ts";
 export { CADDY_APP_SERVICE, buildCaddyfile } from "./recipes/caddy.ts";
-export { PGDOG_BACKEND_SERVICE, buildPgDogToml, buildPgDogUsersToml } from "./recipes/pgdog.ts";
+export {
+  PGDOG_BACKEND_SERVICE,
+  PGDOG_CONFIG_DIR,
+  buildPgDogToml,
+  buildPgDogUsersToml,
+} from "./recipes/pgdog.ts";
 export { SOCKET_PROXY_IMAGE, SOCKET_PROXY_SERVICE, traefikAppLabels } from "./recipes/traefik.ts";
 export {
   formatStackPreview,

package/src/docker/recipes/index.ts

@@ -10,7 +10,6 @@ import { llamaCpp } from "./llama-cpp.ts";
 import { mailpit } from "./mailpit.ts";
 import { meilisearch } from "./meilisearch.ts";
 import { ollama } from "./ollama.ts";
-import { openbao } from "./openbao.ts";
 import { pgdog } from "./pgdog.ts";
 import { postgres } from "./postgres.ts";
 import { redis } from "./redis.ts";
@@ -36,7 +35,6 @@ export const builtinRecipes: readonly ImageRecipe[] = [
   redis,
   mailpit,
   rustfs,
-  openbao,
   meilisearch,
   llamaCpp,
   vllm,
@@ -54,7 +52,6 @@ export {
   mailpit,
   meilisearch,
   ollama,
-  openbao,
   pgdog,
   postgres,
   redis,

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

@@ -55,7 +55,7 @@ def cache_dir() -> str:
 
 
 def parse_model(model: str) -> tuple[str, str]:
-    raw = model.strip() or "smollm2"
+    raw = model.strip() or "granite3.3:2b"
     if "/" not in raw.split(":", 1)[0]:
         raw = f"ai/{raw}"
     if ":" in raw:
@@ -187,7 +187,7 @@ def hub_pull(repo: str, tag: str, dest: str) -> None:
 def ensure_model(model: str) -> str:
     repo, tag = parse_model(model)
     # llama download -dr expects id without forced ai/ prefix when using default org.
-    dr = model.strip() or "smollm2"
+    dr = model.strip() or "granite3.3:2b"
     if dr.startswith("ai/"):
         dr = dr[3:]
     dest = os.path.join(cache_dir(), expected_gguf(repo, tag))
@@ -219,7 +219,7 @@ def ensure_model(model: str) -> str:
 
 
 def main() -> None:
-    model = (os.environ.get("OKE_AI_MODEL") or "smollm2").strip() or "smollm2"
+    model = (os.environ.get("OKE_AI_MODEL") or "granite3.3:2b").strip() or "granite3.3:2b"
     gguf = ensure_model(model)
     # Without an explicit --ctx-size, llama-server defaults to the model's
     # full native training context (32K-256K+ for many current models). The
@@ -259,7 +259,7 @@ export const llamaCpp: ImageRecipe = {
   match: (i) => /llama\.cpp|llamacpp/i.test(i),
   apply: (s) => ({
     // OKE_AI_MODEL comes from compose `env_file` (`.env.docker`). Do not
-    // re-declare it as `${OKE_AI_MODEL:-smollm2}` here — Compose interpolates
+    // re-declare it as `${OKE_AI_MODEL:-granite3.3:2b}` here — Compose interpolates
     // that from the *host* shell and can override the stack file with the
     // default. Never set LLAMA_ARG_MODELS_PRESET / LLAMA_ARG_DOCKER_REPO
     // (router children inherit `LLAMA_ARG_*` and can OOM).

package/src/docker/recipes/pgdog.ts

@@ -3,10 +3,14 @@
  *
  * Sits in front of the `postgres` recipe. Transaction pooling is set
  * explicitly (`pooler_mode = "transaction"` — also PgDog's upstream default).
- * Config shape matches upstream docs: `pgdog.toml` + `users.toml`
+ * Config shape matches upstream docs under `pgdog/`:
+ * `pgdog/pgdog.toml` + `pgdog/users.toml`
  * (https://docs.pgdog.dev/configuration/).
  */
 
+/** Relative directory for generated PgDog TOML (under the compose dir). */
+export const PGDOG_CONFIG_DIR = "pgdog";
+
 import type { ImageRecipe } from "../types.ts";
 
 /** Backend Postgres service name in the compose network. */
@@ -66,7 +70,10 @@ export const pgdog: ImageRecipe = {
   port: 6432,
   match: (i) => /pgdog/i.test(i),
   apply: () => ({
-    volumes: ["./pgdog.toml:/pgdog/pgdog.toml:ro", "./users.toml:/pgdog/users.toml:ro"],
+    volumes: [
+      `./${PGDOG_CONFIG_DIR}/pgdog.toml:/pgdog/pgdog.toml:ro`,
+      `./${PGDOG_CONFIG_DIR}/users.toml:/pgdog/users.toml:ro`,
+    ],
     dependsOn: {
       [PGDOG_BACKEND_SERVICE]: { condition: "service_healthy" },
     },

package/src/docker/resources.test.ts

@@ -0,0 +1,71 @@
+/**
+ * Server budget → per-service resource allocation.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  DEFAULT_SERVER_BUDGET,
+  allocateServiceResources,
+  mergeDeployResources,
+  resolveServerBudget,
+} from "./resources.ts";
+
+describe("resolveServerBudget", () => {
+  test("defaults to 4 CPU / 8 GiB", () => {
+    expect(resolveServerBudget(undefined)).toEqual(DEFAULT_SERVER_BUDGET);
+    expect(DEFAULT_SERVER_BUDGET).toEqual({ cpus: 4, memoryGb: 8 });
+  });
+
+  test("accepts client overrides", () => {
+    expect(resolveServerBudget({ cpus: 8, memoryGb: 16 })).toEqual({
+      cpus: 8,
+      memoryGb: 16,
+    });
+  });
+});
+
+describe("allocateServiceResources", () => {
+  test("apportion 4/8 across app + sql + kv without exceeding the usable pool", () => {
+    const limits = allocateServiceResources(["app", "store-sql", "store-kv"], {
+      cpus: 4,
+      memoryGb: 8,
+    });
+    expect(limits.size).toBe(3);
+    let cpuSum = 0;
+    let memSum = 0;
+    for (const limit of limits.values()) {
+      cpuSum += Number(limit.cpus);
+      memSum += limit.memory.endsWith("G")
+        ? Number(limit.memory.slice(0, -1)) * 1024
+        : Number(limit.memory.slice(0, -1));
+    }
+    // 10% host overhead → usable 3.6 CPU / ~7372 MiB
+    expect(cpuSum).toBeLessThanOrEqual(3.6 + 0.05);
+    expect(memSum).toBeLessThanOrEqual(8 * 1024 * 0.9 + 8);
+    expect(Number(limits.get("store-sql")!.cpus)).toBeGreaterThan(
+      Number(limits.get("store-kv")!.cpus),
+    );
+  });
+
+  test("mergeDeployResources preserves GPU reservations", () => {
+    const merged = mergeDeployResources(
+      { cpus: "1.5", memory: "2G" },
+      {
+        resources: {
+          reservations: {
+            devices: [{ driver: "nvidia", count: 1, capabilities: ["gpu"] }],
+          },
+        },
+      },
+    );
+    const resources = merged.resources as {
+      limits: { cpus: string; memory: string };
+      reservations: { devices: unknown[]; cpus: string; memory: string };
+    };
+    expect(resources.limits).toEqual({ cpus: "1.5", memory: "2G" });
+    expect(resources.reservations.devices).toEqual([
+      { driver: "nvidia", count: 1, capabilities: ["gpu"] },
+    ]);
+    expect(resources.reservations.cpus).toBe("0.75");
+  });
+});

package/src/docker/resources.ts

@@ -0,0 +1,176 @@
+/**
+ * Server resource budget → per-service Compose `deploy.resources` limits.
+ *
+ * Defaults assume a small production host (4 CPU / 8 GiB). Callers may override
+ * via {@link ServerBudget}. ~10% stays unallocated for the Docker daemon / OS.
+ */
+
+/** Host capacity used when apportioning container limits. */
+export type ServerBudget = {
+  /** Logical CPUs available to the stack (default 4). */
+  readonly cpus: number;
+  /** RAM in GiB available to the stack (default 8). */
+  readonly memoryGb: number;
+};
+
+/** Default production host size when the client does not specify one. */
+export const DEFAULT_SERVER_BUDGET: ServerBudget = {
+  cpus: 4,
+  memoryGb: 8,
+};
+
+/** Fraction of the host reserved for Docker / OS (not given to services). */
+const HOST_OVERHEAD = 0.1;
+
+/** Relative weights by compose role — heavier roles get a larger share. */
+const ROLE_WEIGHT: Readonly<Record<string, number>> = {
+  app: 20,
+  "store.sql": 30,
+  pgdog: 5,
+  "store.kv": 15,
+  "store.files": 10,
+  "store.index": 10,
+  "channel.email": 5,
+  ai: 40,
+  proxy: 5,
+};
+
+const DEFAULT_WEIGHT = 10;
+const MIN_CPUS = 0.1;
+const MIN_MEMORY_MB = 64;
+
+/** Resolved CPU + memory limit for one compose service. */
+export type ServiceResourceLimit = {
+  readonly cpus: string;
+  readonly memory: string;
+};
+
+/**
+ * Normalise a partial budget against {@link DEFAULT_SERVER_BUDGET}.
+ *
+ * @param budget - Optional caller overrides
+ */
+export function resolveServerBudget(budget: Partial<ServerBudget> | undefined): ServerBudget {
+  const cpus = budget?.cpus ?? DEFAULT_SERVER_BUDGET.cpus;
+  const memoryGb = budget?.memoryGb ?? DEFAULT_SERVER_BUDGET.memoryGb;
+  if (!(cpus > 0) || !Number.isFinite(cpus)) {
+    throw new Error(
+      `oke docker: server cpus must be a positive number (got ${String(budget?.cpus)})`,
+    );
+  }
+  if (!(memoryGb > 0) || !Number.isFinite(memoryGb)) {
+    throw new Error(
+      `oke docker: server memoryGb must be a positive number (got ${String(budget?.memoryGb)})`,
+    );
+  }
+  return { cpus, memoryGb };
+}
+
+/**
+ * Apportion a server budget across named services (compose service names).
+ *
+ * @param serviceNames - Services that receive limits (`app`, `store-sql`, …)
+ * @param budget - Host capacity
+ * @returns Map of service name → deploy.resources.limits fields
+ */
+export function allocateServiceResources(
+  serviceNames: readonly string[],
+  budget: Partial<ServerBudget> | undefined = undefined,
+): ReadonlyMap<string, ServiceResourceLimit> {
+  const resolved = resolveServerBudget(budget);
+  const usableCpus = resolved.cpus * (1 - HOST_OVERHEAD);
+  const usableMemoryMb = resolved.memoryGb * 1024 * (1 - HOST_OVERHEAD);
+
+  const weights = serviceNames.map((name) => {
+    const role = serviceNameToRole(name);
+    return ROLE_WEIGHT[role] ?? DEFAULT_WEIGHT;
+  });
+  const total = weights.reduce((a, b) => a + b, 0);
+  const out = new Map<string, ServiceResourceLimit>();
+  if (total <= 0 || serviceNames.length === 0) return out;
+
+  for (let i = 0; i < serviceNames.length; i++) {
+    const name = serviceNames[i]!;
+    const share = weights[i]! / total;
+    const cpus = Math.max(MIN_CPUS, roundCpus(usableCpus * share));
+    const memoryMb = Math.max(MIN_MEMORY_MB, Math.round(usableMemoryMb * share));
+    out.set(name, {
+      cpus: formatCpus(cpus),
+      memory: formatMemoryMb(memoryMb),
+    });
+  }
+  return out;
+}
+
+/**
+ * Build a Compose `deploy.resources` block from a limit, preserving any
+ * existing reservations (e.g. GPU devices from AI recipes).
+ *
+ * @param limit - Allocated CPU / memory
+ * @param existing - Prior `deploy` object from a recipe, if any
+ */
+export function mergeDeployResources(
+  limit: ServiceResourceLimit,
+  existing: Readonly<Record<string, unknown>> | undefined,
+): Record<string, unknown> {
+  const prev = existing ? { ...existing } : {};
+  const prevResources = isPlainObject(prev.resources)
+    ? { ...prev.resources }
+    : ({} as Record<string, unknown>);
+  const prevLimits = isPlainObject(prevResources.limits)
+    ? { ...prevResources.limits }
+    : ({} as Record<string, unknown>);
+  prevResources.limits = {
+    ...prevLimits,
+    cpus: limit.cpus,
+    memory: limit.memory,
+  };
+  // Soft reservation ≈ half the limit so the scheduler can pack peers.
+  const prevReservations = isPlainObject(prevResources.reservations)
+    ? { ...prevResources.reservations }
+    : ({} as Record<string, unknown>);
+  if (prevReservations.cpus === undefined) {
+    prevReservations.cpus = formatCpus(Math.max(MIN_CPUS, Number(limit.cpus) * 0.5));
+  }
+  if (prevReservations.memory === undefined) {
+    prevReservations.memory = formatMemoryMb(
+      Math.max(MIN_MEMORY_MB, Math.round(parseMemoryMb(limit.memory) * 0.5)),
+    );
+  }
+  prevResources.reservations = prevReservations;
+  prev.resources = prevResources;
+  return prev;
+}
+
+function serviceNameToRole(serviceName: string): string {
+  if (serviceName === "app") return "app";
+  return serviceName.replaceAll("-", ".");
+}
+
+function roundCpus(n: number): number {
+  return Math.round(n * 100) / 100;
+}
+
+function formatCpus(n: number): string {
+  return String(Math.round(n * 100) / 100);
+}
+
+function formatMemoryMb(mb: number): string {
+  if (mb >= 1024 && mb % 1024 === 0) return `${mb / 1024}G`;
+  if (mb >= 1024) {
+    const gb = Math.round((mb / 1024) * 100) / 100;
+    return `${gb}G`;
+  }
+  return `${mb}M`;
+}
+
+function parseMemoryMb(value: string): number {
+  const m = /^(\d+(?:\.\d+)?)(G|M)$/i.exec(value);
+  if (!m) return MIN_MEMORY_MB;
+  const n = Number(m[1]);
+  return m[2]!.toUpperCase() === "G" ? n * 1024 : n;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/src/docker/stack-id.test.ts

@@ -63,11 +63,18 @@ describe("loadExistingStackControls", () => {
     expect(controls?.OKE_AI_MODEL).toBe("gemma4:e4b-q4_K_M");
   });
 
+  test("seeds commented OKE_AI_MODEL from .env.local when .env.docker omits it", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-stack-ai-"));
+    await writeFile(join(dir, ".env.local"), "# OKE_AI_MODEL=gemma4:e4b-q4_K_M\n", "utf8");
+    const controls = await loadExistingStackControls(dir);
+    expect(controls?.OKE_AI_MODEL).toBe("gemma4:e4b-q4_K_M");
+  });
+
   test("prefers active OKE_AI_MODEL in docker/.env.docker over .env.local", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-stack-ai-"));
     await mkdir(join(dir, "docker"), { recursive: true });
     await writeFile(join(dir, "docker", ".env.docker"), "OKE_AI_MODEL=smollm2\n", "utf8");
-    await writeFile(join(dir, ".env.local"), "OKE_AI_MODEL=gemma4:e4b-q4_K_M\n", "utf8");
+    await writeFile(join(dir, ".env.local"), "# OKE_AI_MODEL=gemma4:e4b-q4_K_M\n", "utf8");
     const controls = await loadExistingStackControls(dir);
     expect(controls?.OKE_AI_MODEL).toBe("smollm2");
   });
@@ -132,7 +139,7 @@ describe("deriveInfrastructure instanceId", () => {
         },
       },
     });
-    const base = result.files.find((f) => f.path === "compose.yml")!.content;
+    const base = result.files.find((f) => f.path === "docker-compose.yml")!.content;
     expect(base).toContain("oke-dev-abcdef");
     expect(result.stackEnv.DATABASE_URL).toMatch(/:15\d{3}\//);
     expect(result.stackEnv.REDIS_URL).toMatch(/:16\d{3}/);
@@ -163,8 +170,8 @@ describe("deriveInfrastructure instanceId", () => {
         },
       },
     });
-    const mailYml = result.files.find((f) => f.path === "compose.channel.email.yml")!.content;
-    const filesYml = result.files.find((f) => f.path === "compose.store.files.yml")!.content;
+    const mailYml = result.files.find((f) => f.path === "docker-compose.yml")!.content;
+    const filesYml = mailYml;
     expect(mailYml).toContain(`${20_000 + n}:1025`);
     expect(mailYml).toContain(`${21_000 + n}:8025`);
     expect(mailYml).not.toContain("8025:8025");

package/src/docker/stack-id.ts

@@ -131,9 +131,6 @@ export const STACK_CONTROL_KEYS = [
   "OKE_AI_CTX_SIZE",
   "OKE_PROXY_HOST",
   "OKE_PROXY_ACME_EMAIL",
-  // OpenBao app token — minted by bootstrap, must survive `writeDerivedFiles`.
-  "OKE_VAULT_TOKEN",
-  "OKE_VAULT_MOUNT",
 ] as const;
 
 /**
@@ -176,9 +173,6 @@ export async function loadExistingStackCredentials(
 /**
  * Load optional controls from `docker/.env.docker` when present.
  *
- * Falls back to `.oke/openbao/app.token` for `OKE_VAULT_TOKEN` when the env
- * file was regenerated without the bootstrap overlay (per-project token).
- *
  * @param cwd - Project root
  */
 export async function loadExistingStackControls(
@@ -192,31 +186,17 @@ export async function loadExistingStackControls(
     controls = parseStackControls(await file.text());
     break;
   }
-  // create-oke / `oke ai setup` write the chosen model into `.env.local`.
-  // Seed it into stack controls on first docker boot so `LLAMA_ARG_DOCKER_REPO`
-  // is not stuck on the recipe default (`smollm2`).
+  // create-oke / `oke ai setup` write the chosen model into `.env.local` as a
+  // commented hint (active would shadow `docker/.env.docker`). Seed active or
+  // commented `OKE_AI_MODEL` on first docker boot so `LLAMA_ARG_DOCKER_REPO`
+  // is not stuck on the recipe default (`granite3.3:2b`).
   if (!controls.OKE_AI_MODEL) {
     const localEnv = Bun.file(resolve(cwd, ".env.local"));
     if (await localEnv.exists()) {
-      const model = parseDotenv(await localEnv.text())
-        .get("OKE_AI_MODEL")
-        ?.trim();
+      const model = readEnvAssignment(await localEnv.text(), "OKE_AI_MODEL");
       if (model) controls = { ...controls, OKE_AI_MODEL: model };
     }
   }
-  if (!controls.OKE_VAULT_TOKEN) {
-    const tokenFile = Bun.file(resolve(cwd, ".oke", "openbao", "app.token"));
-    if (await tokenFile.exists()) {
-      const token = (await tokenFile.text()).trim();
-      if (token) {
-        controls = {
-          ...controls,
-          OKE_VAULT_TOKEN: token,
-          OKE_VAULT_MOUNT: controls.OKE_VAULT_MOUNT ?? "secret",
-        };
-      }
-    }
-  }
   return Object.keys(controls).length > 0 ? controls : undefined;
 }
 
@@ -228,14 +208,44 @@ function parseDotenv(text: string): Map<string, string> {
     const eq = trimmed.indexOf("=");
     if (eq <= 0) continue;
     const key = trimmed.slice(0, eq);
-    let value = trimmed.slice(eq + 1);
-    if (
-      (value.startsWith('"') && value.endsWith('"')) ||
-      (value.startsWith("'") && value.endsWith("'"))
-    ) {
-      value = value.slice(1, -1);
-    }
+    const value = unquoteEnvValue(trimmed.slice(eq + 1));
     map.set(key, value);
   }
   return map;
 }
+
+/**
+ * Read `KEY=value` from dotenv text — active line wins; otherwise the last
+ * `# KEY=value` hint (create-oke / `oke ai setup` leave AI stack keys commented).
+ *
+ * @param text - Dotenv contents
+ * @param key - Variable name
+ */
+function readEnvAssignment(text: string, key: string): string | undefined {
+  const active = parseDotenv(text).get(key)?.trim();
+  if (active) return active;
+  let hinted: string | undefined;
+  const prefix = `# ${key}=`;
+  const altPrefix = `#${key}=`;
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith(prefix)) {
+      hinted = unquoteEnvValue(trimmed.slice(prefix.length));
+    } else if (trimmed.startsWith(altPrefix)) {
+      hinted = unquoteEnvValue(trimmed.slice(altPrefix.length));
+    }
+  }
+  const value = hinted?.trim();
+  return value || undefined;
+}
+
+function unquoteEnvValue(raw: string): string {
+  let value = raw;
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    value = value.slice(1, -1);
+  }
+  return value;
+}

package/src/docker/stack.integration.test.ts

@@ -55,8 +55,8 @@ describe("oke dev --docker postgres integration", () => {
           writeStackEnv: true,
         });
 
-        // Infra-only: network + role compose (no app build).
-        const composeFiles = ["compose.yml", "compose.store.sql.yml"];
+        // Infra-only: single docker-compose.yml (no app build).
+        const composeFiles = ["docker-compose.yml"];
         const up = Bun.spawn(
           [
             "docker",
@@ -122,24 +122,13 @@ describe("oke dev --docker postgres integration", () => {
         }
 
         // Prove credentials live in docker/.env.docker, not YAML.
-        const yml = await Bun.file(join(dockerDir, "compose.store.sql.yml")).text();
+        const yml = await Bun.file(join(dockerDir, "docker-compose.yml")).text();
         expect(yml).not.toContain("stack-integration-pass");
         expect(formatStackEnv(derived.stackEnv)).toContain("stack-integration-pass");
         expect(await Bun.file(join(dockerDir, ".env.docker")).exists()).toBe(true);
       } finally {
         await Bun.spawn(
-          [
-            "docker",
-            "compose",
-            "-p",
-            project,
-            "-f",
-            "compose.yml",
-            "-f",
-            "compose.store.sql.yml",
-            "down",
-            "-v",
-          ],
+          ["docker", "compose", "-p", project, "-f", "docker-compose.yml", "down", "-v"],
           { cwd: dockerDir, stdout: "pipe", stderr: "pipe" },
         ).exited.catch(() => {});
         await rm(dir, { recursive: true, force: true }).catch(() => {});

package/src/docker/types.ts

@@ -132,6 +132,15 @@ export interface ImageRecipe {
   url(spec: ServiceSpec, endpoint: ServiceEndpoint): string;
 }
 
+/**
+ * How derived compose artefacts are laid out under {@link DeriveOptions.composeDir}.
+ *
+ * - `single` (default) — one production-grade `docker-compose.yml`
+ * - `split` — `compose.yml` + per-role `compose.<role>.yml` (+ `compose.prod.yml` when prod)
+ * - `stack` — one Swarm-oriented `docker-stack.yml`
+ */
+export type ComposeLayout = "single" | "split" | "stack";
+
 /** Options for compose / Dockerfile derivation. */
 export interface DeriveOptions {
   /** Role → image pin (from `oke.config.ts` / Manifest). */
@@ -140,10 +149,30 @@ export interface DeriveOptions {
   readonly app?: string;
   /** App listen port (default 6530). */
   readonly appPort?: number;
-  /** When true, emit prod overlays (limits, secret refs, deploy.replicas). */
+  /**
+   * When true, fold production readiness (`/_/ready` HEALTHCHECK, deploy,
+   * restart policy, secret refs) and apportion {@link serverCpus} /
+   * {@link serverMemoryGb} across services. `oke docker` defaults true;
+   * `oke dev --docker` keeps false.
+   */
   readonly prod?: boolean;
   /**
-   * Include the `app` service in `compose.yml` (default true).
+   * Compose file layout (default `single` → `docker-compose.yml`).
+   * Pass `split` for layered `compose.<role>.yml`, or `stack` for `docker-stack.yml`.
+   */
+  readonly layout?: ComposeLayout;
+  /**
+   * Host CPU count used to size `deploy.resources` when {@link prod} is true
+   * (default 4).
+   */
+  readonly serverCpus?: number;
+  /**
+   * Host RAM in GiB used to size `deploy.resources` when {@link prod} is true
+   * (default 8).
+   */
+  readonly serverMemoryGb?: number;
+  /**
+   * Include the `app` service in the compose document (default true).
    * `oke dev --docker` sets false — host Bun runs the app; Docker is infra only.
    */
   readonly includeApp?: boolean;
@@ -193,6 +222,9 @@ export interface DeriveResult {
    * never embedded in YAML.
    */
   readonly stackEnv: Readonly<Record<string, string>>;
-  /** Compose `-f` merge order (four override layers). */
+  /**
+   * Compose `-f` merge order (includes a user-owned override that oke never
+   * writes — callers should skip it when the file is absent).
+   */
   readonly composeFiles: readonly string[];
 }

package/src/drivers/ai-ollama.integration.test.ts

@@ -147,12 +147,12 @@ describe("ollama live — real completion", () => {
 
         const runtime = bindAi(
           {
-            config: { drivers: { ai: { local: "ollama", test: "ollama" } } },
+            config: { drivers: { ai: { test: "ollama", dev: "ollama" } } },
             ai: { models: [smart], prompts: [ping] },
           },
           undefined,
           () => Date.now(),
-          "local",
+          "test",
           false,
         );
         expect(runtime.prompts.has("ollama-ping")).toBe(true);