okengine 0.21.1 → 0.23.0

package/src/compiler/extract.test.ts

@@ -63,6 +63,7 @@ describe("extractManifest — five trigger types", () => {
       http: { method: "POST", path: "/orders" },
     });
     expect(manifest.flows?.["triggers.http"]?.effects?.writes).toEqual(["sql:orders"]);
+    expect(manifest.flows?.["triggers.http"]?.idempotency).toEqual({ mode: "auto", ttl: "24h" });
 
     expect(manifest.flows?.["triggers.every"]?.trigger).toEqual({
       every: "10m",
@@ -86,6 +87,7 @@ describe("extractManifest — five trigger types", () => {
       true,
     );
     expect(internal?.effects?.reads).toEqual(["sql:links"]);
+    expect(internal?.idempotency).toEqual({ mode: "off", ttl: "24h" });
   });
 });
 
@@ -99,9 +101,44 @@ describe("extractManifest — fx.raw", () => {
     });
 
     expect(manifest.flows?.["raw.unannotated"]?.cache).toBe(false);
+    expect(manifest.flows?.["raw.unannotated"]?.usesRaw).toBe(true);
+    expect(manifest.flows?.["raw.unannotated"]?.idempotency).toEqual({ mode: "off", ttl: "24h" });
     expect(manifest.flows?.["raw.annotated"]?.cache).toBeUndefined();
+    expect(manifest.flows?.["raw.annotated"]?.usesRaw).toBe(true);
     expect(manifest.flows?.["raw.annotated"]?.effects?.reads).toEqual(["sql:orders"]);
   });
+
+  test("required on a GET flow is an extract error; a bad ttl is an extract error", async () => {
+    const requiredGet = `
+      import { on, flow, http } from "okengine";
+      export const read = on(
+        http.get("/read"),
+        flow("pay.read", { idempotency: "required", do: async () => ({ ok: true }) }),
+      );
+    `;
+    await expect(extractFromSources({ "src/flows/pay.ts": requiredGet })).rejects.toThrow(
+      /header would be ignored/,
+    );
+
+    const badTtl = `
+      import { on, flow, http, store, field } from "okengine";
+      export const db = store.sql("db");
+      export const payments = store.schema.table("payments", { id: field.text().primaryKey() });
+      export const charge = on(
+        http.post("/charge"),
+        flow("pay.charge", {
+          idempotency: { ttl: "nope" },
+          do: async (input, fx) => {
+            await fx.store(db).insert(payments).values(input);
+            return { ok: true };
+          },
+        }),
+      );
+    `;
+    await expect(extractFromSources({ "src/flows/pay.ts": badTtl })).rejects.toThrow(
+      /not a duration/,
+    );
+  });
 });
 
 describe("extractManifest — performance", () => {

package/src/compiler/extract.ts

@@ -6,6 +6,7 @@
  * from source to `manifest.oke.json`.
  */
 
+import { readdir } from "node:fs/promises";
 import { parseSync } from "oxc-parser";
 import { join } from "node:path";
 
@@ -15,11 +16,19 @@ import {
   getAiProviderEntry,
 } from "../elements/ai/providers.ts";
 import { buildCronExpression, type CronField } from "../elements/clock/cron-fields.ts";
+import {
+  hasMutatingEffects,
+  idempotencyTtlMs,
+  resolveIdempotencyMode,
+  ttlOf,
+  type FlowIdempotencyOption,
+} from "../kernel/idempotency.ts";
 import { SearchConfigError } from "../elements/store/search-errors.ts";
 
 import type {
   Ai,
   AiAgent,
+  AiDecision,
   AiMcpServer,
   AiModel,
   AiPrompt,
@@ -45,6 +54,7 @@ import type {
 } from "../manifest/types.ts";
 import { sqlTableRef } from "../manifest/sql-resource.ts";
 import {
+  effectsMissingFromDeclaration,
   identifierName,
   inferEffects,
   resolveCallTarget,
@@ -56,6 +66,7 @@ import {
   type InferBinding,
   type Literal,
 } from "./effects-infer.ts";
+import { buildFxIndex, readTsconfigPaths, type FxIndex } from "./fx-index.ts";
 import {
   isFlowsTreeFile,
   isSkippedExtractSource,
@@ -131,6 +142,8 @@ interface ProjectScope {
   /** Store-wide live defaulting — `oke({ store: { live: true } })`. */
   store?: Manifest["store"];
   flows: Record<string, Flow>;
+  /** Project functions that can receive `fx`, built once per extract. */
+  fxIndex: FxIndex;
   /** Export name → flow id (for agent tools). */
   flowExports: Map<string, string>;
   /** Local binding name → store.resource declaration (for on(http.resource)). */
@@ -168,6 +181,7 @@ export async function extractManifest(options: ExtractManifestOptions = {}): Pro
 
   const scope: ProjectScope = {
     app: options.app ?? "app",
+    fxIndex: buildFxIndex([]),
     bindings: new Map(),
     signals: {},
     stores: {},
@@ -198,6 +212,12 @@ export async function extractManifest(options: ExtractManifestOptions = {}): Pro
     return { file, program: result.program as unknown as AstNode };
   });
 
+  const tsPaths = options.rootDir ? await readTsconfigPaths(options.rootDir) : [];
+  scope.fxIndex = buildFxIndex(
+    parsed.map(({ file, program }) => ({ path: file.path, program })),
+    tsPaths,
+  );
+
   // Pass 1 — declarations (elements, config, named bindings).
   for (const { file, program } of parsed) {
     collectDeclarations(file.path, program, scope);
@@ -238,11 +258,18 @@ export async function extractManifest(options: ExtractManifestOptions = {}): Pro
   if (Object.keys(gates).length > 0) manifest.gates = gates;
   if (Object.keys(vault).length > 0) manifest.vault = vault;
   if (Object.keys(channels).length > 0) manifest.channels = channels;
-  if (scope.ai.models || scope.ai.prompts || scope.ai.agents || scope.ai.mcpServers) {
+  if (
+    scope.ai.models ||
+    scope.ai.prompts ||
+    scope.ai.agents ||
+    scope.ai.decisions ||
+    scope.ai.mcpServers
+  ) {
     manifest.ai = {
       ...(scope.ai.models ? { models: sortRecord(scope.ai.models) } : {}),
       ...(scope.ai.prompts ? { prompts: sortRecord(scope.ai.prompts) } : {}),
       ...(scope.ai.agents ? { agents: sortRecord(scope.ai.agents) } : {}),
+      ...(scope.ai.decisions ? { decisions: sortRecord(scope.ai.decisions) } : {}),
       ...(scope.ai.mcpServers ? { mcpServers: sortRecord(scope.ai.mcpServers) } : {}),
     };
   }
@@ -295,21 +322,50 @@ export async function extractFromSources(
 }
 
 async function readSources(rootDir: string, pattern: string): Promise<SourceFile[]> {
-  // Bun.Glob (global) — bare `import … from "bun"` is rejected by JSR.
-  const glob = new Bun.Glob(pattern);
   const files: SourceFile[] = [];
-  for await (const path of glob.scan({
-    cwd: rootDir,
-    onlyFiles: true,
-  })) {
-    if (isSkippedExtractSource(path)) continue;
-    const abs = join(rootDir, path);
-    files.push({ path: toPosixPath(path), source: await Bun.file(abs).text() });
+  if (pattern === "**/*.{ts,tsx}") {
+    await walkSources(rootDir, rootDir, files);
+  } else {
+    // Bun.Glob (global) — bare `import … from "bun"` is rejected by JSR.
+    const glob = new Bun.Glob(pattern);
+    for await (const path of glob.scan({ cwd: rootDir, onlyFiles: true })) {
+      if (isSkippedExtractSource(path)) continue;
+      const abs = join(rootDir, path);
+      files.push({ path: toPosixPath(path), source: await Bun.file(abs).text() });
+    }
   }
   files.sort((a, b) => a.path.localeCompare(b.path));
   return files;
 }
 
+/**
+ * Walk an app tree without entering `node_modules` or directory symlinks.
+ *
+ * A template's `node_modules/okengine` link points back at this repo, which
+ * contains the template again. Globbing through that link never terminates.
+ */
+async function walkSources(rootDir: string, dir: string, files: SourceFile[]): Promise<void> {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name === "node_modules" || entry.name === ".git" || entry.isSymbolicLink()) continue;
+    const abs = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await walkSources(rootDir, abs, files);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    if (!entry.name.endsWith(".ts") && !entry.name.endsWith(".tsx")) continue;
+    const rel = toPosixPath(abs.slice(rootDir.length + 1));
+    if (isSkippedExtractSource(rel)) continue;
+    files.push({ path: rel, source: await Bun.file(abs).text() });
+  }
+}
+
 function collectDeclarations(filePath: string, program: AstNode, scope: ProjectScope): void {
   walk(program, (node) => {
     if (node.type === "CallExpression") {
@@ -1378,7 +1434,11 @@ function visitDeclarationCall(call: CallExpression, program: AstNode, scope: Pro
     }
 
     if (obj === "ai" && prop === "agent") {
-      collectAgent(call, scope);
+      collectAgent(call, program, scope);
+    }
+
+    if (obj === "ai" && prop === "decision") {
+      collectDecision(call, program, scope);
     }
 
     if (obj === "ai" && prop === "mcpServer") {
@@ -1446,6 +1506,7 @@ function visitDeclarationCall(call: CallExpression, program: AstNode, scope: Pro
             : {}),
           ...(via && via.length > 0 ? { via } : {}),
           ...(timeout !== undefined ? { timeout } : {}),
+          ...(numberProp(opts, "repair") === 1 ? { repair: 1 as const } : {}),
         };
         scope.ai.prompts = scope.ai.prompts ?? {};
         scope.ai.prompts[promptName] = prompt;
@@ -1600,27 +1661,267 @@ function visitDeclarationCall(call: CallExpression, program: AstNode, scope: Pro
   }
 }
 
-function collectAgent(call: CallExpression, scope: ProjectScope): void {
+function agentToolEntry(
+  el: AstNode,
+  scope: ProjectScope,
+): { name: string; approval: boolean } | undefined {
+  if (el.type === "ObjectExpression") {
+    const nameNode = objectProp(el, "name");
+    const raw =
+      (nameNode ? resolveCallTarget(nameNode, scope.bindings) : undefined) ??
+      stringArg(nameNode) ??
+      identifierName(nameNode);
+    if (!raw) return undefined;
+    const name = scope.flowExports.get(raw) ?? scope.bindings.get(raw)?.ref ?? raw;
+    const approvalNode = objectProp(el, "approval");
+    return { name, approval: approvalNode !== undefined && boolProp(el, "approval") !== false };
+  }
+  const resolved = resolveCallTarget(el, scope.bindings);
+  const raw = resolved ?? identifierName(el) ?? stringArg(el);
+  if (!raw) return undefined;
+  const name = scope.flowExports.get(raw) ?? scope.bindings.get(raw)?.ref ?? raw;
+  return { name, approval: false };
+}
+
+function assertDecisionPlacement(flowName: string, flow: Flow, scope: ProjectScope): void {
+  const names = flow.effects?.decides ?? [];
+  if (names.length === 0) return;
+  const http = flow.trigger !== undefined && "http" in flow.trigger;
+  for (const decisionName of names) {
+    const decision = scope.ai.decisions?.[decisionName];
+    if (!decision || decision.mode !== "review") continue;
+    if (http) {
+      throw new Error(
+        `ai.decision("${decisionName}") review cannot run in HTTP flow "${flowName}" — a park answers 204. fx.emit a signal and decide in a consumer.`,
+      );
+    }
+    if (flow.durable !== true) {
+      throw new Error(
+        `ai.decision("${decisionName}"): flow "${flowName}" must set durable: true to review`,
+      );
+    }
+  }
+}
+
+function decisionReviewName(node: AstNode | undefined, scope: ProjectScope): string {
+  const literal = stringArg(node);
+  if (literal) return literal;
+  if (node?.type === "Identifier") {
+    const name = (node as Identifier).name;
+    return scope.gateIds.get(name) ?? name;
+  }
+  if (node?.type === "CallExpression") {
+    const arg = stringArg((node as CallExpression).arguments[0]);
+    if (arg) return arg;
+  }
+  if (node?.type === "MemberExpression") {
+    const member = node as AstNode & { property: AstNode; computed?: boolean };
+    if (member.property.type === "Identifier" && member.computed !== true) {
+      return (member.property as Identifier).name;
+    }
+  }
+  throw new Error("ai.decision: review gate name could not be resolved");
+}
+
+function assertDecisionQuestion(
+  decisionName: string,
+  key: string,
+  value: AstNode | undefined,
+  program: AstNode,
+): void {
+  const resolved = resolveDecisionExpr(value, program, decisionName, key);
+  if (!resolved || resolved.type !== "CallExpression") {
+    throw new Error(
+      `ai.decision("${decisionName}"): question "${key}" must be ai.choice, ai.score, or ai.boolean`,
+    );
+  }
+  const callee = (resolved as CallExpression).callee;
+  const member = callee as AstNode & { property?: AstNode };
+  const fn =
+    callee.type === "MemberExpression" && member.property?.type === "Identifier"
+      ? (member.property as Identifier).name
+      : undefined;
+  const args = (resolved as CallExpression).arguments;
+  if (fn === "choice") {
+    const options = args[1];
+    if (!options || options.type !== "ObjectExpression") {
+      throw new Error(
+        `ai.decision("${decisionName}"): choice "${key}" options must be an object literal`,
+      );
+    }
+    const keys = objectProperties(options)
+      .map((prop) => propKey(prop))
+      .filter((name): name is string => typeof name === "string");
+    if (keys.includes("none_of_these")) {
+      throw new Error(`ai.decision("${decisionName}"): choice "${key}" must not set none_of_these`);
+    }
+    if (keys.length > 254) {
+      throw new Error(
+        `ai.decision("${decisionName}"): choice "${key}" has ${keys.length} options; max 254`,
+      );
+    }
+  }
+  if (fn === "score") {
+    const levels = resolveScoreLevels(args[1], program, decisionName, key);
+    const count = ((levels as AstNode & { elements?: unknown[] }).elements ?? []).length;
+    if (count < 2 || count > 10) {
+      throw new Error(`ai.decision("${decisionName}"): score "${key}" needs 2–10 levels`);
+    }
+  }
+}
+
+function resolveDecisionExpr(
+  value: AstNode | undefined,
+  program: AstNode,
+  decisionName: string,
+  key: string,
+): AstNode | undefined {
+  if (!value) return undefined;
+  if (value.type !== "Identifier") return value;
+  const name = (value as Identifier).name;
+  const init = sameFileConstInit(name, program);
+  if (!init) {
+    throw new Error(
+      `ai.decision("${decisionName}"): question "${key}" is "${name}", which is not a same-file const`,
+    );
+  }
+  return init;
+}
+
+function resolveScoreLevels(
+  levels: AstNode | undefined,
+  program: AstNode,
+  decisionName: string,
+  key: string,
+): AstNode {
+  const resolved =
+    levels?.type === "Identifier"
+      ? sameFileConstInit((levels as Identifier).name, program)
+      : levels;
+  if (!resolved || resolved.type !== "ArrayExpression") {
+    const label = levels?.type === "Identifier" ? (levels as Identifier).name : "the levels";
+    throw new Error(
+      `ai.decision("${decisionName}"): score "${key}" levels (${label}) must be an array literal or a same-file const`,
+    );
+  }
+  return resolved;
+}
+
+function sameFileConstInit(name: string, program: AstNode): AstNode | undefined {
+  let found: AstNode | undefined;
+  walk(program, (node) => {
+    if (found || node.type !== "VariableDeclarator") return;
+    const decl = node as AstNode & { id?: AstNode; init?: AstNode };
+    if (decl.id?.type === "Identifier" && (decl.id as Identifier).name === name) {
+      found = decl.init;
+    }
+  });
+  return found;
+}
+
+function collectDecision(call: CallExpression, program: AstNode, scope: ProjectScope): void {
+  const decisionName = stringArg(call.arguments[0]);
+  const opts = objectArg(call.arguments[1]);
+  if (!decisionName || !opts) return;
+  const ask = objectProp(opts, "ask");
+  const questionProps = ask?.type === "ObjectExpression" ? objectProperties(ask) : [];
+  const questionNames = questionProps
+    .map((prop) => propKey(prop))
+    .filter((name): name is string => typeof name === "string" && name.length > 0);
+  if (questionNames.length === 0) {
+    throw new Error(`ai.decision("${decisionName}"): ask is empty`);
+  }
+  for (const prop of questionProps) {
+    const key = propKey(prop);
+    if (!key) continue;
+    if (key === "meta" || key === "$") {
+      throw new Error(`ai.decision("${decisionName}"): question id "${key}" is reserved`);
+    }
+    assertDecisionQuestion(
+      decisionName,
+      key,
+      (prop as AstNode & { value?: AstNode }).value,
+      program,
+    );
+  }
+  if (scope.ai.decisions?.[decisionName]) {
+    throw new Error(`ai.decision("${decisionName}"): duplicate decision name`);
+  }
+  const hasReview = objectProp(opts, "review") !== undefined;
+  const uncertain = stringProp(opts, "onUncertain");
+  const abstain = uncertain === "abstain";
+  if (hasReview === abstain) {
+    throw new Error(
+      `ai.decision("${decisionName}"): declare exactly one of review or onUncertain: "abstain"`,
+    );
+  }
+  const autonomyNode = objectProp(opts, "autonomy");
+  let autonomy: AiDecision["autonomy"];
+  if (autonomyNode?.type === "ObjectExpression") {
+    if (objectProp(autonomyNode, "audit") === undefined) {
+      throw new Error(`ai.decision("${decisionName}"): autonomy requires audit`);
+    }
+    const maxError = numberProp(autonomyNode, "maxError");
+    const audit = numberProp(autonomyNode, "audit");
+    const risk = numberProp(autonomyNode, "risk");
+    if (maxError === undefined || audit === undefined) {
+      throw new Error(`ai.decision("${decisionName}"): autonomy requires maxError and audit`);
+    }
+    autonomy = { maxError, audit, ...(risk !== undefined ? { risk } : {}) };
+  }
+  const evals = stringProp(opts, "evals");
+  const decision: AiDecision = {
+    mode: abstain ? "abstain" : "review",
+    questions: questionNames,
+    ...(hasReview ? { review: decisionReviewName(objectProp(opts, "review"), scope) } : {}),
+    ...(stringProp(opts, "model") ? { model: stringProp(opts, "model") } : {}),
+    driverId: stringProp(opts, "driverId") === "typesafe" ? "typesafe" : "openrouter",
+    ...(evals !== undefined ? { evals } : {}),
+    ...(autonomy !== undefined ? { autonomy } : {}),
+  };
+  scope.ai.decisions = scope.ai.decisions ?? {};
+  scope.ai.decisions[decisionName] = decision;
+  const bindingName = enclosingConstName(call, program);
+  if (bindingName) {
+    scope.bindings.set(bindingName, { kind: "decision", ref: decisionName });
+  }
+}
+
+function collectAgent(call: CallExpression, program: AstNode, scope: ProjectScope): void {
   const agentName = stringArg(call.arguments[0]);
   const opts = objectArg(call.arguments[1]);
   if (!agentName || !opts) return;
   const toolsArr = arrayProp(opts, "tools");
-  const tools = toolsArr
-    ?.map((el) => {
-      const resolved = resolveCallTarget(el, scope.bindings);
-      if (resolved) return resolved;
-      return identifierName(el) ?? stringArg(el);
-    })
-    .filter((x): x is string => typeof x === "string")
-    .map((id) => scope.flowExports.get(id) ?? scope.bindings.get(id)?.ref ?? id);
+  const entries = (toolsArr ?? [])
+    .map((el) => agentToolEntry(el, scope))
+    .filter((entry): entry is { name: string; approval: boolean } => entry !== undefined);
+  const tools = entries.map((entry) => entry.name);
+  const agentCalls = tools.filter(
+    (name) => scope.bindings.get(name)?.kind === "agent" || scope.ai.agents?.[name],
+  );
+  const approvals = Object.fromEntries(
+    entries.filter((entry) => entry.approval).map((entry) => [entry.name, true as const]),
+  );
   const agent: AiAgent = {
-    ...(tools && tools.length > 0 ? { tools } : {}),
+    ...(tools.length > 0 ? { tools } : {}),
+    ...(Object.keys(approvals).length > 0 ? { approvals } : {}),
     ...(numberProp(opts, "maxSteps") !== undefined
       ? { maxSteps: numberProp(opts, "maxSteps") }
       : {}),
+    ...(numberProp(opts, "maxDepth") !== undefined
+      ? { maxDepth: numberProp(opts, "maxDepth") }
+      : {}),
   };
   scope.ai.agents = scope.ai.agents ?? {};
   scope.ai.agents[agentName] = agent;
+  const bindingName = enclosingConstName(call, program);
+  if (bindingName) {
+    scope.bindings.set(bindingName, {
+      kind: "agent",
+      ref: agentName,
+      ...(agentCalls.length > 0 ? { agentCalls } : {}),
+    });
+  }
 }
 
 function collectMcpServer(call: CallExpression, program: AstNode, scope: ProjectScope): void {
@@ -1882,13 +2183,17 @@ function registerFlow(args: {
   }
   args.scope.bindings.set(name, { kind: "flow", ref: name });
 
-  const hasExplicitEffects = objectProp(opts, "effects") !== undefined;
+  const effectsNode = objectProp(opts, "effects");
+  const hasExplicitEffects = effectsNode !== undefined;
   const doNode = objectProp(opts, "do");
   const inferred = doNode
     ? inferEffects({
         doNode,
         bindings: args.scope.bindings,
         hasExplicitEffects,
+        flowName: name,
+        file: args.file.path,
+        resolveCallee: (callee, file) => args.scope.fxIndex.resolve(file, callee),
       })
     : {
         effects: {} as Effects,
@@ -1900,8 +2205,16 @@ function registerFlow(args: {
       };
 
   let effects: Effects | undefined;
-  if (hasExplicitEffects) {
-    effects = parseEffectsObject(objectProp(opts, "effects"));
+  if (hasExplicitEffects && effectsNode?.type === "ObjectExpression") {
+    effects = parseEffectsObject(effectsNode);
+    const missing = effectsMissingFromDeclaration(effects ?? {}, inferred.effects);
+    if (missing.length > 0) {
+      throw new Error(
+        `OKE1900: flow "${name}" declares effects that omit ${missing.join(", ")}. An effects block must include every effect inference can see.`,
+      );
+    }
+  } else if (hasExplicitEffects) {
+    effects = parseEffectsObject(effectsNode);
   } else {
     effects = inferred.effects;
   }
@@ -1950,6 +2263,7 @@ function registerFlow(args: {
   flow.source = `${args.file.path}:${line}`;
 
   if (boolProp(opts, "durable")) flow.durable = true;
+  assertDecisionPlacement(name, flow, args.scope);
   if (typeof liveFromTrigger === "string") {
     flow.live = liveFromTrigger;
     // Manual live surface — `.live(tableBinding)` on the trigger. Synthesize
@@ -2039,6 +2353,24 @@ function registerFlow(args: {
     flow.cacheKeys = `computed:${effects.reads[0]}/userId`;
   }
 
+  const idempotencyOption = parseIdempotencyOption(opts);
+  const httpMethod = manifestTrigger?.http?.method;
+  const stream = boolProp(opts, "stream") === true;
+  const live = typeof liveFromTrigger === "string";
+  const canHonor =
+    httpMethod !== "GET" && !stream && !live && (inferred.usesRaw || hasMutatingEffects(effects));
+  if (idempotencyRequired(idempotencyOption) && !canHonor) {
+    throw new Error(
+      `flow "${name}" sets idempotency required, but the header would be ignored (read-only, GET, stream, or live).`,
+    );
+  }
+  const ttl = ttlOf(idempotencyOption);
+  if (idempotencyTtlMs(ttl) <= 0) {
+    throw new Error(`flow "${name}" has an idempotency ttl that is not a duration ("${ttl}").`);
+  }
+  flow.idempotency = resolveIdempotencyMode(idempotencyOption, canHonor);
+  if (inferred.usesRaw) flow.usesRaw = true;
+
   putFlow(args.scope, name, flow);
 }
 
@@ -2830,6 +3162,7 @@ function parseEffectsObject(node: AstNode | undefined): Effects | undefined {
   const secrets = stringArrayProp(node, "secrets");
   const calls = stringArrayProp(node, "calls");
   const fetches = stringArrayProp(node, "fetches");
+  const decides = stringArrayProp(node, "decides");
   if (reads) effects.reads = reads as Effects["reads"];
   if (writes) effects.writes = writes as Effects["writes"];
   if (emits) effects.emits = emits;
@@ -2839,6 +3172,7 @@ function parseEffectsObject(node: AstNode | undefined): Effects | undefined {
   if (secrets) effects.secrets = secrets;
   if (calls) effects.calls = calls;
   if (fetches) effects.fetches = fetches;
+  if (decides) effects.decides = decides;
   return effects;
 }
 
@@ -3279,6 +3613,29 @@ function numberProp(obj: AstNode | undefined, key: string): number | undefined {
   return typeof v === "number" ? v : undefined;
 }
 
+function parseIdempotencyOption(opts: AstNode | undefined): FlowIdempotencyOption | undefined {
+  const node = objectProp(opts, "idempotency");
+  if (!node) return undefined;
+  if (node.type === "Literal") {
+    const value = (node as Literal).value;
+    if (value === false) return false;
+    if (value === "required") return "required";
+  }
+  if (node.type === "ObjectExpression") {
+    const required = boolProp(node, "required");
+    const ttl = stringProp(node, "ttl");
+    return {
+      ...(required !== undefined ? { required } : {}),
+      ...(ttl !== undefined ? { ttl } : {}),
+    };
+  }
+  return undefined;
+}
+
+function idempotencyRequired(option: FlowIdempotencyOption | undefined): boolean {
+  return option === "required" || (typeof option === "object" && option.required === true);
+}
+
 function boolProp(obj: AstNode | undefined, key: string): boolean | undefined {
   const node = objectProp(obj, key);
   if (!node || node.type !== "Literal") return undefined;

package/src/compiler/fixtures/skyport.expected.json

@@ -3,6 +3,10 @@
   "app": "skyport",
   "flows": {
     "bookings.create": {
+      "idempotency": {
+        "mode": "auto",
+        "ttl": "24h"
+      },
       "trigger": {
         "http": {
           "method": "POST",
@@ -29,12 +33,20 @@
       "plane": "user"
     },
     "bookings.getBooking": {
+      "idempotency": {
+        "mode": "off",
+        "ttl": "24h"
+      },
       "effects": {
         "reads": ["sql:bookings"]
       },
       "source": "src/flows/bookings/index.ts:50"
     },
     "bookings.mine": {
+      "idempotency": {
+        "mode": "off",
+        "ttl": "24h"
+      },
       "trigger": {
         "http": {
           "method": "GET",
@@ -49,6 +61,10 @@
       "cacheKeys": "computed:sql:bookings/userId"
     },
     "bookings.refundBooking": {
+      "idempotency": {
+        "mode": "auto",
+        "ttl": "24h"
+      },
       "effects": {
         "reads": ["sql:bookings"],
         "writes": ["sql:bookings"]
@@ -56,6 +72,10 @@
       "source": "src/flows/bookings/index.ts:54"
     },
     "payments.chargeBooking": {
+      "idempotency": {
+        "mode": "off",
+        "ttl": "24h"
+      },
       "effects": {
         "secrets": ["STRIPE_KEY"]
       },
@@ -64,6 +84,10 @@
       "steps": ["create-intent", "confirm"]
     },
     "support.createTicket": {
+      "idempotency": {
+        "mode": "auto",
+        "ttl": "24h"
+      },
       "trigger": {
         "http": {
           "method": "POST",