okengine 0.10.1 → 0.10.2

package/src/kernel/flow.test.ts

@@ -11,8 +11,7 @@ beforeEach(() => {
 
 describe("flow — one species", () => {
   test("flow() returns a branded FlowDef", () => {
-    const f = flow({
-      name: "ping",
+    const f = flow("ping", {
       do: () => ({ ok: true }),
     });
     expect(isFlow(f)).toBe(true);
@@ -22,7 +21,7 @@ describe("flow — one species", () => {
   });
 
   test("on() returns the same flow object and records the trigger", () => {
-    const f = flow({ name: "create", do: () => 1 });
+    const f = flow("create", { do: () => 1 });
     const bound = on(http.post("/notes"), f);
     // Same runtime object; trigger stamp is type-only so identities differ at the type level.
     expect(bound as object).toBe(f);
@@ -33,8 +32,7 @@ describe("flow — one species", () => {
 
   test("the same flow object is reachable from HTTP and signal triggers", async () => {
     const calls: string[] = [];
-    const shared = flow({
-      name: "shared.work",
+    const shared = flow("shared.work", {
       do: (input: { n: number }) => {
         calls.push(`n=${input.n}`);
         return { n: input.n * 2 };
@@ -65,8 +63,7 @@ describe("five trigger kinds", () => {
 
     const httpFlow = on(
       http.get("/:code"),
-      flow({
-        name: "t.http",
+      flow("t.http", {
         do: ({ code }: { code: string }) => {
           seen.push(`http:${code}`);
           return { code };
@@ -76,8 +73,7 @@ describe("five trigger kinds", () => {
 
     on(
       every("1h"),
-      flow({
-        name: "t.every",
+      flow("t.every", {
         do: () => {
           seen.push("every");
         },
@@ -86,8 +82,7 @@ describe("five trigger kinds", () => {
 
     on(
       { name: "link-clicked", delivery: "once" },
-      flow({
-        name: "t.signal",
+      flow("t.signal", {
         do: ({ code }: { code: string }) => {
           seen.push(`signal:${code}`);
         },
@@ -96,8 +91,7 @@ describe("five trigger kinds", () => {
 
     on(
       table("orders").changed("status"),
-      flow({
-        name: "t.cdc",
+      flow("t.cdc", {
         do: (p: { before: { status: string }; after: { status: string } }) => {
           seen.push(`cdc:${p.before.status}->${p.after.status}`);
         },
@@ -106,8 +100,7 @@ describe("five trigger kinds", () => {
 
     on(
       internal,
-      flow({
-        name: "t.internal",
+      flow("t.internal", {
         do: () => {
           seen.push("internal");
           return { ok: true };

package/src/kernel/flow.ts

@@ -38,10 +38,6 @@ export type FlowHandler<I = unknown, O = unknown> = (
 
 /** Options for {@link flow}. */
 export interface FlowOptions<I = unknown, O = unknown, E extends FlowErrorMap = FlowErrorMap> {
-  /** Optional stable name (used by `fx.call` and the Manifest). */
-  readonly name?: string;
-  /** Optional unit scope for unit-level hooks. */
-  readonly unit?: string;
   /** Input schema (Standard Schema when present). */
   readonly in?: SchemaInput;
   /** Output schema (Standard Schema when present). */
@@ -155,7 +151,7 @@ export interface FlowDef<
   readonly [triggerPhantom]?: T;
   /** Stable name (auto-assigned when omitted). */
   readonly name: string;
-  /** Optional unit scope. */
+  /** Unit scope — derived from `name`'s first dot segment (e.g. `"auth.refresh"` → `"auth"`). */
   readonly unit: string | undefined;
   /** Input schema. */
   readonly in: SchemaInput | undefined;
@@ -231,28 +227,30 @@ export interface FlowDef<
 /** Unique brand symbol for {@link FlowDef}. */
 export const flowBrand: unique symbol = Symbol("oke.flow");
 
-let flowSeq = 0;
-
 /**
  * Define a Flow — the one species of backend behavior.
  *
  * Input / output types are inferred from Standard Schema `in` / `out` when
  * present; otherwise from the `do` handler signature.
  *
+ * @param name - Stable name (used by `fx.call` and the Manifest)
  * @param options - Contract and handler
  */
 export function flow<Opts extends FlowOptions<any, any, any>>(
-  options: Opts,
+  name: string,
+  options: Opts & { readonly name?: never },
 ): FlowDef<InferFlowIn<Opts>, InferFlowOut<Opts>, InferFlowErrors<Opts>> {
-  const name = options.name ?? `flow_${++flowSeq}`;
   const triggers: Trigger[] = [];
   const hooks: Partial<Record<HookStage, HookFn[]>> = {};
   const pendingPlugins: PluginDef[] = [];
 
+  const dot = name.indexOf(".");
+  const unit = dot > 0 ? name.slice(0, dot) : undefined;
+
   const def: FlowDef<InferFlowIn<Opts>, InferFlowOut<Opts>, InferFlowErrors<Opts>> = {
     [flowBrand]: true,
     name,
-    unit: options.unit,
+    unit,
     in: options.in,
     out: options.out,
     errors: (options.errors ?? undefined) as InferFlowErrors<Opts> | undefined,
@@ -316,10 +314,10 @@ export function isFlow(value: unknown): value is AnyFlowDef {
 }
 
 /**
- * Reset the auto-name sequence (tests only).
+ * No-op. `name` is a required positional argument now, so there is no
+ * auto-name sequence left to reset — kept so existing test `beforeEach`
+ * blocks don't need touching.
  *
  * @internal
  */
-export function resetFlowSeq(): void {
-  flowSeq = 0;
-}
+export function resetFlowSeq(): void {}

package/src/kernel/hook-timing.test.ts

@@ -27,7 +27,7 @@ describe("hook timing", () => {
     });
     const ctx: InvocationContext = {
       trigger: { kind: "internal" },
-      flow: flow({ name: "t", do: () => ({ ok: true }) }),
+      flow: flow("t", { do: () => ({ ok: true }) }),
       input: undefined,
       params: {},
       state: {},
@@ -56,7 +56,7 @@ describe("hook timing", () => {
     const hooks = registry.hooksAt("app", undefined, "x");
     const ctx: InvocationContext = {
       trigger: { kind: "internal" },
-      flow: flow({ name: "x", do: () => undefined }),
+      flow: flow("x", { do: () => undefined }),
       input: undefined,
       params: {},
       state: {},

package/src/kernel/hooks.test.ts

@@ -40,7 +40,7 @@ describe("hooks — order and composition", () => {
       void fn(
         {
           trigger: { kind: "internal" },
-          flow: flow({ name: "x", do: () => undefined }),
+          flow: flow("x", { do: () => undefined }),
           input: undefined,
           params: {},
           state: {},
@@ -57,9 +57,7 @@ describe("hooks — order and composition", () => {
   test("pipeline fires stages in order around the handler", async () => {
     const order: string[] = [];
 
-    const f = flow({
-      name: "ordered",
-      unit: "links",
+    const f = flow("links.ordered", {
       do: () => {
         order.push("handler");
         return { ok: true };
@@ -119,8 +117,7 @@ describe("hooks — order and composition", () => {
 
     on(
       http.get("/sc"),
-      flow({
-        name: "sc",
+      flow("sc", {
         do: () => {
           order.push("handler");
           return { ok: true };
@@ -151,8 +148,7 @@ describe("hooks — order and composition", () => {
 
     on(
       http.get("/data"),
-      flow({
-        name: "data",
+      flow("data", {
         do: () => ({ ok: true }),
       }),
     );
@@ -184,8 +180,7 @@ describe("hooks — order and composition", () => {
 
     on(
       http.get("/fail"),
-      flow({
-        name: "fail-flow",
+      flow("fail-flow", {
         do: () => {
           order.push("handler");
         },

package/src/kernel/horizontal-child.ts

@@ -131,16 +131,13 @@ const storeRt = createStoreRuntime({
 });
 storeRt.register(db);
 
-const ping = flow({
-  name: "horizontal.ping",
+const ping = flow("horizontal.ping", {
   do: () => ({ ok: true as const, instanceId }),
 });
-const rate = flow({
-  name: "horizontal.rate",
+const rate = flow("horizontal.rate", {
   do: () => ({ ok: true as const, instanceId }),
 });
-const write = flow({
-  name: "horizontal.write",
+const write = flow("horizontal.write", {
   do: async (_input, fx) => {
     const id = crypto.randomUUID();
     await fx
@@ -155,15 +152,13 @@ const write = flow({
     return { id };
   },
 });
-const emit = flow({
-  name: "horizontal.emit",
+const emit = flow("horizontal.emit", {
   do: async (_input, fx) => {
     await fx.emit(SIG, { from: instanceId, at: Date.now() });
     return { emitted: true as const };
   },
 });
-const charge = flow({
-  name: "horizontal.charge",
+const charge = flow("horizontal.charge", {
   durable: true,
   do: async (_input, fx) => {
     await fx.step("create-intent", async () => {

package/src/kernel/journal-boot.test.ts

@@ -73,8 +73,7 @@ async function waitFor(cond: () => Promise<boolean>, timeoutMs = 5_000): Promise
 
 /** Flow whose step 2 blocks once per execution; the test unblocks survivors. */
 function blockingFlow(step1Calls: string[], blockers: Array<() => void>): Binding {
-  const charge = flow({
-    name: "charge",
+  const charge = flow("charge", {
     durable: true,
     do: async (_input, fx) => {
       await fx.step("create-intent", () => {
@@ -96,8 +95,7 @@ function blockingFlow(step1Calls: string[], blockers: Array<() => void>): Bindin
 
 /** Flow that sleeps `wake`, then records one confirm execution. */
 function sleeperBinding(wake: string, confirms: string[]): Binding {
-  const sleeper = flow({
-    name: "sleeper",
+  const sleeper = flow("sleeper", {
     durable: true,
     do: async (_input, fx) => {
       await fx.step("create-intent", () => ({ id: "pi_1" }));

package/src/kernel/pipeline.test.ts

@@ -72,8 +72,7 @@ describe("pipeline — Unauthorized for anonymous", () => {
 
     on(
       http.post("/orders").gate(member),
-      flow({
-        name: "orders.create",
+      flow("orders.create", {
         in: z.object({ sku: z.string() }),
         out: z.object({ id: z.string() }),
         do: (_input, fx) => ({ id: fx.id() }),
@@ -111,8 +110,7 @@ describe("pipeline — Unauthorized for anonymous", () => {
 
     on(
       http.post("/orders").gate(member, canOrder),
-      flow({
-        name: "orders.create2",
+      flow("orders.create2", {
         in: z.object({ sku: z.string() }),
         do: () => ({ ok: true }),
       }),
@@ -150,8 +148,7 @@ describe("pipeline — evaluated gates on the run", () => {
 
     on(
       http.post("/orders").gate(member, canOrder),
-      flow({
-        name: "orders.create3",
+      flow("orders.create3", {
         in: z.object({ sku: z.string() }),
         do: () => ({ ok: true }),
       }),
@@ -203,8 +200,7 @@ describe("pipeline — Bearer cryptographic verification", () => {
 
     on(
       http.get("/secure").gate(member),
-      flow({
-        name: "secure.get",
+      flow("secure.get", {
         do: () => ({ ok: true }),
       }),
     );
@@ -242,8 +238,7 @@ describe("pipeline — Bearer cryptographic verification", () => {
 
     on(
       http.get("/secure").gate(member),
-      flow({
-        name: "secure.get2",
+      flow("secure.get2", {
         do: () => ({ ok: true }),
       }),
     );
@@ -313,8 +308,7 @@ describe("pipeline — Bearer cryptographic verification", () => {
 
     on(
       http.post("/orders").gate(member),
-      flow({
-        name: "orders.inject",
+      flow("orders.inject", {
         in: z.object({ sku: z.string() }),
         do: () => ({ ok: true }),
       }),

package/src/kernel/plugin/capabilities.test.ts

@@ -25,7 +25,7 @@ describe("plugin capability capture", () => {
       .table("audit_events")
       .driver("postgres")
       .image("store.sql", "postgres:16")
-      .flow(flow({ name: "audit.flush", do: () => undefined }))
+      .flow(flow("audit.flush", { do: () => undefined }))
       .client("audit", { subscribe: true });
 
     const { api, snapshot } = createRecordingApi({

package/src/kernel/plugin/decorate.test.ts

@@ -27,8 +27,7 @@ describe("plugin decorate — types and runtime", () => {
     let seen: unknown;
     on(
       http.get("/x"),
-      flow({
-        name: "x",
+      flow("x", {
         do: (_input, _fx) => {
           return { ok: true };
         },
@@ -75,9 +74,7 @@ describe("plugin decorate — types and runtime", () => {
 
     on(
       http.get("/orders"),
-      flow({
-        name: "orders.list",
-        unit: "orders",
+      flow("orders.list", {
         do: () => ({}),
       }).hook("beforeHandle", (ctx) => {
         seen.orders = ctx.decorations.flag;
@@ -85,9 +82,7 @@ describe("plugin decorate — types and runtime", () => {
     );
     on(
       http.get("/payments"),
-      flow({
-        name: "payments.list",
-        unit: "payments",
+      flow("payments.list", {
         do: () => ({}),
       }).hook("beforeHandle", (ctx) => {
         seen.payments = ctx.decorations.flag;

package/src/kernel/plugin/scoping.test.ts

@@ -20,18 +20,14 @@ describe("plugin scoping — attachment point is the scope", () => {
   test("unit-scoped plugin hook does not fire for another unit's flows", async () => {
     const fired: string[] = [];
 
-    const ordersFlow = flow({
-      name: "orders.create",
-      unit: "orders",
+    const ordersFlow = flow("orders.create", {
       do: () => {
         fired.push("orders:handler");
         return { ok: true };
       },
     });
 
-    const paymentsFlow = flow({
-      name: "payments.charge",
-      unit: "payments",
+    const paymentsFlow = flow("payments.charge", {
       do: () => {
         fired.push("payments:handler");
         return { ok: true };
@@ -62,9 +58,7 @@ describe("plugin scoping — attachment point is the scope", () => {
 
     on(
       http.get("/a"),
-      flow({
-        name: "a",
-        unit: "alpha",
+      flow("alpha.a", {
         do: () => {
           fired.push("a");
           return {};
@@ -73,9 +67,7 @@ describe("plugin scoping — attachment point is the scope", () => {
     );
     on(
       http.get("/b"),
-      flow({
-        name: "b",
-        unit: "beta",
+      flow("beta.b", {
         do: () => {
           fired.push("b");
           return {};
@@ -98,8 +90,7 @@ describe("plugin scoping — attachment point is the scope", () => {
   test("flow-scoped plugin hook fires only for that flow", async () => {
     const fired: string[] = [];
 
-    const marked = flow({
-      name: "marked",
+    const marked = flow("marked", {
       do: () => {
         fired.push("marked");
         return {};
@@ -110,8 +101,7 @@ describe("plugin scoping — attachment point is the scope", () => {
       }),
     );
 
-    const plain = flow({
-      name: "plain",
+    const plain = flow("plain", {
       do: () => {
         fired.push("plain");
         return {};

package/src/kernel/plugin-elements.test.ts

@@ -32,7 +32,7 @@ describe("plugin element contributions", () => {
       .table("otp_codes")
       .needs("store.sql");
 
-    on(http.get("/ok").gate(gate.public), flow({ name: "ok", do: () => ({ ok: true }) }));
+    on(http.get("/ok").gate(gate.public), flow("ok", { do: () => ({ ok: true }) }));
 
     const app = oke({
       name: "plugin-elements",

package/src/kernel/plugin-needs.test.ts

@@ -75,7 +75,7 @@ describe("plugin .needs() resolution", () => {
   test("boot fails when plugin needs missing peer plugin", async () => {
     resetBindings();
     resetFlowSeq();
-    on(http.get("/x").gate(gate.public), flow({ name: "x", do: () => ({ ok: true }) }));
+    on(http.get("/x").gate(gate.public), flow("x", { do: () => ({ ok: true }) }));
     const dependent = plugin("needs-auth", { version: "0.0.1" }).needs("auth");
     const app = oke({ name: "needs-boot", gate: { policies: [gate.public] } }).plug(dependent);
     await expect(app.boot({ env: "test" })).rejects.toThrow(PluginNeedsError);

package/src/kernel/ready.test.ts

@@ -33,8 +33,7 @@ describe("GET /_/ready", () => {
   test("orphan_scan then ready when durable journal is bound", async () => {
     const journalStore = createMemoryJournalStore();
     expect(hasJournalLease(journalStore)).toBe(true);
-    const charge = flow({
-      name: "charge",
+    const charge = flow("charge", {
       durable: true,
       do: () => ({ ok: true }),
     });

package/src/kernel/registry-isolation.test.ts

@@ -21,11 +21,11 @@ afterEach(() => {
 
 describe("registry isolation", () => {
   test("consume (default): App B does not serve App A routes", async () => {
-    on(http.get("/a"), flow({ name: "app-a.ping", do: () => "a" }));
+    on(http.get("/a"), flow("app-a.ping", { do: () => "a" }));
     const appA = oke({ autoBoot: false, name: "app-a" });
 
     // No resetBindings() between the apps — the pre-fix leak scenario.
-    on(http.get("/b"), flow({ name: "app-b.ping", do: () => "b" }));
+    on(http.get("/b"), flow("app-b.ping", { do: () => "b" }));
     const appB = oke({ autoBoot: false, name: "app-b" });
 
     // Pre-fix this was 200: App B adopted App A's leftover binding.
@@ -45,7 +45,7 @@ describe("registry isolation", () => {
   });
 
   test("keep: today's behavior — registry survives construction", async () => {
-    on(http.get("/a"), flow({ name: "kept.ping", do: () => "a" }));
+    on(http.get("/a"), flow("kept.ping", { do: () => "a" }));
     oke({ autoBoot: false, name: "app-a", registry: "keep" });
     expect(listBindings()).toHaveLength(1);
 
@@ -54,11 +54,11 @@ describe("registry isolation", () => {
   });
 
   test("ignore: only options.bindings are served", async () => {
-    on(http.get("/stray"), flow({ name: "stray.ping", do: () => "stray" }));
+    on(http.get("/stray"), flow("stray.ping", { do: () => "stray" }));
 
     const onlyB: Binding = {
       trigger: http.get("/b"),
-      flow: flow({ name: "only-b.ping", do: () => "b" }),
+      flow: flow("only-b.ping", { do: () => "b" }),
     };
     const app = oke({ autoBoot: false, name: "app-b", registry: "ignore", bindings: [onlyB] });
 

package/src/kernel/triggers.ts

@@ -323,7 +323,7 @@ export function table(name: string, store?: string): TableHandle {
 
 /**
  * Explicit internal / call-only trigger.
- * Prefer an untriggered `flow({…})` when no trigger value is needed.
+ * Prefer an untriggered `flow(name, {…})` when no trigger value is needed.
  */
 export const internal: InternalTrigger = { kind: "internal" };
 

package/src/plugins/anonymous.ts

@@ -30,9 +30,7 @@ export interface AnonymousPluginOptions extends AuthMethodOptions {
 export function anonymous(opts: AnonymousPluginOptions = {}): PluginDef {
   const runtime = createMethodRuntime(opts);
 
-  const signIn = flow({
-    name: "auth.signInAnonymous",
-    unit: "auth",
+  const signIn = flow("auth.signInAnonymous", {
     plane: "user",
     out: SessionTokensOut,
     errors: { AuthFailed, AuthRateLimited },

package/src/plugins/compression.test.ts

@@ -37,7 +37,7 @@ describe("acceptsGzip", () => {
 
 describe("compression plugin", () => {
   test("gzips a large JSON body when the client accepts gzip", async () => {
-    on(http.get("/big"), flow({ name: "big.get", do: bigPayload }));
+    on(http.get("/big"), flow("big.get", { do: bigPayload }));
     const app = oke({ autoBoot: false, name: "zip" }).plug(compression());
 
     const res = await app.fetch(
@@ -58,7 +58,7 @@ describe("compression plugin", () => {
   });
 
   test("passes through untouched without Accept-Encoding: gzip", async () => {
-    on(http.get("/big"), flow({ name: "big.get", do: bigPayload }));
+    on(http.get("/big"), flow("big.get", { do: bigPayload }));
     const app = oke({ autoBoot: false, name: "zip-plain" }).plug(compression());
 
     const res = await app.fetch(new Request("http://localhost/big"));
@@ -69,7 +69,7 @@ describe("compression plugin", () => {
   });
 
   test("skips bodies under minSize", async () => {
-    on(http.get("/small"), flow({ name: "small.get", do: () => ({ ok: true }) }));
+    on(http.get("/small"), flow("small.get", { do: () => ({ ok: true }) }));
     const app = oke({ autoBoot: false, name: "zip-small" }).plug(compression());
 
     const res = await app.fetch(
@@ -80,7 +80,7 @@ describe("compression plugin", () => {
   });
 
   test("minSize: 0 compresses even tiny bodies", async () => {
-    on(http.get("/small"), flow({ name: "small.get", do: () => ({ ok: true }) }));
+    on(http.get("/small"), flow("small.get", { do: () => ({ ok: true }) }));
     const app = oke({ autoBoot: false, name: "zip-zero" }).plug(compression({ minSize: 0 }));
 
     const res = await app.fetch(
@@ -93,8 +93,7 @@ describe("compression plugin", () => {
   test("skips non-matching content types and no-transform responses", async () => {
     on(
       http.get("/img"),
-      flow({
-        name: "img.get",
+      flow("img.get", {
         do: () =>
           new Response(new Uint8Array(4096), {
             headers: { "content-type": "image/png" },
@@ -103,8 +102,7 @@ describe("compression plugin", () => {
     );
     on(
       http.get("/nt"),
-      flow({
-        name: "nt.get",
+      flow("nt.get", {
         do: () =>
           Response.json(
             { data: bigPayload(), error: null },

package/src/plugins/config-source.test.ts

@@ -155,7 +155,7 @@ describe("configSource — plugin wiring", () => {
       kv: cfg,
     });
 
-    on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
+    on(http.get("/x"), flow("x.get", { do: () => ({ ok: true }) }));
     const app = oke({ autoBoot: false, name: "cfg-live" }).plug(maintenanceMode(source));
 
     expect((await app.fetch(new Request("http://localhost/x"))).status).toBe(200);

package/src/plugins/config-source.ts

@@ -116,8 +116,7 @@ export function configSource<T extends object>(options: ConfigSourceOptions<T>):
       }
       if (options.db !== undefined) reads.push(options.db.store.ref);
 
-      return flow({
-        name: `${options.plugin}.config-sync`,
+      return flow(`${options.plugin}.config-sync`, {
         effects: { reads, writes },
         do: async (_input, fx) => {
           if (options.kv !== undefined) {