okengine 0.19.0 → 0.19.2

package/src/kernel/cdc-payload.ts

@@ -0,0 +1,146 @@
+/**
+ * CDC flow payload — `{ before, after }` plus additive `table` / `action` / `id`.
+ *
+ * PK lookup reuses the Manifest `DeclaredColumn.primaryKey` walk already proven
+ * by search-embed (not `resolvePkColumn`'s `"id"`/`"code"` heuristics).
+ */
+
+import type { DeclaredColumn, Manifest, Table } from "../manifest/types.ts";
+
+/** Insert / update / delete derived from before/after presence. */
+export type CdcAction = "created" | "updated" | "deleted";
+
+/** Payload for a CDC invocation. */
+export interface CdcPayload {
+  readonly before: Record<string, unknown> | null;
+  readonly after: Record<string, unknown> | null;
+  readonly table: string;
+  readonly action: CdcAction;
+  readonly id: string | number;
+}
+
+/**
+ * Images-only (or partially enriched) input accepted by {@link dispatchCdc}.
+ * Missing `table` / `action` / `id` are filled in before the Flow runs.
+ */
+export type CdcPayloadInput = Pick<CdcPayload, "before" | "after"> &
+  Partial<Pick<CdcPayload, "table" | "action" | "id">>;
+
+/** JS key + SQL name for a declared primary-key column. */
+export interface DeclaredPk {
+  readonly key: string;
+  readonly sqlName: string;
+}
+
+const DEFAULT_PK: DeclaredPk = { key: "id", sqlName: "id" };
+
+/**
+ * Declared PK from a Manifest table column map.
+ * `primaryKey: true` wins; otherwise `"id"` (CDC does not require a PK).
+ *
+ * @param columns - Manifest `tables.*.columns`
+ */
+export function declaredPk(columns: Table["columns"] | undefined): DeclaredPk {
+  for (const [key, col] of Object.entries(columns ?? {})) {
+    if (!col || typeof col !== "object") continue;
+    const c = col as DeclaredColumn;
+    if (c.primaryKey === true) return { key, sqlName: c.sqlName ?? key };
+  }
+  return DEFAULT_PK;
+}
+
+/**
+ * SQL name of the declared PK (search-embed SQL `WHERE` uses this).
+ *
+ * @param columns - Manifest `tables.*.columns`
+ */
+export function declaredPkColumn(columns: Table["columns"] | undefined): string {
+  return declaredPk(columns).sqlName;
+}
+
+/**
+ * Table name → declared PK for every SQL table in the Manifest.
+ *
+ * @param manifest - Compiled Manifest (optional)
+ */
+export function pkColumnByTableFromManifest(
+  manifest: Pick<Manifest, "stores"> | undefined,
+): ReadonlyMap<string, DeclaredPk> {
+  const out = new Map<string, DeclaredPk>();
+  for (const store of Object.values(manifest?.stores ?? {})) {
+    if (store.facet !== "sql" || !store.tables) continue;
+    for (const [tableName, table] of Object.entries(store.tables)) {
+      out.set(tableName, declaredPk(table.columns));
+    }
+  }
+  return out;
+}
+
+/**
+ * Derive action from row images. `before === null` → created; `after === null`
+ * → deleted; otherwise updated. Not `event.op`.
+ *
+ * @param before - Prior row image
+ * @param after - New row image
+ */
+export function cdcActionFromImages(
+  before: Record<string, unknown> | null,
+  after: Record<string, unknown> | null,
+): CdcAction {
+  if (before === null) return "created";
+  if (after === null) return "deleted";
+  return "updated";
+}
+
+function pkNames(pkColumn: string | DeclaredPk): DeclaredPk {
+  return typeof pkColumn === "string" ? { key: pkColumn, sqlName: pkColumn } : pkColumn;
+}
+
+function asCdcId(raw: unknown): string | number {
+  if (typeof raw === "number" && Number.isFinite(raw)) return raw;
+  if (typeof raw === "string") return raw;
+  return String(raw ?? "");
+}
+
+/**
+ * Extract the PK value from the surviving image (`after` for created/updated,
+ * `before` for deleted). Tries the JS key then the SQL name.
+ *
+ * @param before - Prior row image
+ * @param after - New row image
+ * @param pkColumn - Declared PK key and/or SQL name
+ */
+export function cdcIdFromImages(
+  before: Record<string, unknown> | null,
+  after: Record<string, unknown> | null,
+  pkColumn: string | DeclaredPk,
+): string | number {
+  const { key, sqlName } = pkNames(pkColumn);
+  const row = after ?? before;
+  if (!row) return "";
+  const raw = key in row ? row[key] : row[sqlName];
+  return asCdcId(raw);
+}
+
+/**
+ * Build the full CDC payload from table name, images, and the declared PK.
+ *
+ * @param tableName - Physical table name (`resolveTableName` / `dispatchCdc` arg)
+ * @param before - Prior row image
+ * @param after - New row image
+ * @param pkColumn - Declared PK (Manifest) or a column name string
+ */
+export function enrichCdcPayload(
+  tableName: string,
+  before: Record<string, unknown> | null,
+  after: Record<string, unknown> | null,
+  pkColumn: string | DeclaredPk = DEFAULT_PK,
+): CdcPayload {
+  return {
+    before,
+    after,
+    table: tableName,
+    action: cdcActionFromImages(before, after),
+    id: cdcIdFromImages(before, after, pkColumn),
+  };
+}

package/src/kernel/errors-flow-name.ts

@@ -0,0 +1,17 @@
+/**
+ * OKE1070 — kept off the kernel edge profile.
+ *
+ * Duplicate Flow names throw this at `oke()` construction. `oke()` imports
+ * it directly (that graph is not in `budget-entry`). Registry discovery
+ * includes this file; the edge `lookupOkeError` path stays off this def.
+ */
+
+import type { OkeErrorDefinition } from "./errors.ts";
+
+/** Two Flow definitions share the same Manifest / `fx.call` name. */
+export const FLOW_NAME_DUPLICATE: OkeErrorDefinition = {
+  code: 1070,
+  domain: "kernel",
+  cause: 'Flow "{flow}" is defined twice.',
+  fix: 'Give at least one Flow an explicit flow("…") or a distinct tree export.',
+};

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

@@ -17,6 +17,7 @@ import {
 } from "./errors.ts";
 import { LIVE_RESUME_GAP } from "./errors-live-resume.ts";
 import { CHANNEL_SCHEMA } from "./errors-channel.ts";
+import { FLOW_NAME_DUPLICATE } from "./errors-flow-name.ts";
 import { TENANT_NOT_MEMBER, TENANT_REQUIRED, TENANT_UNKNOWN_SCOPE } from "./errors-tenant.ts";
 import {
   assertCodesInDomainRanges,
@@ -164,10 +165,11 @@ describe("OKE error-code registry", () => {
     expect(lookupOkeError(1830)).toEqual(TENANT_UNKNOWN_SCOPE);
   });
 
-  test("lookupOkeError finds UNDECLARED_EMBED at 1009 (not tenant)", () => {
-    expect(lookupOkeError(1009)).toEqual(OKE_ERRORS.UNDECLARED_EMBED);
-    expect(OKE_ERRORS.UNDECLARED_EMBED.code).toBe(1009);
-    expect(TENANT_REQUIRED.code).toBe(1810);
+  test("lazy discovery finds FLOW_NAME_DUPLICATE at 1070", async () => {
+    const { files, defs } = await discoverLazyErrorDefs(KERNEL_DIR);
+    expect(files).toContain("errors-flow-name.ts");
+    expect(defs.some((d) => d.code === 1070)).toBe(true);
+    expect(FLOW_NAME_DUPLICATE.code).toBe(1070);
   });
 
   test("NO_EFFECTS_DECLARED owns 1020 after renumber (was UNDECLARED_EMBED)", () => {

package/src/kernel/flow-name.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Nameless Flow inherits Signal/Clock trigger names; duplicates fail OKE1070.
+ */
+
+import { beforeEach, describe, expect, test } from "bun:test";
+import { clock, resetClocks } from "../elements/clock/declare.ts";
+import { resetSignals, signal } from "../elements/signal/declare.ts";
+import { oke } from "./app.ts";
+import { OkeError } from "./errors.ts";
+import { FLOW_NAME_DUPLICATE } from "./errors-flow-name.ts";
+import { flow, resetFlowSeq } from "./flow.ts";
+import { on, resetBindings } from "./on.ts";
+import { stampFlowName } from "./stamp-http.ts";
+import { http } from "./triggers.ts";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+  resetSignals();
+  resetClocks();
+});
+
+describe("on() — Signal/Clock name inheritance", () => {
+  test("nameless flow inherits inline signal.once name", () => {
+    const bound = on(
+      signal.once("link-clicked"),
+      flow({
+        do: () => ({ ok: true }),
+      }),
+    );
+    expect(bound.name).toBe("link-clicked");
+  });
+
+  test("nameless flow inherits clock.every name", () => {
+    const bound = on(
+      clock.every("cleanup", "10m"),
+      flow({
+        do: () => ({ ok: true }),
+      }),
+    );
+    expect(bound.name).toBe("cleanup");
+  });
+
+  test("explicit flow name wins over the trigger name", () => {
+    const bound = on(
+      signal.once("order-placed"),
+      flow("orders.fulfill", { do: () => ({ ok: true }) }),
+    );
+    expect(bound.name).toBe("orders.fulfill");
+  });
+
+  test("HTTP does not inherit a name from the trigger", () => {
+    const bound = on(
+      http.post("/notes"),
+      flow({
+        do: () => ({ ok: true }),
+      }),
+    );
+    expect(bound.name).toBe("");
+  });
+
+  test("file-tree stamp overwrites a trigger-inherited name", () => {
+    const bound = on(
+      signal.once("note-created"),
+      flow({
+        do: () => ({ ok: true }),
+      }),
+    );
+    expect(bound.name).toBe("note-created");
+    stampFlowName(bound, "notes.onCreated");
+    expect(bound.name).toBe("notes.onCreated");
+  });
+});
+
+describe("oke — FLOW_NAME_DUPLICATE OKE1070", () => {
+  test("two nameless inheritances of the same trigger name fail at construction", () => {
+    const ping = signal.once("health.ping");
+    on(ping, flow({ do: () => ({ a: true }) }));
+    on(ping, flow({ do: () => ({ b: true }) }));
+    try {
+      oke({ name: "t", autoBoot: false });
+      expect.unreachable("oke() should throw OKE1070");
+    } catch (err) {
+      expect(err).toBeInstanceOf(OkeError);
+      const okeErr = err as OkeError;
+      expect(okeErr.code).toBe(1070);
+      expect(okeErr.code).toBe(FLOW_NAME_DUPLICATE.code);
+      expect(okeErr.message).toMatch(/OKE1070/);
+    }
+  });
+
+  test("two explicit flows with the same name fail OKE1070", () => {
+    on(signal.once("a"), flow("shared", { do: () => 1 }));
+    on(clock.every("b", "1h"), flow("shared", { do: () => 2 }));
+    expect(() => oke({ name: "t", autoBoot: false })).toThrow(/OKE1070/);
+  });
+
+  test("the same flow object bound twice is not a duplicate", () => {
+    const shared = flow("shared.work", { do: (input: { n: number }) => input.n });
+    on(http.post("/work"), shared);
+    on(signal.once("order-placed"), shared);
+    expect(() => oke({ name: "t", autoBoot: false })).not.toThrow();
+  });
+});

package/src/kernel/flow.ts

@@ -240,8 +240,9 @@ export const flowBrand: unique symbol = Symbol("oke.flow");
  * {@link call} / `mcp.tool`, not here.
  *
  * A nameless `flow({ do })` is stamped `unit.export` by the file-tree
- * generator, {@link unit}, or `.adopt()`. Explicit `flow("notes.get", {…})`
- * still wins.
+ * generator, {@link unit}, or `.adopt()`. Bound to a named Signal or Clock
+ * with no explicit / tree / export name, it inherits the trigger's name.
+ * Explicit `flow("notes.get", {…})` still wins.
  *
  * @param options - Runtime options and handler (name stamped later)
  */

package/src/kernel/fx-emit-types.test.ts

@@ -0,0 +1,31 @@
+/**
+ * Typed `fx.emit(SignalDecl<T>, payload)` vs untyped string-name emits.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { signal } from "../elements/signal/declare.ts";
+import { createFxContext, type Fx } from "./fx.ts";
+
+describe("fx.emit — SignalDecl payload inference", () => {
+  test("exported handle type-checks a matching payload; string names stay unknown", () => {
+    const orderPlaced = signal.once<{ orderId: string }>("order-placed");
+    const { fx } = createFxContext({
+      flow: "orders.create",
+      effects: { emits: ["order-placed"] },
+    });
+
+    const typed: (s: typeof orderPlaced, p: { orderId: string }) => Promise<void> = (s, p) =>
+      fx.emit(s, p);
+    const untyped: (name: string, p: { extra: boolean }) => Promise<void> = (name, p) =>
+      fx.emit(name, p);
+
+    expect(typeof typed).toBe("function");
+    expect(typeof untyped).toBe("function");
+
+    function _wrongPayload(fxArg: Fx): void {
+      // @ts-expect-error payload must match SignalDecl
+      void fxArg.emit(orderPlaced, { orderId: 1 });
+    }
+    expect(typeof _wrongPayload).toBe("function");
+  });
+});

package/src/kernel/fx.test.ts

@@ -8,6 +8,7 @@ import {
   jsonResultBrand,
   type Fx,
   type FxStubStoreHandle,
+  type NamedRef,
 } from "./fx.ts";
 import { Redacted } from "./redacted.ts";
 
@@ -426,7 +427,7 @@ describe("fx — wholesale swap", () => {
           throw new Error("runs must not be used");
         },
       },
-      async emit(signal) {
+      async emit(signal: NamedRef) {
         calls.push(`emit:${typeof signal === "string" ? signal : signal.name}`);
       },
       async deadLetters() {

package/src/kernel/fx.ts

@@ -686,11 +686,21 @@ export interface Fx {
   /**
    * Emit a signal (records `emit`).
    *
+   * Pass a {@link SignalDecl} handle for compile-time payload checking.
+   * A string name accepts `unknown` (runtime `schema` still applies).
+   *
    * @param signal - Signal name or handle
    * @param payload - Payload
    * @param options - Optional emit options (`key` for per-key once ordering)
    */
-  emit(signal: NamedRef, payload?: unknown, options?: SignalEmitOptions): Promise<void>;
+  emit<T>(signal: SignalDecl<T>, payload?: T, options?: SignalEmitOptions): Promise<void>;
+  emit(
+    signal:
+      | string
+      | { readonly name: string; readonly version?: number; readonly delivery?: never },
+    payload?: unknown,
+    options?: SignalEmitOptions,
+  ): Promise<void>;
   /**
    * Query dead-lettered messages for one signal (records `read` on `signal:<name>`).
    *
@@ -847,7 +857,7 @@ export interface Fx {
   t(key: AppMessageKey, values?: MessageValues): string;
   /** Active locale for {@link Fx.t} and default channel sends. */
   readonly locale: string;
-  /** Generate a unique id (UUID). */
+  /** Generate a unique id (OKID). */
   id(): string;
   /** User-plane auth principal. */
   readonly auth: FxAuth;
@@ -1928,7 +1938,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
   const fx: Fx = {
     store: storeHandle,
     runs: runsSurface,
-    emit(signal, payload, emitOptions) {
+    emit(signal: NamedRef, payload?: unknown, emitOptions?: SignalEmitOptions) {
       const name = resolveName(signal);
       return gated("emit", name, async () => {
         if (options.signalRuntime) {

package/src/kernel/index.ts

@@ -4,7 +4,9 @@
 
 export {
   oke,
+  type CdcAction,
   type CdcPayload,
+  type CdcPayloadInput,
   type ExecuteResult,
   type OkeApp,
   type OkeOptions,

package/src/kernel/on.ts

@@ -203,6 +203,11 @@ export function on(
   list.push(normalized);
   // Stamp runtime carrier for the first bound trigger (type follows BoundTriggerOf).
   (flowDef as { $trigger: Trigger }).$trigger = normalized;
+  // `$n` = name inherited from this Signal/Clock (file-tree / unit() may overwrite).
+  if ((normalized.kind === "signal" || normalized.kind === "clock") && !flowDef.name) {
+    (flowDef as { name: string; $n?: boolean }).name = normalized.name;
+    (flowDef as { $n?: boolean }).$n = true;
+  }
   stampExposureContract(flowDef as AnyFlowDef, normalized, triggerOrMount);
   bindings.push({ trigger: normalized, flow: flowDef as AnyFlowDef });
   return flowDef;

package/src/kernel/stamp-http.test.ts

@@ -3,6 +3,7 @@
  */
 
 import { describe, expect, test, beforeEach } from "bun:test";
+import { resetSignals, signal } from "../elements/signal/declare.ts";
 import type { RuntimeRouteMap } from "./adopt-routes.ts";
 import { oke } from "./app.ts";
 import { flow, resetFlowSeq } from "./flow.ts";
@@ -16,6 +17,7 @@ beforeEach(() => {
   resetBindings();
   resetFlowSeq();
   resetRegisteredFlowUnits();
+  resetSignals();
 });
 
 describe("stampHttpPath", () => {
@@ -49,6 +51,17 @@ describe("stampFlowName", () => {
     stampFlowName(f, "notes.list");
     expect(f.name).toBe("notes.get");
   });
+
+  test("file-tree stamp overwrites a trigger-inherited name", () => {
+    const bound = on(
+      signal.once("note-created"),
+      flow({
+        do: () => ({ ok: true }),
+      }),
+    );
+    stampFlowName(bound, "notes.onCreated");
+    expect(bound.name).toBe("notes.onCreated");
+  });
 });
 
 describe("oke — unresolved sentinel and duplicate routes", () => {

package/src/kernel/stamp-http.ts

@@ -35,8 +35,25 @@ export function stampHttpPath<F extends AnyFlowDef, P extends string>(
   return flow as StampHttpPath<F, P>;
 }
 
+/** Mutable name fields used by {@link stampFlowName} / {@link on}. */
+type FlowNameCarrier = {
+  name: string;
+  unit: string | undefined;
+  $n?: boolean;
+};
+
+/**
+ * True when a Flow name is still a placeholder: empty, synthetic `flow_*`,
+ * or inherited from a Signal/Clock trigger (`$n`). File-tree / `unit()` may overwrite.
+ *
+ * @param flow - Flow name carrier
+ */
+export function isUnsetFlowName(flow: { readonly name: string; readonly $n?: boolean }): boolean {
+  return !flow.name || flow.name.startsWith("flow_") || flow.$n === true;
+}
+
 /**
- * Stamp `unit.export` onto a nameless (or `flow_*`) Flow.
+ * Stamp `unit.export` onto a nameless (or `flow_*` / trigger-inherited) Flow.
  *
  * Explicit `flow("notes.get")` wins. Fills `unit` when missing.
  *
@@ -45,9 +62,10 @@ export function stampHttpPath<F extends AnyFlowDef, P extends string>(
  */
 export function stampFlowName<F extends AnyFlowDef>(flow: F, name: string): F {
   if (!isFlow(flow)) return flow;
-  const f = flow as { name: string; unit: string | undefined };
-  if (!f.name || f.name.startsWith("flow_")) {
+  const f = flow as FlowNameCarrier;
+  if (isUnsetFlowName(f)) {
     f.name = name;
+    f.$n = false;
   }
   if (!f.unit) {
     const resolved = f.name || name;

package/src/kernel/unit.ts

@@ -5,6 +5,7 @@
  * unit. Plugins queue until an app flushes them at boot / adopt time.
  */
 
+import { isUnsetFlowName } from "./stamp-http.ts";
 import type { AnyFlowDef, FlowDef } from "./flow.ts";
 import type { PluginDef } from "./plugin.ts";
 
@@ -40,8 +41,9 @@ export function unit<const T extends Record<string, AnyFlowDef>>(
   const pending: PluginDef[] = [];
   for (const [exportName, flowDef] of Object.entries(flows)) {
     const f = flowDef as FlowDef;
-    if (!f.name || f.name.startsWith("flow_")) {
-      (f as { name: string }).name = `${name}.${exportName}`;
+    if (isUnsetFlowName(f)) {
+      (f as { name: string; $n?: boolean }).name = `${name}.${exportName}`;
+      (f as { $n?: boolean }).$n = false;
     }
     if (!f.unit) {
       (f as { unit: string }).unit = name;

package/src/kernel-entry.ts

@@ -27,6 +27,9 @@ export {
   type OkeApp,
   type OkeOptions,
   type ReadyState,
+  type CdcAction,
+  type CdcPayload,
+  type CdcPayloadInput,
   type FlowDef,
   type FlowFailure,
   type FlowErrorValue,

package/src/mcp/docs-index.ts

@@ -12,7 +12,7 @@ import { join } from "node:path";
 export interface DocsPage {
   /** URL slug under `/docs` (`""` for the index page). */
   readonly slug: string;
-  /** Content-relative path (e.g. `understand/the-problem.mdx`). */
+  /** Content-relative path (e.g. `understand/the-architecture.mdx`). */
   readonly path: string;
   /** Frontmatter title. */
   readonly title: string;
@@ -39,7 +39,7 @@ export interface DocsIndex {
   /**
    * Look up a page by slug or content path.
    *
-   * @param id - Slug (`understand/the-problem`) or path (`…/the-problem.mdx`)
+   * @param id - Slug (`understand/the-architecture`) or path (`…/the-architecture.mdx`)
    */
   readonly get: (id: string) => DocsPage | null;
   /**
@@ -203,7 +203,7 @@ export async function loadDocsIndex(
 }
 
 /**
- * @param relativePath - e.g. `understand/the-problem.mdx`
+ * @param relativePath - e.g. `understand/the-architecture.mdx`
  */
 function pathToSlug(relativePath: string): string {
   const noExt = relativePath.replace(/\.mdx?$/i, "");

package/src/mcp/docs-mcp.test.ts

@@ -112,7 +112,7 @@ describe("docs MCP tools", () => {
 
   test("oke.docs.get returns body byte-identical to on-disk source", async () => {
     const mcp = await createDocsMcpServer({ contentDir: CONTENT });
-    const slug = "understand/the-problem";
+    const slug = "understand/the-architecture";
     const res = await mcpPost(mcp.fetch, {
       jsonrpc: "2.0",
       id: 2,
@@ -133,7 +133,7 @@ describe("docs MCP tools", () => {
     const content = envelope.content as { body: string; slug: string };
     expect(content.slug).toBe(slug);
 
-    const raw = await Bun.file(join(CONTENT, "understand", "the-problem.mdx")).text();
+    const raw = await Bun.file(join(CONTENT, "understand", "the-architecture.mdx")).text();
     expect(content.body).toBe(stripYamlFrontmatter(raw));
   });
 

package/src/mcp/docs-tools.ts

@@ -52,7 +52,8 @@ export const DOCS_MCP_TOOLS: readonly DocsToolDescriptor[] = [
       properties: {
         slug: {
           type: "string",
-          description: "Page slug (e.g. understand/the-problem) or path (…/the-problem.mdx)",
+          description:
+            "Page slug (e.g. understand/the-architecture) or path (…/the-architecture.mdx)",
         },
       },
       required: ["slug"],