okengine 0.19.9 → 0.21.0

package/src/kernel/project-out.test.ts

@@ -0,0 +1,176 @@
+/**
+ * Flow `out` projection — store rows through ISO `out` without DTO mappers.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { oke } from "./app.ts";
+import { flow, resetFlowSeq } from "./flow.ts";
+import { isJsonResult } from "./fx.ts";
+import { on, resetBindings } from "./on.ts";
+import { projectFlowOut } from "./project-out.ts";
+import { http } from "./triggers.ts";
+
+afterEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+const IsoInstant = z.iso.datetime();
+
+const LinkOut = z.object({
+  id: z.string(),
+  clicks: z.number(),
+  expiresAt: IsoInstant.nullable(),
+  createdAt: IsoInstant,
+});
+
+describe("projectFlowOut", () => {
+  test("JSON-wires Date timestamps onto iso.datetime out", async () => {
+    const createdAt = new Date("2026-09-14T12:00:00.000Z");
+    const projected = await projectFlowOut(LinkOut, {
+      id: "lnk_1",
+      clicks: 0,
+      expiresAt: null,
+      createdAt,
+      extra: "drop-me",
+    });
+    expect(projected).toEqual({
+      id: "lnk_1",
+      clicks: 0,
+      expiresAt: null,
+      createdAt: "2026-09-14T12:00:00.000Z",
+    });
+  });
+
+  test("JSON-wires fx.clock.now()-style epoch-ms *At onto iso.datetime out", async () => {
+    const createdAt = Date.parse("2026-09-14T12:00:00.000Z");
+    const projected = await projectFlowOut(LinkOut, {
+      id: "lnk_1",
+      clicks: 0,
+      expiresAt: null,
+      createdAt,
+    });
+    expect(projected).toEqual({
+      id: "lnk_1",
+      clicks: 0,
+      expiresAt: null,
+      createdAt: "2026-09-14T12:00:00.000Z",
+    });
+  });
+
+  test("fx.json.create carrier projects .value and keeps 201", async () => {
+    const createdAt = new Date("2026-09-14T12:00:00.000Z");
+    const fx = (await import("./fx.ts")).createFx({ flow: "links.create" });
+    const carrier = await projectFlowOut(
+      LinkOut,
+      fx.json.create({
+        id: "lnk_1",
+        clicks: 0,
+        expiresAt: null,
+        createdAt,
+      }),
+    );
+    expect(isJsonResult(carrier)).toBe(true);
+    if (!isJsonResult(carrier)) return;
+    expect(carrier.status).toBe(201);
+    expect(carrier.value).toEqual({
+      id: "lnk_1",
+      clicks: 0,
+      expiresAt: null,
+      createdAt: "2026-09-14T12:00:00.000Z",
+    });
+  });
+
+  test("z.date() out keeps Date (direct parse, no wire)", async () => {
+    const createdAt = new Date("2026-09-14T12:00:00.000Z");
+    const Out = z.object({ createdAt: z.date() });
+    const projected = await projectFlowOut(Out, { createdAt });
+    expect(projected).toEqual({ createdAt });
+    expect((projected as { createdAt: Date }).createdAt).toBe(createdAt);
+  });
+
+  test("array out projects each row", async () => {
+    const createdAt = new Date("2026-09-14T12:00:00.000Z");
+    const projected = await projectFlowOut(z.array(LinkOut), [
+      { id: "lnk_1", clicks: 1, expiresAt: null, createdAt },
+    ]);
+    expect(projected).toEqual([
+      { id: "lnk_1", clicks: 1, expiresAt: null, createdAt: "2026-09-14T12:00:00.000Z" },
+    ]);
+  });
+
+  test("bigint integers JSON-wire onto z.number()", async () => {
+    const Out = z.object({ clicks: z.number() });
+    const projected = await projectFlowOut(Out, { clicks: 3n });
+    expect(projected).toEqual({ clicks: 3 });
+  });
+
+  test("missing out is a no-op", async () => {
+    const row = { id: "lnk_1", createdAt: new Date() };
+    expect(await projectFlowOut(undefined, row)).toBe(row);
+  });
+});
+
+describe("execute — out projects fx.json.create(row)", () => {
+  test("in-process create returns ISO timestamps from a Date row", async () => {
+    resetBindings();
+    resetFlowSeq();
+    const createdAt = new Date("2026-09-14T12:00:00.000Z");
+    on(
+      http.post("/links", { out: LinkOut }).public(),
+      flow("links.create", {
+        do: (_input, fx) =>
+          fx.json.create({
+            id: "lnk_1",
+            clicks: 0,
+            expiresAt: null,
+            createdAt,
+            secret: "not-on-the-wire",
+          }),
+      }),
+    );
+    const app = oke({ name: "project-out", env: "test" });
+    await app.boot({ env: "test" });
+    const flowDef = app.flow("links.create")!;
+    const result = await app.execute(flowDef, {}, flowDef.triggers[0]!);
+    expect(result.failure).toBeUndefined();
+    expect(isJsonResult(result.output)).toBe(true);
+    if (!isJsonResult(result.output)) return;
+    expect(result.output.status).toBe(201);
+    expect(result.output.value).toEqual({
+      id: "lnk_1",
+      clicks: 0,
+      expiresAt: null,
+      createdAt: "2026-09-14T12:00:00.000Z",
+    });
+    await app.bootResult?.close();
+  });
+
+  test("withQuery page projects Date rows onto array out", async () => {
+    resetBindings();
+    resetFlowSeq();
+    const createdAt = new Date("2026-09-14T12:00:00.000Z");
+    on(
+      http.get("/links", { out: z.array(LinkOut) }).public(),
+      flow("links.list", {
+        do: (input, fx) =>
+          fx.json.withQuery(
+            [{ id: "lnk_1", clicks: 0, expiresAt: null, createdAt, extra: true }],
+            input,
+          ),
+      }),
+    );
+    const app = oke({ name: "project-out-list", env: "test" });
+    await app.boot({ env: "test" });
+    const flowDef = app.flow("links.list")!;
+    const result = await app.execute(flowDef, { limit: 10 }, flowDef.triggers[0]!);
+    expect(result.failure).toBeUndefined();
+    expect(isJsonResult(result.output)).toBe(true);
+    if (!isJsonResult(result.output)) return;
+    expect(result.output.value).toEqual([
+      { id: "lnk_1", clicks: 0, expiresAt: null, createdAt: "2026-09-14T12:00:00.000Z" },
+    ]);
+    await app.bootResult?.close();
+  });
+});

package/src/kernel/project-out.ts

@@ -0,0 +1,91 @@
+/**
+ * Project a Flow success value onto the exposure `out` schema.
+ *
+ * Store rows carry `Date` timestamps (or epoch-ms from `fx.clock.now()`);
+ * HTTP `out` is usually ISO-8601. Direct Standard Schema parse keeps
+ * `z.date()` replies as dates. When that fails, JSON-wire (`Date` → ISO,
+ * `*At` / `*_at` / `at` epoch-ms → ISO) and parse again so
+ * `fx.json.create(row)` matches `out` without a hand-written DTO mapper.
+ * Extra keys strip when parse succeeds. Parse failure is not a client
+ * error — `out` is a projector, not a hard gate.
+ */
+
+import type { SchemaInput } from "../validation/standard-schema.ts";
+import { validate } from "../validation/standard-schema.ts";
+import { isJsonResult, isJsonStreamResult, jsonResultBrand, type JsonResult } from "./fx.ts";
+
+/**
+ * Project `output` through `schema` when the exposure declared `out`.
+ *
+ * JsonResult carriers project `.value` (status / meta stay). Streams, 204,
+ * and missing schema pass through.
+ *
+ * @param schema - Flow `out` (Standard Schema or unknown)
+ * @param output - Handler return
+ */
+export async function projectFlowOut(
+  schema: SchemaInput | undefined,
+  output: unknown,
+): Promise<unknown> {
+  if (schema === undefined || schema === null) return output;
+  if (output === undefined) return output;
+  if (isJsonStreamResult(output)) return output;
+  if (isJsonResult(output)) {
+    if (output.status === 204 || output.value === undefined) return output;
+    const value = await projectValue(schema, output.value);
+    if (value === output.value) return output;
+    return {
+      [jsonResultBrand]: true,
+      status: output.status,
+      value,
+      ...(output.meta !== undefined ? { meta: output.meta } : {}),
+    } as JsonResult;
+  }
+  return projectValue(schema, output);
+}
+
+/**
+ * Parse `value` as `schema`. On miss, JSON-wire then parse (Date / epoch-ms → ISO).
+ *
+ * @param schema - Success reply schema
+ * @param value - Raw handler / store value
+ */
+async function projectValue(schema: SchemaInput, value: unknown): Promise<unknown> {
+  const direct = await validate(schema, value);
+  if (direct.ok) return direct.value;
+  const wired = jsonWire(value);
+  if (wired === value) return value;
+  const second = await validate(schema, wired);
+  return second.ok ? second.value : value;
+}
+
+/**
+ * Whether a JSON key looks like a temporal field (`createdAt`, `expires_at`, `at`).
+ *
+ * @param key - Property name from {@link JSON.stringify} replacer
+ */
+function isTemporalKey(key: string): boolean {
+  return key === "at" || key.endsWith("At") || key.endsWith("_at");
+}
+
+/**
+ * JSON round-trip so `Date` and temporal epoch-ms become ISO-8601
+ * (same bytes `Response.json` emits for dates).
+ *
+ * @param value - Arbitrary success payload
+ */
+function jsonWire(value: unknown): unknown {
+  try {
+    return JSON.parse(
+      JSON.stringify(value, (key, item) => {
+        if (typeof item === "bigint") return Number(item);
+        if (typeof item === "number" && Number.isFinite(item) && isTemporalKey(key)) {
+          return new Date(item).toISOString();
+        }
+        return item;
+      }),
+    );
+  } catch {
+    return value;
+  }
+}

package/src/kernel/realtime-bind.ts

@@ -22,6 +22,8 @@ import { setSqlCdcSink, type SqlCdcSink } from "../elements/store/sql-session.ts
 import type { LiveQueryEvent, LiveSubscription } from "../elements/store/live-query-runtime.ts";
 import { currentAbortSignal, linkAbort } from "./abort-scope.ts";
 
+export { MUTATION_ID_HEADER } from "./mutation-id.ts";
+
 /**
  * Column-kind hint for one SQL column — drives {@link restoreImage} type
  * restoration for outbox-round-tripped CDC images.
@@ -41,9 +43,6 @@ export function liveSignalName(table: string): string {
   return `${LIVE_SIGNAL_PREFIX}${table}`;
 }
 
-/** Mutation header echoed into `mutationId` on write-path events. */
-export const MUTATION_ID_HEADER = "x-oke-mutation-id";
-
 /** Per-stream event buffer cap (bounded memory per SSE session). */
 const LIVE_STREAM_BUFFER_MAX = 512;
 

package/src/kernel/router/linear.ts

@@ -31,6 +31,9 @@ export class LinearRouter<T> implements Router<T> {
   }
 
   /**
+   * Match a method + pathname. Static routes win over `/:param` / `*` even
+   * when the parametric route was registered first.
+   *
    * @param method - HTTP method
    * @param path - Pathname
    */
@@ -40,15 +43,18 @@ export class LinearRouter<T> implements Router<T> {
       pathParts.pop();
     }
 
+    // Static first — `GET /health` must win over an earlier `GET /:code`.
     for (const route of this.#routes) {
       if (route.method !== method) continue;
-
-      if (!route.path.includes(":") && !route.path.includes("*")) {
-        if (route.path === path || `${route.path}/` === path) {
-          return { value: route.value, params: {} };
-        }
-        continue;
+      if (route.path.includes(":") || route.path.includes("*")) continue;
+      if (route.path === path || `${route.path}/` === path) {
+        return { value: route.value, params: {} };
       }
+    }
+
+    for (const route of this.#routes) {
+      if (route.method !== method) continue;
+      if (!route.path.includes(":") && !route.path.includes("*")) continue;
 
       const params: Record<string, string> = {};
       let pi = 0;

package/src/kernel/router.test.ts

@@ -71,6 +71,19 @@ describe("router — RegExp + Trie + Linear + Smart", () => {
     expect(r.match("GET", "/x/1")).toEqual({ value: "x", params: { id: "1" } });
   });
 
+  test("LinearRouter prefers static over an earlier /:param", () => {
+    const linear = new LinearRouter<string>();
+    linear.add("GET", "/:code", "redirect");
+    linear.add("GET", "/health", "health");
+    linear.add("GET", "/links", "list");
+    expect(linear.match("GET", "/health")?.value).toBe("health");
+    expect(linear.match("GET", "/links")?.value).toBe("list");
+    expect(linear.match("GET", "/abc")).toEqual({
+      value: "redirect",
+      params: { code: "abc" },
+    });
+  });
+
   test("allowedMethods lists verbs for a path and is empty for unknown paths", () => {
     const regexp = new RegExpRouter<string>();
     regexp.add("POST", "/notes", "create");

package/src/plugins/magic-link.ts

@@ -40,31 +40,36 @@ const DEFAULT_TTL_MS = 10 * 60 * 1000;
 const DEFAULT_FROM = "OKE <no-reply@oke.local>";
 const DEFAULT_BASE_URL = "http://127.0.0.1:6530";
 
+const MAGIC_LINK_SCHEMA = z.object({
+  email: z.string(),
+  token: z.string(),
+  link: z.string(),
+});
+
+const MAGIC_LINK_BODIES = {
+  en: {
+    subject: "Your sign-in link",
+    text: "Sign in with this link:\n{{link}}\n\nOr enter this token:\n{{token}}\n",
+    html: '<p>Sign in with this link:</p><p><a href="{{link}}">{{link}}</a></p><p>Or enter this token:</p><p><code>{{token}}</code></p>',
+  },
+  ar: {
+    subject: "رابط تسجيل الدخول",
+    text: "سجّل الدخول عبر هذا الرابط:\n{{link}}\n\nأو أدخل هذا الرمز:\n{{token}}\n",
+    html: '<p dir="rtl">سجّل الدخول عبر هذا الرابط:</p><p dir="rtl"><a href="{{link}}">{{link}}</a></p><p dir="rtl">أو أدخل هذا الرمز:</p><p dir="rtl"><code>{{token}}</code></p>',
+  },
+} as const;
+
 /** Channel template for magic-link delivery. */
 export const magicLinkTemplate = channel.email({ from: DEFAULT_FROM }).template("auth-magic-link", {
   description: "Magic-link sign-in email",
-  schema: z.object({
-    email: z.string(),
-    token: z.string(),
-    link: z.string(),
-  }),
+  schema: MAGIC_LINK_SCHEMA,
   locales: ["en", "ar"],
+  catalog: MAGIC_LINK_BODIES,
 });
 
-/** Default EN/AR bodies for {@link magicLinkTemplate}. */
+/** Default EN/AR bodies for {@link magicLinkTemplate} (overlay / tests). */
 export const magicLinkCatalog = {
-  "auth-magic-link": {
-    en: {
-      subject: "Your sign-in link",
-      text: "Sign in with this link:\n{{link}}\n\nOr enter this token:\n{{token}}\n",
-      html: '<p>Sign in with this link:</p><p><a href="{{link}}">{{link}}</a></p><p>Or enter this token:</p><p><code>{{token}}</code></p>',
-    },
-    ar: {
-      subject: "رابط تسجيل الدخول",
-      text: "سجّل الدخول عبر هذا الرابط:\n{{link}}\n\nأو أدخل هذا الرمز:\n{{token}}\n",
-      html: '<p dir="rtl">سجّل الدخول عبر هذا الرابط:</p><p dir="rtl"><a href="{{link}}">{{link}}</a></p><p dir="rtl">أو أدخل هذا الرمز:</p><p dir="rtl"><code>{{token}}</code></p>',
-    },
-  },
+  "auth-magic-link": MAGIC_LINK_BODIES,
 } as const;
 
 /** Options for {@link magicLink}. */
@@ -101,12 +106,9 @@ export function magicLink(opts: MagicLinkOptions = {}): PluginDef {
     opts.from !== undefined
       ? channel.email({ from: opts.from }).template("auth-magic-link", {
           description: "Magic-link sign-in email",
-          schema: z.object({
-            email: z.string(),
-            token: z.string(),
-            link: z.string(),
-          }),
+          schema: MAGIC_LINK_SCHEMA,
           locales: ["en", "ar"],
+          catalog: MAGIC_LINK_BODIES,
         })
       : magicLinkTemplate;
 
@@ -213,7 +215,6 @@ export function magicLink(opts: MagicLinkOptions = {}): PluginDef {
     .needs("auth")
     .needs("channel")
     .channelTemplate(tmpl)
-    .channelCatalog(magicLinkCatalog)
     .binding(bindPublicAuth("/magic-link/request", request, "otp", requestContract))
     .binding(bindPublicAuth("/magic-link/verify", verify, "otp", verifyContract));
 }

package/src/plugins/otp.ts

@@ -94,11 +94,37 @@ export interface OtpAppModeOptions extends OtpBaseOptions {
 /** Options for {@link otp}. `mode` is mandatory — no auto-detect. */
 export type OtpOptions = OtpProviderModeOptions | OtpAppModeOptions;
 
+const OTP_EMAIL_BODIES = {
+  en: {
+    subject: "Your sign-in code",
+    text: "Your one-time sign-in code is: {{otp}}\n",
+    html: "<p>Your one-time sign-in code is:</p><p><strong>{{otp}}</strong></p>",
+  },
+  ar: {
+    subject: "رمز تسجيل الدخول",
+    text: "رمز تسجيل الدخول لمرة واحدة هو: {{otp}}\n",
+    html: '<p dir="rtl">رمز تسجيل الدخول لمرة واحدة هو:</p><p dir="rtl"><strong>{{otp}}</strong></p>',
+  },
+} as const;
+
+const OTP_SMS_BODIES = {
+  en: { text: "Your sign-in code is: {{otp}}" },
+  ar: { text: "رمز تسجيل الدخول: {{otp}}" },
+} as const;
+
+const OTP_WHATSAPP_BODIES = {
+  en: { text: "Your sign-in code is: {{otp}}" },
+  ar: { text: "رمز تسجيل الدخول: {{otp}}" },
+} as const;
+
+const OTP_EMAIL_SCHEMA = z.object({ email: z.string(), otp: z.string() });
+
 /** Email OTP template (app mode). */
 export const otpEmailTemplate = channel.email({ from: DEFAULT_FROM }).template("auth-otp-email", {
   description: "OTP sign-in code (email)",
-  schema: z.object({ email: z.string(), otp: z.string() }),
+  schema: OTP_EMAIL_SCHEMA,
   locales: ["en", "ar"],
+  catalog: OTP_EMAIL_BODIES,
 });
 
 /** SMS OTP template (app mode — plain message, not provider Verify). */
@@ -106,6 +132,7 @@ export const otpSmsTemplate = channel.sms().template("auth-otp-sms", {
   description: "OTP sign-in code (SMS)",
   schema: z.object({ phone: z.string(), otp: z.string() }),
   locales: ["en", "ar"],
+  catalog: OTP_SMS_BODIES,
 });
 
 /** WhatsApp OTP template (app mode). */
@@ -113,30 +140,14 @@ export const otpWhatsappTemplate = channel.whatsapp().template("auth-otp-whatsap
   description: "OTP sign-in code (WhatsApp)",
   schema: z.object({ phone: z.string(), otp: z.string() }),
   locales: ["en", "ar"],
+  catalog: OTP_WHATSAPP_BODIES,
 });
 
-/** Default EN/AR bodies for OTP templates. */
+/** Default EN/AR bodies for OTP templates (overlay / tests). */
 export const otpCatalog = {
-  "auth-otp-email": {
-    en: {
-      subject: "Your sign-in code",
-      text: "Your one-time sign-in code is: {{otp}}\n",
-      html: "<p>Your one-time sign-in code is:</p><p><strong>{{otp}}</strong></p>",
-    },
-    ar: {
-      subject: "رمز تسجيل الدخول",
-      text: "رمز تسجيل الدخول لمرة واحدة هو: {{otp}}\n",
-      html: '<p dir="rtl">رمز تسجيل الدخول لمرة واحدة هو:</p><p dir="rtl"><strong>{{otp}}</strong></p>',
-    },
-  },
-  "auth-otp-sms": {
-    en: { text: "Your sign-in code is: {{otp}}" },
-    ar: { text: "رمز تسجيل الدخول: {{otp}}" },
-  },
-  "auth-otp-whatsapp": {
-    en: { text: "Your sign-in code is: {{otp}}" },
-    ar: { text: "رمز تسجيل الدخول: {{otp}}" },
-  },
+  "auth-otp-email": OTP_EMAIL_BODIES,
+  "auth-otp-sms": OTP_SMS_BODIES,
+  "auth-otp-whatsapp": OTP_WHATSAPP_BODIES,
 } as const;
 
 function assertOtpOptions(opts: OtpOptions): void {
@@ -217,8 +228,9 @@ export function otp(opts: OtpOptions): PluginDef {
     from !== undefined
       ? channel.email({ from }).template("auth-otp-email", {
           description: "OTP sign-in code (email)",
-          schema: z.object({ email: z.string(), otp: z.string() }),
+          schema: OTP_EMAIL_SCHEMA,
           locales: ["en", "ar"],
+          catalog: OTP_EMAIL_BODIES,
         })
       : otpEmailTemplate;
 
@@ -613,7 +625,6 @@ export function otp(opts: OtpOptions): PluginDef {
     .channelTemplate(emailTmpl)
     .channelTemplate(otpSmsTemplate)
     .channelTemplate(otpWhatsappTemplate)
-    .channelCatalog(otpCatalog)
     .binding(bindPublicAuth("/otp/request", request, "otp", requestContract))
     .binding(bindPublicAuth("/otp/verify", verify, "otp", verifyContract))
     .binding(bindPublicAuth("/otp/resend", resend, "otp", resendContract));

package/src/plugins/two-factor.ts

@@ -126,10 +126,24 @@ export function twoFactor(opts: TwoFactorOptions = {}): PluginDef {
     opts.verifications ?? active?.twoFactorVerifications ?? createVerificationStore();
   const exposeDevOtp = opts.exposeDevOtp === true;
 
+  const TWO_FACTOR_EMAIL_BODIES = {
+    en: {
+      subject: "Your two-factor code",
+      text: "Your two-factor sign-in code is: {{otp}}\n",
+      html: "<p>Your two-factor sign-in code is:</p><p><strong>{{otp}}</strong></p>",
+    },
+    ar: {
+      subject: "رمز التحقق بخطوتين",
+      text: "رمز التحقق بخطوتين هو: {{otp}}\n",
+      html: '<p dir="rtl">رمز التحقق بخطوتين هو:</p><p dir="rtl"><strong>{{otp}}</strong></p>',
+    },
+  } as const;
+
   const emailTmpl = channel.email({ from: "OKE <no-reply@oke.local>" }).template("auth-2fa-email", {
     description: "Two-factor email OTP",
     schema: z.object({ email: z.string(), otp: z.string() }),
     locales: ["en", "ar"],
+    catalog: TWO_FACTOR_EMAIL_BODIES,
   });
 
   async function provisionEmailOtp(userId: string, now: number): Promise<string | undefined> {
@@ -566,6 +580,7 @@ export function twoFactor(opts: TwoFactorOptions = {}): PluginDef {
 
   return plugin("twoFactor", { version: "0.0.1", config: { method: "two-factor" } })
     .needs("auth")
+    .channelTemplate(emailTmpl)
     .table("oke_two_factor", undefined, { plane: "user", description: "TOTP secrets + recovery" })
     .binding(bindSessionAuth("/two-factor/enable", enable, enableContract))
     .binding(bindPublicAuth("/two-factor/verify", verify, "otp", verifyContract))

package/src/runs/duckdb.test.ts

@@ -19,9 +19,9 @@ describe("openDuckDB", () => {
     }
   });
 
-  test("both create-oke templates declare @duckdb/node-api", () => {
+  test("create-oke templates declare @duckdb/node-api", () => {
     const root = join(import.meta.dir, "../../packages/create-oke/templates");
-    for (const tier of ["standard", "advanced"] as const) {
+    for (const tier of ["blank", "shorter"] as const) {
       const pkg = JSON.parse(readFileSync(join(root, tier, "package.json"), "utf8")) as {
         dependencies?: { "@duckdb/node-api"?: string };
         trustedDependencies?: readonly string[];

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

@@ -56,6 +56,8 @@ export type DevRequestLogInput = {
   readonly ms: number;
   /** Human failure detail (error.message / code) for 4xx/5xx. */
   readonly detail?: string;
+  /** Failure `error.code` for the title chip. */
+  readonly errorCode?: string;
 };
 
 /**
@@ -85,16 +87,19 @@ export function isSilentDevRequest(method: string, path: string, surface?: DevLo
  *
  * @param response - HTTP response (cloned; original body stays readable)
  */
-export async function failureDetailFromResponse(response: Response): Promise<string | undefined> {
-  if (response.status < 400) return undefined;
+export async function failureEnvelopeFromResponse(
+  response: Response,
+): Promise<{ readonly detail?: string; readonly code?: string }> {
+  if (response.status < 400) return {};
   try {
     const body: unknown = await response.clone().json();
-    if (body === null || typeof body !== "object" || !("error" in body)) return undefined;
+    if (body === null || typeof body !== "object" || !("error" in body)) return {};
     const error = (body as { error: unknown }).error;
-    if (error === null || typeof error !== "object") return undefined;
+    if (error === null || typeof error !== "object") return {};
     const rec = error as { message?: unknown; code?: unknown; data?: unknown };
+    const code = typeof rec.code === "string" ? rec.code : undefined;
     if (typeof rec.message === "string" && rec.message.trim().length > 0) {
-      return rec.message.trim();
+      return { detail: rec.message.trim(), ...(code ? { code } : {}) };
     }
     if (
       rec.data !== null &&
@@ -103,14 +108,25 @@ export async function failureDetailFromResponse(response: Response): Promise<str
       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}`;
+      return {
+        detail: `${code ?? "Error"}: ${reason}`,
+        ...(code ? { code } : {}),
+      };
     }
-    if (typeof rec.code === "string") return rec.code;
+    if (code) return { detail: code, code };
   } catch {
     // non-JSON error bodies stay status-only
   }
-  return undefined;
+  return {};
+}
+
+/**
+ * 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> {
+  return (await failureEnvelopeFromResponse(response)).detail;
 }
 
 /**
@@ -135,6 +151,7 @@ export function logDevRequest(input: DevRequestLogInput): void {
       status: input.status,
       ms: input.ms,
       detail: input.detail,
+      errorCode: input.errorCode,
     }),
   );
 }
@@ -167,7 +184,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);
+  const envelope = await failureEnvelopeFromResponse(response);
   logDevRequest({
     surface: options.surface ?? currentDevSurface(),
     method,
@@ -176,7 +193,8 @@ export async function timedDevFetch(
     runId: options.resolveRunId?.(request, response),
     status: response.status,
     ms: Math.round(performance.now() - started),
-    detail,
+    detail: envelope.detail,
+    errorCode: envelope.code,
   });
   return response;
 }