okengine 0.19.1 → 0.19.3

package/src/kernel/once-signal.test.ts

@@ -0,0 +1,71 @@
+/**
+ * Once-signal uniqueness (OKE1071) — two different Flows on `signal.once`.
+ */
+
+import { beforeEach, describe, expect, test } from "bun:test";
+import { 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 { ONCE_SIGNAL_MULTI_FLOW } from "./errors-once-signal.ts";
+import { flow, resetFlowSeq } from "./flow.ts";
+import { on, resetBindings } from "./on.ts";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+  resetSignals();
+  resetClocks();
+});
+
+describe("oke — ONCE_SIGNAL_MULTI_FLOW OKE1071", () => {
+  test("two differently-named flows on the same once signal fail OKE1071", () => {
+    const orderPlaced = signal.once("orders.placed");
+    on(orderPlaced, flow("orders.charge", { do: () => ({ a: true }) }));
+    on(orderPlaced, flow("orders.ship", { do: () => ({ b: true }) }));
+    try {
+      oke({ name: "t", autoBoot: false });
+      expect.unreachable("oke() should throw OKE1071");
+    } catch (err) {
+      expect(err).toBeInstanceOf(OkeError);
+      const okeErr = err as OkeError;
+      expect(okeErr.code).toBe(1071);
+      expect(okeErr.code).toBe(ONCE_SIGNAL_MULTI_FLOW.code);
+      expect(okeErr.message).toMatch(/OKE1071/);
+      expect(okeErr.causeText).toContain("orders.placed");
+      expect(okeErr.causeText).toContain("orders.charge");
+      expect(okeErr.causeText).toContain("orders.ship");
+      expect(okeErr.fix).toMatch(/signal\.broadcast/);
+    }
+  });
+
+  test("the same scenario with signal.broadcast does not fail", () => {
+    const catalogChanged = signal.broadcast("catalog.changed");
+    on(catalogChanged, flow("cache.invalidate", { do: () => ({ a: true }) }));
+    on(catalogChanged, flow("search.reindex", { do: () => ({ b: true }) }));
+    expect(() => oke({ name: "t", autoBoot: false })).not.toThrow();
+  });
+
+  test("two differently-named flows on signal.live do not fail OKE1071", () => {
+    const status = signal.live("order-status", { optional: true });
+    on(status, flow("orders.mirrorA", { do: () => ({ a: true }) }));
+    on(status, flow("orders.mirrorB", { do: () => ({ b: true }) }));
+    expect(() => oke({ name: "t", autoBoot: false })).not.toThrow();
+  });
+
+  test("a single flow bound to once boots with zero warnings", () => {
+    const warnings: string[] = [];
+    const orig = console.warn;
+    console.warn = (...args: unknown[]) => {
+      warnings.push(args.map(String).join(" "));
+    };
+    try {
+      const emailTask = signal.once("tasks.email");
+      on(emailTask, flow("workers.email", { do: () => ({ ok: true }) }));
+      expect(() => oke({ name: "t", autoBoot: false })).not.toThrow();
+      expect(warnings).toEqual([]);
+    } finally {
+      console.warn = orig;
+    }
+  });
+});

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,