okengine 0.20.0 → 0.21.1

package/src/kernel/errors-text.ts

@@ -0,0 +1,99 @@
+/**
+ * English cause/fix templates for {@link OKE_ERRORS}.
+ *
+ * Loaded on first read so the kernel edge profile does not carry the
+ * strings. Localization still prefers the i18n catalogs when a locale
+ * overrides `oke.{code}.cause` / `oke.{code}.fix`.
+ */
+
+/** One registry template pair. */
+export interface OkeErrorText {
+  /** One-line cause template. */
+  readonly cause: string;
+  /** Suggested fix template. */
+  readonly fix: string;
+}
+
+/** Keyed by {@link OKE_ERRORS} property name. */
+export const OKE_ERROR_TEXT: Readonly<Record<string, OkeErrorText>> = {
+  UNDECLARED_READ: {
+    cause: 'Flow "{flow}" reads "{resource}" without declaring it.',
+    fix: 'Add "{resource}" to this flow\'s effects.reads.',
+  },
+  UNDECLARED_WRITE: {
+    cause: 'Flow "{flow}" writes "{resource}" without declaring it.',
+    fix: 'Add "{resource}" to this flow\'s effects.writes.',
+  },
+  UNDECLARED_EMIT: {
+    cause: 'Flow "{flow}" emits "{resource}" without declaring it.',
+    fix: 'Add "{resource}" to this flow\'s effects.emits.',
+  },
+  UNDECLARED_SEND: {
+    cause: 'Flow "{flow}" sends "{resource}" without declaring it.',
+    fix: 'Add "{resource}" to this flow\'s effects.sends.',
+  },
+  UNDECLARED_ASK: {
+    cause: 'Flow "{flow}" asks "{resource}" without declaring it.',
+    fix: 'Add "{resource}" to this flow\'s effects.asks.',
+  },
+  UNDECLARED_SECRET: {
+    cause: 'Flow "{flow}" reads secret "{resource}" without declaring it.',
+    fix: 'Add "{resource}" to this flow\'s effects.secrets.',
+  },
+  UNDECLARED_CALL: {
+    cause: 'Flow "{flow}" calls "{resource}" without declaring it.',
+    fix: 'Add "{resource}" to this flow\'s effects.calls.',
+  },
+  UNDECLARED_FETCH: {
+    cause: 'Flow "{flow}" fetches "{resource}" without declaring it.',
+    fix: 'Add "{resource}" to this flow\'s effects.fetches.',
+  },
+  UNDECLARED_EMBED: {
+    cause: 'Flow "{flow}" embeds with "{resource}" without declaring it.',
+    fix: 'Add "{resource}" to this flow\'s effects.embeds.',
+  },
+  NO_EFFECTS_DECLARED: {
+    cause: 'Flow "{flow}" has no declared effects and no Manifest to derive them from.{extract}',
+    fix:
+      "Add explicit `effects` to this flow, or boot with a Manifest (`oke build`) / " +
+      "`rootDir` so effects can be derived. If extract failed, ensure `oxc-parser` is " +
+      "installed (okengine dependency). dev+compose/prod refuse an open capability token.",
+  },
+  ADOPT_BARREL_STALE: {
+    cause: "src/flows/{unit} exists on disk but adopted no flows — the .adopt() barrel is stale.",
+    fix: "Run `oke dev` or `oke build` to regenerate `src/flows/index.ts`.",
+  },
+  HTTP_PATH_UNRESOLVED: {
+    cause: 'Flow "{flow}" bound {method} with no path — the file-tree stamp never ran.',
+    fix: 'Put the file under `src/flows/<unit>/` and import `@/flows`, or pass an explicit path to `http.{method}("/…")`.',
+  },
+  HTTP_ROUTE_DUPLICATE: {
+    cause: '{method} {path} is bound twice (flow "{flow}").',
+    fix: "Give each HTTP flow a unique method + path.",
+  },
+  HTTP_FLOW_UNNAMED: {
+    cause: "An HTTP flow on {method} {path} has no name.",
+    fix: 'Use `flow("unit.export", {…})` or export it from a `src/flows/<unit>/` file so the tree can stamp `unit.export`.',
+  },
+  LIVE_EXPOSURE_DUPLICATE: {
+    cause:
+      'Live signal "{signal}" is exposed twice with the same gates ({gates}) and match ({match}).',
+    fix: "Use a different gate or path-param filter, or drop the extra route.",
+  },
+  MCP_TOOL_DUPLICATE: {
+    cause: 'MCP tool "{tool}" is bound twice (flow "{flow}").',
+    fix: "Give each MCP tool exposure a unique tool name.",
+  },
+  ORPHAN_EMIT: {
+    cause: 'Flow "{flow}" emits signal "{resource}" with no subscriber.',
+    fix: "Add `on({resource}, …)` or mark the signal `{ optional: true }`.",
+  },
+  SIGNAL_SCHEMA: {
+    cause: '"{resource}": {detail}',
+    fix: "Fix schema payload.",
+  },
+  DOMAIN_SCHEMA_MISSING: {
+    cause: "domain table not found — migrations have not been applied.",
+    fix: "run `oke db migrate` against this environment.",
+  },
+};

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,10 +145,100 @@ 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.
  *
+ * Cause/fix templates load from {@link OKE_ERROR_TEXT} on first read so the
+ * edge profile does not carry the English strings.
+ *
  * Ranges:
  * - `1000–1099` — Kernel (Flow / Trigger / Gate-posture)
  * - `1100–1199` — Store
@@ -160,168 +251,117 @@ export interface FailOptions {
  * - `1800–1899` — MCP + Tenancy
  * - `1900–1999` — Compiler / Manifest
  */
-export const OKE_ERRORS = {
+const OKE_ERROR_ROWS = {
   /** Flow reads a store resource not listed in `effects.reads`. */
-  UNDECLARED_READ: {
-    code: 1001,
-    domain: "kernel",
-    cause: 'Flow "{flow}" reads "{resource}" without declaring it.',
-    fix: 'Add "{resource}" to this flow\'s effects.reads.',
-  },
+  UNDECLARED_READ: { code: 1001, domain: "kernel" },
   /** Flow writes a store resource not listed in `effects.writes`. */
-  UNDECLARED_WRITE: {
-    code: 1002,
-    domain: "kernel",
-    cause: 'Flow "{flow}" writes "{resource}" without declaring it.',
-    fix: 'Add "{resource}" to this flow\'s effects.writes.',
-  },
+  UNDECLARED_WRITE: { code: 1002, domain: "kernel" },
   /** Flow emits a signal not listed in `effects.emits`. */
-  UNDECLARED_EMIT: {
-    code: 1003,
-    domain: "kernel",
-    cause: 'Flow "{flow}" emits "{resource}" without declaring it.',
-    fix: 'Add "{resource}" to this flow\'s effects.emits.',
-  },
+  UNDECLARED_EMIT: { code: 1003, domain: "kernel" },
   /** Flow sends a channel template not listed in `effects.sends`. */
-  UNDECLARED_SEND: {
-    code: 1004,
-    domain: "kernel",
-    cause: 'Flow "{flow}" sends "{resource}" without declaring it.',
-    fix: 'Add "{resource}" to this flow\'s effects.sends.',
-  },
+  UNDECLARED_SEND: { code: 1004, domain: "kernel" },
   /** Flow asks a prompt not listed in `effects.asks`. */
-  UNDECLARED_ASK: {
-    code: 1005,
-    domain: "kernel",
-    cause: 'Flow "{flow}" asks "{resource}" without declaring it.',
-    fix: 'Add "{resource}" to this flow\'s effects.asks.',
-  },
+  UNDECLARED_ASK: { code: 1005, domain: "kernel" },
   /** Flow reads a secret not listed in `effects.secrets`. */
-  UNDECLARED_SECRET: {
-    code: 1006,
-    domain: "kernel",
-    cause: 'Flow "{flow}" reads secret "{resource}" without declaring it.',
-    fix: 'Add "{resource}" to this flow\'s effects.secrets.',
-  },
+  UNDECLARED_SECRET: { code: 1006, domain: "kernel" },
   /** Flow calls another flow not listed in `effects.calls`. */
-  UNDECLARED_CALL: {
-    code: 1007,
-    domain: "kernel",
-    cause: 'Flow "{flow}" calls "{resource}" without declaring it.',
-    fix: 'Add "{resource}" to this flow\'s effects.calls.',
-  },
+  UNDECLARED_CALL: { code: 1007, domain: "kernel" },
   /** Flow fetches a host not listed in `effects.fetches`. */
-  UNDECLARED_FETCH: {
-    code: 1008,
-    domain: "kernel",
-    cause: 'Flow "{flow}" fetches "{resource}" without declaring it.',
-    fix: 'Add "{resource}" to this flow\'s effects.fetches.',
-  },
+  UNDECLARED_FETCH: { code: 1008, domain: "kernel" },
   /** Flow embeds via a model not listed in `effects.embeds`. */
-  UNDECLARED_EMBED: {
-    code: 1009,
-    domain: "kernel",
-    cause: 'Flow "{flow}" embeds with "{resource}" without declaring it.',
-    fix: 'Add "{resource}" to this flow\'s effects.embeds.',
-  },
+  UNDECLARED_EMBED: { code: 1009, domain: "kernel" },
   /**
    * Flow has no declared `effects` and no Manifest-derived effects were
    * available to stamp at boot (dev+compose / prod — never a silent open token).
    */
-  NO_EFFECTS_DECLARED: {
-    code: 1020,
-    domain: "kernel",
-    cause: 'Flow "{flow}" has no declared effects and no Manifest to derive them from.{extract}',
-    fix:
-      "Add explicit `effects` to this flow, or boot with a Manifest (`oke build`) / " +
-      "`rootDir` so effects can be derived. If extract failed, ensure `oxc-parser` is " +
-      "installed (okengine dependency). dev+compose/prod refuse an open capability token.",
-  },
+  NO_EFFECTS_DECLARED: { code: 1020, domain: "kernel" },
   /**
    * A `src/flows/<unit>` folder exists on disk but no adopted flow carries
    * that unit — the generated `.adopt()` barrel (`src/flows/index.ts`)
    * is stale or was hand-edited. dev+compose / prod — never a silently-incomplete
    * route table in a deploy-shaped environment.
    */
-  ADOPT_BARREL_STALE: {
-    code: 1030,
-    domain: "kernel",
-    cause: "src/flows/{unit} exists on disk but adopted no flows — the .adopt() barrel is stale.",
-    fix: "Run `oke dev` or `oke build` to regenerate `src/flows/index.ts`.",
-  },
-  /**
-   * `http.get()` was never stamped from the file tree — refuse a silent `/`.
-   */
-  HTTP_PATH_UNRESOLVED: {
-    code: 1040,
-    domain: "kernel",
-    cause: 'Flow "{flow}" bound {method} with no path — the file-tree stamp never ran.',
-    fix: 'Put the file under `src/flows/<unit>/` and import `@/flows`, or pass an explicit path to `http.{method}("/…")`.',
-  },
-  /**
-   * Two HTTP bindings share method + path — last-add-wins is the opposite of this DX.
-   */
-  HTTP_ROUTE_DUPLICATE: {
-    code: 1041,
-    domain: "kernel",
-    cause: '{method} {path} is bound twice (flow "{flow}").',
-    fix: "Give each HTTP flow a unique method + path.",
-  },
-  /**
-   * Adopted HTTP flow still has no name (`flow({ do })` outside a unit).
-   */
-  HTTP_FLOW_UNNAMED: {
-    code: 1045,
-    domain: "kernel",
-    cause: "An HTTP flow on {method} {path} has no name.",
-    fix: 'Use `flow("unit.export", {…})` or export it from a `src/flows/<unit>/` file so the tree can stamp `unit.export`.',
-  },
-  /**
-   * Two live HTTP exposures of the same signal share gates + match shape.
-   */
-  LIVE_EXPOSURE_DUPLICATE: {
-    code: 1050,
-    domain: "kernel",
-    cause:
-      'Live signal "{signal}" is exposed twice with the same gates ({gates}) and match ({match}).',
-    fix: "Use a different gate or path-param filter, or drop the extra route.",
-  },
-  /**
-   * Two MCP tool bindings share the same exposed tool name.
-   */
-  MCP_TOOL_DUPLICATE: {
-    code: 1060,
-    domain: "kernel",
-    cause: 'MCP tool "{tool}" is bound twice (flow "{flow}").',
-    fix: "Give each MCP tool exposure a unique tool name.",
-  },
+  ADOPT_BARREL_STALE: { code: 1030, domain: "kernel" },
+  /** `http.get()` was never stamped from the file tree — refuse a silent `/`. */
+  HTTP_PATH_UNRESOLVED: { code: 1040, domain: "kernel" },
+  /** Two HTTP bindings share method + path. */
+  HTTP_ROUTE_DUPLICATE: { code: 1041, domain: "kernel" },
+  /** Adopted HTTP flow still has no name (`flow({ do })` outside a unit). */
+  HTTP_FLOW_UNNAMED: { code: 1045, domain: "kernel" },
+  /** Two live HTTP exposures of the same signal share gates + match shape. */
+  LIVE_EXPOSURE_DUPLICATE: { code: 1050, domain: "kernel" },
+  /** Two MCP tool bindings share the same exposed tool name. */
+  MCP_TOOL_DUPLICATE: { code: 1060, domain: "kernel" },
   /**
    * Emit target has no subscriber (unified-theory §21).
    * Thrown at emit when `optional` is false and nobody is subscribed.
    */
-  ORPHAN_EMIT: {
-    code: 1240,
-    domain: "signal",
-    cause: 'Flow "{flow}" emits signal "{resource}" with no subscriber.',
-    fix: "Add `on({resource}, …)` or mark the signal `{ optional: true }`.",
-  },
+  ORPHAN_EMIT: { code: 1240, domain: "signal" },
   /** Emit payload failed the signal's declared Standard Schema. */
-  SIGNAL_SCHEMA: {
-    code: 1250,
-    domain: "signal",
-    cause: '"{resource}": {detail}',
-    fix: "Fix schema payload.",
-  },
-  /**
-   * Domain table/column missing under docker/prod (migrations not applied).
-   */
-  DOMAIN_SCHEMA_MISSING: {
-    code: 1110,
-    domain: "store",
-    cause: "domain table not found — migrations have not been applied.",
-    fix: "run `oke db migrate` against this environment.",
-  },
-} as const satisfies Record<string, OkeErrorDefinition>;
+  SIGNAL_SCHEMA: { code: 1250, domain: "signal" },
+  /** Domain table/column missing under docker/prod (migrations not applied). */
+  DOMAIN_SCHEMA_MISSING: { code: 1110, domain: "store" },
+} as const satisfies Record<string, { readonly code: number; readonly domain: OkeErrorDomain }>;
+
+type OkeErrorRowTable = typeof OKE_ERROR_ROWS;
+
+/** Registry entries with literal codes and lazy cause/fix. */
+type OkeErrorTable = {
+  readonly [K in keyof OkeErrorRowTable]: OkeErrorDefinition & {
+    readonly code: OkeErrorRowTable[K]["code"];
+    readonly domain: OkeErrorRowTable[K]["domain"];
+  };
+};
+
+/**
+ * Load English cause/fix templates. Computed stem so Bun.build cannot inline them.
+ */
+function loadErrorText(): typeof import("./errors-text.ts") {
+  return lazyRequire(import.meta.dir, ["errors", "text"].join("-"));
+}
+
+/**
+ * Read one cause or fix template.
+ *
+ * @param key - {@link OKE_ERRORS} property name
+ * @param part - `cause` or `fix`
+ */
+function errorPart(key: string, part: "cause" | "fix"): string {
+  const row = loadErrorText().OKE_ERROR_TEXT[key];
+  if (!row) throw new Error(`Missing OKE error text for ${key}.${part}`);
+  return row[part];
+}
+
+/**
+ * Attach lazy cause/fix getters. Strings stay in the text chunk until read.
+ *
+ * @param rows - Code and domain table
+ */
+function attachErrorText(rows: OkeErrorRowTable): OkeErrorTable {
+  const out: Record<string, OkeErrorDefinition> = {};
+  for (const key of Object.keys(rows) as (keyof OkeErrorRowTable)[]) {
+    const row = rows[key];
+    out[key] = {
+      code: row.code,
+      domain: row.domain,
+      get cause() {
+        return errorPart(key, "cause");
+      },
+      get fix() {
+        return errorPart(key, "fix");
+      },
+    };
+  }
+  return out as OkeErrorTable;
+}
+
+/**
+ * Permanent error registry. Cause/fix load from the lazy text chunk.
+ *
+ * `@__PURE__` lets bundles that never read the registry drop the getter
+ * table. A plain call looks like a side effect and stays in every importer.
+ */
+export const OKE_ERRORS: OkeErrorTable = /* @__PURE__ */ attachErrorText(OKE_ERROR_ROWS);
 
 /** Tenant error keys — definitions live in the lazy `errors-tenant` chunk. */
 export type TenantOkeErrorKey = "TENANT_REQUIRED" | "TENANT_NOT_MEMBER" | "TENANT_UNKNOWN_SCOPE";
@@ -368,6 +408,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 +429,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";