okengine 0.20.0 → 0.21.0

package/src/elements/store/sql-errors.ts

@@ -0,0 +1,294 @@
+/**
+ * Map driver SQL errors to typed {@link FlowFailure} values.
+ *
+ * Lives on the store path — not the kernel edge graph. Public payloads are
+ * names only (constraint / table / column / sqlstate). Never copy
+ * `message` / `detail` / `hint`.
+ */
+
+import { fail } from "../../kernel/fail-helpers.ts";
+import type { FlowFailure } from "../../kernel/errors.ts";
+import type { BuiltinErrorMap } from "../../kernel/builtin-errors.ts";
+
+/** How to treat serialization / deadlock SQLSTATE (`40001` / `40P01`). */
+export type SqlRetryableMode = "leave" | "unavailable";
+
+/** Options for {@link sqlErrorToFailure}. */
+export interface SqlErrorToFailureOptions {
+  /**
+   * `leave` — return `undefined` so {@link flow.retry} can rethrow.
+   * `unavailable` — map to `ServiceUnavailable` after retries exhaust.
+   */
+  readonly retryable?: SqlRetryableMode;
+}
+
+type SqlFailure = FlowFailure<
+  | BuiltinErrorMap["Conflict"]
+  | BuiltinErrorMap["DatabaseError"]
+  | BuiltinErrorMap["ServiceUnavailable"]
+>;
+
+type SqlErrShape = {
+  readonly name?: unknown;
+  readonly code?: unknown;
+  readonly errno?: unknown;
+  readonly message?: unknown;
+  readonly cause?: unknown;
+  readonly constraint?: unknown;
+  readonly table?: unknown;
+  readonly column?: unknown;
+  readonly table_name?: unknown;
+  readonly column_name?: unknown;
+  readonly constraint_name?: unknown;
+};
+
+const CONFLICT_STATE = new Set(["23505", "23P01"]);
+const FOREIGN_KEY_STATE = new Set(["23503", "23001"]);
+const NOT_NULL_STATE = new Set(["23502"]);
+const CHECK_STATE = new Set(["23514"]);
+const RETRY_STATE = new Set(["40001", "40P01", "55P03"]);
+const TOO_LONG_STATE = new Set(["22001"]);
+const OUT_OF_RANGE_STATE = new Set(["22003", "22008"]);
+const INVALID_STATE = new Set(["22P02", "22007", "22023", "42804"]);
+const UNAVAILABLE_STATE = new Set([
+  "53300",
+  "53100",
+  "53200",
+  "53400",
+  "57P01",
+  "57P02",
+  "57P03",
+  "57P04",
+  "57014",
+  "25P03",
+]);
+
+/** bun:sqlite / libsql busy / locked (leave thrown for retry). */
+const SQLITE_RETRY_ERRNO = new Set([5, 6, 261, 517]);
+/** bun:sqlite PRIMARYKEY / ROWID unique. */
+const SQLITE_CONFLICT_ERRNO = new Set([1555, 2067, 2579]);
+const SQLITE_UNAVAILABLE_ERRNO = new Set([8, 10, 13, 14, 15]);
+
+/**
+ * True when `err` is a serialization / deadlock / lock-busy failure.
+ *
+ * Left thrown during retries; mapped to `ServiceUnavailable` after exhaust.
+ *
+ * @param err - Caught driver error
+ */
+export function isRetryableSqlError(err: unknown): boolean {
+  return walk(err, (node) => retrySignal(node));
+}
+
+/**
+ * Map a driver SQL error to a typed failure, or `undefined` when it is not a
+ * SQL constraint / connection failure (or is retryable under `leave`).
+ *
+ * @param err - Caught value from `query` / `exec`
+ * @param options - Retryable handling
+ */
+export function sqlErrorToFailure(
+  err: unknown,
+  options: SqlErrorToFailureOptions = {},
+): SqlFailure | undefined {
+  const retryable = options.retryable ?? "leave";
+  let unknownNode: unknown;
+  let current: unknown = err;
+  for (let i = 0; i < 4; i++) {
+    if (!current || typeof current !== "object") break;
+    if (retrySignal(current)) {
+      if (retryable === "leave") return undefined;
+      return fail.serviceUnavailable();
+    }
+    if (isConnectionUnavailable(current)) return fail.serviceUnavailable();
+    const mapped = mapConstraint(current);
+    if (mapped) return mapped;
+    if (unknownNode === undefined && looksLikeSqlError(current)) unknownNode = current;
+    current = causeOf(current);
+  }
+  if (unknownNode !== undefined) {
+    return fail.database({ reason: "unknown", ...publicNames(unknownNode) });
+  }
+  return undefined;
+}
+
+function mapConstraint(err: unknown): SqlFailure | undefined {
+  const code = sqlCode(err);
+  const names = publicNames(err);
+
+  if (CONFLICT_STATE.has(code)) return fail.conflict(names);
+  if (FOREIGN_KEY_STATE.has(code)) return fail.foreignKey(names);
+  if (NOT_NULL_STATE.has(code)) return fail.database({ reason: "not_null", ...names });
+  if (CHECK_STATE.has(code)) return fail.database({ reason: "check", ...names });
+  if (TOO_LONG_STATE.has(code)) return fail.database({ reason: "too_long", ...names });
+  if (OUT_OF_RANGE_STATE.has(code)) return fail.database({ reason: "out_of_range", ...names });
+  if (INVALID_STATE.has(code)) return fail.database({ reason: "invalid", ...names });
+
+  const sqlite = sqliteConstraint(err);
+  if (sqlite === "unique") return fail.conflict(names);
+  if (sqlite === "fk") return fail.foreignKey(names);
+  if (sqlite === "not_null") return fail.database({ reason: "not_null", ...names });
+  if (sqlite === "check") return fail.database({ reason: "check", ...names });
+
+  return undefined;
+}
+
+function retrySignal(err: unknown): boolean {
+  const code = sqlCode(err);
+  if (RETRY_STATE.has(code)) return true;
+  const errno = sqlErrno(err);
+  if (errno !== undefined && SQLITE_RETRY_ERRNO.has(errno)) return true;
+  const named = sqlCode(err);
+  if (named === "SQLITE_BUSY" || named === "SQLITE_LOCKED" || named === "SQLITE_BUSY_SNAPSHOT") {
+    return true;
+  }
+  return false;
+}
+
+function isConnectionUnavailable(err: unknown): boolean {
+  const e = err as SqlErrShape;
+  const code = sqlCode(err);
+  if (code.startsWith("08")) return true;
+  if (code.startsWith("53")) return true;
+  if (UNAVAILABLE_STATE.has(code)) return true;
+  if (code.startsWith("ERR_POSTGRES_")) return true;
+  if (code === "ERR_OKE_POSTGRES_PAUSED") return true;
+  if (typeof e.name === "string" && e.name === "SharedPostgresPausedError") return true;
+  const errno = sqlErrno(err);
+  if (errno !== undefined && SQLITE_UNAVAILABLE_ERRNO.has(errno)) return true;
+  if (code === "SQLITE_READONLY" || code === "SQLITE_FULL" || code === "SQLITE_CANTOPEN") {
+    return true;
+  }
+  const message = typeof e.message === "string" ? e.message : "";
+  if (/postgres pools are paused/i.test(message)) return true;
+  return false;
+}
+
+function looksLikeSqlError(err: unknown): boolean {
+  const e = err as SqlErrShape;
+  const code = sqlCode(err);
+  if (/^[0-9A-Z]{5}$/.test(code)) return true;
+  if (code.startsWith("SQLITE_")) return true;
+  if (typeof e.name === "string" && /postgres|sqlite|pglite|libsql/i.test(e.name)) return true;
+  const message = typeof e.message === "string" ? e.message : "";
+  return /sqlstate|constraint|syntax error/i.test(message);
+}
+
+function sqlCode(err: unknown): string {
+  if (!err || typeof err !== "object") return "";
+  const code = (err as SqlErrShape).code;
+  return typeof code === "string" ? code : "";
+}
+
+function sqlErrno(err: unknown): number | undefined {
+  if (!err || typeof err !== "object") return undefined;
+  const errno = (err as SqlErrShape).errno;
+  return typeof errno === "number" ? errno : undefined;
+}
+
+function publicNames(err: unknown): {
+  readonly sqlstate?: string;
+  readonly constraint?: string;
+  readonly table?: string;
+  readonly column?: string;
+} {
+  const e = err as SqlErrShape;
+  const sqlstate = sqlCode(err);
+  const constraint = firstString(e.constraint, e.constraint_name);
+  const table = firstString(e.table, e.table_name);
+  const column = firstString(e.column, e.column_name);
+  const fromMessage = parseSqliteNames(typeof e.message === "string" ? e.message : "");
+  const out: {
+    sqlstate?: string;
+    constraint?: string;
+    table?: string;
+    column?: string;
+  } = {};
+  if (/^[0-9A-Z]{5}$/.test(sqlstate)) out.sqlstate = sqlstate;
+  const constraintName = constraint ?? fromMessage.constraint;
+  if (constraintName) out.constraint = constraintName;
+  const tableName = table ?? fromMessage.table;
+  const columnName = column ?? fromMessage.column;
+  if (tableName) out.table = tableName;
+  if (columnName) out.column = columnName;
+  return out;
+}
+
+function firstString(...values: readonly unknown[]): string | undefined {
+  for (const v of values) {
+    if (typeof v === "string" && v.length > 0) return v;
+  }
+  return undefined;
+}
+
+function parseSqliteNames(message: string): {
+  table?: string;
+  column?: string;
+  constraint?: string;
+} {
+  const dotted =
+    /(?:UNIQUE|NOT NULL|PRIMARY KEY) constraint failed:\s*([A-Za-z_][\w]*)\.([A-Za-z_][\w]*)/i.exec(
+      message,
+    );
+  if (dotted?.[1] && dotted[2]) {
+    return { table: dotted[1], column: dotted[2] };
+  }
+  const check = /CHECK constraint failed:\s*([A-Za-z_][\w]*)/i.exec(message);
+  if (check?.[1]) return { constraint: check[1] };
+  return {};
+}
+
+type SqliteKind = "unique" | "fk" | "not_null" | "check";
+
+function sqliteConstraint(err: unknown): SqliteKind | undefined {
+  const e = err as SqlErrShape;
+  const message = typeof e.message === "string" ? e.message : "";
+  const errno = sqlErrno(err);
+  const code = sqlCode(err);
+  if (
+    (errno !== undefined && SQLITE_CONFLICT_ERRNO.has(errno)) ||
+    code === "SQLITE_CONSTRAINT_UNIQUE" ||
+    code === "SQLITE_CONSTRAINT_PRIMARYKEY" ||
+    /UNIQUE constraint failed/i.test(message) ||
+    /PRIMARY KEY constraint failed/i.test(message)
+  ) {
+    return "unique";
+  }
+  if (
+    errno === 787 ||
+    code === "SQLITE_CONSTRAINT_FOREIGNKEY" ||
+    /FOREIGN KEY constraint failed/i.test(message)
+  ) {
+    return "fk";
+  }
+  if (
+    errno === 1299 ||
+    code === "SQLITE_CONSTRAINT_NOTNULL" ||
+    /NOT NULL constraint failed/i.test(message)
+  ) {
+    return "not_null";
+  }
+  if (
+    errno === 275 ||
+    code === "SQLITE_CONSTRAINT_CHECK" ||
+    /CHECK constraint failed/i.test(message)
+  ) {
+    return "check";
+  }
+  return undefined;
+}
+
+function causeOf(err: unknown): unknown {
+  if (!err || typeof err !== "object") return undefined;
+  return (err as SqlErrShape).cause;
+}
+
+function walk(err: unknown, pred: (node: unknown) => boolean): boolean {
+  let current: unknown = err;
+  for (let i = 0; i < 4; i++) {
+    if (pred(current)) return true;
+    current = causeOf(current);
+    if (current === undefined) break;
+  }
+  return false;
+}

package/src/elements/store/sql-session.test.ts

@@ -15,6 +15,7 @@ import { and, desc, eq, like, lt, or } from "drizzle-orm";
 import { integer, pgTable, text } from "drizzle-orm/pg-core";
 import { pgliteDriver } from "../../drivers/pglite.ts";
 import type { SqlConnection } from "../../drivers/types.ts";
+import { isFlowFailure } from "../../kernel/hooks.ts";
 import { createSqlStoreHandle, type SqlStoreHandle } from "./sql-session.ts";
 
 const posts = pgTable("posts", {
@@ -168,3 +169,54 @@ describe("SqlStoreHandle — upsert", () => {
     expect(row).toEqual({ id: "n1", title: "two", createdAt: 20 });
   });
 });
+
+describe("SqlStoreHandle — SQL constraints become typed failures", () => {
+  test("unique insert is Conflict; missing FK is ForeignKey", async () => {
+    await sharedConn.exec(`
+      CREATE TABLE IF NOT EXISTS "acct" (
+        "id" TEXT PRIMARY KEY,
+        "email" TEXT NOT NULL UNIQUE
+      )
+    `);
+    await sharedConn.exec(`
+      CREATE TABLE IF NOT EXISTS "note" (
+        "id" TEXT PRIMARY KEY,
+        "acct_id" TEXT NOT NULL REFERENCES "acct"("id")
+      )
+    `);
+    await sharedConn.exec(`TRUNCATE "note", "acct" RESTART IDENTITY CASCADE`);
+
+    const acct = pgTable("acct", {
+      id: text("id").primaryKey(),
+      email: text("email").notNull(),
+    });
+    const note = pgTable("note", {
+      id: text("id").primaryKey(),
+      acctId: text("acct_id").notNull(),
+    });
+
+    await sharedHandle.insert(acct).values({ id: "a1", email: "a@b.c" });
+    let unique: unknown;
+    try {
+      await sharedHandle.insert(acct).values({ id: "a2", email: "a@b.c" });
+    } catch (err) {
+      unique = err;
+    }
+    expect(isFlowFailure(unique)).toBe(true);
+    if (isFlowFailure(unique)) {
+      expect(unique.error.code).toBe("Conflict");
+      expect(JSON.stringify(unique)).not.toContain("a@b.c");
+    }
+
+    let fk: unknown;
+    try {
+      await sharedHandle.insert(note).values({ id: "n1", acctId: "missing" });
+    } catch (err) {
+      fk = err;
+    }
+    expect(isFlowFailure(fk)).toBe(true);
+    if (isFlowFailure(fk)) {
+      expect(fk.error.code).toBe("ForeignKey");
+    }
+  });
+});

package/src/elements/store/sql-session.ts

@@ -14,6 +14,8 @@ import {
   type RlsIdentity,
 } from "../../drivers/pg-rls.ts";
 import { throwOke } from "../../kernel/errors.ts";
+import { isFlowFailure } from "../../kernel/hooks.ts";
+import { isRetryableSqlError, sqlErrorToFailure } from "./sql-errors.ts";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { maskRows, tableFromSql } from "./classify.ts";
 import { isMissingDomainRelationError } from "./missing-relation.ts";
@@ -549,9 +551,13 @@ export function createSqlStoreHandle(
     try {
       return await fn();
     } catch (err) {
+      if (isFlowFailure(err)) throw err;
       if (domainDdl === "off" && isMissingDomainRelationError(err)) {
         throwOke("DOMAIN_SCHEMA_MISSING");
       }
+      if (isRetryableSqlError(err)) throw err;
+      const failure = sqlErrorToFailure(err, { retryable: "leave" });
+      if (failure) throw failure;
       throw err;
     }
   }

package/src/elements/store/store-errors.ts

@@ -0,0 +1,47 @@
+/**
+ * Store-path error map — SQL, Redis KV, then files. Off the kernel edge graph.
+ */
+
+import { isFlowFailure } from "../../kernel/hooks.ts";
+import type { FlowFailure } from "../../kernel/errors.ts";
+import { filesErrorToFailure, type FilesErrorToFailureOptions } from "./files-errors.ts";
+import { kvErrorToFailure, type KvErrorToFailureOptions } from "./kv-errors.ts";
+import { sqlErrorToFailure, type SqlErrorToFailureOptions } from "./sql-errors.ts";
+
+/** Shared retryable handling for SQL, Redis KV, and files mappers. */
+export type StoreErrorToFailureOptions = SqlErrorToFailureOptions &
+  KvErrorToFailureOptions &
+  FilesErrorToFailureOptions;
+
+/**
+ * Map a store driver throw to a typed failure (SQL, then Redis KV, then files).
+ *
+ * @param err - Caught value from `fx.store`
+ * @param options - Retryable handling
+ */
+export function storeErrorToFailure(
+  err: unknown,
+  options: StoreErrorToFailureOptions = {},
+): FlowFailure | undefined {
+  return (
+    sqlErrorToFailure(err, options) ??
+    kvErrorToFailure(err, options) ??
+    filesErrorToFailure(err, options)
+  );
+}
+
+/**
+ * Run a store op; remap known SQL / Redis / files failures, leave retryable throws.
+ *
+ * @param fn - Store operation
+ */
+export async function withStoreErrorMap<T>(fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn();
+  } catch (err) {
+    if (isFlowFailure(err)) throw err;
+    const mapped = storeErrorToFailure(err, { retryable: "leave" });
+    if (mapped) throw mapped;
+    throw err;
+  }
+}

package/src/http.ts

@@ -23,7 +23,15 @@ export { http, internal } from "./kernel/triggers.ts";
 export type { BoundaryContract } from "./kernel/boundary-contract.ts";
 export { clock } from "./elements/clock/declare.ts";
 export { gate, GATE_PUBLIC_NAME } from "./elements/gate/declare.ts";
-export { fail, type FlowFailure } from "./kernel/errors.ts";
+export { fail, type FailFn } from "./kernel/fail-helpers.ts";
+export { type FlowFailure, type FlowErrorValue } from "./kernel/errors.ts";
+export type {
+  BuiltinErrorBag,
+  BuiltinErrorCode,
+  BuiltinErrorMap,
+  BuiltinValidationIssue,
+  DatabaseErrorReason,
+} from "./kernel/builtin-errors.ts";
 export { isFlowFailure } from "./kernel/hooks.ts";
 export { plugin, isPlugin, type PluginDef } from "./kernel/plugin.ts";
 export { createBunRuntime, APP_PORT, type Runtime, type ServeOptions } from "./runtime/index.ts";

package/src/i18n/catalogs/ar.ts

@@ -64,6 +64,10 @@ export const builtinAr = {
       cause: "جدول النطاق غير موجود — لم تُطبَّق الترحيلات.",
       fix: "شغّل `oke db migrate` على هذه البيئة.",
     },
+    "1510": {
+      cause: "{count} أسرار بلا قيمة في أي طبقة حل.",
+      fix: "عيّن كل اسم (`oke vault set <name>` أو `.env.local`).",
+    },
   },
   errors: {
     Unauthorized: "المصادقة مطلوبة.",
@@ -71,6 +75,19 @@ export const builtinAr = {
     RateLimited: "طلبات كثيرة جداً. حاول لاحقاً.",
     ValidationError: "فشل التحقق من الطلب.",
     NotFound: "المورد المطلوب غير موجود.",
+    Conflict: "هذه القيمة مستخدمة بالفعل.",
+    ForeignKey: "السجل المرتبط غير موجود.",
+    DatabaseError: "رفضت قاعدة البيانات هذا التغيير.",
+    "DatabaseError.not_null": "حقل مطلوب مفقود.",
+    "DatabaseError.check": "قيمة لم تستوفِ قيداً في قاعدة البيانات.",
+    "DatabaseError.invalid": "قيمة غير صالحة لهذا العمود.",
+    "DatabaseError.too_long": "القيمة أطول من المسموح لهذا العمود.",
+    "DatabaseError.out_of_range": "القيمة خارج النطاق المسموح.",
+    "DatabaseError.retryable": "قاعدة البيانات مشغولة. حاول بعد قليل.",
+    ServiceUnavailable: "الخدمة غير متاحة مؤقتاً.",
+    InternalError: "حدث خطأ. حاول مرة أخرى.",
+    InvalidQuery: "الاستعلام غير صالح.",
+    UnsupportedMediaType: "نوع المحتوى هذا غير مدعوم.",
     AuthFailed: "فشلت المصادقة.",
     AuthRateLimited: "محاولات مصادقة كثيرة جداً. حاول لاحقاً.",
     "AuthFailed.invalid_credentials": "بيانات الاعتماد غير صحيحة.",
@@ -83,6 +100,7 @@ export const builtinAr = {
     "AuthFailed.password_policy": "كلمة المرور لا تستوفي متطلبات السياسة.",
     "AuthFailed.invalid_origin": "تم رفض أصل مفتاح المرور.",
     "Forbidden.csrf": "تم حظر الطلب عبر المواقع.",
+    "Forbidden.invalid_key": "مفتاح الكائن هذا غير مسموح.",
     "Forbidden.ip_denied": "عنوان IP الخاص بك محظور.",
     "Forbidden.ip_not_allowed": "عنوان IP الخاص بك غير مسموح.",
     "Forbidden.policy_denied": "رفضت السياسة هذا الطلب.",

package/src/i18n/catalogs/en.ts

@@ -64,6 +64,10 @@ export const builtinEn = {
       cause: "domain table not found — migrations have not been applied.",
       fix: "run `oke db migrate` against this environment.",
     },
+    "1510": {
+      cause: "{count} secrets have no value in any resolution layer.",
+      fix: "Set each name (`oke vault set <name>`, or `.env.local`).",
+    },
   },
   errors: {
     Unauthorized: "Authentication required.",
@@ -71,6 +75,19 @@ export const builtinEn = {
     RateLimited: "Too many requests. Try again later.",
     ValidationError: "The request failed validation.",
     NotFound: "The requested resource was not found.",
+    Conflict: "That value is already in use.",
+    ForeignKey: "That related record does not exist.",
+    DatabaseError: "The database rejected this change.",
+    "DatabaseError.not_null": "A required field is missing.",
+    "DatabaseError.check": "A value did not meet a database check.",
+    "DatabaseError.invalid": "A value is not valid for that column.",
+    "DatabaseError.too_long": "A value is too long for that column.",
+    "DatabaseError.out_of_range": "A value is outside the allowed range.",
+    "DatabaseError.retryable": "The database is busy. Try again shortly.",
+    ServiceUnavailable: "The service is temporarily unavailable.",
+    InternalError: "Something went wrong. Try again.",
+    InvalidQuery: "The query is not valid.",
+    UnsupportedMediaType: "That content type is not supported.",
     AuthFailed: "Authentication failed.",
     AuthRateLimited: "Too many authentication attempts. Try again later.",
     "AuthFailed.invalid_credentials": "Invalid credentials.",
@@ -84,6 +101,7 @@ export const builtinEn = {
     "AuthFailed.password_policy": "That password does not meet the policy requirements.",
     "AuthFailed.invalid_origin": "Passkey origin was rejected.",
     "Forbidden.csrf": "Cross-site request blocked.",
+    "Forbidden.invalid_key": "That object key is not allowed.",
     "Forbidden.ip_denied": "Your IP address is blocked.",
     "Forbidden.ip_not_allowed": "Your IP address is not allowed.",
     "Forbidden.policy_denied": "Policy denied this request.",

package/src/index.ts

@@ -32,7 +32,15 @@ export { http, internal, mcp } from "./kernel/triggers.ts";
 export type { BoundaryContract } from "./kernel/boundary-contract.ts";
 export { registerFlowUnits } from "./kernel/flow-units.ts";
 export { stampFlowName, stampHttpPath } from "./kernel/stamp-http.ts";
-export { fail, type FlowFailure, type FlowErrorValue } from "./kernel/errors.ts";
+export { fail, type FailFn } from "./kernel/fail-helpers.ts";
+export { type FlowFailure, type FlowErrorValue } from "./kernel/errors.ts";
+export type {
+  BuiltinErrorBag,
+  BuiltinErrorCode,
+  BuiltinErrorMap,
+  BuiltinValidationIssue,
+  DatabaseErrorReason,
+} from "./kernel/builtin-errors.ts";
 export { isFlowFailure } from "./kernel/hooks.ts";
 export { plugin, isPlugin, type PluginDef, type PluginCapabilities } from "./kernel/plugin.ts";
 export type { Fx, FxPrincipal, StepOptions } from "./kernel/fx.ts";

package/src/kernel/app.ts

@@ -61,7 +61,7 @@ import type {
 } from "./fx.ts";
 import {
   currentDevSurface,
-  failureDetailFromResponse,
+  failureEnvelopeFromResponse,
   logDevRequest,
   shouldLogDevRequests,
 } from "../runtime/dev-request-log.ts";
@@ -351,6 +351,11 @@ export interface ExecuteResult {
   readonly failure: PipelineResult["failure"];
   readonly response: Response | undefined;
   readonly ctx: InvocationContext;
+  /**
+   * Derived projection of {@link InvocationContext.error} — never a separate
+   * store. Always `=== ctx.error` by reference.
+   */
+  readonly error: unknown;
   readonly fx: Fx;
   /** Wide-event cache dimension from this invocation's telemetry. */
   readonly cache: "hit" | "miss" | "none";
@@ -1915,6 +1920,7 @@ export function oke(options: OkeOptions): OkeApp {
           },
         );
         if (inner.failure) return inner.failure;
+        if (inner.ctx.error !== undefined) throw inner.ctx.error;
         return inner.output;
       },
     });
@@ -2144,6 +2150,9 @@ export function oke(options: OkeOptions): OkeApp {
       failure: result.failure,
       response: result.response,
       ctx: result.ctx,
+      get error() {
+        return result.ctx.error;
+      },
       fx,
       cache: cacheDimensionOf(telemetry),
       durationMs,
@@ -2328,6 +2337,7 @@ export function oke(options: OkeOptions): OkeApp {
           response.headers.set("accept-query", '"application/json"');
         }
         if (shouldLogDevRequests()) {
+          const envelope = await failureEnvelopeFromResponse(response);
           logDevRequest({
             surface: currentDevSurface(),
             method,
@@ -2336,7 +2346,8 @@ export function oke(options: OkeOptions): OkeApp {
             runId: runLabel,
             status: response.status,
             ms: Math.round(performance.now() - started),
-            detail: await failureDetailFromResponse(response),
+            detail: envelope.detail,
+            errorCode: envelope.code,
           });
         }
         const jcb = loadJsonCodeBlock();
@@ -2552,6 +2563,7 @@ export function oke(options: OkeOptions): OkeApp {
         flowDef.triggers[0] ?? ({ kind: "internal" } satisfies InternalTrigger);
       const result = await execute(flowDef, input, trigger);
       if (result.failure) return result.failure;
+      if (result.ctx.error !== undefined) throw result.ctx.error;
       return result.output;
     },
     resolveMcpTool(name) {