okengine 0.6.1 → 0.7.0

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

@@ -2,29 +2,86 @@
  * Lazy signal binder — loaded only when Signal is declared.
  */
 
+import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
 import { memorySignalDriver } from "../../drivers/signal-memory.ts";
+import { createBunSignalRedisClient, redisSignalDriver } from "../../drivers/signal-redis.ts";
+import type { SignalRedisClientLike } from "../../drivers/signal-types.ts";
 import { createSignalRuntime, type SignalRuntime } from "../../elements/signal.ts";
-import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
 import type { BootOptions } from "../boot.ts";
 
+/**
+ * Resolve `drivers.signal` for the active env (default `memory`).
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ */
+export function resolveSignalDriverId(options: BootOptions, env: ConfigEnv): string {
+  return resolveDriverId(options.config?.drivers?.signal, env) ?? "memory";
+}
+
+function redisUrlFor(docker: boolean): string | undefined {
+  const url = process.env.REDIS_URL ?? process.env.OKE_STORE_KV_URL ?? undefined;
+  if (!url && docker) {
+    throw new Error(
+      "oke boot: signal redis driver needs REDIS_URL (did `oke dev -d` write docker/.env.docker?)",
+    );
+  }
+  return url;
+}
+
 /**
  * Construct a Signal runtime, register decls / binding names, start the bus.
  *
+ * Supported ids: `memory` · `redis`. `postgres` / `nats` fail loud until a real
+ * native client can be constructed (never silently bind memory).
+ *
  * @param options - Boot options
  * @param env - Active environment
  * @param now - Clock
+ * @param docker - Docker mode
  */
 export async function bindSignal(
   options: BootOptions,
   env: ConfigEnv,
   now: () => number,
+  docker = false,
 ): Promise<SignalRuntime> {
-  const signalId = resolveDriverId(options.config?.drivers?.signal, env) ?? "memory";
-  void signalId;
-  const signal = createSignalRuntime({
-    driver: memorySignalDriver,
-    now,
-  });
+  const signalId = resolveSignalDriverId(options, env);
+  const injectedRedis = options.clients?.signalRedis as SignalRedisClientLike | undefined;
+
+  let signal: SignalRuntime;
+  switch (signalId) {
+    case "memory":
+      signal = createSignalRuntime({
+        driver: memorySignalDriver,
+        now,
+      });
+      break;
+    case "redis": {
+      const redis = injectedRedis ?? createBunSignalRedisClient(redisUrlFor(docker));
+      signal = createSignalRuntime({
+        driver: redisSignalDriver,
+        now,
+        redis,
+      });
+      break;
+    }
+    case "postgres":
+      throw new Error(
+        'oke boot: signal driver "postgres" needs a LISTEN/NOTIFY-capable SQL client — ' +
+          'not available via Bun.SQL yet. Use "redis" or "memory", or inject elements.signal.',
+      );
+    case "nats":
+      throw new Error(
+        'oke boot: signal driver "nats" has no production client bind yet — ' +
+          'use "redis" or "memory", or inject elements.signal.',
+      );
+    default:
+      throw new Error(
+        `oke boot: unknown signal driver "${signalId}" (expected memory · redis · postgres · nats)`,
+      );
+  }
+
   for (const decl of options.signals ?? []) {
     signal.register(decl);
   }

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

@@ -2,28 +2,47 @@
  * Lazy vault binder — loaded only when secrets are declared.
  */
 
-import { memoryVaultDriver } from "../../drivers/vault-memory.ts";
+import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
 import { createVaultRuntime, type VaultRuntime } from "../../elements/vault.ts";
-import type { ConfigEnv } from "../../config/index.ts";
+import { buildVaultBootChain, normalizeVaultDriverId } from "../../elements/vault/boot-chain.ts";
 import type { BootOptions } from "../boot.ts";
 
+/**
+ * Resolve `drivers.vault` for the active env (default `env` locally, `memory` in test).
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ */
+export function resolveVaultDriverId(options: BootOptions, env: ConfigEnv): string {
+  const resolved = resolveDriverId(options.config?.drivers?.vault, env);
+  if (resolved) return resolved;
+  return env === "test" ? "memory" : "env";
+}
+
 /**
  * Construct and boot a Vault runtime from BootOptions.
  *
+ * Uses `drivers.vault` via the shared {@link buildVaultBootChain} helper
+ * (same chain Console uses). Injected `options.vault.chain` still wins for tests.
+ *
  * @param options - Boot options
  * @param env - Active environment
  */
 export async function bindVault(options: BootOptions, env: ConfigEnv): Promise<VaultRuntime> {
   const vaultSecrets = options.vault?.secrets ?? options.secrets ?? [];
+  const chain =
+    options.vault?.chain ??
+    buildVaultBootChain({
+      driverId: normalizeVaultDriverId(resolveVaultDriverId(options, env)),
+      env,
+      cwd: process.cwd(),
+      seed: {},
+    });
   const vault = createVaultRuntime({
     secrets: vaultSecrets,
-    chain: options.vault?.chain ?? [
-      {
-        driver: memoryVaultDriver,
-        options: { secrets: {} },
-      },
-    ],
+    chain,
     allowDevFallbacks: options.vault?.allowDevFallbacks ?? env !== "prod",
+    now: options.vault?.now,
   });
   await vault.boot();
   return vault;

package/src/kernel/boot.ts

@@ -114,6 +114,14 @@ export interface BootOptions {
   readonly onSignal?: (signal: string, payload: unknown) => void | Promise<void>;
   /** Injectable clock for test / frozen harnesses. */
   readonly now?: () => number;
+  /**
+   * Test-only client injection for binders that open redis / signal redis.
+   * Production apps leave this unset.
+   */
+  readonly clients?: {
+    readonly kv?: import("../drivers/types.ts").KvClientLike;
+    readonly signalRedis?: import("../drivers/signal-types.ts").SignalRedisClientLike;
+  };
   /** Instance id for leader election. */
   readonly instanceId?: string;
   /**
@@ -344,7 +352,7 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   let signal = pre.signal;
   if (needs.signal) {
     if (!signal) {
-      signal = await signalBind!.bindSignal(options, env, now);
+      signal = await signalBind!.bindSignal(options, env, now, docker);
     } else {
       // Pre-built: still register decls / start if needed.
       for (const decl of options.signals ?? []) {
@@ -376,7 +384,7 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   // Gate (before AI)
   let gate = pre.gate;
   if (needs.gate && !gate) {
-    gate = await gateBind!.bindGate(options, now);
+    gate = await gateBind!.bindGate(options, now, env, docker);
   }
 
   // 5. Channel

package/src/kernel/errors.ts

@@ -143,14 +143,20 @@ export const OKE_ERRORS = {
     fix: 'Add "{resource}" to this flow\'s effects.calls.',
   },
   /**
-   * Emit target has no subscriber (unified-theory §21 example).
-   * Reserved now so the number stays permanent.
+   * Emit target has no subscriber (unified-theory §21).
+   * Thrown at emit when `optional` is false and nobody is subscribed.
    */
   ORPHAN_EMIT: {
     code: 1042,
     cause: 'Flow "{flow}" emits signal "{resource}" with no subscriber.',
     fix: "Add `on({resource}, …)` or mark the signal `{ optional: true }`.",
   },
+  /** Emit payload failed the signal's declared Standard Schema. */
+  SIGNAL_SCHEMA: {
+    code: 1043,
+    cause: '"{resource}": {detail}',
+    fix: "Fix schema payload.",
+  },
   /**
    * Domain table/column missing under docker/prod (migrations not applied).
    * Store/DDL band starts at 1100.

package/src/kernel/fx.test.ts

@@ -258,6 +258,19 @@ describe("errors — registry", () => {
     expect(err.message).toContain("→");
   });
 
+  test("OKE1043 is reserved for signal schema emit failures", () => {
+    const def = OKE_ERRORS.SIGNAL_SCHEMA;
+    expect(def.code).toBe(1043);
+    expect(lookupOkeError(1043)).toEqual(def);
+    const err = new OkeError(def, {
+      resource: "order-placed",
+      detail: "total: Expected number, received string",
+    });
+    expect(err.message).toContain("OKE1043");
+    expect(err.message).toContain("order-placed");
+    expect(err.message).toContain("https://oke.omqkhafi.dev/e/1043");
+  });
+
   test("fx.fail returns a value, not an exception", () => {
     const fx = createFx({ flow: "x", effects: {} });
     const result = fx.fail(

package/src/kernel/fx.ts

@@ -19,6 +19,7 @@ import type {
 } from "../elements/store.ts";
 import type { SqlRow } from "../drivers/types.ts";
 import type { SignalRuntime } from "../elements/signal.ts";
+import type { SignalEmitOptions } from "../drivers/signal-types.ts";
 import type { VaultRuntime } from "../elements/vault.ts";
 import type { ChannelRuntime } from "../elements/channel.ts";
 import type { AiRuntime } from "../elements/ai.ts";
@@ -295,8 +296,9 @@ export interface Fx {
    *
    * @param signal - Signal name or handle
    * @param payload - Payload
+   * @param options - Optional emit options (`key` for per-key once ordering)
    */
-  emit(signal: NamedRef, payload?: unknown): Promise<void>;
+  emit(signal: NamedRef, payload?: unknown, options?: SignalEmitOptions): Promise<void>;
   /**
    * Call another flow (records `call`). Stub returns `undefined`.
    *
@@ -892,7 +894,28 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         });
       }
 
-      // KV / files / index — thin gated wrappers preserving driver methods.
+      if (decl.facet === "files") {
+        const ref = decl.ref;
+        return runtime.openFilesFx(
+          decl as Extract<StoreDecl, { facet: "files" }>,
+          {
+            effects: options.effects ?? {},
+            revealPii: options.revealPii,
+          },
+          {
+            gate: gated,
+            refuseDryRunWrite: () => {
+              if (isDryRun()) {
+                throw new DryRunWriteIsolationError(
+                  `Driver-backed store "${ref}" cannot isolate writes during dry-run; dry-run refused rather than risk a double-write.`,
+                );
+              }
+            },
+          },
+        );
+      }
+
+      // KV / index — thin gated wrappers preserving driver methods.
       const baseRef = decl.ref;
       return new Proxy({} as StoreHandle, {
         get(_t, prop) {
@@ -1010,11 +1033,11 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     store(ref) {
       return storeHandle(ref);
     },
-    emit(signal, payload) {
+    emit(signal, payload, emitOptions) {
       const name = resolveName(signal);
       return gated("emit", name, async () => {
         if (options.signalRuntime) {
-          await options.signalRuntime.emit(name, payload);
+          await options.signalRuntime.emit(name, payload, emitOptions);
         }
       });
     },

package/src/runtime/dev-request-log.test.ts

@@ -3,7 +3,11 @@
  */
 
 import { afterEach, describe, expect, test } from "bun:test";
-import { isSilentDevRequest, shouldLogDevRequests } from "./dev-request-log.ts";
+import {
+  failureDetailFromResponse,
+  isSilentDevRequest,
+  shouldLogDevRequests,
+} from "./dev-request-log.ts";
 
 describe("dev-request-log", () => {
   const prev = process.env.OKE_DEV_REQUEST_LOG;
@@ -27,4 +31,19 @@ describe("dev-request-log", () => {
     expect(isSilentDevRequest("GET", "/_oke/client.json")).toBe(true);
     expect(isSilentDevRequest("POST", "/console/flows")).toBe(false);
   });
+
+  test("failureDetailFromResponse reads error.message from envelope", async () => {
+    const res = Response.json(
+      {
+        data: null,
+        error: {
+          code: "ClaimFailed",
+          data: { reason: "password_policy" },
+          message: "Password needs at least 12 characters, including a letter and a number.",
+        },
+      },
+      { status: 400 },
+    );
+    expect(await failureDetailFromResponse(res)).toMatch(/12 characters/);
+  });
 });

package/src/runtime/dev-request-log.ts

@@ -52,6 +52,8 @@ export type DevRequestLogInput = {
   readonly flow?: string;
   readonly status: number;
   readonly ms: number;
+  /** Human failure detail (error.message / code) for 4xx/5xx. */
+  readonly detail?: string;
 };
 
 /**
@@ -70,6 +72,39 @@ export function isSilentDevRequest(method: string, path: string): boolean {
   return /\.(?:js|css|map|svg|png|ico|woff2?|ttf|webp)$/i.test(path);
 }
 
+/**
+ * Extract a short failure detail from an OKE JSON envelope body.
+ *
+ * @param response - HTTP response (cloned; original body stays readable)
+ */
+export async function failureDetailFromResponse(response: Response): Promise<string | undefined> {
+  if (response.status < 400) return undefined;
+  try {
+    const body: unknown = await response.clone().json();
+    if (body === null || typeof body !== "object" || !("error" in body)) return undefined;
+    const error = (body as { error: unknown }).error;
+    if (error === null || typeof error !== "object") return undefined;
+    const rec = error as { message?: unknown; code?: unknown; data?: unknown };
+    if (typeof rec.message === "string" && rec.message.trim().length > 0) {
+      return rec.message.trim();
+    }
+    if (
+      rec.data !== null &&
+      typeof rec.data === "object" &&
+      "reason" in rec.data &&
+      typeof (rec.data as { reason: unknown }).reason === "string"
+    ) {
+      const reason = (rec.data as { reason: string }).reason;
+      const code = typeof rec.code === "string" ? rec.code : "Error";
+      return `${code}: ${reason}`;
+    }
+    if (typeof rec.code === "string") return rec.code;
+  } catch {
+    // non-JSON error bodies stay status-only
+  }
+  return undefined;
+}
+
 /**
  * Print one request line when {@link shouldLogDevRequests} is on.
  *
@@ -86,6 +121,7 @@ export function logDevRequest(input: DevRequestLogInput): void {
       flow: input.flow,
       status: input.status,
       ms: input.ms,
+      detail: input.detail,
     }),
   );
 }
@@ -115,6 +151,7 @@ export async function timedDevFetch(
   const url = new URL(request.url);
   const method = request.method.toUpperCase();
   const response = await handle(request);
+  const detail = await failureDetailFromResponse(response);
   logDevRequest({
     surface: options.surface ?? currentDevSurface(),
     method,
@@ -122,6 +159,7 @@ export async function timedDevFetch(
     flow: options.resolveFlow?.(request, response),
     status: response.status,
     ms: Math.round(performance.now() - started),
+    detail,
   });
   return response;
 }

package/src/term.test.ts

@@ -125,6 +125,21 @@ describe("term", () => {
     expect(out).not.toMatch(/\u001b\[/);
   });
 
+  test("formatRequestLine prints failure detail under 4xx/5xx", () => {
+    const out = formatRequestLine({
+      surface: "Console",
+      method: "POST",
+      path: "/console/setup/claim",
+      flow: "console.setup.claim",
+      status: 400,
+      ms: 1,
+      detail: "Password needs at least 12 characters, including a letter and a number.",
+      color: false,
+    });
+    expect(out).toContain("400");
+    expect(out).toContain("↳ Password needs at least 12 characters");
+  });
+
   test("formatStackSummary is scannable", () => {
     const out = formatStackSummary({
       project: "oke-dev-a3f791",

package/src/term.ts

@@ -300,6 +300,8 @@ export function formatRequestLine(options: {
   /** Instant for date/time columns (default now). */
   readonly at?: Date;
   readonly color?: boolean;
+  /** Failure detail printed on a follow-up line (4xx/5xx). */
+  readonly detail?: string;
 }): string {
   const s = termStyle(options.color ?? termColorEnabled());
   const at = options.at ?? new Date();
@@ -323,7 +325,7 @@ export function formatRequestLine(options: {
   const path = options.path.length > 28 ? `${options.path.slice(0, 27)}…` : options.path.padEnd(28);
   const flow = (options.flow ?? "—").padEnd(22);
   const ms = `${options.ms}ms`.padStart(6);
-  return (
+  const main =
     `${surfaceColor}●${s.reset}  ` +
     `${surfaceColor}${options.surface.padEnd(7)}${s.reset}  ` +
     `${methodColor}${method}${s.reset} ` +
@@ -332,8 +334,11 @@ export function formatRequestLine(options: {
     `${s.dim}${ms}${s.reset}  ` +
     `${statusColor}${options.status}${s.reset}  ` +
     `${s.dim}${date}${s.reset}  ` +
-    `${s.dim}${time}${s.reset}\n`
-  );
+    `${s.dim}${time}${s.reset}\n`;
+  const detail = options.detail?.trim();
+  if (!detail || options.status < 400) return main;
+  const clipped = detail.length > 120 ? `${detail.slice(0, 119)}…` : detail;
+  return `${main}${s.dim}   ↳ ${clipped}${s.reset}\n`;
 }
 
 /**