okengine 0.9.1 → 0.10.1

package/src/kernel/boot.test.ts

@@ -79,7 +79,7 @@ describe("boot — lazy element needs", () => {
     expect(needs.signal).toBe(false);
   });
 
-  test("oke() Store-only graph stays under the prior 53 kB baseline", async () => {
+  test("oke() Store-only graph stays under the prior 54 kB baseline", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-store-only-"));
     const entry = join(dir, "entry.ts");
     const appPath = join(import.meta.dir, "app.ts");
@@ -117,10 +117,11 @@ describe("boot — lazy element needs", () => {
         total += Bun.gzipSync(new Uint8Array(raw)).byteLength;
       }
       // Rebased after fx.sendOtp/verifyOtp on the shared fx surface (~50.1 kB
-      // gzip), durable-journal lease surface (~51.2 kB), then fx.deliverOtp +
-      // unified otp() plugin wiring on the shared surface (~50.9 kB → 53 kB
-      // cap). Clock/channel/journal drivers stay lazy-bound; far below eager bind.
-      expect(total).toBeLessThan(53_000);
+      // gzip), durable-journal lease surface (~51.2 kB), fx.deliverOtp +
+      // unified otp() (~50.9 kB → 53 kB), then fx.runs / SLO window on the
+      // shared surface (~53.3 kB → 54 kB cap). Clock/channel/journal drivers
+      // stay lazy-bound; far below eager bind.
+      expect(total).toBeLessThan(54_000);
     } finally {
       await rm(dir, { recursive: true, force: true });
     }

package/src/kernel/boot.ts

@@ -17,7 +17,10 @@
  * Element runtimes are loaded via `new URL("./boot-bind/"+name+".ts", …)` so
  * unused binders stay out of the `oke()` bundle (semantic tree-shaking).
  * Vault still loads whenever secrets are declared and lists every gap in one
- * failure; capability minting uses flow effect refs only — no element modules.
+ * failure; capability minting uses flow effect refs only — no element modules,
+ * except a lazy `extractManifest` import when a flow has no hand-declared
+ * `effects` and neither {@link BootOptions.manifest} nor
+ * {@link BootOptions.rootDir} / `OKE_ROOT_DIR` are set to derive one.
  *
  * The scheduler reads the effective state from the Store after reconciliation,
  * never the code directly (console §5).
@@ -38,8 +41,11 @@ import type {
 import type { JournalRuntime } from "./boot-bind/journal.ts";
 import type { CreateRunsRuntimeOptions, RunsRuntime } from "../runs/index.ts";
 import { createCapabilityToken, type CapabilityToken } from "./capability.ts";
+import { throwOke } from "./errors.ts";
 import type { AnyFlowDef } from "./flow.ts";
 import type { Binding } from "./on.ts";
+import type { Manifest } from "../manifest/types.ts";
+import { emitBootWarn } from "../runtime/boot-warn.ts";
 
 /** Pre-built or partially-built element runtimes. */
 export interface ElementRuntimes {
@@ -104,6 +110,21 @@ export interface BootOptions {
   readonly bindings?: readonly Binding[];
   /** Flows known to the app (for capability minting). */
   readonly flows?: readonly AnyFlowDef[];
+  /**
+   * Compiled Manifest to derive capability tokens from for flows with no
+   * hand-declared `effects` (highest priority — build tooling / bundler
+   * import, never a filesystem read the kernel performs itself).
+   */
+  readonly manifest?: Manifest;
+  /**
+   * Project root for a lazy, best-effort `extractManifest` when a flow has
+   * no hand-declared `effects` and no {@link manifest} was given. Explicit
+   * opt-in only — never defaults to `process.cwd()` — so the existing test
+   * suite (hundreds of boots against synthetic flows, not a real source
+   * tree) never pays extraction cost. Falls back to `OKE_ROOT_DIR` when
+   * unset (the CLI sets this for `oke dev` / `oke start`).
+   */
+  readonly rootDir?: string;
   /**
    * Dispatch a cron / every interval when the scheduler fires.
    *
@@ -115,8 +136,13 @@ export interface BootOptions {
    *
    * @param signal - Signal name
    * @param payload - Payload
+   * @param meta - Optional envelope (producer run id for trace chains)
    */
-  readonly onSignal?: (signal: string, payload: unknown) => void | Promise<void>;
+  readonly onSignal?: (
+    signal: string,
+    payload: unknown,
+    meta?: { readonly parentRunId?: string; readonly messageId?: string },
+  ) => void | Promise<void>;
   /**
    * Resume due durable runs — called on every scheduler tick when any flow
    * declares `durable: true` (claimDueSleep on the shared journal store).
@@ -257,8 +283,8 @@ async function loadBind<T>(name: string): Promise<T> {
 export async function bootApplication(input: BootOptions = {}): Promise<BootResult> {
   const docker =
     input.docker === true || (input.docker !== false && process.env.OKE_DOCKER === "1");
-  // `-d` always selects the `docker` driver profile — not a mix of test/local +
-  // prod store overrides (templates often pin `env: "test"` for harnesses).
+  // `-d` always selects the `docker` driver profile — not a mix of local/test +
+  // prod store overrides when `$options.env` is unset.
   const env: ConfigEnv = docker ? "docker" : (input.env ?? "local");
   let config = input.config;
   if (config === undefined) {
@@ -452,8 +478,11 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
     }
   }
 
-  // 8. Caps — effect refs only; no element modules.
-  const capabilities = mintCapabilities(options.flows ?? []);
+  // 8. Caps — effect refs only; no element modules (unless a lazy extract is needed).
+  const capabilities = await mintCapabilities(options.flows ?? [], env, {
+    manifest: options.manifest,
+    rootDir: options.rootDir,
+  });
 
   return {
     vault,
@@ -486,16 +515,90 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   };
 }
 
+/** Per-process guard so the "no effects" boot warning fires once, not per-flow. */
+let noEffectsWarned = false;
+
+/** Reset the once-per-process "no effects" warn latch (tests only). */
+export function resetNoEffectsWarnForTests(): void {
+  noEffectsWarned = false;
+}
+
+/**
+ * Best-effort AoT extraction from `rootDir` — mirrors the CLI's own lazy,
+ * defensive `extractManifest` use (`oke dev`'s `tryLoadProjectManifest`).
+ * Never throws: a broken or mid-edit source tree just means "no Manifest
+ * available," handled by the caller like any other missing Manifest.
+ *
+ * `new URL` (not a literal specifier) so `oxc-parser` / the whole compiler
+ * never enters the bundler graph for apps that never hit this path — same
+ * trick as {@link loadBind} for the element binders.
+ *
+ * @param rootDir - Project root to extract from
+ */
+async function tryAutoExtractManifest(rootDir: string): Promise<Manifest | undefined> {
+  try {
+    const url = new URL("../compiler/extract.ts", import.meta.url);
+    const { extractManifest } = (await import(url.href)) as typeof import("../compiler/extract.ts");
+    return await extractManifest({ rootDir });
+  } catch {
+    return undefined;
+  }
+}
+
 /**
- * Mint capability tokens from each flow's declared effects.
- * Tokens come from the Manifest / flow contract — never hand-passed sets.
+ * Mint capability tokens from each flow's declared effects, falling back to
+ * a Manifest-derived stamp when a flow declares no `effects` of its own —
+ * an explicit {@link BootOptions.manifest}, or a lazy AoT extract from
+ * {@link BootOptions.rootDir} / `OKE_ROOT_DIR`.
+ *
+ * When neither is available: `local` / `test` stay open (today's dev-loop
+ * behavior, unbroken) with a once-per-process `oke boot:` warning; `docker`
+ * / `prod` fail loud (`OKE1008`) — docker mirrors prod's posture, never a
+ * silent open door in a deploy-shaped environment.
  *
  * @param flows - Adopted flows
+ * @param env - Resolved {@link ConfigEnv}
+ * @param options - Manifest / rootDir sources for the fallback stamp
  */
-export function mintCapabilities(flows: readonly AnyFlowDef[]): Map<string, CapabilityToken> {
+export async function mintCapabilities(
+  flows: readonly AnyFlowDef[],
+  env: ConfigEnv = "local",
+  options: { readonly manifest?: Manifest; readonly rootDir?: string } = {},
+): Promise<Map<string, CapabilityToken>> {
   const map = new Map<string, CapabilityToken>();
+
+  let manifest = options.manifest;
+  const needsManifest = manifest === undefined && flows.some((f) => f.effects === undefined);
+  if (needsManifest) {
+    const rootDir = options.rootDir ?? process.env["OKE_ROOT_DIR"];
+    if (rootDir) manifest = await tryAutoExtractManifest(rootDir);
+  }
+
   for (const f of flows) {
-    map.set(f.name, createCapabilityToken(f.name, f.effects));
+    if (f.effects !== undefined) {
+      map.set(f.name, createCapabilityToken(f.name, f.effects));
+      continue;
+    }
+
+    const stamped = manifest?.flows?.[f.name]?.effects;
+    if (stamped !== undefined) {
+      map.set(f.name, createCapabilityToken(f.name, stamped));
+      continue;
+    }
+
+    if (env === "docker" || env === "prod") {
+      throwOke("NO_EFFECTS_DECLARED", { flow: f.name });
+    }
+    if (!noEffectsWarned) {
+      noEffectsWarned = true;
+      emitBootWarn(
+        `oke boot: flow "${f.name}" (and possibly others) has no declared effects and no ` +
+          "Manifest-derived effects — running with an OPEN capability token (every access " +
+          "allowed, ledgered but not gated). Run `oke build`, or boot with `manifest` / " +
+          "`rootDir`, before deploying — docker/prod refuse to boot this way.",
+      );
+    }
+    map.set(f.name, createCapabilityToken(f.name, undefined));
   }
   return map;
 }

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);
+  });
+});