okengine 0.10.2 → 0.11.0

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

@@ -3,8 +3,8 @@
  * 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
+ * via `rootDir`, `test` warns once (dev-loop stays unbroken),
+ * `dev`+compose / `prod` hard-fail (`OKE1009`) — never a silently-incomplete route
  * table in a deploy-shaped environment.
  */
 
@@ -41,23 +41,23 @@ describe("assertAdoptBarrelFresh — direct", () => {
     try {
       await makeUnitDir(root, "notes");
       const notesFlow = flow("notes.create", { do: () => ({ ok: true as const }) });
-      await expect(assertAdoptBarrelFresh([notesFlow], "docker", root)).resolves.toBeUndefined();
+      await expect(assertAdoptBarrelFresh([notesFlow], "dev", root, true)).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 () => {
+  test("stale: unit on disk, zero adopted flows for it — dev+compose 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/);
+      await expect(assertAdoptBarrelFresh([], "dev", root, true)).rejects.toThrow(/OKE1009/);
     } finally {
       await rm(root, { recursive: true, force: true });
     }
   });
 
-  test("stale: prod — same posture as docker", async () => {
+  test("stale: prod — same posture as dev+compose", async () => {
     const root = await mkdtemp(join(tmpdir(), "oke-adopt-fresh-"));
     try {
       await makeUnitDir(root, "notes");
@@ -67,11 +67,11 @@ describe("assertAdoptBarrelFresh — direct", () => {
     }
   });
 
-  test("stale: local — warns, never throws (dev-loop stays unbroken)", async () => {
+  test("stale: test — 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();
+      await expect(assertAdoptBarrelFresh([], "test", root)).resolves.toBeUndefined();
     } finally {
       await rm(root, { recursive: true, force: true });
     }
@@ -79,7 +79,7 @@ describe("assertAdoptBarrelFresh — direct", () => {
 });
 
 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 () => {
+  test("dev+compose: 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" —
@@ -94,7 +94,22 @@ describe("boot-level: stale barrel through a real oke() boot", () => {
       const app = oke({ name: "stale-barrel", gate: { unguardedHttp: "allow" } });
 
       await expect(
-        app.boot({ env: "docker", rootDir: root, unguardedHttp: "allow", startScheduler: false }),
+        app.boot({
+          env: "dev",
+          docker: true,
+          rootDir: root,
+          unguardedHttp: "allow",
+          startScheduler: false,
+          config: {
+            drivers: {
+              store: {
+                sql: { dev: "memory" },
+                kv: { dev: "memory" },
+              },
+              channel: { email: { dev: "console" } },
+            },
+          },
+        }),
       ).rejects.toThrow(/OKE1009/);
     } finally {
       await rm(root, { recursive: true, force: true });

package/src/kernel/app.ts

@@ -41,6 +41,7 @@ import { runWithLocale } from "../i18n/locale-context.ts";
 import { getMessageCatalogs, matchConfiguredLocale } from "../i18n/messages.ts";
 import { runDurable } from "../elements/clock/durable.ts";
 import { isFlow, type AnyFlowDef } from "./flow.ts";
+import { failureCodeOf, runCompensationPhase } from "./compensate.ts";
 import { fxRetry } from "./concurrency.ts";
 import {
   createFxContext,
@@ -85,6 +86,7 @@ import type { JournalRuntime } from "./boot-bind/journal.ts";
 import { listBindings, resetBindings, type Binding } from "./on.ts";
 import {
   channelTemplateRegistry,
+  requiredEnvRegistry,
   secretRegistry,
   signalRegistry,
   storeRegistry,
@@ -159,11 +161,11 @@ export interface OkeOptions {
    * subject key.
    */
   readonly archiveInputFields?: readonly string[];
-  /** Active environment for {@link OkeApp.boot} (defaults to `local`). */
+  /** Active environment for {@link OkeApp.boot} (`dev` / `test` / `prod`). */
   readonly env?: BootOptions["env"];
   /**
-   * Docker mode (`oke dev -d` / `OKE_DOCKER=1`) — force the `docker`
-   * driver profile at boot.
+   * Compose mode (`oke dev` / `OKE_DOCKER=1`) — select the `dev` driver
+   * profile at boot when `env` is omitted.
    */
   readonly docker?: BootOptions["docker"];
   /** Optional `oke.config.ts` document consumed at boot. */
@@ -485,22 +487,35 @@ export function oke(options: OkeOptions): OkeApp {
   // explicitly-passed decl that is also in the registry is not doubled.
   const registrySnapshot =
     registry === "ignore"
-      ? { stores: [], secrets: [], signals: [], channelTemplates: [] }
+      ? { stores: [], secrets: [], requiredEnv: [], signals: [], channelTemplates: [] }
       : {
           stores: storeRegistry.slice(),
           secrets: secretRegistry.slice(),
+          requiredEnv: requiredEnvRegistry.slice(),
           signals: signalRegistry.slice(),
           channelTemplates: channelTemplateRegistry.slice(),
         };
   if (registry === "consume") {
     storeRegistry.length = 0;
     secretRegistry.length = 0;
+    requiredEnvRegistry.length = 0;
     signalRegistry.length = 0;
     channelTemplateRegistry.length = 0;
   }
   const effectiveStores = mergeUnique(options.stores, registrySnapshot.stores);
   const effectiveSecrets = mergeUnique(options.secrets, registrySnapshot.secrets);
   const effectiveSignals = mergeUnique(options.signals, registrySnapshot.signals);
+  /**
+   * Fold registered `vault.env.required` names into the vault boot options so
+   * boot reports missing env vars in the same gap list as missing secrets.
+   *
+   * @param base - Vault options from `oke({ vault })` / a boot override
+   */
+  const withRequiredEnv = (base: BootOptions["vault"]): BootOptions["vault"] => {
+    const names = [...new Set([...(base?.requiredEnv ?? []), ...registrySnapshot.requiredEnv])];
+    if (names.length === 0) return base;
+    return { ...(base ?? {}), requiredEnv: names };
+  };
   // Stay `undefined` (never a defined-but-empty object) when neither an
   // explicit `options.channel` nor a registered template exists — a defined
   // object here would flip `resolveElementNeeds`'s `channel` need to `true`
@@ -655,7 +670,7 @@ export function oke(options: OkeOptions): OkeApp {
   let bootResult: BootResult | undefined;
   let bootPromise: Promise<BootResult> | undefined;
   let readyState: ReadyState = "booting";
-  let bootEnv: BootOptions["env"] = options.env ?? "local";
+  let bootEnv: BootOptions["env"] = options.env;
   let authBinding: AppAuthBinding | undefined =
     gateConfig.auth !== undefined
       ? createAppAuthBinding({
@@ -787,7 +802,7 @@ export function oke(options: OkeOptions): OkeApp {
     }
   }
 
-  /** Boot-time orphan scan — `running`/`sleeping` runs with no live lease. */
+  /** Boot-time orphan scan — `running`/`sleeping`/`compensating` with no live lease. */
   async function resumeOrphanedDurableRuns(): Promise<void> {
     const { store } = activeJournal();
     if (!hasJournalLease(store)) return;
@@ -807,7 +822,15 @@ export function oke(options: OkeOptions): OkeApp {
     const { bootApplication, resolveElementNeeds } = await import("./boot.ts");
     const { assertHttpGatePosture } = await import("../elements/gate/boot.ts");
     const { assertPluginNeeds, buildAvailableNeedTokens } = await import("./plugin-needs.ts");
-    bootEnv = overrides?.env ?? options.env ?? "local";
+    const dockerFlag =
+      overrides?.docker === true ||
+      (overrides?.docker !== false &&
+        (options.docker === true || (options.docker !== false && process.env.OKE_DOCKER === "1")));
+    // Mirror bootApplication: prod / compose-dev / else test (PGLite + memory).
+    bootEnv =
+      overrides?.env ??
+      options.env ??
+      (process.env.NODE_ENV === "production" ? "prod" : dockerFlag ? "dev" : "test");
 
     // Prod without a real secret fails even if construction minted a dev secret.
     if (gateConfig.auth?.secretMinted && bootEnv === "prod") {
@@ -830,7 +853,7 @@ export function oke(options: OkeOptions): OkeApp {
       config: overrides?.config ?? options.config,
       elements: overrides?.elements ?? options.elements,
       secrets: overrides?.secrets ?? effectiveSecrets,
-      vault: overrides?.vault ?? options.vault,
+      vault: withRequiredEnv(overrides?.vault ?? options.vault),
       gates: [...baseGates, ...authGates],
       signals: overrides?.signals ?? effectiveSignals,
       clocks: overrides?.clocks ?? options.clocks,
@@ -900,7 +923,7 @@ export function oke(options: OkeOptions): OkeApp {
       rootDir: overrides?.rootDir ?? options.rootDir,
       elements: overrides?.elements ?? options.elements,
       secrets: [...baseSecrets, ...pluginSecrets],
-      vault: overrides?.vault ?? options.vault,
+      vault: withRequiredEnv(overrides?.vault ?? options.vault),
       gates: [...baseGates, ...authGates, ...pluginGates],
       unguardedHttp,
       signals: [...baseSignals, ...pluginSignals],
@@ -1013,7 +1036,7 @@ export function oke(options: OkeOptions): OkeApp {
     registerFlow(flowDef);
 
     const i18nConfig = options.config?.i18n;
-    const configuredLocales = i18nConfig?.locales ?? ["en", "ar"];
+    const configuredLocales = i18nConfig?.locales ?? ["en"];
     const defaultLocale = i18nConfig?.default ?? "en";
     const acceptLanguage = extras?.request?.headers.get("accept-language") ?? undefined;
     const resolvedLocale = matchConfiguredLocale(
@@ -1281,30 +1304,13 @@ export function oke(options: OkeOptions): OkeApp {
         });
       } else if (!sleeping && isTerminalFailure(result)) {
         const terminalErr = result.failure ?? result.ctx.error;
-        if (flowDef.compensate) {
-          try {
-            const completedSteps = journalSession.run.entries
-              .filter((e) => e.kind === "step")
-              .map((e) => e.name);
-            await flowDef.compensate(
-              {
-                input: ctx.input as never,
-                error: terminalErr,
-                completedSteps,
-              },
-              fx,
-            );
-          } catch (compErr) {
-            await journalSession.commit("failed", {
-              error: `compensate:${failureCodeOf(compErr)}`,
-            });
-          }
-        }
-        if (journalSession.run.status === "running") {
-          await journalSession.commit("failed", {
-            error: failureCodeOf(terminalErr),
-          });
-        }
+        await runCompensationPhase({
+          flow: flowDef,
+          input: ctx.input,
+          session: journalSession,
+          fx,
+          error: terminalErr,
+        });
       } else if (!sleeping) {
         await journalSession.commit("completed", { output: result.output });
       }
@@ -1699,14 +1705,6 @@ function isTerminalFailure(result: PipelineResult): boolean {
   return result.ctx.error !== undefined && !isJournalSuspend(result.ctx.error);
 }
 
-/** Machine-readable code for journal / Runs failure fields. */
-function failureCodeOf(err: unknown): string {
-  if (isFlowFailure(err)) return err.error.code;
-  if (err instanceof Error && err.name && err.name !== "Error") return err.name;
-  if (err instanceof Error && err.message) return err.message.slice(0, 120);
-  return "Error";
-}
-
 /** Coerce a thrown value into a FlowFailure for Runs wide events. */
 function failureFromUnknown(err: unknown): FlowFailure {
   if (isFlowFailure(err)) return err;

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

@@ -40,7 +40,7 @@ describe("oke() auto-registry — stores/secrets/signals/channel.templates", ()
         sends: ["before-note-created"],
       },
       do: async (_input, fx) => {
-        const secret = fx.vault(secretBefore);
+        const secret = await fx.vault.get(secretBefore);
         await fx.emit(signalBefore, {});
         await fx.send(templateBefore, { to: "you@localhost", data: {} });
         return { secret };
@@ -78,7 +78,7 @@ describe("oke() auto-registry — stores/secrets/signals/channel.templates", ()
         sends: ["after-note-created"],
       },
       do: async (_input, fx) => {
-        const secret = fx.vault(secretAfter);
+        const secret = await fx.vault.get(secretAfter);
         await fx.emit(signalAfter, {});
         await fx.send(templateAfter, { to: "you@localhost", data: {} });
         return { secret };

package/src/kernel/boot-bind/ai.test.ts

@@ -16,15 +16,15 @@ describe("ai boot binder", () => {
   });
 
   test("resolveAiDriverId defaults to mock; honours config + OKE_AI_DRIVER in docker", () => {
-    expect(resolveAiDriverId({}, "local")).toBe("mock");
-    expect(resolveAiDriverId({ config: { drivers: { ai: { local: "ollama" } } } }, "local")).toBe(
+    expect(resolveAiDriverId({}, "test")).toBe("mock");
+    expect(resolveAiDriverId({ config: { drivers: { ai: { test: "ollama" } } } }, "test")).toBe(
       "ollama",
     );
 
     const prev = process.env.OKE_AI_DRIVER;
     process.env.OKE_AI_DRIVER = "ollama";
     try {
-      expect(resolveAiDriverId({}, "local", true)).toBe("ollama");
+      expect(resolveAiDriverId({}, "test", true)).toBe("ollama");
     } finally {
       if (prev === undefined) delete process.env.OKE_AI_DRIVER;
       else process.env.OKE_AI_DRIVER = prev;
@@ -48,12 +48,12 @@ describe("ai boot binder", () => {
   test("bindAi uses injected defaultDriver over config (tests stay on mock)", () => {
     const runtime = bindAi(
       {
-        config: { drivers: { ai: { local: "ollama" } } },
+        config: { drivers: { ai: { test: "ollama" } } },
         ai: { defaultDriver: mockAiDriver },
       },
       undefined,
       () => 0,
-      "local",
+      "test",
     );
     expect(runtime.autoCacheDisabled).toBe(true);
   });

package/src/kernel/boot-bind/ai.ts

@@ -33,7 +33,7 @@ export function bindAi(
   options: BootOptions,
   gate: GateRuntime | undefined,
   now: () => number,
-  env: ConfigEnv = "local",
+  env: ConfigEnv = "test",
   docker = false,
 ): AiRuntime {
   const id = resolveAiDriverId(options, env, docker);
@@ -115,6 +115,7 @@ export function openDefaultsFor(id: string, docker = false): AiOpenOptions {
     return {
       ...(apiKey ? { apiKey } : {}),
       ...(baseUrl ? { baseUrl } : {}),
+      ...(process.env.OKE_AI_MODEL?.trim() ? { model: process.env.OKE_AI_MODEL.trim() } : {}),
     };
   }
   return {};

package/src/kernel/boot-bind/channel.test.ts

@@ -58,23 +58,23 @@ describe("bindChannel driver resolution", () => {
     config: {
       drivers: {
         channel: {
-          email: { local: "console", docker: "smtp", test: "console", prod: "sndr" },
-          sms: { local: "console", docker: "taqnyat", test: "msegat", prod: "taqnyat" },
+          email: { dev: "smtp", test: "console", prod: "sndr" },
+          sms: { dev: "taqnyat", test: "msegat", prod: "taqnyat" },
         },
       },
     },
   };
 
   test("uses console locally and smtp in docker", () => {
-    expect(resolveEmailDriverId(options, "local", false)).toBe("console");
-    expect(resolveEmailDriverId(options, "docker", true)).toBe("smtp");
+    expect(resolveEmailDriverId(options, "test", false)).toBe("console");
+    expect(resolveEmailDriverId(options, "dev", true)).toBe("smtp");
     expect(resolveEmailDriverId(options, "prod", false)).toBe("sndr");
   });
 
   test("resolves sms driver ids", () => {
-    expect(resolveSmsDriverId(options, "local")).toBe("console");
-    expect(resolveSmsDriverId(options, "docker")).toBe("taqnyat");
     expect(resolveSmsDriverId(options, "test")).toBe("msegat");
+    expect(resolveSmsDriverId(options, "dev")).toBe("taqnyat");
+    expect(resolveSmsDriverId(options, "prod")).toBe("taqnyat");
   });
 
   test("parses SMTP_URL and optional auth overrides", () => {

package/src/kernel/boot-bind/channel.ts

@@ -3,6 +3,7 @@
  */
 
 import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
+import { CHANNEL_EMAIL_DEFAULTS, CHANNEL_SMS_DEFAULTS } from "../../config/driver-defaults.ts";
 import { openConsoleChannel } from "../../drivers/channel-console.ts";
 import { openMsegatChannel } from "../../drivers/channel-msegat.ts";
 import { openResendChannel } from "../../drivers/channel-resend.ts";
@@ -81,9 +82,9 @@ export function resolveEmailDriverId(
   env: ConfigEnv,
   docker: boolean,
 ): string {
-  return (
-    resolveDriverId(options.config?.drivers?.channel?.email, env) ?? (docker ? "smtp" : "console")
-  );
+  void docker;
+  // Defaults cover every ConfigEnv key, so this is never undefined.
+  return resolveDriverId(options.config?.drivers?.channel?.email, env, CHANNEL_EMAIL_DEFAULTS)!;
 }
 
 /**
@@ -93,7 +94,7 @@ export function resolveEmailDriverId(
  * @param env - Active environment
  */
 export function resolveSmsDriverId(options: BootOptions, env: ConfigEnv): string | undefined {
-  return resolveDriverId(options.config?.drivers?.channel?.sms, env);
+  return resolveDriverId(options.config?.drivers?.channel?.sms, env, CHANNEL_SMS_DEFAULTS);
 }
 
 /**

package/src/kernel/boot-bind/clock.ts

@@ -15,6 +15,7 @@ import {
 } from "../../elements/clock.ts";
 import { createPostgresCronStore } from "../../drivers/clock-postgres.ts";
 import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
+import { CLOCK_DEFAULTS } from "../../config/driver-defaults.ts";
 import type { BootOptions } from "../boot.ts";
 
 /** Result of binding a clock runtime. */
@@ -33,9 +34,8 @@ export const DEFAULT_FILE_CRON_PATH = ".oke/crons.json";
  * @param env - Active environment
  */
 export function resolveClockDriverId(options: BootOptions, env: ConfigEnv): string {
-  const resolved = resolveDriverId(options.config?.drivers?.clock, env);
-  if (resolved) return resolved;
-  return env === "test" ? "frozen" : "memory";
+  // Defaults cover every ConfigEnv key, so this is never undefined.
+  return resolveDriverId(options.config?.drivers?.clock, env, CLOCK_DEFAULTS)!;
 }
 
 /**
@@ -79,8 +79,8 @@ export async function bindClock(
     const url = process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL ?? undefined;
     if (!url) {
       throw new Error(
-        env === "docker"
-          ? 'oke boot: clock driver "postgres" needs DATABASE_URL (did `oke dev -d` write docker/.env.docker?)'
+        env === "dev"
+          ? 'oke boot: clock driver "postgres" needs DATABASE_URL (did `oke dev` write docker/.env.docker?)'
           : 'oke boot: clock driver "postgres" needs DATABASE_URL',
       );
     }

package/src/kernel/boot-bind/gate.ts

@@ -3,6 +3,7 @@
  */
 
 import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
+import { STORE_KV_DEFAULTS } from "../../config/driver-defaults.ts";
 import { memoryDrivers } from "../../drivers/memory.ts";
 import { redisDriver } from "../../drivers/redis.ts";
 import type { KvClientLike } from "../../drivers/types.ts";
@@ -27,10 +28,8 @@ export function resolveGateKvDriverId(
   const fromEnv = process.env.OKE_KV_DRIVER?.trim();
   if (docker && fromEnv === "redis") return "redis";
   if (docker && fromEnv === "memory") return "memory";
-  const resolved = resolveDriverId(options.config?.drivers?.store?.kv, env);
-  if (resolved === "redis") return "redis";
-  if (resolved === "memory") return "memory";
-  return docker ? "redis" : "memory";
+  const resolved = resolveDriverId(options.config?.drivers?.store?.kv, env, STORE_KV_DEFAULTS);
+  return resolved === "redis" ? "redis" : "memory";
 }
 
 function kvUrlFor(docker: boolean): string {
@@ -38,8 +37,8 @@ function kvUrlFor(docker: boolean): string {
   if (!url) {
     throw new Error(
       docker
-        ? "oke boot: gate redis kv needs REDIS_URL (did `oke dev -d` write docker/.env.docker?)"
-        : "oke boot: gate redis kv needs REDIS_URL — declare drivers.store.kv memory for local, or set REDIS_URL",
+        ? "oke boot: gate redis kv needs REDIS_URL (did `oke dev` write docker/.env.docker?)"
+        : "oke boot: gate redis kv needs REDIS_URL — declare drivers.store.kv memory for test, or set REDIS_URL",
     );
   }
   return url;
@@ -56,7 +55,7 @@ function kvUrlFor(docker: boolean): string {
 export async function bindGate(
   options: BootOptions,
   now: () => number,
-  env: ConfigEnv = "local",
+  env: ConfigEnv = "test",
   docker = false,
 ): Promise<GateRuntime> {
   const kvId = resolveGateKvDriverId(options, env, docker);