okengine 0.9.1 → 0.10.0

package/src/kernel/compensate.test.ts

@@ -0,0 +1,131 @@
+/**
+ * Durable compensation — terminal failure only; undo steps are distinct
+ * journaled names that survive orphan resume without re-running forwards.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { createMemoryJournalStore } from "./journal.ts";
+import type { JournalRuntime } from "./boot-bind/journal.ts";
+import { flow } from "./flow.ts";
+import { oke } from "./app.ts";
+import { createRunsRuntime } from "../runs/runtime.ts";
+
+function memoryJournal(store = createMemoryJournalStore()): JournalRuntime {
+  return {
+    store,
+    instanceId: "test-inst",
+    leaseMs: 30_000,
+    driverId: "memory",
+  };
+}
+
+describe("durable compensate", () => {
+  test("throw commits journal failed and runs compensate undo steps", async () => {
+    const store = createMemoryJournalStore();
+    const undos: string[] = [];
+
+    const pay = flow({
+      name: "pay.charge",
+      durable: true,
+      do: async (_input: { amount: number }, fx) => {
+        await fx.step("reserve", async () => "reserved");
+        await fx.step("charge", async () => {
+          throw new Error("card_declined");
+        });
+        return { ok: true as const };
+      },
+      compensate: async (_ctx, fx) => {
+        await fx.step("undo:charge", async () => {
+          undos.push("undo:charge");
+        });
+        await fx.step("undo:reserve", async () => {
+          undos.push("undo:reserve");
+        });
+      },
+    });
+
+    const app = oke({
+      name: "compensate-throw",
+      env: "test",
+      startScheduler: false,
+      gate: { unguardedHttp: "allow" },
+      elements: { journal: memoryJournal(store) },
+    }).adopt(pay);
+
+    await app.boot();
+    const result = await app.execute(pay, { amount: 10 }, { kind: "internal" });
+    expect(result.ctx.error).toBeDefined();
+
+    const runs = await store.list();
+    expect(runs).toHaveLength(1);
+    expect(runs[0]!.status).toBe("failed");
+    expect(runs[0]!.error).toBe("card_declined");
+    expect(undos).toEqual(["undo:charge", "undo:reserve"]);
+    const stepNames = runs[0]!.entries
+      .filter((e) => e.kind === "step")
+      .map((e) => (e as { name: string }).name);
+    expect(stepNames).toContain("reserve");
+    expect(stepNames).toContain("undo:reserve");
+    expect(stepNames).toContain("undo:charge");
+  });
+
+  test("compensate does not run on successful path", async () => {
+    let compensated = 0;
+    const store = createMemoryJournalStore();
+    const ok = flow({
+      name: "pay.ok",
+      durable: true,
+      do: async (_input, fx) => {
+        await fx.step("a", () => "done");
+        return { ok: true as const };
+      },
+      compensate: async () => {
+        compensated += 1;
+      },
+    });
+
+    const app = oke({
+      name: "compensate-ok",
+      env: "test",
+      startScheduler: false,
+      gate: { unguardedHttp: "allow" },
+      elements: { journal: memoryJournal(store) },
+    }).adopt(ok);
+    await app.boot();
+    const result = await app.execute(ok, {}, { kind: "internal" });
+    expect(result.failure).toBeUndefined();
+    expect(compensated).toBe(0);
+    expect((await store.list())[0]!.status).toBe("completed");
+  });
+
+  test("WideEvent records thrown errors after classification fix", async () => {
+    const runs = createRunsRuntime({ driver: "memory" });
+    await runs.open();
+    const store = createMemoryJournalStore();
+
+    const boom = flow({
+      name: "pay.boom",
+      durable: true,
+      do: async () => {
+        throw new Error("boom");
+      },
+    });
+
+    const app = oke({
+      name: "compensate-runs",
+      env: "test",
+      startScheduler: false,
+      gate: { unguardedHttp: "allow" },
+      runs,
+      elements: { journal: memoryJournal(store) },
+    }).adopt(boom);
+    await app.boot();
+    await app.execute(boom, {}, { kind: "internal" });
+    await runs.flush();
+
+    const events = await runs.all();
+    expect(events[0]!.error?.code).toBe("boom");
+    expect((await store.list())[0]!.status).toBe("failed");
+    await runs.close();
+  });
+});

package/src/kernel/correlation.test.ts

@@ -0,0 +1,108 @@
+/**
+ * Trace parentId continuity: HTTP/producer → fx.emit → Signal → consumer Runs.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { signal } from "../elements/signal/declare.ts";
+import { createRunsRuntime } from "../runs/runtime.ts";
+import { flow } from "./flow.ts";
+import { oke } from "./app.ts";
+import { on, resetBindings } from "./on.ts";
+import { http } from "./triggers.ts";
+
+describe("correlation — parentId across Flow → Signal → Flow", () => {
+  test("consumer WideEvent.parentId equals producer run id", async () => {
+    resetBindings();
+    const orderPlaced = signal("corr-order-placed", { delivery: "once" });
+    const runs = createRunsRuntime({ driver: "memory" });
+    await runs.open();
+
+    const producer = flow({
+      name: "orders.create",
+      effects: { emits: ["corr-order-placed"] },
+      do: async (input: { id: string }, fx) => {
+        await fx.emit(orderPlaced, { id: input.id });
+        return { ok: true as const };
+      },
+    });
+
+    const consumer = flow({
+      name: "orders.notify",
+      do: async (_input: { id: string }) => ({ notified: true as const }),
+    });
+
+    on(http.post("/orders"), producer);
+    on(orderPlaced, consumer);
+
+    const app = oke({
+      name: "corr-signal",
+      runs,
+      signals: [orderPlaced],
+      gate: { unguardedHttp: "allow" },
+      startScheduler: false,
+    });
+
+    await app.boot({ env: "test", unguardedHttp: "allow" });
+    const res = await app.fetch(
+      new Request("http://localhost/orders", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ id: "ord_1" }),
+      }),
+    );
+    expect(res.ok).toBe(true);
+
+    const bus = app.bootResult?.signal?.bus;
+    expect(bus).toBeDefined();
+    await bus!.drain();
+    await runs.flush();
+
+    const events = await runs.all();
+    const create = events.find((e) => e.flow === "orders.create");
+    const notify = events.find((e) => e.flow === "orders.notify");
+    expect(create).toBeDefined();
+    expect(notify).toBeDefined();
+    expect(notify!.parentId).toBe(create!.id);
+
+    await runs.close();
+  });
+
+  test("fx.call child records parentId", async () => {
+    resetBindings();
+    const runs = createRunsRuntime({ driver: "memory" });
+    await runs.open();
+
+    const child = flow({
+      name: "inner.work",
+      do: () => ({ done: true as const }),
+    });
+
+    const parent = flow({
+      name: "outer.work",
+      effects: { calls: ["inner.work"] },
+      do: async (_input, fx) => {
+        await fx.call(child, {});
+        return { ok: true as const };
+      },
+    });
+
+    const app = oke({
+      name: "corr-call",
+      autoBoot: false,
+      runs,
+      gate: { unguardedHttp: "allow" },
+    }).adopt(child, parent);
+    await app.boot({ env: "test", unguardedHttp: "allow" });
+    await app.execute(parent, {}, { kind: "internal" });
+    await runs.flush();
+
+    const events = await runs.all();
+    const outer = events.find((e) => e.flow === "outer.work");
+    const inner = events.find((e) => e.flow === "inner.work");
+    expect(outer).toBeDefined();
+    expect(inner).toBeDefined();
+    expect(inner!.parentId).toBe(outer!.id);
+
+    await runs.close();
+  });
+});

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

@@ -0,0 +1,82 @@
+/**
+ * Part 4 verification: per-effect timing lives on EffectEntry via recordEffect /
+ * gated — not RunTelemetry, not plugin hooks.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { createEffectLedger, recordEffect } from "./effects.ts";
+import { createFxContext, type FxStubStoreHandle } from "./fx.ts";
+import { HOOK_STAGES } from "./hooks.ts";
+import { createRunTelemetry } from "./run-telemetry.ts";
+
+/** Narrow stub handle for tests that exercise the in-memory store. */
+function stub(fx: ReturnType<typeof createFxContext>["fx"], ref: string): FxStubStoreHandle {
+  return fx.store(ref) as FxStubStoreHandle;
+}
+
+describe("per-effect timing (EffectEntry, not RunTelemetry / hooks)", () => {
+  test("recordEffect writes timestamp + duration", async () => {
+    const ledger = createEffectLedger();
+    let t = 1000;
+    await recordEffect(
+      ledger,
+      "read",
+      "sql:notes",
+      () => t++,
+      async () => {
+        t += 40;
+        return "ok";
+      },
+    );
+    expect(ledger.entries).toHaveLength(1);
+    expect(ledger.entries[0]!.timestamp).toBe(1000);
+    expect(ledger.entries[0]!.duration).toBe(41);
+  });
+
+  test("gated fx.store / fx.emit / fx.send populate EffectEntry timing", async () => {
+    const telemetry = createRunTelemetry();
+    let t = 5000;
+    const { fx, ledger } = createFxContext({
+      flow: "timing.demo",
+      effects: {
+        writes: ["kv:cache"],
+        emits: ["tick"],
+        sends: ["hello"],
+      },
+      runTelemetry: telemetry,
+      now: () => t++,
+      channelRuntime: {
+        send: async () => ({ ok: true as const }),
+      } as never,
+      signalRuntime: {
+        emit: async () => {},
+      } as never,
+    });
+
+    await stub(fx, "kv:cache").set("a", 1);
+    await fx.emit("tick", {});
+    await fx.send("hello", { to: "u1", data: {} });
+
+    expect(ledger.entries.map((e) => e.kind)).toEqual(["write", "emit", "send"]);
+    for (const e of ledger.entries) {
+      expect(e.timestamp).toBeGreaterThan(0);
+      expect(e.duration).toBeGreaterThanOrEqual(0);
+    }
+    // RunTelemetry stays aggregate-only — no effect span list.
+    expect("effects" in telemetry).toBe(false);
+    expect(telemetry.cacheHits).toBe(0);
+  });
+
+  test("plugin hook stages are pipeline stages, not fx wrap points", () => {
+    expect([...HOOK_STAGES]).toEqual([
+      "onRequest",
+      "onParse",
+      "onAuth",
+      "beforeHandle",
+      "afterHandle",
+      "onError",
+      "onResponse",
+    ]);
+    expect(HOOK_STAGES.includes("aroundFx" as never)).toBe(false);
+  });
+});

package/src/kernel/flow.ts

@@ -73,6 +73,20 @@ export interface FlowOptions<I = unknown, O = unknown, E extends FlowErrorMap =
    * (`oke doctor --diff` / CI gate).
    */
   readonly breaking?: boolean;
+  /**
+   * Compensation phase after terminal failure on a durable flow.
+   * Runs under the same journal session before `commit("failed")`.
+   * Bodies must use distinct `fx.step("undo:…")` names — never reuse
+   * forward step names. Never called on retryable attempts or sleep park.
+   */
+  readonly compensate?: (
+    ctx: {
+      readonly input: I;
+      readonly error: unknown;
+      readonly completedSteps: readonly string[];
+    },
+    fx: import("./fx.ts").Fx,
+  ) => unknown | Promise<unknown>;
   /** The behavior. */
   readonly do: FlowHandler<I, O>;
 }
@@ -165,6 +179,20 @@ export interface FlowDef<
   readonly plane: FlowPlane | undefined;
   /** Intentional contract-break acknowledgement for Manifest Diff. */
   readonly breaking: boolean;
+  /**
+   * Optional compensation phase after terminal durable failure.
+   * See {@link FlowOptions.compensate}.
+   */
+  readonly compensate:
+    | ((
+        ctx: {
+          readonly input: I;
+          readonly error: unknown;
+          readonly completedSteps: readonly string[];
+        },
+        fx: import("./fx.ts").Fx,
+      ) => unknown | Promise<unknown>)
+    | undefined;
   /** Handler body. */
   readonly do: FlowHandler<I, O>;
   /** Triggers bound via {@link on} (zero or more). */
@@ -236,6 +264,16 @@ export function flow<Opts extends FlowOptions<any, any, any>>(
     slo: options.slo,
     plane: options.plane,
     breaking: options.breaking ?? false,
+    compensate: options.compensate as
+      | ((
+          ctx: {
+            readonly input: InferFlowIn<Opts>;
+            readonly error: unknown;
+            readonly completedSteps: readonly string[];
+          },
+          fx: import("./fx.ts").Fx,
+        ) => unknown | Promise<unknown>)
+      | undefined,
     do: options.do as FlowHandler<InferFlowIn<Opts>, InferFlowOut<Opts>>,
     triggers,
     $trigger: undefined,

package/src/kernel/fx-runs.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from "bun:test";
+import { createRunsRuntime } from "../runs/runtime.ts";
+import type { WideEvent } from "../runs/types.ts";
+import { createFxContext } from "./fx.ts";
+
+describe("fx.runs", () => {
+  test("window + checkSlo over bound runs runtime", async () => {
+    const runs = createRunsRuntime({ driver: "memory" });
+    await runs.open();
+    const now = Date.now();
+    const event: WideEvent = {
+      id: "r1",
+      flow: "checkout.create",
+      trigger: "http",
+      plane: "user",
+      gates: [],
+      cache: "none",
+      error: null,
+      effects: [],
+      logs: [],
+      durationMs: 250,
+      startedAt: now - 1_000,
+      endedAt: now,
+      dimensions: {},
+    };
+    await runs.append(event);
+
+    const { fx } = createFxContext({
+      flow: "ops.slo-check",
+      effects: { reads: ["runs"] },
+      runsRuntime: runs,
+      now: () => now,
+    });
+
+    const stats = await fx.runs.window("checkout.create", 5 * 60_000);
+    expect(stats.total).toBe(1);
+    expect(stats.p95Ms).toBe(250);
+
+    const breaches = await fx.runs.checkSlo(
+      "checkout.create",
+      { latency: { p95: "100ms" } },
+      5 * 60_000,
+    );
+    expect(breaches).toHaveLength(1);
+    expect(breaches[0]!.kind).toBe("latency_p95");
+
+    await runs.close();
+  });
+});

package/src/kernel/fx.test.ts

@@ -120,6 +120,20 @@ describe("fx — wholesale swap", () => {
       store() {
         throw new Error("store must not be used");
       },
+      runs: {
+        query: async () => {
+          throw new Error("runs must not be used");
+        },
+        all: async () => {
+          throw new Error("runs must not be used");
+        },
+        window: async () => {
+          throw new Error("runs must not be used");
+        },
+        checkSlo: async () => {
+          throw new Error("runs must not be used");
+        },
+      },
       async emit(signal) {
         calls.push(`emit:${typeof signal === "string" ? signal : signal.name}`);
       },

package/src/kernel/fx.ts

@@ -52,9 +52,20 @@ import {
 import { maskRedactedDeep, Redacted } from "./redacted.ts";
 import type { JournalSession } from "./journal.ts";
 import type { RunTelemetry } from "./run-telemetry.ts";
+import type { RunsRuntime } from "../runs/runtime.ts";
+import type { RunsRow, WideEvent } from "../runs/types.ts";
+import {
+  evaluateSloBreaches,
+  windowStatsForFlow,
+  type RunWindowStats,
+  type SloBreach,
+} from "../runs/window.ts";
 import { translate, type MessageCatalogs } from "../i18n/messages.ts";
 import type { AppMessageKey, MessageValues } from "../i18n/types.ts";
 
+/** Resource ref Flows declare to read the Runs store via {@link Fx.runs}. */
+export const RUNS_RESOURCE = "runs";
+
 export type { FxRetryOptions, FxThunk } from "./concurrency.ts";
 
 /** Named ref: plain string or `{ name }` element handle. */
@@ -327,6 +338,45 @@ export interface FxJson {
   with<T>(data: T, meta: Record<string, unknown>): JsonResult<T>;
 }
 
+/**
+ * Flow-facing read door to the Runs wide-event store.
+ *
+ * Declare `effects: { reads: ["runs"] }`. Powers native SLO checkers
+ * (Clock + Channel) without a parallel `fx.metric` API.
+ */
+export interface FxRuns {
+  /**
+   * Run SQL against the Runs store (`FROM runs` for files/memory).
+   *
+   * @param sql - Driver SQL
+   */
+  query(sql: string): Promise<RunsRow[]>;
+  /** Materialise all visible wide events (small stores / tests). */
+  all(): Promise<WideEvent[]>;
+  /**
+   * Rolling P95 / success-rate stats for one flow over a window.
+   *
+   * @param flow - Flow name
+   * @param windowMs - Lookback window (default 5 minutes)
+   */
+  window(flow: string, windowMs?: number): Promise<RunWindowStats>;
+  /**
+   * Evaluate Manifest-style SLO thresholds against a rolling window.
+   *
+   * @param flow - Flow name
+   * @param slo - Availability / latency thresholds
+   * @param windowMs - Lookback window (default 5 minutes)
+   */
+  checkSlo(
+    flow: string,
+    slo: {
+      readonly availability?: string;
+      readonly latency?: { readonly p95?: string; readonly p99?: string };
+    },
+    windowMs?: number,
+  ): Promise<readonly SloBreach[]>;
+}
+
 /**
  * The `fx` context object — v1 surface.
  *
@@ -362,6 +412,11 @@ export interface Fx {
    * @param input - Input payload
    */
   call(flow: NamedRef, input?: unknown): Promise<unknown>;
+  /**
+   * Query the Runs wide-event store (records `read` on `"runs"`).
+   * Requires a bound runs runtime and `effects.reads` including `"runs"`.
+   */
+  readonly runs: FxRuns;
   /** Clock surface. */
   readonly clock: FxClock;
   /**
@@ -589,6 +644,11 @@ export interface CreateFxOptions {
    * configured driver (postgres = same transaction as store writes).
    */
   readonly signalRuntime?: SignalRuntime;
+  /**
+   * Optional runs runtime. When set, `fx.runs` queries wide events for
+   * native SLO checkers (Clock + Channel alerting).
+   */
+  readonly runsRuntime?: RunsRuntime;
   /**
    * Optional vault runtime. When set, `fx.vault` reads through it and
    * `fx.log` redacts loaded secret values automatically.
@@ -610,6 +670,11 @@ export interface CreateFxOptions {
    * with zero flow instrumentation.
    */
   readonly runTelemetry?: RunTelemetry;
+  /**
+   * This invocation's WideEvent / run id. Stamped onto `fx.emit` messages
+   * as `parentRunId` so consuming Flows can join the trace chain.
+   */
+  readonly runId?: string;
   /** Reveal PII through the store runtime (requires `pii:reveal` upstream). */
   readonly revealPii?: boolean;
   /**
@@ -1135,13 +1200,58 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     },
   };
 
+  const runsSurface: FxRuns = {
+    query(sql) {
+      return gated("read", RUNS_RESOURCE, async () => {
+        if (!options.runsRuntime) {
+          throw new Error("fx.runs.query requires a bound runs runtime (oke({ runs }))");
+        }
+        return options.runsRuntime.query(sql);
+      });
+    },
+    all() {
+      return gated("read", RUNS_RESOURCE, async () => {
+        if (!options.runsRuntime) {
+          throw new Error("fx.runs.all requires a bound runs runtime (oke({ runs }))");
+        }
+        return options.runsRuntime.all();
+      });
+    },
+    async window(flowName, windowMs = 5 * 60_000) {
+      return gated("read", RUNS_RESOURCE, async () => {
+        if (!options.runsRuntime) {
+          throw new Error("fx.runs.window requires a bound runs runtime (oke({ runs }))");
+        }
+        const events = await options.runsRuntime.all();
+        return windowStatsForFlow(events, flowName, now(), windowMs);
+      });
+    },
+    async checkSlo(flowName, slo, windowMs = 5 * 60_000) {
+      return gated("read", RUNS_RESOURCE, async () => {
+        if (!options.runsRuntime) {
+          throw new Error("fx.runs.checkSlo requires a bound runs runtime (oke({ runs }))");
+        }
+        const events = await options.runsRuntime.all();
+        const stats = windowStatsForFlow(events, flowName, now(), windowMs);
+        return evaluateSloBreaches(stats, slo);
+      });
+    },
+  };
+
   const fx: Fx = {
     store: storeHandle,
+    runs: runsSurface,
     emit(signal, payload, emitOptions) {
       const name = resolveName(signal);
       return gated("emit", name, async () => {
         if (options.signalRuntime) {
-          await options.signalRuntime.emit(name, payload, emitOptions);
+          const merged: SignalEmitOptions = {
+            ...emitOptions,
+            ...(options.runId !== undefined && emitOptions?.parentRunId === undefined
+              ? { parentRunId: options.runId }
+              : {}),
+          };
+          await options.signalRuntime.emit(name, payload, merged);
         }
       });
     },

package/src/manifest/types.ts

@@ -40,6 +40,12 @@ export type ChannelMedium = "email" | "sms" | "whatsapp" | "push" | "any";
 /** Resource ref: `sql:table`, `kv:namespace`, `files:bucket`, `index:name`. */
 export type ResourceRef = `${StoreFacet}:${string}`;
 
+/**
+ * Observability read capability for `fx.runs` — not a store facet.
+ * Declare on `effects.reads` (never `writes`).
+ */
+export type RunsResourceRef = "runs";
+
 /** Signal name reference. */
 export type SignalRef = string;
 
@@ -68,8 +74,8 @@ export type JsonSchema = string | Record<string, unknown>;
  * `sends` / `asks` are irreversible (asks also nondeterministic + cost).
  */
 export interface Effects {
-  /** Store reads. */
-  reads?: ResourceRef[];
+  /** Store reads, plus optional `"runs"` for `fx.runs`. */
+  reads?: Array<ResourceRef | RunsResourceRef>;
   /** Store writes. */
   writes?: ResourceRef[];
   /** Emitted signals. */

package/src/runs/collect.ts

@@ -32,6 +32,8 @@ export interface CollectWideEventInput {
   readonly endedAt: number;
   /** Pipeline failure when present. */
   readonly failure?: FlowFailure | null;
+  /** Validated flow input (for local replay). */
+  readonly input?: unknown;
   /** Optional parent run id (causal chain). */
   readonly parentId?: string;
   /** Optional run id (generated when omitted). */
@@ -104,6 +106,7 @@ export function collectWideEvent(input: CollectWideEventInput): WideEvent {
       : {}),
     ...(input.buildVersion !== undefined ? { buildVersion: input.buildVersion } : {}),
     error,
+    ...(input.input !== undefined ? { input: input.input } : {}),
     effects: [...input.ledger.entries],
     logs: [...input.telemetry.logs],
     durationMs,