okengine 0.19.8 → 0.20.0

package/src/elements/store/schema-decl.test.ts

@@ -3,6 +3,9 @@
  */
 
 import { describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
 import { plugin } from "../../kernel/plugin.ts";
 import { createRecordingApi } from "../../kernel/registry.ts";
 import {
@@ -18,9 +21,13 @@ import {
   type SqlStoreHandle,
 } from "../store.ts";
 import {
+  discoverDeclareRel,
+  discoverGeneratedRel,
   emitDrizzleSource,
   GENERATED_SCHEMA_HEADER,
+  maybeEmitDomainSchema,
   mergeSchemaTables,
+  resolveEmitPaths,
   tablesFromPluginContributions,
 } from "./emit-drizzle.ts";
 
@@ -297,3 +304,174 @@ describe("store.schema RLS extras", () => {
     expect(emitDrizzleSource([notes], "postgres")).toContain("pgTable.withRLS");
   });
 });
+
+describe("declare path discovery", () => {
+  test("schema.ts wins over schema/index.ts", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-decl-priority-"));
+    await mkdir(join(dir, "src", "db", "schema"), { recursive: true });
+    await writeFile(join(dir, "src", "db", "schema.ts"), "export {}\n");
+    await writeFile(join(dir, "src", "db", "schema", "index.ts"), "export {}\n");
+    expect(discoverDeclareRel(dir)).toBe("src/db/schema.ts");
+    expect(resolveEmitPaths(dir).declarePath).toBe(join(dir, "src/db/schema.ts"));
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("schema.decl.ts when schema.ts is absent", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-decl-prev-"));
+    await mkdir(join(dir, "src", "db", "schema"), { recursive: true });
+    await writeFile(join(dir, "src", "db", "schema.decl.ts"), "export {}\n");
+    await writeFile(join(dir, "src", "db", "schema", "index.ts"), "export {}\n");
+    expect(discoverDeclareRel(dir)).toBe("src/db/schema.decl.ts");
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("schema/index.ts when single-file declare is absent", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-decl-folder-"));
+    await mkdir(join(dir, "src", "db", "schema"), { recursive: true });
+    await writeFile(join(dir, "src", "db", "schema", "index.ts"), "export {}\n");
+    expect(discoverDeclareRel(dir)).toBe("src/db/schema/index.ts");
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("db.declare overrides discovery", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-decl-override-"));
+    await mkdir(join(dir, "src", "db", "schema"), { recursive: true });
+    await writeFile(join(dir, "src", "db", "schema.ts"), "export {}\n");
+    const resolved = resolveEmitPaths(dir, { declare: "src/db/schema/index.ts" });
+    expect(resolved.declarePath).toBe(join(dir, "src/db/schema/index.ts"));
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("drizzle/index.ts wins over drizzle.ts", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-gen-folder-"));
+    await mkdir(join(dir, "src", "db", "drizzle"), { recursive: true });
+    await writeFile(join(dir, "src", "db", "drizzle", "index.ts"), "export {}\n");
+    await writeFile(join(dir, "src", "db", "drizzle.ts"), "export {}\n");
+    expect(discoverGeneratedRel(dir, "src/db/schema.ts")).toBe("src/db/drizzle/index.ts");
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("omitted generated is drizzle/index.ts even if older files exist", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-gen-default-"));
+    await mkdir(join(dir, "src", "db"), { recursive: true });
+    await writeFile(join(dir, "src", "db", "drizzle.ts"), "export {}\n");
+    await writeFile(join(dir, "src", "db", "schema.drizzle.ts"), "export {}\n");
+    expect(discoverGeneratedRel(dir, "src/db/schema.ts")).toBe("src/db/drizzle/index.ts");
+    await rm(dir, { recursive: true, force: true });
+  });
+});
+
+describe("maybeEmitDomainSchema — barrel declare", () => {
+  test("emits from schema/index.ts without schema.ts", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-schema-folder-"));
+    const schemaDir = join(dir, "src", "db", "schema");
+    await mkdir(schemaDir, { recursive: true });
+    const oke = resolve(import.meta.dir, "../../index.ts");
+    await writeFile(
+      join(schemaDir, "posts.ts"),
+      `import { store, field } from ${JSON.stringify(oke)};
+export const posts = store.schema.table("posts", {
+  id: field.id().primaryKey(),
+  title: field.text().notNull(),
+});
+`,
+    );
+    await writeFile(join(schemaDir, "index.ts"), `export * from "./posts.ts";\n`);
+    const result = await maybeEmitDomainSchema({
+      cwd: dir,
+      dialect: "postgres",
+    });
+    expect(result.emitted).toBe(true);
+    expect(result.tableCount).toBe(1);
+    const generated = await readFile(join(dir, "src", "db", "drizzle", "posts.ts"), "utf8");
+    expect(generated).toContain('pgTable("posts"');
+    const barrel = await readFile(join(dir, "src", "db", "drizzle", "index.ts"), "utf8");
+    expect(barrel).toContain('export * from "./posts.ts"');
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("writes one file per table with FK import + relations", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-drizzle-split-"));
+    const schemaDir = join(dir, "src", "db", "schema");
+    await mkdir(schemaDir, { recursive: true });
+    const oke = resolve(import.meta.dir, "../../index.ts");
+    await writeFile(
+      join(schemaDir, "links.ts"),
+      `import { store, field } from ${JSON.stringify(oke)};
+export const links = store.schema.table("links", {
+  id: field.id().primaryKey(),
+  code: field.text().notNull().unique(),
+});
+`,
+    );
+    await writeFile(
+      join(schemaDir, "daily.ts"),
+      `import { store, field } from ${JSON.stringify(oke)};
+import { links } from "./links.ts";
+export const daily = store.schema.table("daily", {
+  id: field.id().primaryKey(),
+  code: field.text().notNull().references(() => links.code, { onDelete: "cascade" }),
+});
+`,
+    );
+    await writeFile(
+      join(schemaDir, "relations.ts"),
+      `import { store } from ${JSON.stringify(oke)};
+import { daily } from "./daily.ts";
+import { links } from "./links.ts";
+export const relations = store.schema.relations({ links, daily }, (r) => ({
+  links: { daily: r.many.daily({ from: r.links.code, to: r.daily.code }) },
+  daily: { link: r.one.links({ from: r.daily.code, to: r.links.code, optional: false }) },
+}));
+`,
+    );
+    await writeFile(
+      join(schemaDir, "index.ts"),
+      `export * from "./links.ts";
+export * from "./daily.ts";
+export * from "./relations.ts";
+`,
+    );
+    const result = await maybeEmitDomainSchema({ cwd: dir, dialect: "postgres" });
+    expect(result.emitted).toBe(true);
+    expect(result.tableCount).toBe(2);
+    const daily = await readFile(join(dir, "src", "db", "drizzle", "daily.ts"), "utf8");
+    expect(daily).toContain('import { links } from "./links.ts"');
+    expect(daily).toContain(".references(() => links.code");
+    const rel = await readFile(join(dir, "src", "db", "drizzle", "relations.ts"), "utf8");
+    expect(rel).toContain("defineRelations({ links, daily }");
+    const barrel = await readFile(join(dir, "src", "db", "drizzle", "index.ts"), "utf8");
+    expect(barrel).toContain('export * from "./relations.ts"');
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("prunes stale generated files and drops sibling drizzle.ts", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-drizzle-prune-"));
+    const schemaDir = join(dir, "src", "db", "schema");
+    await mkdir(schemaDir, { recursive: true });
+    await mkdir(join(dir, "src", "db", "drizzle"), { recursive: true });
+    const oke = resolve(import.meta.dir, "../../index.ts");
+    await writeFile(
+      join(schemaDir, "posts.ts"),
+      `import { store, field } from ${JSON.stringify(oke)};
+export const posts = store.schema.table("posts", {
+  id: field.id().primaryKey(),
+});
+`,
+    );
+    await writeFile(join(schemaDir, "index.ts"), `export * from "./posts.ts";\n`);
+    await writeFile(
+      join(dir, "src", "db", "drizzle.ts"),
+      `// generated by oke — do not edit\nexport const stale = true;\n`,
+    );
+    await writeFile(
+      join(dir, "src", "db", "drizzle", "gone.ts"),
+      `// generated by oke — do not edit\nexport const gone = true;\n`,
+    );
+    await maybeEmitDomainSchema({ cwd: dir, dialect: "postgres" });
+    expect(await Bun.file(join(dir, "src", "db", "drizzle.ts")).exists()).toBe(false);
+    expect(await Bun.file(join(dir, "src", "db", "drizzle", "gone.ts")).exists()).toBe(false);
+    expect(await Bun.file(join(dir, "src", "db", "drizzle", "posts.ts")).exists()).toBe(true);
+    await rm(dir, { recursive: true, force: true });
+  });
+});

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

@@ -22,9 +22,11 @@ import {
   compileWhere,
   compileOrderBy,
   resolveSelectColumns,
+  type CompiledWhere,
   type WhereMap,
 } from "./sql-condition.ts";
 import {
+  coerceTemporalBindValue,
   mapRowToJs,
   prepareInsertRow,
   prepareUpdateRow,
@@ -622,6 +624,46 @@ export function createSqlStoreHandle(
     return out;
   }
 
+  /**
+   * Coerce epoch-ms / ISO strings on temporal WHERE binds the same way
+   * insert/update SET does, so `lte(col, fx.clock.now())` is a timestamp.
+   *
+   * @param table - Table whose columns supply SQL types
+   * @param compiled - Predicate list from {@link compileWhere}
+   */
+  function coerceCompiledWhere(
+    table: TableHandle | unknown,
+    compiled: CompiledWhere,
+  ): CompiledWhere {
+    const cols = resolveColumns(table);
+    if (cols.length === 0 || compiled.predicates.length === 0) return compiled;
+    const bySql = new Map(cols.map((c) => [c.sqlName, c]));
+
+    let changed = false;
+    const predicates = compiled.predicates.map((p) => {
+      const col = bySql.get(p.column);
+      if (!col || p.op === "is null" || p.op === "is not null") return p;
+      if (p.op === "in" && Array.isArray(p.value)) {
+        const incoming = p.value;
+        const value = incoming.map((v) => coerceTemporalBindValue(col.sqlType, v));
+        if (value.some((v, i) => v !== incoming[i])) changed = true;
+        return { ...p, value };
+      }
+      const value = coerceTemporalBindValue(col.sqlType, p.value);
+      if (value !== p.value) changed = true;
+      return { ...p, value };
+    });
+    if (!changed) return compiled;
+
+    const params: unknown[] = [];
+    for (const p of predicates) {
+      if (p.op === "is null" || p.op === "is not null") continue;
+      if (p.op === "in" && Array.isArray(p.value)) params.push(...p.value);
+      else params.push(p.value);
+    }
+    return { clause: compiled.clause, params, predicates };
+  }
+
   function compileTableWhere(
     table: TableHandle | unknown,
     where: unknown,
@@ -632,9 +674,9 @@ export function createSqlStoreHandle(
       !Array.isArray(where) &&
       !("queryChunks" in (where as object))
     ) {
-      return compileWhere(normalizeWhereMap(table, where as WhereMap));
+      return coerceCompiledWhere(table, compileWhere(normalizeWhereMap(table, where as WhereMap)));
     }
-    return compileWhere(where);
+    return coerceCompiledWhere(table, compileWhere(where));
   }
 
   /**

package/src/elements/store/table.ts

@@ -295,7 +295,8 @@ function drizzleSqlType(
 
 /**
  * Bind value for a temporal SQL column. Epoch-ms numbers (e.g. `fx.clock.now()`)
- * become `Date` so Postgres `timestamp` / `date` accept them; other values pass through.
+ * and parseable ISO datetime strings (HTTP `z.iso.datetime()`) become `Date`
+ * so Postgres `timestamp` / `date` accept them; other values pass through.
  *
  * @param sqlType - Resolved DDL type
  * @param value - Incoming JS value
@@ -304,13 +305,14 @@ export function coerceTemporalBindValue(
   sqlType: ResolvedColumn["sqlType"],
   value: unknown,
 ): unknown {
-  if (
-    (sqlType === "TIMESTAMP" || sqlType === "DATE") &&
-    typeof value === "number" &&
-    Number.isFinite(value)
-  ) {
+  if (sqlType !== "TIMESTAMP" && sqlType !== "DATE") return value;
+  if (typeof value === "number" && Number.isFinite(value)) {
     return new Date(value);
   }
+  if (typeof value === "string") {
+    const parsed = Date.parse(value);
+    if (Number.isFinite(parsed)) return new Date(parsed);
+  }
   return value;
 }
 

package/src/kernel/adopt-barrel-fresh.test.ts

@@ -82,7 +82,7 @@ describe("boot-level: stale barrel through a real oke() boot", () => {
     const root = await mkdtemp(join(tmpdir(), "oke-adopt-fresh-"));
     try {
       // "notes" exists on disk but this app only ever adopted "main" —
-      // exactly what a stale `src/flows/generated.ts` after adding a unit
+      // exactly what a stale `src/flows/index.ts` after adding a unit
       // (and forgetting to rerun `oke dev` / `oke build`) looks like.
       await makeUnitDir(root, "notes");
       const mainFlow = flow("main.health", {

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,
@@ -381,13 +382,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 +854,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 +968,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 +1454,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 +1481,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 ??
@@ -1965,7 +1981,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 = {
@@ -2616,28 +2633,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/errors.ts

@@ -239,7 +239,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 +247,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 +256,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.

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.ts

@@ -182,7 +182,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 +469,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>;

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