okengine 0.20.0 → 0.21.0

package/src/kernel/builtin-errors.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Built-in failure HTTP status map.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { fail } from "./errors.ts";
+import { httpStatusForFailure, statusForBuiltinError } from "./builtin-errors.ts";
+import { encodeExecuteResult, statusForFailure } from "../compiler/response.ts";
+
+describe("statusForBuiltinError", () => {
+  test("maps REST codes", () => {
+    expect(statusForBuiltinError("NotFound")).toBe(404);
+    expect(statusForBuiltinError("Conflict")).toBe(409);
+    expect(statusForBuiltinError("ForeignKey")).toBe(409);
+    expect(statusForBuiltinError("Unauthorized")).toBe(401);
+    expect(statusForBuiltinError("Forbidden")).toBe(403);
+    expect(statusForBuiltinError("RateLimited")).toBe(429);
+    expect(statusForBuiltinError("AuthRateLimited")).toBe(429);
+    expect(statusForBuiltinError("ValidationError")).toBe(422);
+    expect(statusForBuiltinError("UnsupportedMediaType")).toBe(415);
+    expect(statusForBuiltinError("ServiceUnavailable")).toBe(503);
+    expect(statusForBuiltinError("InternalError")).toBe(500);
+    expect(statusForBuiltinError("AuthFailed")).toBe(400);
+    expect(statusForBuiltinError("InvalidQuery")).toBe(400);
+  });
+
+  test("DatabaseError status follows data.reason", () => {
+    expect(statusForBuiltinError("DatabaseError", { reason: "not_null" })).toBe(422);
+    expect(statusForBuiltinError("DatabaseError", { reason: "check" })).toBe(422);
+    expect(statusForBuiltinError("DatabaseError", { reason: "invalid" })).toBe(422);
+    expect(statusForBuiltinError("DatabaseError", { reason: "too_long" })).toBe(422);
+    expect(statusForBuiltinError("DatabaseError", { reason: "out_of_range" })).toBe(422);
+    expect(statusForBuiltinError("DatabaseError", { reason: "retryable" })).toBe(503);
+    expect(statusForBuiltinError("DatabaseError", { reason: "unknown" })).toBe(500);
+    expect(statusForBuiltinError("DatabaseError", {})).toBe(500);
+  });
+
+  test("domain codes are undefined so HTTP defaults to 400", () => {
+    expect(statusForBuiltinError("OutOfStock")).toBeUndefined();
+    expect(httpStatusForFailure("OutOfStock")).toBe(400);
+    expect(httpStatusForFailure("OKE1110")).toBe(500);
+  });
+});
+
+describe("statusForFailure", () => {
+  test("reads DatabaseError reason from the envelope", () => {
+    expect(statusForFailure(fail("DatabaseError", { reason: "not_null" }))).toBe(422);
+    expect(statusForFailure(fail("NotFound", { id: "n1" }))).toBe(404);
+    expect(statusForFailure(fail("FlightFull", { seatsLeft: 0 }))).toBe(400);
+  });
+});
+
+describe("encodeExecuteResult InternalError", () => {
+  test("never copies the thrown Error.message", async () => {
+    const res = await encodeExecuteResult({ error: new Error("secret leak") });
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as {
+      data: null;
+      error: { code: string; message?: string; data?: unknown };
+    };
+    expect(body.error.code).toBe("InternalError");
+    expect(JSON.stringify(body)).not.toContain("secret leak");
+  });
+
+  test("maps leftover unique SQLSTATE to Conflict", async () => {
+    const res = await encodeExecuteResult({
+      error: {
+        code: "23505",
+        message: "duplicate key value violates unique constraint",
+        detail: "Key (email)=(a@b.c) already exists.",
+      },
+    });
+    expect(res.status).toBe(409);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("Conflict");
+    expect(JSON.stringify(body)).not.toContain("a@b.c");
+  });
+
+  test("maps leftover Redis connection failure to ServiceUnavailable", async () => {
+    const res = await encodeExecuteResult({
+      error: Object.assign(new Error("Connection closed"), { code: "ECONNREFUSED" }),
+    });
+    expect(res.status).toBe(503);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("ServiceUnavailable");
+    expect(JSON.stringify(body)).not.toContain("Connection closed");
+  });
+
+  test("maps leftover S3 AccessDenied to Forbidden", async () => {
+    const res = await encodeExecuteResult({
+      error: Object.assign(new Error("Access Denied"), { code: "AccessDenied", status: 403 }),
+    });
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("Forbidden");
+    expect(JSON.stringify(body)).not.toContain("Access Denied");
+  });
+
+  test("leaves WRONGTYPE as InternalError", async () => {
+    const res = await encodeExecuteResult({
+      error: new Error("WRONGTYPE Operation against a key holding the wrong kind of value"),
+    });
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("InternalError");
+    expect(JSON.stringify(body)).not.toContain("WRONGTYPE");
+  });
+
+  test("maps exhausted serialization failure to ServiceUnavailable", async () => {
+    const res = await encodeExecuteResult({
+      error: { code: "40001", message: "could not serialize access" },
+    });
+    expect(res.status).toBe(503);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("ServiceUnavailable");
+  });
+});

package/src/kernel/builtin-errors.ts

@@ -0,0 +1,129 @@
+/**
+ * Built-in flow-boundary error codes — HTTP status + payload types.
+ *
+ * Always-on for `fx.fail` helpers and the typed client. Domain codes
+ * (`OutOfStock`, `FlightFull`) stay on the exposure `errors:` bag.
+ * No Zod — this module sits on the kernel edge graph.
+ */
+
+/** Built-in codes with a fixed HTTP status (not `DatabaseError`). */
+export const BUILTIN_ERROR_STATUS = {
+  ValidationError: 422,
+  Unauthorized: 401,
+  Forbidden: 403,
+  NotFound: 404,
+  Conflict: 409,
+  ForeignKey: 409,
+  UnsupportedMediaType: 415,
+  RateLimited: 429,
+  AuthRateLimited: 429,
+  InvalidQuery: 400,
+  AuthFailed: 400,
+  InternalError: 500,
+  ServiceUnavailable: 503,
+} as const;
+
+/** Built-in error code (including `DatabaseError`). */
+export type BuiltinErrorCode = keyof typeof BUILTIN_ERROR_STATUS | "DatabaseError";
+
+/** `DatabaseError.data.reason` — encoder maps these to HTTP status. */
+export type DatabaseErrorReason =
+  | "not_null"
+  | "check"
+  | "invalid"
+  | "too_long"
+  | "out_of_range"
+  | "retryable"
+  | "unknown";
+
+/**
+ * One `ValidationError` issue — same shape as the validation layer,
+ * inlined so this module stays off that graph.
+ */
+export type BuiltinValidationIssue = {
+  readonly message: string;
+  readonly path: ReadonlyArray<string | number>;
+};
+
+/** Loose identity / constraint bag used by several built-in codes. */
+export type BuiltinErrorBag = {
+  readonly id?: string;
+  readonly key?: string;
+  readonly code?: string;
+  readonly reason?: string;
+  readonly gate?: string;
+  readonly constraint?: string;
+  readonly table?: string;
+  readonly column?: string;
+  readonly sqlstate?: string;
+  readonly retryAfterMs?: number;
+  readonly retryAfter?: number;
+  readonly contentType?: string;
+  readonly [key: string]: unknown;
+};
+
+/**
+ * Built-in error code → payload. Client unions this with declared `errors:`.
+ */
+export type BuiltinErrorMap = {
+  readonly ValidationError: { readonly issues: readonly BuiltinValidationIssue[] };
+  readonly Unauthorized: BuiltinErrorBag;
+  readonly Forbidden: BuiltinErrorBag;
+  readonly NotFound: BuiltinErrorBag;
+  readonly Conflict: BuiltinErrorBag;
+  readonly ForeignKey: BuiltinErrorBag;
+  readonly UnsupportedMediaType: BuiltinErrorBag;
+  readonly RateLimited: { readonly retryAfterMs?: number };
+  readonly AuthRateLimited: BuiltinErrorBag;
+  readonly InvalidQuery: BuiltinErrorBag;
+  readonly AuthFailed: BuiltinErrorBag;
+  readonly DatabaseError: {
+    readonly reason: DatabaseErrorReason;
+    readonly sqlstate?: string;
+    readonly constraint?: string;
+    readonly table?: string;
+    readonly column?: string;
+  };
+  readonly InternalError: Record<string, never>;
+  readonly ServiceUnavailable: { readonly retryAfter?: number };
+};
+
+/**
+ * HTTP status for a built-in failure code, or `undefined` for domain codes.
+ *
+ * `DatabaseError` uses `data.reason`: `retryable` → 503, `unknown` / missing
+ * → 500, any other reason (`not_null`, `check`, `invalid`, …) → 422.
+ *
+ * @param code - Failure `error.code`
+ * @param data - Failure `error.data` (reason for `DatabaseError`)
+ */
+export function statusForBuiltinError(code: string, data?: unknown): number | undefined {
+  if (code === "DatabaseError") {
+    const reason = databaseErrorReason(data);
+    if (reason === "retryable") return 503;
+    if (reason !== undefined && reason !== "unknown") return 422;
+    return 500;
+  }
+  if (Object.prototype.hasOwnProperty.call(BUILTIN_ERROR_STATUS, code)) {
+    return BUILTIN_ERROR_STATUS[code as keyof typeof BUILTIN_ERROR_STATUS];
+  }
+  return undefined;
+}
+
+/**
+ * HTTP status for a typed flow failure. Domain codes default to 400.
+ *
+ * @param code - Failure code
+ * @param data - Failure payload
+ */
+export function httpStatusForFailure(code: string, data?: unknown): number {
+  const mapped = statusForBuiltinError(code, data);
+  if (mapped !== undefined) return mapped;
+  return code.startsWith("OKE") ? 500 : 400;
+}
+
+function databaseErrorReason(data: unknown): string | undefined {
+  if (data === null || typeof data !== "object") return undefined;
+  const reason = (data as { reason?: unknown }).reason;
+  return typeof reason === "string" ? reason : undefined;
+}

package/src/kernel/call.test.ts

@@ -1,6 +1,8 @@
 import { describe, expect, test, beforeEach } from "bun:test";
 import { oke } from "./app.ts";
+import { fail } from "./fail-helpers.ts";
 import { flow, resetFlowSeq } from "./flow.ts";
+import { isFlowFailure } from "./hooks.ts";
 import { on, resetBindings } from "./on.ts";
 import { http } from "./triggers.ts";
 
@@ -120,3 +122,183 @@ describe("fx.call — untriggered flows", () => {
     expect(runs).toBe(2);
   });
 });
+
+describe("error pipeline — RPC / call propagation", () => {
+  test("regression: unhandled RPC exception must never become 204 No Content", async () => {
+    const boom = flow("math.boom", {
+      do: () => {
+        throw new Error("sensitive leak");
+      },
+    });
+    const app = oke({ autoBoot: false, name: "rpc-boom" }).adopt(boom);
+
+    const res = await app.fetch(
+      new Request("http://localhost/_oke/math/boom", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+      }),
+    );
+
+    expect(res.status).toBe(500);
+    expect(res.status).not.toBe(204);
+    const body = (await res.json()) as {
+      data: unknown;
+      error: { code: string; data: unknown; message?: string };
+    };
+    expect(body.data).toBeNull();
+    expect(body.error.code).toBe("InternalError");
+    expect(body.error.data).toEqual({});
+    expect(body.error.message).toBe("Something went wrong. Try again.");
+    expect(JSON.stringify(body)).not.toContain("sensitive leak");
+  });
+
+  test("RPC store auto-map unique violation is Conflict 409", async () => {
+    const clash = flow("math.clash", {
+      do: () => {
+        throw Object.assign(new Error("duplicate key"), {
+          code: "23505",
+          constraint: "users_email_key",
+        });
+      },
+    });
+    const app = oke({ autoBoot: false, name: "rpc-clash" }).adopt(clash);
+
+    const res = await app.fetch(
+      new Request("http://localhost/_oke/math/clash", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+      }),
+    );
+
+    expect(res.status).toBe(409);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("Conflict");
+  });
+
+  test("ExecuteResult.error is a derived projection of ctx.error", async () => {
+    const boom = flow("math.boom", {
+      do: () => {
+        throw new Error("disk failed");
+      },
+    });
+    const app = oke({ autoBoot: false, name: "exec-err" }).adopt(boom);
+    const result = await app.execute(boom, {}, { kind: "internal" });
+
+    expect(result.failure).toBeUndefined();
+    expect(result.ctx.error).toBeDefined();
+    expect(result.error).toBe(result.ctx.error);
+  });
+
+  test("app.call returns FlowFailure value for controlled fail", async () => {
+    const missing = flow("notes.missing", {
+      do: () => fail.notFound({ id: "1" }),
+    });
+    const app = oke({ autoBoot: false, name: "call-fail" }).adopt(missing);
+    const out = await app.call(missing, {});
+    expect(isFlowFailure(out)).toBe(true);
+    if (isFlowFailure(out)) {
+      expect(out.error.code).toBe("NotFound");
+    }
+  });
+
+  test("app.call rethrows unhandled exception (never undefined)", async () => {
+    const boom = flow("notes.boom", {
+      do: () => {
+        throw new Error("disk failed");
+      },
+    });
+    const app = oke({ autoBoot: false, name: "call-throw" }).adopt(boom);
+    await expect(app.call(boom, {})).rejects.toThrow("disk failed");
+  });
+
+  test("fx.call returns FlowFailure value for controlled fail", async () => {
+    const child = flow("child.fail", {
+      do: () => fail.notFound({ id: "x" }),
+    });
+    on(
+      http.post("/run"),
+      flow("parent.run", {
+        effects: { calls: ["child.fail"] },
+        do: async (_input: Record<string, never>, fx) => {
+          const out = await fx.call("child.fail", {});
+          expect(isFlowFailure(out)).toBe(true);
+          return isFlowFailure(out) ? out : { unexpected: true };
+        },
+      }),
+    );
+    const app = oke({ autoBoot: false, name: "fx-fail" }).adopt(child);
+    const res = await app.fetch(
+      new Request("http://localhost/run", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+      }),
+    );
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("NotFound");
+  });
+
+  test("fx.call rethrows when child throws", async () => {
+    const child = flow("child.boom", {
+      do: () => {
+        throw new Error("worker crash");
+      },
+    });
+    on(
+      http.post("/run"),
+      flow("parent.run", {
+        effects: { calls: ["child.boom"] },
+        do: async (_input: Record<string, never>, fx) => {
+          return fx.call("child.boom", {});
+        },
+      }),
+    );
+    const app = oke({ autoBoot: false, name: "fx-throw" }).adopt(child);
+    const res = await app.fetch(
+      new Request("http://localhost/run", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+      }),
+    );
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { data: unknown; error: { code: string; message?: string } };
+    expect(body.data).toBeNull();
+    expect(body.error.code).toBe("InternalError");
+    expect(JSON.stringify(body)).not.toContain("worker crash");
+  });
+
+  test("nested fx.call chain propagates throw to outer boundary", async () => {
+    const deep = flow("deep.boom", {
+      do: () => {
+        throw new Error("deep crash");
+      },
+    });
+    const mid = flow("mid.call", {
+      effects: { calls: ["deep.boom"] },
+      do: async (_input: Record<string, never>, fx) => fx.call("deep.boom", {}),
+    });
+    on(
+      http.post("/run"),
+      flow("outer.run", {
+        effects: { calls: ["mid.call"] },
+        do: async (_input: Record<string, never>, fx) => fx.call("mid.call", {}),
+      }),
+    );
+    const app = oke({ autoBoot: false, name: "nested-throw" }).adopt(deep).adopt(mid);
+    const res = await app.fetch(
+      new Request("http://localhost/run", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+      }),
+    );
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("InternalError");
+    expect(JSON.stringify(body)).not.toContain("deep crash");
+  });
+});

package/src/kernel/errors-vault.ts

@@ -0,0 +1,16 @@
+/**
+ * OKE1510 — kept off the kernel edge graph.
+ *
+ * Vault boot gaps. Loaded via computed `import.meta.require` from
+ * {@link lookupOkeError}.
+ */
+
+import type { OkeErrorDefinition } from "./errors.ts";
+
+/** Vault contract has no value in any resolution layer (boot). */
+export const VAULT_SECRET_MISSING: OkeErrorDefinition = {
+  code: 1510,
+  domain: "vault",
+  cause: "{count} secrets have no value in any resolution layer.",
+  fix: "Set each name (`oke vault set <name>`, or `.env.local`).",
+};

package/src/kernel/errors.registry.test.ts

@@ -20,6 +20,7 @@ import { CHANNEL_SCHEMA } from "./errors-channel.ts";
 import { FLOW_NAME_DUPLICATE, FLOW_UNNAMED } from "./errors-flow-name.ts";
 import { ONCE_SIGNAL_MULTI_FLOW } from "./errors-once-signal.ts";
 import { TENANT_NOT_MEMBER, TENANT_REQUIRED, TENANT_UNKNOWN_SCOPE } from "./errors-tenant.ts";
+import { VAULT_SECRET_MISSING } from "./errors-vault.ts";
 import {
   assertCodesInDomainRanges,
   assertUniqueCodes,
@@ -65,8 +66,10 @@ describe("OKE error-code registry", () => {
     expect(files).toContain("errors-live-resume.ts");
     expect(files).toContain("errors-channel.ts");
     expect(files).toContain("errors-tenant.ts");
+    expect(files).toContain("errors-vault.ts");
     const codes = defs.map((d) => d.code);
     expect(codes).toContain(1210);
+    expect(codes).toContain(1510);
     expect(codes).toContain(1605);
     expect(codes).toContain(1810);
     expect(codes).toContain(1820);
@@ -160,6 +163,10 @@ describe("OKE error-code registry", () => {
     expect(lookupOkeError(1605)).toEqual(CHANNEL_SCHEMA);
   });
 
+  test("lookupOkeError finds the lazy VAULT_SECRET_MISSING entry", () => {
+    expect(lookupOkeError(1510)).toEqual(VAULT_SECRET_MISSING);
+  });
+
   test("lookupOkeError finds lazy tenant entries", () => {
     expect(lookupOkeError(1810)).toEqual(TENANT_REQUIRED);
     expect(lookupOkeError(1820)).toEqual(TENANT_NOT_MEMBER);

package/src/kernel/errors.ts

@@ -9,6 +9,7 @@
 import { docsUrl as absoluteDocsUrl } from "../docs-origin.ts";
 import { getActiveDefaultLocale, getActiveLocale } from "../i18n/locale-context.ts";
 import { lazyRequire } from "./lazy-require.ts";
+import type { BuiltinErrorMap } from "./builtin-errors.ts";
 
 /** Catalogs — kept off the edge `fail` / `OKE_ERRORS` static graph. */
 function loadMessages(): typeof import("../i18n/messages.ts") {
@@ -144,6 +145,93 @@ export interface FailOptions {
   readonly message?: string;
 }
 
+/**
+ * Callable `fail` plus built-in helpers (`fail.notFound`, `fail.forbidden`, …).
+ */
+export interface FailFn {
+  /**
+   * Flow-boundary failure value (does not throw).
+   *
+   * @param code - Declared or built-in error code
+   * @param data - Error payload
+   * @param opts - Optional message override
+   */
+  <E>(code: string, data: E, opts?: FailOptions): FlowFailure<E>;
+  /** Missing row / object — HTTP 404. */
+  notFound(
+    data?: BuiltinErrorMap["NotFound"],
+    opts?: FailOptions,
+  ): FlowFailure<BuiltinErrorMap["NotFound"]>;
+  /** Not authenticated — HTTP 401. */
+  unauthorized(
+    data?: BuiltinErrorMap["Unauthorized"],
+    opts?: FailOptions,
+  ): FlowFailure<BuiltinErrorMap["Unauthorized"]>;
+  /** Authenticated but denied — HTTP 403. */
+  forbidden(
+    data?: BuiltinErrorMap["Forbidden"],
+    opts?: FailOptions,
+  ): FlowFailure<BuiltinErrorMap["Forbidden"]>;
+  /** Unique / exclusion conflict — HTTP 409. */
+  conflict(
+    data?: BuiltinErrorMap["Conflict"],
+    opts?: FailOptions,
+  ): FlowFailure<BuiltinErrorMap["Conflict"]>;
+  /** Foreign-key violation — HTTP 409. */
+  foreignKey(
+    data?: BuiltinErrorMap["ForeignKey"],
+    opts?: FailOptions,
+  ): FlowFailure<BuiltinErrorMap["ForeignKey"]>;
+  /** Rate budget exhausted — HTTP 429. */
+  rateLimited(
+    data?: BuiltinErrorMap["RateLimited"],
+    opts?: FailOptions,
+  ): FlowFailure<BuiltinErrorMap["RateLimited"]>;
+  /** Maintenance / connection — HTTP 503. */
+  serviceUnavailable(
+    data?: BuiltinErrorMap["ServiceUnavailable"],
+    opts?: FailOptions,
+  ): FlowFailure<BuiltinErrorMap["ServiceUnavailable"]>;
+  /** SQL / store constraint that is not unique or FK. */
+  database(
+    data: BuiltinErrorMap["DatabaseError"],
+    opts?: FailOptions,
+  ): FlowFailure<BuiltinErrorMap["DatabaseError"]>;
+  /** Unhandled throw — HTTP 500. Catalog message only. */
+  internal(
+    data?: BuiltinErrorMap["InternalError"],
+    opts?: FailOptions,
+  ): FlowFailure<BuiltinErrorMap["InternalError"]>;
+}
+
+/**
+ * Create a flow-boundary failure value (does not throw).
+ *
+ * When `opts.message` is omitted, attaches a localized message from the
+ * built-in / app catalogs (`errors.{code}.{reason}` → `errors.{code}`) using
+ * the active request locale. Custom codes with no catalog entry stay
+ * message-less.
+ *
+ * @param code - Declared error code from the flow's `errors` map
+ * @param data - Error payload
+ * @param opts - Optional message override
+ */
+function failImpl<E>(code: string, data: E, opts?: FailOptions): FlowFailure<E> {
+  const message =
+    opts?.message !== undefined
+      ? opts.message
+      : loadFailureMessage().resolveFailureMessage(code, data);
+  const error: FlowErrorValue<E> = message !== undefined ? { code, data, message } : { code, data };
+  return { data: null, error };
+}
+
+/**
+ * Flow-boundary failure (callable). Built-in helpers live on the lazy
+ * `fail-helpers` chunk so they stay off the kernel edge graph — {@link createFx}
+ * and the public `okengine` export load that chunk.
+ */
+export const fail: FailFn = failImpl as FailFn;
+
 /**
  * Permanent error registry. Codes are stable within their domain range after
  * the domain-range renumber; each entry declares `domain` for range guards.
@@ -368,6 +456,12 @@ export function lookupOkeError(code: OkeErrorCode): OkeErrorDefinition | undefin
       ["errors", "live", "resume"].join("-"),
     ).LIVE_RESUME_GAP;
   }
+  if (code === 1510) {
+    return lazyRequire<typeof import("./errors-vault.ts")>(
+      import.meta.dir,
+      ["errors", "vault"].join("-"),
+    ).VAULT_SECRET_MISSING;
+  }
   if (code === 1605) {
     return lazyRequire<typeof import("./errors-channel.ts")>(
       import.meta.dir,
@@ -383,27 +477,6 @@ export function lookupOkeError(code: OkeErrorCode): OkeErrorDefinition | undefin
   return undefined;
 }
 
-/**
- * Create a flow-boundary failure value (does not throw).
- *
- * When `opts.message` is omitted, attaches a localized message from the
- * built-in / app catalogs (`errors.{code}.{reason}` → `errors.{code}`) using
- * the active request locale. Custom codes with no catalog entry stay
- * message-less.
- *
- * @param code - Declared error code from the flow's `errors` map
- * @param data - Error payload
- * @param opts - Optional message override
- */
-export function fail<E>(code: string, data: E, opts?: FailOptions): FlowFailure<E> {
-  const message =
-    opts?.message !== undefined
-      ? opts.message
-      : loadFailureMessage().resolveFailureMessage(code, data);
-  const error: FlowErrorValue<E> = message !== undefined ? { code, data, message } : { code, data };
-  return { data: null, error };
-}
-
 /**
  * Format the canonical multi-line OKE error message (§21).
  *

package/src/kernel/fail-helpers.ts

@@ -0,0 +1,34 @@
+/**
+ * Built-in `fail.notFound` / `fail.forbidden` / … helpers.
+ *
+ * Kept off the kernel edge graph — loaded via computed `import.meta.require`.
+ * Mutates the shared {@link fail} function so `fx.fail` and `import { fail }`
+ * share one identity.
+ */
+
+import { fail as failImpl, type FailFn, type FailOptions } from "./errors.ts";
+import type { BuiltinErrorMap } from "./builtin-errors.ts";
+
+const empty = {};
+const helper =
+  (code: string) =>
+  (data = empty, opts?: FailOptions) =>
+    failImpl(code, data, opts);
+
+/**
+ * Callable `fail` plus helpers. Same function object as kernel `fail`.
+ */
+export const fail: FailFn = Object.assign(failImpl, {
+  notFound: helper("NotFound"),
+  unauthorized: helper("Unauthorized"),
+  forbidden: helper("Forbidden"),
+  conflict: helper("Conflict"),
+  foreignKey: helper("ForeignKey"),
+  rateLimited: helper("RateLimited"),
+  serviceUnavailable: helper("ServiceUnavailable"),
+  database: (data: BuiltinErrorMap["DatabaseError"], opts?: FailOptions) =>
+    failImpl("DatabaseError", data, opts),
+  internal: helper("InternalError"),
+});
+
+export type { FailFn, FailOptions } from "./errors.ts";

package/src/kernel/fx.test.ts

@@ -728,6 +728,14 @@ describe("errors — registry", () => {
     });
   });
 
+  test("fx.fail.notFound is callable without errors: declaration", () => {
+    const fx = createFx({ flow: "x", effects: {} });
+    const result = fx.fail.notFound({ id: "n1" });
+    expect(result.error.code).toBe("NotFound");
+    expect(result.error.data).toEqual({ id: "n1" });
+    expect(result.data).toBeNull();
+  });
+
   test("capability token allows only declared resources", () => {
     const token = createCapabilityToken("f", {
       reads: ["sql:a"],