okengine 0.21.1 → 0.23.0

package/src/kernel/effects.ts

@@ -17,7 +17,8 @@ export type EffectKind =
   | "embed"
   | "secret"
   | "call"
-  | "fetch";
+  | "fetch"
+  | "decide";
 
 /**
  * Reversibility tier — console §9.1 ranking, applied to all effect kinds.
@@ -65,6 +66,11 @@ export interface EffectEntry {
    * Omitted for in-process work (PGlite, mock AI, local channel console).
    */
   readonly external?: EffectExternal;
+  /**
+   * Agent run this `fx.run` or nested agent call started.
+   * Absent on prompt asks and on calls that are not agents.
+   */
+  readonly agentRunId?: string;
 }
 
 /** Append-only ledger of effect entries for one flow invocation. */
@@ -92,6 +98,7 @@ const TIER_BY_KIND: Readonly<Record<EffectKind, ReversibilityTier>> = {
   secret: "capability",
   call: "portal",
   fetch: "irreversible",
+  decide: "irreversible",
 };
 
 /**
@@ -143,6 +150,7 @@ export async function recordEffect<T>(
   externalOf?:
     | EffectExternal
     | ((result: T | undefined, error: unknown) => EffectExternal | undefined),
+  stamp?: (result: T | undefined) => { readonly agentRunId?: string } | undefined,
 ): Promise<T> {
   const timestamp = now();
   const t0 = performance.now();
@@ -163,6 +171,7 @@ export async function recordEffect<T>(
       timestamp,
       resolveDurationMs(now() - timestamp, performance.now() - t0),
       external,
+      stamp?.(result),
     );
   }
 }
@@ -187,7 +196,9 @@ export function recordObservedEffect(
   timestamp: number,
   duration: number,
   external?: EffectExternal,
+  stamp?: { readonly agentRunId?: string },
 ): void {
+  const agentRunId = stamp?.agentRunId;
   ledger.record({
     kind,
     resource,
@@ -195,6 +206,7 @@ export function recordObservedEffect(
     duration,
     reversibility: reversibilityOf(kind),
     ...(external !== undefined ? { external } : {}),
+    ...(agentRunId !== undefined && agentRunId.length > 0 ? { agentRunId } : {}),
   });
 }
 

package/src/kernel/element-registries.ts

@@ -16,6 +16,7 @@
 
 import type {
   AiAgentDecl,
+  AiDecisionDecl,
   AiEmbedDecl,
   AiMcpServerDecl,
   AiModelDecl,
@@ -52,3 +53,5 @@ export const aiEmbedRegistry: AiEmbedDecl[] = [];
 export const aiAgentRegistry: AiAgentDecl[] = [];
 /** `ai.mcpServer` declarations since the last reset. */
 export const aiMcpServerRegistry: AiMcpServerDecl[] = [];
+/** `ai.decision` declarations since the last reset. */
+export const aiDecisionRegistry: AiDecisionDecl[] = [];

package/src/kernel/errors-compiler.ts

@@ -0,0 +1,20 @@
+/**
+ * OKE1900 — kept off the kernel edge profile.
+ *
+ * Effect inference throws a plain `Error` (`OKE1900` in the message) from
+ * `okengine/compiler`. This definition is registry-only so the compiler
+ * chunk does not import the kernel error module.
+ */
+
+import type { OkeErrorDefinition } from "./errors.ts";
+
+/**
+ * A Flow hides `fx` from effect inference, or an explicit `effects` block
+ * omits an effect the walk can see.
+ */
+export const FX_INFERENCE_OPAQUE: OkeErrorDefinition = {
+  code: 1900,
+  domain: "compiler",
+  cause: 'Flow "{flow}" hides fx from effect inference ({detail}).',
+  fix: "Name the parameter fx, keep chain aliases in the same function, and include every effect inference can see. An effects block may add keys; it cannot omit keys inference can see.",
+};

package/src/kernel/errors-text.ts

@@ -52,6 +52,10 @@ export const OKE_ERROR_TEXT: Readonly<Record<string, OkeErrorText>> = {
     cause: 'Flow "{flow}" embeds with "{resource}" without declaring it.',
     fix: 'Add "{resource}" to this flow\'s effects.embeds.',
   },
+  UNDECLARED_DECIDE: {
+    cause: 'Flow "{flow}" decides "{resource}" without declaring it.',
+    fix: 'Add "{resource}" to this flow\'s effects.decides.',
+  },
   NO_EFFECTS_DECLARED: {
     cause: 'Flow "{flow}" has no declared effects and no Manifest to derive them from.{extract}',
     fix:

package/src/kernel/errors.ts

@@ -270,6 +270,8 @@ const OKE_ERROR_ROWS = {
   UNDECLARED_FETCH: { code: 1008, domain: "kernel" },
   /** Flow embeds via a model not listed in `effects.embeds`. */
   UNDECLARED_EMBED: { code: 1009, domain: "kernel" },
+  /** Flow decides a decision not listed in `effects.decides`. */
+  UNDECLARED_DECIDE: { code: 1010, domain: "kernel" },
   /**
    * Flow has no declared `effects` and no Manifest-derived effects were
    * available to stamp at boot (dev+compose / prod — never a silent open token).

package/src/kernel/external-effects.test.ts

@@ -85,6 +85,42 @@ describe("fx.fetch", () => {
       globalThis.fetch = originalFetch;
     }
   });
+
+  test("fx.race aborts an in-flight fx.fetch", async () => {
+    const originalFetch = globalThis.fetch;
+    let signal: AbortSignal | undefined;
+    globalThis.fetch = (async (_input: unknown, init?: RequestInit) => {
+      signal = init?.signal ?? undefined;
+      return new Promise<Response>((_resolve, reject) => {
+        const onAbort = (): void => {
+          reject(new DOMException("aborted", "AbortError"));
+        };
+        if (init?.signal?.aborted) {
+          onAbort();
+          return;
+        }
+        init?.signal?.addEventListener("abort", onAbort, { once: true });
+      });
+    }) as typeof fetch;
+    try {
+      const { fx } = createFxContext({
+        flow: "stripe.pull",
+        effects: { fetches: ["api.stripe.com"] },
+      });
+      const winner = await fx.race([
+        () => fx.fetch("https://api.stripe.com/v1/charges").then(() => "slow"),
+        async () => {
+          await new Promise((r) => setTimeout(r, 10));
+          return "fast" as const;
+        },
+      ]);
+      expect(winner).toBe("fast");
+      await new Promise((r) => setTimeout(r, 15));
+      expect(signal?.aborted).toBe(true);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
 });
 
 describe("Channel failover — winning provider on EffectEntry", () => {

package/src/kernel/flow.test.ts

@@ -46,9 +46,8 @@ describe("flow — one species", () => {
     on(signal, shared);
 
     const app = oke({ autoBoot: false, name: "one-species" });
-    expect(app.bindings).toHaveLength(2);
-    expect(app.bindings[0]?.flow).toBe(shared);
-    expect(app.bindings[1]?.flow).toBe(shared);
+    const sharedBindings = app.bindings.filter((binding) => binding.flow === shared);
+    expect(sharedBindings).toHaveLength(2);
 
     const httpResult = await app.execute(shared, { n: 3 }, shared.triggers[0]!);
     const signalResults = await app.dispatchSignal("order-placed", { n: 4 });

package/src/kernel/flow.ts

@@ -54,6 +54,16 @@ export interface FlowOptions<I = unknown, O = unknown> {
    * (`"30s"`) adds a TTL on top of write invalidation.
    */
   readonly cache?: boolean | string;
+  /**
+   * HTTP `Idempotency-Key` handling.
+   * Omitted is auto: the header is honored on an eligible mutating flow.
+   * `"required"` rejects a missing header. `false` ignores the header.
+   * A TTL string (`"24h"`) overrides the 24 hour default.
+   */
+  readonly idempotency?:
+    | false
+    | "required"
+    | { readonly required?: boolean; readonly ttl?: string };
   /** Declared service-level objective. */
   readonly slo?: Slo;
   /**
@@ -168,6 +178,19 @@ export interface FlowDef<
   readonly liveCustomMatch: boolean;
   /** Cache option. */
   readonly cache: boolean | string | undefined;
+  /** Author idempotency option. */
+  readonly idempotency:
+    | false
+    | "required"
+    | { readonly required?: boolean; readonly ttl?: string }
+    | undefined;
+  /**
+   * Extracted idempotency stamp. Boot copies this from the Manifest.
+   * Runtime resolves it when extract has not run.
+   */
+  resolvedIdempotency?: { readonly mode: "off" | "auto" | "required"; readonly ttl: string };
+  /** True when extract saw `fx.raw`. A throw then completes the idempotency row. */
+  usesRaw?: boolean;
   /** SLO. */
   readonly slo: Slo | undefined;
   /** Plane (user vs operator). */
@@ -305,6 +328,7 @@ export function flow(
     live: undefined,
     liveCustomMatch: false,
     cache: options.cache,
+    idempotency: options.idempotency,
     slo: options.slo,
     plane: options.plane,
     breaking: false,