okengine 0.19.9 → 0.21.0

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.
@@ -239,7 +327,7 @@ export const OKE_ERRORS = {
   },
   /**
    * A `src/flows/<unit>` folder exists on disk but no adopted flow carries
-   * that unit — the generated `.adopt()` barrel (`src/flows/generated.ts`)
+   * 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.
    */
@@ -247,7 +335,7 @@ export const OKE_ERRORS = {
     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/generated.ts`.",
+    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 `/`.
@@ -256,7 +344,7 @@ export const OKE_ERRORS = {
     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/generated`, or pass an explicit path to `http.{method}("/…")`.',
+    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.
@@ -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/flow-units.ts

@@ -1,7 +1,7 @@
 /**
- * Module-evaluation registry for `src/flows/generated.ts`.
+ * Module-evaluation registry for `src/flows/index.ts`.
  *
- * Same consume/ignore posture as `on()` / `listBindings()`: generated.ts
+ * Same consume/ignore posture as `on()` / `listBindings()`: the adopt barrel
  * calls {@link registerFlowUnits}; {@link oke} drains the bag into `$routes`
  * unless `registry: "ignore"`.
  */
@@ -19,7 +19,7 @@ const pending: Record<string, FlowUnitBag> = {};
 /**
  * Record generated flow units for the next {@link oke} construction.
  *
- * @param units - `{ notes, main, … }` from `generated.ts`
+ * @param units - `{ notes, main, … }` from `src/flows/index.ts`
  */
 export function registerFlowUnits(units: Record<string, FlowUnitBag>): void {
   Object.assign(pending, units);

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"],

package/src/kernel/fx.ts

@@ -58,7 +58,7 @@ import {
   recordWouldHaveFired,
   touchDryRunStore,
 } from "./dry-run.ts";
-import { fail, type FailOptions, type FlowFailure } from "./errors.ts";
+import type { FailFn } from "./errors.ts";
 import { currentAbortSignal, linkAbort } from "./abort-scope.ts";
 import {
   fxAll,
@@ -82,6 +82,13 @@ import { okid } from "../okid.ts";
 import { lazyRequire } from "./lazy-require.ts";
 import type { AppMessageKey, MessageValues } from "../i18n/types.ts";
 
+function loadFail(): FailFn {
+  return lazyRequire<typeof import("./fail-helpers.ts")>(
+    import.meta.dir,
+    ["fail", "helpers"].join("-"),
+  ).fail;
+}
+
 /** Lazy runs/window helpers — kept off the cold `oke` static graph. */
 async function loadRunsWindow(): Promise<typeof import("../runs/window.ts")> {
   return import("../runs/window.ts");
@@ -182,7 +189,11 @@ export interface FxTenant {
 
 /** Clock surface on `fx`. */
 export interface FxClock {
-  /** Current epoch-ms (injectable via {@link CreateFxOptions.now}). */
+  /**
+   * Current epoch-ms (injectable via {@link CreateFxOptions.now}).
+   * Pass into SQL `timestamp` / `date` columns as-is — store insert/update
+   * and WHERE binds coerce finite numbers and parseable ISO strings to `Date`.
+   */
   now(): number;
   /**
    * Instant `duration` before {@link FxClock.now} (`"30d"` → now − 30 days).
@@ -465,11 +476,17 @@ export type JsonPage<T> = {
  * JSON response helpers. `fx.json.create` answers 201; `fx.json.ok` can carry
  * a top-level `meta` (Stripe-style `{ data, meta?, error }`);
  * `fx.json.empty` answers 204.
+ * When the exposure declares `out`, the kernel projects the success value onto
+ * that schema — `fx.json.create(row)` is enough; no Date→ISO mapper.
  */
 export interface FxJson {
   /** 200 — body `{ data: value, meta?, error: null }`. */
   ok<T>(value: T, opts?: { readonly meta?: Record<string, unknown> }): JsonResult<T>;
-  /** 201 — body `{ data: value, error: null }`. */
+  /**
+   * 201 — body `{ data: value, error: null }`.
+   * When the exposure declares `out`, the kernel projects `value` onto that
+   * schema (Date → ISO-8601, extra keys stripped) so a store `row` is enough.
+   */
   create<T>(value: T): JsonResult<T>;
   /** 204 — no body. */
   empty(): JsonResult<never>;
@@ -874,11 +891,10 @@ export interface Fx {
   /**
    * Flow-boundary failure value (does not throw).
    *
-   * @param code - Declared error code (narrowed by clients via `error.code`)
-   * @param data - Error payload
-   * @param opts - Optional message
+   * Built-in helpers (`fx.fail.notFound`, `fx.fail.forbidden`, …) need no
+   * `errors:` declaration. Domain codes still use `fx.fail("OutOfStock", data)`.
    */
-  fail<E>(code: string, data: E, opts?: FailOptions): FlowFailure<E>;
+  readonly fail: FailFn;
   /** JSON response helpers (status + Stripe-style envelope). */
   readonly json: FxJson;
   /**
@@ -2236,7 +2252,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     operator,
     principal,
     tenant,
-    fail,
+    fail: loadFail(),
     json: {
       ok<T>(value: T, opts?: { readonly meta?: Record<string, unknown> }): JsonResult<T> {
         return {

package/src/kernel/index.ts

@@ -106,14 +106,15 @@ export {
   type RunTelemetry,
 } from "./run-telemetry.ts";
 
+export { fail } from "./fail-helpers.ts";
 export {
-  fail,
   formatOkeMessage,
   lookupOkeError,
   OKE_ERROR_RANGES,
   OKE_ERRORS,
   OkeError,
   throwOke,
+  type FailFn,
   type FailOptions,
   type FlowErrorValue,
   type FlowFailure,
@@ -122,6 +123,16 @@ export {
   type OkeErrorDomain,
   type OkeErrorParams,
 } from "./errors.ts";
+export {
+  BUILTIN_ERROR_STATUS,
+  httpStatusForFailure,
+  statusForBuiltinError,
+  type BuiltinErrorBag,
+  type BuiltinErrorCode,
+  type BuiltinErrorMap,
+  type BuiltinValidationIssue,
+  type DatabaseErrorReason,
+} from "./builtin-errors.ts";
 
 export {
   flow,

package/src/kernel/mutation-id.ts

@@ -0,0 +1,8 @@
+/**
+ * Write-path mutation id header — shared by the kernel HTTP glue and
+ * `okengine/client-react` optimistic mutate. Keep this file free of Node
+ * APIs so Vite SPAs can import `Can` / `useLiveQuery`.
+ */
+
+/** Header echoed into `mutationId` on write-path live-query events. */
+export const MUTATION_ID_HEADER = "x-oke-mutation-id";

package/src/kernel/plugin.ts

@@ -290,9 +290,10 @@ export interface PluginApi {
    */
   channelTemplate(decl: ChannelTemplateDecl): PluginApi;
   /**
-   * Contribute template body catalog entries (merged into boot channel catalog).
+   * Contribute template body catalog entries — overlay merged into boot
+   * channel catalog after `.template({ catalog })` bodies (`{{field}}`).
    *
-   * @param catalog - Locale bodies keyed by template name (`{{field}}` interpolation)
+   * @param catalog - Locale bodies keyed by template name
    */
   channelCatalog(catalog: TemplateCatalog): PluginApi;
 }
@@ -475,7 +476,7 @@ export interface PluginDef<D extends Record<string, unknown> = {}> {
   gate(decl: GateDecl | GateAllDecl): PluginDef<D>;
   /** Queue a channel template. */
   channelTemplate(decl: ChannelTemplateDecl): PluginDef<D>;
-  /** Queue channel template body catalog entries. */
+  /** Queue channel template body catalog entries (overlay after `.template({ catalog })`). */
   channelCatalog(catalog: TemplateCatalog): PluginDef<D>;
 }