okengine 0.22.0 → 0.23.1

package/src/compiler/decisions.extract.test.ts

@@ -0,0 +1,164 @@
+/**
+ * Decision extraction: exclusive modes, and review cannot sit on HTTP.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { extractFromSources } from "./extract.ts";
+
+const header = `const triage = ai.decision("triage", {\n`;
+
+describe("ai.decision extract", () => {
+  test("review and abstain together fail to compile", async () => {
+    await expect(
+      extractFromSources({
+        "src/flows/run.ts": `${header}  review: "ops",\n  onUncertain: "abstain",\n  ask: { team: ai.choice("which", { a: "A" }) },\n});\n`,
+      }),
+    ).rejects.toThrow(/exactly one of review/);
+  });
+
+  test("an HTTP trigger that reviews fails to compile", async () => {
+    await expect(
+      extractFromSources({
+        "src/flows/run.ts": `
+          const triage = ai.decision("triage", {
+            review: "ops",
+            ask: { team: ai.choice("which", { a: "A" }) },
+          });
+          on(http.post("/t"), flow("run", {
+            durable: true,
+            do: async (input, fx) => fx.decide(triage, input),
+          }));
+        `,
+      }),
+    ).rejects.toThrow(/fx\.emit/);
+  });
+
+  test("choice, score, and duplicate names fail at compile time", async () => {
+    const many = Array.from({ length: 255 }, (_, i) => `o${i}: "x"`).join(", ");
+    await expect(
+      extractFromSources({
+        "src/flows/run.ts": `${header}  onUncertain: "abstain",\n  ask: { team: ai.choice("which", { ${many} }) },\n});\n`,
+      }),
+    ).rejects.toThrow(/max 254/);
+    await expect(
+      extractFromSources({
+        "src/flows/run.ts": `${header}  onUncertain: "abstain",\n  ask: { team: ai.choice("which", { none_of_these: null }) },\n});\n`,
+      }),
+    ).rejects.toThrow(/none_of_these/);
+    await expect(
+      extractFromSources({
+        "src/flows/run.ts": `${header}  onUncertain: "abstain",\n  ask: { rank: ai.score("rank", ["only"]) },\n});\n`,
+      }),
+    ).rejects.toThrow(/2–10 levels/);
+    await expect(
+      extractFromSources({
+        "src/flows/a.ts": `${header}  onUncertain: "abstain",\n  ask: { team: ai.choice("which", { a: "A", b: "B" }) },\n});\n`,
+        "src/flows/b.ts": `${header}  onUncertain: "abstain",\n  ask: { team: ai.choice("which", { a: "A", b: "B" }) },\n});\n`,
+      }),
+    ).rejects.toThrow(/duplicate decision name/);
+  });
+
+  test("review records the gate name", async () => {
+    const manifest = await extractFromSources({
+      "src/flows/run.ts": `
+        const ops = gate.policy("ops", () => true);
+        const triage = ai.decision("triage", {
+          review: ops,
+          ask: { team: ai.choice("which", { a: "A", b: "B" }) },
+        });
+        on(signal.once("job"), flow("run", {
+          durable: true,
+          do: async (input, fx) => fx.decide(triage, input),
+        }));
+      `,
+    });
+    expect(manifest.ai?.decisions?.triage?.review).toBe("ops");
+  });
+
+  test("review resolves a variable to the gate's declared name", async () => {
+    const manifest = await extractFromSources({
+      "src/flows/run.ts": `
+        const someVar = gate.policy("ops", () => true);
+        const triage = ai.decision("triage", {
+          review: someVar,
+          ask: { team: ai.choice("which", { a: "A", b: "B" }) },
+        });
+        on(signal.once("job"), flow("run", {
+          durable: true,
+          do: async (input, fx) => fx.decide(triage, input),
+        }));
+      `,
+    });
+    expect(manifest.ai?.decisions?.triage?.review).toBe("ops");
+  });
+
+  test("autonomy and evals survive extraction", async () => {
+    const manifest = await extractFromSources({
+      "src/flows/run.ts": `
+        const triage = ai.decision("triage", {
+          onUncertain: "abstain",
+          evals: "evals/triage.jsonl",
+          autonomy: { maxError: 0.05, audit: 0.1, risk: 0.1 },
+          ask: { team: ai.choice("which", { a: "A", b: "B" }) },
+        });
+      `,
+    });
+    expect(manifest.ai?.decisions?.triage?.evals).toBe("evals/triage.jsonl");
+    expect(manifest.ai?.decisions?.triage?.autonomy).toEqual({
+      maxError: 0.05,
+      audit: 0.1,
+      risk: 0.1,
+    });
+  });
+
+  test("choice options passed through a variable fail to compile", async () => {
+    await expect(
+      extractFromSources({
+        "src/flows/run.ts": `
+          const options = { a: "A", b: "B" };
+          ai.decision("triage", {
+            onUncertain: "abstain",
+            ask: { team: ai.choice("which", options) },
+          });
+        `,
+      }),
+    ).rejects.toThrow(/object literal/);
+  });
+
+  test("score levels and a whole question resolve a same-file const", async () => {
+    const manifest = await extractFromSources({
+      "src/flows/run.ts": `
+        const levels = ["low", "high"];
+        const team = ai.choice("which", { a: "A", b: "B" });
+        ai.decision("triage", {
+          onUncertain: "abstain",
+          ask: { team, rank: ai.score("rank", levels) },
+        });
+      `,
+    });
+    expect(manifest.ai?.decisions?.triage?.questions).toEqual(["team", "rank"]);
+  });
+
+  test("an unresolved score or question fails to compile", async () => {
+    await expect(
+      extractFromSources({
+        "src/flows/run.ts": `
+          ai.decision("triage", {
+            onUncertain: "abstain",
+            ask: { rank: ai.score("rank", missing) },
+          });
+        `,
+      }),
+    ).rejects.toThrow(/same-file const/);
+    await expect(
+      extractFromSources({
+        "src/flows/run.ts": `
+          ai.decision("triage", {
+            onUncertain: "abstain",
+            ask: { team: missingQuestion },
+          });
+        `,
+      }),
+    ).rejects.toThrow(/not a same-file const/);
+  });
+});

package/src/compiler/effects-fetch.test.ts

@@ -3,6 +3,7 @@
  */
 
 import { describe, expect, test } from "bun:test";
+import { extractFromSources } from "./extract.ts";
 import { inferEffects, type AstNode, type InferBinding } from "./effects-infer.ts";
 
 function parseDo(src: string): AstNode {
@@ -39,5 +40,81 @@ describe("inferEffects — fx.fetch → effects.fetches", () => {
     expect(inferred.effects.fetches).toEqual(["api.stripe.com"]);
     expect(inferred.effects.calls).toBeUndefined();
     expect(inferred.effects.sends).toBeUndefined();
+    expect(inferred.bareIrreversible).toEqual(["fetch"]);
+  });
+
+  test("fx.fetch inside fx.step is not a bare irreversible call", () => {
+    const stepBody = {
+      type: "ArrowFunctionExpression",
+      params: [],
+      body: {
+        type: "BlockStatement",
+        body: [
+          {
+            type: "ExpressionStatement",
+            expression: {
+              type: "CallExpression",
+              callee: {
+                type: "MemberExpression",
+                object: { type: "Identifier", name: "fx" },
+                property: { type: "Identifier", name: "fetch" },
+                computed: false,
+              },
+              arguments: [{ type: "Literal", value: "https://example.com/data" }],
+            },
+          },
+        ],
+      },
+    };
+    const inferred = inferEffects({
+      doNode: {
+        type: "ArrowFunctionExpression",
+        params: [
+          { type: "Identifier", name: "_input" },
+          { type: "Identifier", name: "fx" },
+        ],
+        body: {
+          type: "BlockStatement",
+          body: [
+            {
+              type: "ExpressionStatement",
+              expression: {
+                type: "CallExpression",
+                callee: {
+                  type: "MemberExpression",
+                  object: { type: "Identifier", name: "fx" },
+                  property: { type: "Identifier", name: "step" },
+                  computed: false,
+                },
+                arguments: [{ type: "Literal", value: "load" }, stepBody],
+              },
+            },
+          ],
+        },
+      } as AstNode,
+      bindings: new Map<string, InferBinding>(),
+      hasExplicitEffects: false,
+    });
+    expect(inferred.bareIrreversible).toEqual([]);
+    expect(inferred.steps).toEqual(["load"]);
+    expect(inferred.effects.fetches).toEqual(["example.com"]);
+  });
+});
+
+describe("extract — durable fx.fetch outside fx.step", () => {
+  test("OKE1901 when a durable flow calls fx.fetch directly", async () => {
+    await expect(
+      extractFromSources({
+        "src/flows/load.ts": `
+import { flow, on, http } from "okengine";
+export const load = on(http.get("/load"), flow("load", {
+  durable: true,
+  do: async (_input, fx) => {
+    return fx.fetch("https://example.com/data");
+  },
+}));
+`,
+      }),
+    ).rejects.toThrow(/OKE1901/);
   });
 });

package/src/compiler/effects-infer.ts

@@ -57,10 +57,12 @@ export interface InferBinding {
     | "signal"
     | "clock"
     | "prompt"
+    | "agent"
     | "secret"
     | "template"
     | "flow"
     | "embed"
+    | "decision"
     | "table"
     | "mcp-server"
     | "mcp-tool"
@@ -71,6 +73,8 @@ export interface InferBinding {
   readonly facet?: "sql" | "kv" | "files" | "index";
   /** Prompt version when kind is `prompt`. */
   readonly version?: number;
+  /** Nested agent tools when kind is `agent`. */
+  readonly agentCalls?: readonly string[];
 }
 
 /** What a callee that is passed `fx` resolves to. */
@@ -106,6 +110,11 @@ export interface InferEffectsOptions {
    * never pass `fx` into another function.
    */
   readonly resolveCallee?: (callee: AstNode, file: string) => FxCalleeResolution;
+  /**
+   * Flow name of an imported handle in `file`. Absent when inference does
+   * not follow imports (unit tests).
+   */
+  readonly resolveFlowRef?: (localName: string, file: string) => string | undefined;
 }
 
 /** Result of effect inference for one flow body. */
@@ -125,6 +134,11 @@ export interface InferredEffects {
   readonly nondeterministic: boolean;
   /** True when the body references `fx.auth.userId`. */
   readonly readsUserId: boolean;
+  /**
+   * `fx.fetch` / `fx.send` calls that are not inside an `fx.step` callback.
+   * A `durable: true` flow must not call these directly.
+   */
+  readonly bareIrreversible: readonly ("fetch" | "send")[];
 }
 
 const READ_METHODS = new Set([
@@ -141,6 +155,10 @@ const READ_METHODS = new Set([
   "page",
   "search",
   "raw",
+  "innerJoin",
+  "leftJoin",
+  "rightJoin",
+  "fullJoin",
 ]);
 
 const WRITE_METHODS = new Set([
@@ -171,6 +189,10 @@ const TABLE_ARG_METHODS = new Set([
   "count",
   "page",
   "search",
+  "innerJoin",
+  "leftJoin",
+  "rightJoin",
+  "fullJoin",
 ]);
 
 /**
@@ -190,6 +212,7 @@ export function inferEffects(options: InferEffectsOptions): InferredEffects {
   const secrets = new Set<SecretRef>();
   const calls = new Set<FlowRef>();
   const fetches = new Set<FetchHostRef>();
+  const decides = new Set<string>();
   const steps: string[] = [];
   let usesRaw = false;
 
@@ -199,7 +222,8 @@ export function inferEffects(options: InferEffectsOptions): InferredEffects {
     name: "liveQuery" | "applySearchEmbedCdc";
     call: CallExpression;
   }> = [];
-  const chains = collectFxChains(options, opaque, userIdRoots, intrinsics);
+  const bareIrreversible = new Set<"fetch" | "send">();
+  const chains = collectFxChains(options, opaque, userIdRoots, intrinsics, bareIrreversible);
 
   for (const { call, chain } of chains) {
     if (chain.rootMethod === "raw") {
@@ -237,6 +261,17 @@ export function inferEffects(options: InferEffectsOptions): InferredEffects {
       continue;
     }
 
+    if (chain.rootMethod === "run" && call === chain.rootCall) {
+      const binding = resolveBinding(call.arguments[0], options.bindings);
+      const name =
+        stringArg(call.arguments[0]) ?? (binding?.kind === "agent" ? binding.ref : undefined);
+      if (name) asks.add(name);
+      if (binding?.kind === "agent") {
+        for (const child of binding.agentCalls ?? []) calls.add(child);
+      }
+      continue;
+    }
+
     if (chain.rootMethod === "ask" && call === chain.rootCall) {
       const ref = resolvePrompt(call.arguments[0], options.bindings);
       if (ref) asks.add(ref);
@@ -268,6 +303,14 @@ export function inferEffects(options: InferEffectsOptions): InferredEffects {
       continue;
     }
 
+    if (chain.rootMethod === "decide" && call === chain.rootCall) {
+      const binding = resolveBinding(call.arguments[0], options.bindings);
+      const name =
+        stringArg(call.arguments[0]) ?? (binding?.kind === "decision" ? binding.ref : undefined);
+      if (name) decides.add(name);
+      continue;
+    }
+
     if (chain.rootMethod === "fetch" && call === chain.rootCall) {
       // fx.fetch(url) — host becomes effects.fetches entry.
       const lit = stringArg(call.arguments[0]);
@@ -289,7 +332,13 @@ export function inferEffects(options: InferEffectsOptions): InferredEffects {
     }
 
     if (chain.rootMethod === "call" && call === chain.rootCall) {
-      const ref = resolveCallTarget(call.arguments[0], options.bindings);
+      const arg = unwrapValueNode(call.arguments[0]);
+      const local = identifierName(arg);
+      const imported =
+        local && options.file && options.resolveFlowRef
+          ? options.resolveFlowRef(local, options.file)
+          : undefined;
+      const ref = imported ?? resolveCallTarget(call.arguments[0], options.bindings);
       if (ref) calls.add(ref);
       continue;
     }
@@ -335,18 +384,28 @@ export function inferEffects(options: InferEffectsOptions): InferredEffects {
       // Skip incomplete chains (`select` before `.from`, `insert` before table) —
       // the sibling call that carries the table arg records the real resource.
       const leaf = resolved.methods[resolved.methods.length - 1]!;
-      const hasTable = tableFromStoreChain(call, options.bindings, chain) !== undefined;
+      const tables = tablesFromStoreChain(call, options.bindings, chain);
+      const hasTable = tables.length > 0;
       if (!hasTable && (leaf === "select" || leaf === "insert" || leaf === "update")) {
         continue;
       }
       // Intermediate chain links that only forward (where/values/returning)
       // still carry read/write from earlier methods — record once we have a table
       // or a terminal key-based op.
-      if (!hasTable && (leaf === "where" || leaf === "values" || leaf === "returning")) {
+      if (
+        !hasTable &&
+        (leaf === "where" || leaf === "values" || leaf === "returning" || leaf === "groupBy")
+      ) {
         continue;
       }
-      if (op === "read" || op === "both") reads.add(resolved.resource);
-      if (op === "write" || op === "both") writes.add(resolved.resource);
+      const resources =
+        tables.length > 0
+          ? tables.map((table) => sqlTableRef(table) as ResourceRef)
+          : [resolved.resource];
+      for (const resource of resources) {
+        if (op === "read" || op === "both") reads.add(resource);
+        if (op === "write" || op === "both") writes.add(resource);
+      }
     }
   }
 
@@ -374,14 +433,16 @@ export function inferEffects(options: InferEffectsOptions): InferredEffects {
   if (secrets.size > 0) effects.secrets = sortUnique([...secrets]);
   if (calls.size > 0) effects.calls = sortUnique([...calls]);
   if (fetches.size > 0) effects.fetches = sortUnique([...fetches]);
+  if (decides.size > 0) effects.decides = sortUnique([...decides]);
 
   return {
     effects,
     steps,
     usesRaw,
     cacheIneligible: usesRaw && !options.hasExplicitEffects,
-    nondeterministic: asks.size > 0 || embeds.size > 0,
+    nondeterministic: asks.size > 0 || embeds.size > 0 || decides.size > 0,
     readsUserId: userIdRoots.some((node) => containsAuthUserId(node)),
+    bareIrreversible: [...bareIrreversible],
   };
 }
 
@@ -395,6 +456,7 @@ const EFFECT_KEYS = [
   "secrets",
   "calls",
   "fetches",
+  "decides",
 ] as const satisfies readonly (keyof Effects)[];
 
 /**
@@ -584,21 +646,37 @@ function tableFromStoreChain(
   bindings: ReadonlyMap<string, InferBinding>,
   chain?: FxChain,
 ): string | undefined {
+  return tablesFromStoreChain(call, bindings, chain)[0];
+}
+
+/**
+ * Every table argument on a store chain, including joins.
+ *
+ * @param call - Any call in the chain
+ * @param bindings - Scope bindings
+ * @param chain - Precomputed chain when already known
+ */
+function tablesFromStoreChain(
+  call: CallExpression,
+  bindings: ReadonlyMap<string, InferBinding>,
+  chain?: FxChain,
+): string[] {
   const found = tableFromStoreWalk(call, bindings, chain);
-  if (found) return found;
+  if (found.length > 0) return found;
   if (chain?.aliasLeaf && chain.aliasLeaf !== call) {
     return tableFromStoreWalk(chain.aliasLeaf, bindings);
   }
-  return undefined;
+  return [];
 }
 
 function tableFromStoreWalk(
   call: CallExpression,
   bindings: ReadonlyMap<string, InferBinding>,
   chain?: FxChain,
-): string | undefined {
+): string[] {
   let current: AstNode | undefined = call;
   const seen = new Set<AstNode>();
+  const names: string[] = [];
   while (current && current.type === "CallExpression" && !seen.has(current)) {
     seen.add(current);
     const c = current as CallExpression;
@@ -618,7 +696,8 @@ function tableFromStoreWalk(
         const id = identifierName(c.arguments[0]);
         if (id) {
           const binding = bindings.get(id);
-          return binding?.kind === "table" ? binding.ref : id;
+          const tableName = binding?.kind === "table" ? binding.ref : id;
+          if (!names.includes(tableName)) names.push(tableName);
         }
       }
     }
@@ -632,7 +711,7 @@ function tableFromStoreWalk(
     }
     break;
   }
-  return undefined;
+  return names;
 }
 
 function methodNameOfCall(call: CallExpression): string | undefined {
@@ -882,7 +961,9 @@ function collectFxChains(
   opaque: string[],
   userIdRoots: AstNode[],
   intrinsics: Array<{ name: "liveQuery" | "applySearchEmbedCdc"; call: CallExpression }>,
+  bareIrreversible: Set<"fetch" | "send">,
 ): ChainHit[] {
+  const stepBodies = new Set<AstNode>();
   const hits: ChainHit[] = [];
   const seen = new Set<AstNode>();
 
@@ -892,7 +973,7 @@ function collectFxChains(
     aliases: ReadonlyMap<string, ChainAlias>,
     locals: ReadonlyMap<string, AstNode>,
   ): void => {
-    analyzeFunction(fn, "fx", aliases, locals, file);
+    analyzeFunction(fn, "fx", aliases, locals, file, stepBodies.has(fn));
   };
 
   const analyzeFunction = (
@@ -901,13 +982,14 @@ function collectFxChains(
     outerAliases: ReadonlyMap<string, ChainAlias>,
     outerLocals: ReadonlyMap<string, AstNode>,
     file: string,
+    insideStep: boolean,
   ): void => {
     if (seen.has(fn)) return;
     seen.add(fn);
     userIdRoots.push(fn);
     const body = (fn as AstNode & { body?: AstNode }).body;
     if (!body) return;
-    analyzeBody(body, door, outerAliases, outerLocals, file);
+    analyzeBody(body, door, outerAliases, outerLocals, file, insideStep);
   };
 
   const analyzeBody = (
@@ -916,6 +998,7 @@ function collectFxChains(
     outerAliases: ReadonlyMap<string, ChainAlias>,
     outerLocals: ReadonlyMap<string, AstNode>,
     file: string,
+    insideStep: boolean,
   ): void => {
     const aliases = new Map(outerAliases);
     const locals = new Map(outerLocals);
@@ -925,6 +1008,20 @@ function collectFxChains(
     });
     for (const call of callsSkippingNested(body)) {
       const chain = chainFromCall(call, aliases);
+      if (chain?.rootMethod === "step") {
+        for (const arg of call.arguments) {
+          const fn = unwrapValue(arg);
+          if (fn && isFunctionNode(fn)) stepBodies.add(fn);
+        }
+      }
+      if (
+        !insideStep &&
+        chain &&
+        call === chain.rootCall &&
+        (chain.rootMethod === "fetch" || chain.rootMethod === "send")
+      ) {
+        bareIrreversible.add(chain.rootMethod);
+      }
       if (chain) {
         hits.push({ call, chain });
         continue;
@@ -935,7 +1032,7 @@ function collectFxChains(
       if (seen.has(nested)) continue;
       const shadows = functionParams(nested).some((param) => paramIdentifierName(param) === door);
       if (shadows) continue;
-      analyzeFunction(nested, door, aliases, locals, file);
+      analyzeFunction(nested, door, aliases, locals, file, insideStep || stepBodies.has(nested));
     }
   };
 
@@ -946,9 +1043,9 @@ function collectFxChains(
     if (second && paramIdentifierName(second) !== "fx") {
       opaque.push("the do callback's second parameter is not named fx");
     }
-    analyzeFunction(options.doNode, "fx", new Map(), new Map(), startFile);
+    analyzeFunction(options.doNode, "fx", new Map(), new Map(), startFile, false);
   } else {
-    analyzeBody(options.doNode, "fx", new Map(), new Map(), startFile);
+    analyzeBody(options.doNode, "fx", new Map(), new Map(), startFile, false);
   }
 
   return hits;

package/src/compiler/effects-join.test.ts

@@ -0,0 +1,48 @@
+/**
+ * Joins and groupBy list every source table under the flow's reads.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { extractFromSources } from "./extract.ts";
+
+describe("extractManifest — joins", () => {
+  test("innerJoin and groupBy record every table", async () => {
+    const manifest = await extractFromSources({
+      "src/app.ts": `
+        import { oke } from "okengine";
+        export const app = oke({ name: "joins" });
+      `,
+      "src/flows/orders.ts": `
+        import { on, flow, http, store, field } from "okengine";
+        import { eq, count } from "drizzle-orm";
+
+        export const db = store.sql("db");
+        export const orders = store.schema.table("orders", {
+          id: field.text().primaryKey(),
+          customerId: field.text(),
+        });
+        export const customers = store.schema.table("customers", {
+          id: field.text().primaryKey(),
+        });
+
+        export const totals = on(
+          http.get("/totals"),
+          flow("orders.totals", {
+            do: async (_input, fx) => {
+              return fx
+                .store(db)
+                .select({ n: count() })
+                .from(orders)
+                .innerJoin(customers, eq(orders.customerId, customers.id))
+                .groupBy(customers.id);
+            },
+          }),
+        );
+      `,
+    });
+    expect(manifest.flows?.["orders.totals"]?.effects?.reads?.slice().sort()).toEqual([
+      "sql:customers",
+      "sql:orders",
+    ]);
+  });
+});

package/src/compiler/extract.test.ts

@@ -1577,6 +1577,34 @@ export const ping = flow({ do: () => ({ ok: true }) });
     expect(manifest.flows?.["notes.ping"]).toBeDefined();
   });
 
+  test("fx.call of an imported flow handle records that flow's name", async () => {
+    const tasks = `
+import { on, flow, http } from "okengine";
+export const create = on(
+  http.post("/tasks"),
+  flow("tasks.create", { do: async () => ({ id: "1" }) }),
+);
+`;
+    const forms = `
+import { on, flow, http } from "okengine";
+import { create as createTask } from "../tasks/index.ts";
+export const submit = on(
+  http.post("/forms/:id/submit"),
+  flow("forms.submit", {
+    do: async (_input, fx) => {
+      await fx.call(createTask, { title: "SSO" });
+      return { ok: true };
+    },
+  }),
+);
+`;
+    const manifest = await extractFromSources({
+      "src/flows/tasks/index.ts": tasks,
+      "src/flows/forms/index.ts": forms,
+    });
+    expect(manifest.flows?.["forms.submit"]?.effects?.calls).toEqual(["tasks.create"]);
+  });
+
   test("effects are identical for the same do body in a tree file vs a barrel", async () => {
     const doBody = `
       const rows = await fx.store(db).select().from(notes);