okengine 0.19.9 → 0.21.0

package/src/kernel/app.ts

@@ -39,15 +39,16 @@ import { requirePackageModule } from "../shared/lazy-src.ts";
 import { lazyRequire } from "./lazy-require.ts";
 import type { DurableResult, RunDurableOptions } from "../elements/clock/durable.ts";
 import { applyClockTimezoneDefaults } from "../elements/clock/declare.ts";
-import type { TemplateCatalog } from "../elements/channel/runtime.ts";
+import { catalogFromTemplates, mergeTemplateCatalogs } from "../elements/channel/declare.ts";
 import { parseAcceptLanguage } from "../elements/channel/locale.ts";
 import { runWithLocale } from "../i18n/locale-context.ts";
 import { isFlow, type AnyFlowDef } from "./flow.ts";
 import { failureFromUnknown, runCompensationPhase } from "./compensate.ts";
 import { withAbortSignal } from "./abort-scope.ts";
 import { withCdcMutationId } from "../elements/store/sql-session.ts";
-import { MUTATION_ID_HEADER } from "./realtime-bind.ts";
+import { MUTATION_ID_HEADER } from "./mutation-id.ts";
 import { fxRetry } from "./concurrency.ts";
+import { projectFlowOut } from "./project-out.ts";
 import type {
   CreateFxOptions,
   Fx,
@@ -60,7 +61,7 @@ import type {
 } from "./fx.ts";
 import {
   currentDevSurface,
-  failureDetailFromResponse,
+  failureEnvelopeFromResponse,
   logDevRequest,
   shouldLogDevRequests,
 } from "../runtime/dev-request-log.ts";
@@ -350,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";
@@ -381,13 +387,13 @@ export interface UnitHooks<D extends Record<string, unknown> = {}> {
 }
 
 /**
- * Module-augmentation slot filled by `src/flows/generated.ts`.
+ * Module-augmentation slot filled by `src/flows/index.ts`.
  * Kernel tests do not import an app generated file, so this stays `{}`.
  */
 export interface RegisteredFlowUnits {}
 
 /**
- * `$routes` derived from {@link RegisteredFlowUnits} after `import generated`.
+ * `$routes` derived from {@link RegisteredFlowUnits} after `import "@/flows"`.
  *
  * @typeParam U - Augmented unit map
  */
@@ -853,7 +859,7 @@ function registerOnceSignalBinding(
 }
 
 /**
- * Fold `generated.ts` units into `$routes` and `flowsByName`.
+ * Fold `src/flows/index.ts` units into `$routes` and `flowsByName`.
  *
  * @param units - Drained {@link registerFlowUnits} bag
  * @param routes - Runtime `$routes`
@@ -967,12 +973,21 @@ export function oke(options: OkeOptions): OkeApp {
   // explicit `options.channel` nor a registered template exists — a defined
   // object here would flip `resolveElementNeeds`'s `channel` need to `true`
   // for every app, whether or not it uses channel at all.
+  const channelTemplates = mergeUnique(
+    options.channel?.templates,
+    registrySnapshot.channelTemplates,
+  );
+  const channelCatalog = mergeTemplateCatalogs(
+    catalogFromTemplates(channelTemplates),
+    options.channel?.catalog,
+  );
   const effectiveChannel: BootOptions["channel"] =
     options.channel === undefined && registrySnapshot.channelTemplates.length === 0
       ? undefined
       : {
           ...(options.channel ?? {}),
-          templates: mergeUnique(options.channel?.templates, registrySnapshot.channelTemplates),
+          templates: channelTemplates,
+          ...(channelCatalog ? { catalog: channelCatalog } : {}),
         };
   // Same undefined-when-empty rule for AI — a bare `{}` would force the AI
   // runtime open even when the app never declared models / prompts.
@@ -1444,7 +1459,13 @@ export function oke(options: OkeOptions): OkeApp {
     const baseSignals = overrides?.signals ?? effectiveSignals;
     const baseClocks = overrides?.clocks ?? effectiveClocks;
     const baseChannel = overrides?.channel ?? effectiveChannel;
-    const mergedCatalog = mergeTemplateCatalogs(baseChannel?.catalog, ...pluginChannelCatalogs);
+    const mergedTemplates = [...(baseChannel?.templates ?? []), ...pluginChannelTemplates];
+    const mergedCatalog = mergeTemplateCatalogs(
+      catalogFromTemplates(baseChannel?.templates),
+      baseChannel?.catalog,
+      catalogFromTemplates(pluginChannelTemplates),
+      ...pluginChannelCatalogs,
+    );
 
     cdcPkByTable = pkColumnByTableFromManifest(overrides?.manifest ?? options.manifest);
 
@@ -1465,7 +1486,7 @@ export function oke(options: OkeOptions): OkeApp {
       stores: overrides?.stores ?? effectiveStores,
       channel: {
         ...(baseChannel ?? {}),
-        templates: [...(baseChannel?.templates ?? []), ...pluginChannelTemplates],
+        templates: mergedTemplates,
         ...(mergedCatalog ? { catalog: mergedCatalog } : {}),
         defaultLocale:
           baseChannel?.defaultLocale ??
@@ -1899,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;
       },
     });
@@ -1965,7 +1987,8 @@ export function oke(options: OkeOptions): OkeApp {
               journalSession?.rewind();
               return flowDef.do(input as never, fx);
             };
-            const output = await (flowDef.retry ? fxRetry(run, flowDef.retry) : run());
+            const raw = await (flowDef.retry ? fxRetry(run, flowDef.retry) : run());
+            const output = isFlowFailure(raw) ? raw : await projectFlowOut(flowDef.out, raw);
             if (!isFlowFailure(output) && cache && storeRt && cacheEffects) {
               const ledgerFx = cache.effectsFromLedger(ledger.entries);
               const writeEffects: Effects = {
@@ -2127,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,
@@ -2311,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,
@@ -2319,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();
@@ -2535,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) {
@@ -2616,28 +2645,5 @@ function redactArchivedFields(input: unknown, fields: readonly string[] | undefi
   return obj;
 }
 
-/**
- * Deep-merge channel template catalogs (later parts win per locale).
- *
- * @param parts - Catalog fragments (undefined skipped)
- */
-function mergeTemplateCatalogs(
-  ...parts: readonly (TemplateCatalog | undefined)[]
-): TemplateCatalog | undefined {
-  const out: Record<
-    string,
-    Record<string, { readonly subject?: string; readonly text?: string; readonly html?: string }>
-  > = {};
-  let any = false;
-  for (const part of parts) {
-    if (!part) continue;
-    any = true;
-    for (const [template, locales] of Object.entries(part)) {
-      out[template] = { ...(out[template] ?? {}), ...locales };
-    }
-  }
-  return any ? out : undefined;
-}
-
 /** @internal expose smart router type for tests */
 export type { HttpTrigger, SmartRouter };

package/src/kernel/auto-registry.test.ts

@@ -13,7 +13,7 @@
  */
 
 import { describe, expect, test } from "bun:test";
-import { channel } from "../elements/channel/declare.ts";
+import { channel, resetChannelTemplates } from "../elements/channel/declare.ts";
 import { clock } from "../elements/clock/declare.ts";
 import { gate } from "../elements/gate/declare.ts";
 import { signal } from "../elements/signal/declare.ts";
@@ -291,4 +291,29 @@ describe("oke() auto-registry — stores/secrets/signals/clocks/gates/channel.te
     const json = (await res.json()) as { data: { summary: string } };
     expect(json.data.summary).toBe("one-line summary");
   });
+
+  test("channel.template({ catalog }) drains into oke() without channel.catalog bag", () => {
+    resetBindings();
+    resetChannelTemplates();
+    const mail = channel.email({ from: "Drain <drain@localhost>" });
+    mail.template("welcome-drain", {
+      locales: ["en"],
+      catalog: {
+        en: { subject: "Hi {{name}}", text: "Hello {{name}}" },
+      },
+    });
+    const sms = channel.sms();
+    sms.template("ops.drain", {
+      catalog: { en: { text: "Disk {{pct}}%" } },
+    });
+
+    const app = oke({
+      name: "catalog-drain",
+      autoBoot: false,
+      startScheduler: false,
+    });
+
+    expect(app.$options.channel?.catalog?.["welcome-drain"]?.en?.subject).toBe("Hi {{name}}");
+    expect(app.$options.channel?.catalog?.["ops.drain"]?.en?.text).toBe("Disk {{pct}}%");
+  });
 });

package/src/kernel/boot.ts

@@ -804,7 +804,7 @@ async function tryListFlowsUnits(rootDir: string): Promise<readonly string[] | u
 /**
  * Confirm every `src/flows/<unit>` folder on disk actually reached this
  * boot's adopted flows — the disk-file counterpart of a stale/missing
- * generated `.adopt()` barrel (`src/flows/generated.ts`). A folder present
+ * generated `.adopt()` barrel (`src/flows/index.ts`). A folder present
  * on disk with zero adopted flows under that unit means the barrel wasn't
  * regenerated (or was hand-edited) after the folder was added.
  *
@@ -846,7 +846,7 @@ export async function assertAdoptBarrelFresh(
     staleAdoptBarrelWarned = true;
     emitBootWarn(
       `oke boot: src/flows/${missing[0]} exists on disk but adopted no flows — the ` +
-        '.adopt() barrel ("src/flows/generated.ts") is stale. Run `oke dev` or `oke build` ' +
+        '.adopt() barrel ("src/flows/index.ts") is stale. Run `oke dev` or `oke build` ' +
         "to regenerate it — dev+compose/prod refuse to boot this way.",
     );
   }

package/src/kernel/boundary-contract.ts

@@ -16,7 +16,12 @@ export interface BoundaryContract<
 > {
   /** Request / args schema (Standard Schema). */
   readonly in?: ISchema;
-  /** Success reply schema (Manifest + typed client; not runtime-validated). */
+  /**
+   * Success reply schema (Manifest + typed client). Success values are
+   * projected onto it (`fx.json.create(row)` / `return row`) — Date timestamps
+   * become ISO-8601; extra keys strip when parse succeeds. Miss is not a client
+   * error.
+   */
   readonly out?: OSchema;
   /** Typed domain errors (`fx.fail`). */
   readonly errors?: E;

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;
+}