okengine 0.19.1 → 0.19.3

package/src/kernel/cdc-payload.test.ts

@@ -0,0 +1,224 @@
+/**
+ * CdcPayload enrichment — action from images, PK from Manifest, additive fields.
+ */
+
+import { beforeEach, describe, expect, test } from "bun:test";
+import { field, store } from "../elements/store.ts";
+import type { Manifest } from "../manifest/types.ts";
+import { oke } from "./app.ts";
+import {
+  cdcActionFromImages,
+  cdcIdFromImages,
+  declaredPk,
+  declaredPkColumn,
+  enrichCdcPayload,
+  pkColumnByTableFromManifest,
+  type CdcPayload,
+} from "./cdc-payload.ts";
+import { flow, resetFlowSeq } from "./flow.ts";
+import { on, resetBindings } from "./on.ts";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+const manifest: Manifest = {
+  oke: "1.0",
+  app: "cdc-enrich",
+  stores: {
+    db: {
+      facet: "sql",
+      tables: {
+        orders: {
+          columns: {
+            id: { type: "text", primaryKey: true, sqlName: "id" },
+            status: { type: "text", sqlName: "status" },
+          },
+        },
+        accounts: {
+          columns: {
+            code: { type: "text", primaryKey: true, sqlName: "code" },
+            name: { type: "text", sqlName: "name" },
+          },
+        },
+        members: {
+          columns: {
+            userId: { type: "text", primaryKey: true, sqlName: "user_id" },
+          },
+        },
+      },
+    },
+  },
+};
+
+describe("cdc-payload helpers", () => {
+  test("action is created / updated / deleted from before/after presence", () => {
+    expect(cdcActionFromImages(null, { id: "1" })).toBe("created");
+    expect(cdcActionFromImages({ id: "1" }, { id: "1" })).toBe("updated");
+    expect(cdcActionFromImages({ id: "1" }, null)).toBe("deleted");
+  });
+
+  test("id uses after for created/updated and before for deleted", () => {
+    expect(cdcIdFromImages(null, { code: "a1" }, "code")).toBe("a1");
+    expect(cdcIdFromImages({ code: "a1" }, { code: "a1", name: "x" }, "code")).toBe("a1");
+    expect(cdcIdFromImages({ code: "a1" }, null, "code")).toBe("a1");
+  });
+
+  test("id preserves number PKs and stringifies anything else", () => {
+    expect(cdcIdFromImages(null, { id: 42 }, "id")).toBe(42);
+    expect(cdcIdFromImages(null, { id: true }, "id")).toBe("true");
+    expect(cdcIdFromImages(null, {}, "id")).toBe("");
+  });
+
+  test("id tries JS key then SQL name when they differ", () => {
+    const pk = { key: "userId", sqlName: "user_id" };
+    expect(cdcIdFromImages(null, { userId: "u1" }, pk)).toBe("u1");
+    expect(cdcIdFromImages(null, { user_id: "u2" }, pk)).toBe("u2");
+  });
+
+  test("declaredPk reads Manifest primaryKey, else id", () => {
+    expect(declaredPk(manifest.stores!.db!.tables!.accounts!.columns)).toEqual({
+      key: "code",
+      sqlName: "code",
+    });
+    expect(declaredPkColumn(manifest.stores!.db!.tables!.members!.columns)).toBe("user_id");
+    expect(declaredPk(undefined)).toEqual({ key: "id", sqlName: "id" });
+    expect(declaredPk({ name: { type: "text" } })).toEqual({ key: "id", sqlName: "id" });
+  });
+
+  test("pkColumnByTableFromManifest maps every SQL table", () => {
+    const map = pkColumnByTableFromManifest(manifest);
+    expect(map.get("orders")).toEqual({ key: "id", sqlName: "id" });
+    expect(map.get("accounts")).toEqual({ key: "code", sqlName: "code" });
+    expect(map.get("members")).toEqual({ key: "userId", sqlName: "user_id" });
+    expect(pkColumnByTableFromManifest(undefined).size).toBe(0);
+  });
+
+  test("enrichCdcPayload fills table, action, and id", () => {
+    expect(enrichCdcPayload("orders", null, { id: "o1", status: "open" }, "id")).toEqual({
+      table: "orders",
+      action: "created",
+      id: "o1",
+      before: null,
+      after: { id: "o1", status: "open" },
+    });
+  });
+});
+
+describe("dispatchCdc — enriched payload", () => {
+  test("insert/update/delete carry table, action, and the declared PK for two tables", async () => {
+    const seen: CdcPayload[] = [];
+    const db = store.sql("main");
+    const orders = store.schema.table("orders", {
+      id: field.text().primaryKey(),
+      status: field.text(),
+    });
+    const accounts = store.schema.table("accounts", {
+      code: field.text().primaryKey(),
+      name: field.text(),
+    });
+
+    on(
+      db.table(orders).changed(),
+      flow("audit.orders", {
+        do: (p: CdcPayload) => {
+          seen.push(p);
+        },
+      }),
+    );
+    on(
+      db.table(accounts).changed(),
+      flow("audit.accounts", {
+        do: (p: CdcPayload) => {
+          seen.push(p);
+        },
+      }),
+    );
+
+    const app = oke({ autoBoot: false, name: "cdc-enrich", manifest });
+
+    await app.dispatchCdc("orders", { before: null, after: { id: "o1", status: "open" } });
+    await app.dispatchCdc("orders", {
+      before: { id: "o1", status: "open" },
+      after: { id: "o1", status: "paid" },
+    });
+    await app.dispatchCdc("orders", { before: { id: "o1", status: "paid" }, after: null });
+
+    await app.dispatchCdc("accounts", { before: null, after: { code: "acme", name: "Acme" } });
+    await app.dispatchCdc("accounts", {
+      before: { code: "acme", name: "Acme" },
+      after: { code: "acme", name: "Acme Inc" },
+    });
+    await app.dispatchCdc("accounts", { before: { code: "acme", name: "Acme Inc" }, after: null });
+
+    expect(seen).toEqual([
+      {
+        table: "orders",
+        action: "created",
+        id: "o1",
+        before: null,
+        after: { id: "o1", status: "open" },
+      },
+      {
+        table: "orders",
+        action: "updated",
+        id: "o1",
+        before: { id: "o1", status: "open" },
+        after: { id: "o1", status: "paid" },
+      },
+      {
+        table: "orders",
+        action: "deleted",
+        id: "o1",
+        before: { id: "o1", status: "paid" },
+        after: null,
+      },
+      {
+        table: "accounts",
+        action: "created",
+        id: "acme",
+        before: null,
+        after: { code: "acme", name: "Acme" },
+      },
+      {
+        table: "accounts",
+        action: "updated",
+        id: "acme",
+        before: { code: "acme", name: "Acme" },
+        after: { code: "acme", name: "Acme Inc" },
+      },
+      {
+        table: "accounts",
+        action: "deleted",
+        id: "acme",
+        before: { code: "acme", name: "Acme Inc" },
+        after: null,
+      },
+    ]);
+  });
+
+  test("a handler that only destructures { before, after } still runs", async () => {
+    const seen: string[] = [];
+    const db = store.sql("main");
+    const orders = store.schema.table("orders", {
+      id: field.text().primaryKey(),
+      status: field.text(),
+    });
+    on(
+      db.table(orders).changed("status"),
+      flow("t.cdc.bare", {
+        do: (p: { before: { status: string }; after: { status: string } }) => {
+          seen.push(`cdc:${p.before.status}->${p.after.status}`);
+        },
+      }),
+    );
+    const app = oke({ autoBoot: false, name: "cdc-bare" });
+    await app.dispatchCdc(
+      "orders",
+      { before: { status: "open" }, after: { status: "paid" } },
+      "status",
+    );
+    expect(seen).toEqual(["cdc:open->paid"]);
+  });
+});

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

@@ -0,0 +1,25 @@
+/**
+ * OKE1071 — kept off the kernel edge profile.
+ *
+ * Two different Flows bound to the same `signal.once` throw this at `oke()`
+ * construction. Extract fails the same collision with a plain `Error`
+ * (`OKE1071` in the message) so `okengine/compiler` stays off this module.
+ * `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 different Flow definitions share one `signal.once` consumer slot.
+ *
+ * Horizontal replicas of the same Flow are one `on()` in source — this only
+ * fires when the Manifest lists two or more Flow names on that signal.
+ */
+export const ONCE_SIGNAL_MULTI_FLOW: OkeErrorDefinition = {
+  code: 1071,
+  domain: "kernel",
+  cause: 'Once signal "{signal}" is bound to more than one Flow ({flows}).',
+  fix: "Use signal.broadcast if each flow should independently receive this event, or bind only one flow if these should compete for the same work.",
+};

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

@@ -17,6 +17,8 @@ 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 { ONCE_SIGNAL_MULTI_FLOW } from "./errors-once-signal.ts";
 import { TENANT_NOT_MEMBER, TENANT_REQUIRED, TENANT_UNKNOWN_SCOPE } from "./errors-tenant.ts";
 import {
   assertCodesInDomainRanges,
@@ -164,10 +166,18 @@ 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("lazy discovery finds ONCE_SIGNAL_MULTI_FLOW at 1071", async () => {
+    const { files, defs } = await discoverLazyErrorDefs(KERNEL_DIR);
+    expect(files).toContain("errors-once-signal.ts");
+    expect(defs.some((d) => d.code === 1071)).toBe(true);
+    expect(ONCE_SIGNAL_MULTI_FLOW.code).toBe(1071);
   });
 
   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;