okengine 0.19.2 → 0.19.4

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

@@ -1,5 +1,5 @@
 /**
- * Nameless Flow inherits Signal/Clock trigger names; duplicates fail OKE1070.
+ * Nameless Signal/Clock consumers fail OKE1072; duplicate names fail OKE1070.
  */
 
 import { beforeEach, describe, expect, test } from "bun:test";
@@ -7,7 +7,7 @@ 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_NAME_DUPLICATE, FLOW_UNNAMED } from "./errors-flow-name.ts";
 import { flow, resetFlowSeq } from "./flow.ts";
 import { on, resetBindings } from "./on.ts";
 import { stampFlowName } from "./stamp-http.ts";
@@ -20,28 +20,28 @@ beforeEach(() => {
   resetClocks();
 });
 
-describe("on() — Signal/Clock name inheritance", () => {
-  test("nameless flow inherits inline signal.once name", () => {
+describe("on() — Signal/Clock names stay explicit or tree-stamped", () => {
+  test("nameless flow does not inherit an inline signal.once name", () => {
     const bound = on(
       signal.once("link-clicked"),
       flow({
         do: () => ({ ok: true }),
       }),
     );
-    expect(bound.name).toBe("link-clicked");
+    expect(bound.name).toBe("");
   });
 
-  test("nameless flow inherits clock.every name", () => {
+  test("nameless flow does not inherit a clock.every name", () => {
     const bound = on(
       clock.every("cleanup", "10m"),
       flow({
         do: () => ({ ok: true }),
       }),
     );
-    expect(bound.name).toBe("cleanup");
+    expect(bound.name).toBe("");
   });
 
-  test("explicit flow name wins over the trigger name", () => {
+  test("explicit flow name is independent of the trigger name", () => {
     const bound = on(
       signal.once("order-placed"),
       flow("orders.fulfill", { do: () => ({ ok: true }) }),
@@ -59,40 +59,88 @@ describe("on() — Signal/Clock name inheritance", () => {
     expect(bound.name).toBe("");
   });
 
-  test("file-tree stamp overwrites a trigger-inherited name", () => {
+  test("file-tree stamp fills a nameless Signal consumer", () => {
     const bound = on(
       signal.once("note-created"),
       flow({
         do: () => ({ ok: true }),
       }),
     );
-    expect(bound.name).toBe("note-created");
+    expect(bound.name).toBe("");
     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 }) }));
+describe("oke — FLOW_UNNAMED OKE1072", () => {
+  test("nameless flow({ do }) on signal.once fails OKE1072", () => {
+    on(
+      signal.once("link-clicked"),
+      flow({
+        do: () => ({ ok: true }),
+      }),
+    );
     try {
       oke({ name: "t", autoBoot: false });
-      expect.unreachable("oke() should throw OKE1070");
+      expect.unreachable("oke() should throw OKE1072");
     } 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/);
+      expect(okeErr.code).toBe(1072);
+      expect(okeErr.code).toBe(FLOW_UNNAMED.code);
+      expect(okeErr.message).toMatch(/OKE1072/);
+      expect(okeErr.causeText).toContain("signal");
+      expect(okeErr.causeText).toContain("link-clicked");
+      expect(okeErr.message).toContain("src/flows/<unit>/");
+      expect(okeErr.message).toContain("export const");
     }
   });
 
+  test("nameless flow({ do }) on signal.broadcast fails OKE1072", () => {
+    on(
+      signal.broadcast("catalog.changed"),
+      flow({
+        do: () => ({ ok: true }),
+      }),
+    );
+    expect(() => oke({ name: "t", autoBoot: false })).toThrow(/OKE1072/);
+  });
+
+  test("nameless flow({ do }) on signal.live fails OKE1072", () => {
+    on(
+      signal.live("order-status", { optional: true }),
+      flow({
+        do: () => ({ ok: true }),
+      }),
+    );
+    expect(() => oke({ name: "t", autoBoot: false })).toThrow(/OKE1072/);
+  });
+
+  test("nameless flow({ do }) on clock.every fails OKE1072", () => {
+    on(
+      clock.every("cleanup", "10m"),
+      flow({
+        do: () => ({ ok: true }),
+      }),
+    );
+    expect(() => oke({ name: "t", autoBoot: false })).toThrow(/OKE1072/);
+  });
+});
+
+describe("oke — FLOW_NAME_DUPLICATE 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/);
+    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("the same flow object bound twice is not a duplicate", () => {
@@ -101,4 +149,41 @@ describe("oke — FLOW_NAME_DUPLICATE OKE1070", () => {
     on(signal.once("order-placed"), shared);
     expect(() => oke({ name: "t", autoBoot: false })).not.toThrow();
   });
+
+  test("two differently-named flows on the same clock do not fail OKE1070", () => {
+    const tick = clock.every("metrics.tick", "1h");
+    on(tick, flow("ops.sweep", { do: () => 1 }));
+    on(tick, flow("ops.report", { do: () => 2 }));
+    expect(() => oke({ name: "t", autoBoot: false })).not.toThrow();
+  });
+
+  test("docs Clock Inline (explicit name) boots", () => {
+    on(
+      clock.every("health.pingExternal", "30s"),
+      flow("health.pingExternal", {
+        plane: "operator",
+        do: async () => ({ ok: true }),
+      }),
+    );
+    expect(() => oke({ name: "t", autoBoot: false })).not.toThrow();
+  });
+
+  test("docs Clock named-export (shared schedule) boots", () => {
+    const tickClock = clock.every("metrics.tick", "1h");
+    on(
+      tickClock,
+      flow("ops.sweep", {
+        plane: "operator",
+        do: async () => ({ ok: true }),
+      }),
+    );
+    on(
+      tickClock,
+      flow("ops.report", {
+        plane: "operator",
+        do: async () => ({ ok: true }),
+      }),
+    );
+    expect(() => oke({ name: "t", autoBoot: false })).not.toThrow();
+  });
 });

package/src/kernel/flow.ts

@@ -240,9 +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()`. 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.
+ * generator, {@link unit}, or `.adopt()`. Explicit `flow("notes.get", {…})`
+ * still wins. Signal / Clock consumers with no explicit or tree-derived name
+ * fail **OKE1072** at `oke()` / extract — they do not inherit the trigger name.
  *
  * @param options - Runtime options and handler (name stamped later)
  */

package/src/kernel/on.ts

@@ -203,11 +203,6 @@ 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/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

@@ -52,13 +52,14 @@ describe("stampFlowName", () => {
     expect(f.name).toBe("notes.get");
   });
 
-  test("file-tree stamp overwrites a trigger-inherited name", () => {
+  test("file-tree stamp fills a nameless Signal consumer", () => {
     const bound = on(
       signal.once("note-created"),
       flow({
         do: () => ({ ok: true }),
       }),
     );
+    expect(bound.name).toBe("");
     stampFlowName(bound, "notes.onCreated");
     expect(bound.name).toBe("notes.onCreated");
   });

package/src/kernel/stamp-http.ts

@@ -39,21 +39,20 @@ export function stampHttpPath<F extends AnyFlowDef, P extends string>(
 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.
+ * True when a Flow name is still a placeholder: empty or synthetic `flow_*`.
+ * 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;
+export function isUnsetFlowName(flow: { readonly name: string }): boolean {
+  return !flow.name || flow.name.startsWith("flow_");
 }
 
 /**
- * Stamp `unit.export` onto a nameless (or `flow_*` / trigger-inherited) Flow.
+ * Stamp `unit.export` onto a nameless (or `flow_*`) Flow.
  *
  * Explicit `flow("notes.get")` wins. Fills `unit` when missing.
  *
@@ -65,7 +64,6 @@ export function stampFlowName<F extends AnyFlowDef>(flow: F, name: string): F {
   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

@@ -42,8 +42,7 @@ export function unit<const T extends Record<string, AnyFlowDef>>(
   for (const [exportName, flowDef] of Object.entries(flows)) {
     const f = flowDef as FlowDef;
     if (isUnsetFlowName(f)) {
-      (f as { name: string; $n?: boolean }).name = `${name}.${exportName}`;
-      (f as { $n?: boolean }).$n = false;
+      (f as { name: string }).name = `${name}.${exportName}`;
     }
     if (!f.unit) {
       (f as { unit: string }).unit = name;