okengine 0.23.0 → 0.23.1

package/src/kernel/flow.ts

@@ -49,9 +49,9 @@ export interface FlowOptions<I = unknown, O = unknown> {
    */
   readonly retry?: FxRetryOptions;
   /**
-   * Cache policy. Read-only flows cache automatically from inferred
-   * effects (`true` / omitted). `false` opts out; a duration string
-   * (`"30s"`) adds a TTL on top of write invalidation.
+   * Cache policy. Omitted caches a pure store-read flow. `true` or a duration
+   * (`"30s"`) opts one flow in when the app set `cache: { auto: false }`.
+   * `false` always disables. The key includes tenant, locale, scopes, and roles.
    */
   readonly cache?: boolean | string;
   /**
@@ -124,6 +124,10 @@ export type InferFlowOut<Opts> = Opts extends { readonly do: FlowHandler<infer _
  * `FlowDef<…, undefined>` remains assignable into `on()` before rebinding.
  */
 declare const triggerPhantom: unique symbol;
+/** Covariant input phantom so `fx.call` can read `I` without hitting `do`. */
+declare const inputPhantom: unique symbol;
+/** Covariant output phantom so `fx.call` can read `O` without hitting `do`. */
+declare const outputPhantom: unique symbol;
 
 /**
  * A Flow definition — one species, trigger-agnostic until {@link on} binds.
@@ -151,6 +155,10 @@ export interface FlowDef<
    * `$trigger` / `triggers[0]` for the value.
    */
   readonly [triggerPhantom]?: T;
+  /** Type-level input. Not present at runtime. */
+  readonly [inputPhantom]?: I;
+  /** Type-level output. Not present at runtime. */
+  readonly [outputPhantom]?: O;
   /** Stable name (auto-assigned when omitted). */
   readonly name: string;
   /** Unit scope — derived from `name`'s first dot segment (e.g. `"auth.refresh"` → `"auth"`). */
@@ -255,6 +263,28 @@ export interface FlowDef<
   ): FlowDef<I, O, E, D & (P extends PluginDef<infer PD> ? PD : Record<string, never>), T>;
 }
 
+/**
+ * Input type of a Flow handle. `unknown` when `F` is a string name.
+ *
+ * @typeParam F - Flow handle or other call target
+ */
+export type FlowInput<F> = F extends { readonly [inputPhantom]?: infer I }
+  ? [I] extends [undefined]
+    ? unknown
+    : Exclude<I, undefined>
+  : unknown;
+
+/**
+ * Output type of a Flow handle. `unknown` when `F` is a string name.
+ *
+ * @typeParam F - Flow handle or other call target
+ */
+export type FlowOutput<F> = F extends { readonly [outputPhantom]?: infer O }
+  ? [O] extends [undefined]
+    ? unknown
+    : Exclude<O, undefined>
+  : unknown;
+
 /** Unique brand symbol for {@link FlowDef}. */
 export const flowBrand: unique symbol = Symbol("oke.flow");
 

package/src/kernel/fx-call-types.test.ts

@@ -0,0 +1,32 @@
+/**
+ * `fx.call(FlowDef)` is typed; a string name stays `Promise<unknown>`.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { flow } from "./flow.ts";
+import { createFxContext, type Fx } from "./fx.ts";
+
+describe("fx.call — FlowDef inference", () => {
+  test("a flow handle types input and output; a string name does not", () => {
+    const load = flow("notes.load", {
+      do: async (input: { id: string }) => ({ id: input.id, title: "n" }),
+    });
+    const { fx } = createFxContext({
+      flow: "notes.copy",
+      effects: { calls: ["notes.load"] },
+    });
+
+    const typed: (id: string) => Promise<{ id: string; title: string }> = (id) =>
+      fx.call(load, { id });
+    const untyped: (name: string) => Promise<unknown> = (name) => fx.call(name, { id: "1" });
+
+    expect(typeof typed).toBe("function");
+    expect(typeof untyped).toBe("function");
+
+    function _wrongInput(fxArg: Fx): void {
+      // @ts-expect-error input must match the flow handler
+      void fxArg.call(load, { id: 1 });
+    }
+    expect(typeof _wrongInput).toBe("function");
+  });
+});

package/src/kernel/fx-decide.ts

@@ -208,19 +208,23 @@ async function executeDecide(options: FxDecideInput, name: string): Promise<unkn
   const stored = (await options.journal.step(step, () =>
     pendingRecord(options, view, false, decl),
   )) as DecisionReviewRecord;
-  if (stored.status === "pending") {
-    await options.journal.sleep(step, "876000h", () => 876000 * 60 * 60 * 1000);
-  }
+  // Always consume the sleep row. Resolve moves wakeAt to now.
+  await options.journal.sleep(step, "876000h", () => 876000 * 60 * 60 * 1000);
   const resolved = readStepRecord(options.journal, step) ?? stored;
   return reviewed(view, resolved.values ?? {});
 }
 
-/** Completed outer `decide` effects for this name. The current call is not stored yet. */
+/** Completed `decide-provider` rows for this name. The current call is not included. */
 function decideOrdinal(journal: JournalSession | undefined, name: string): number {
   if (!journal) return 0;
-  return journal.run.entries.filter(
-    (entry) => entry.kind === "effect" && entry.effectKind === "decide" && entry.resource === name,
-  ).length;
+  return journal
+    .recordedBeforeCursor()
+    .filter(
+      (entry) =>
+        entry.kind === "effect" &&
+        entry.effectKind === "decide-provider" &&
+        entry.resource.startsWith(`${name}#`),
+    ).length;
 }
 
 function readStepRecord(journal: JournalSession, step: string): DecisionReviewRecord | undefined {

package/src/kernel/fx-sql-handle.ts

@@ -9,6 +9,7 @@ import type { SqlRow } from "../drivers/types.ts";
 import type {
   SelectFromBuilder,
   SelectOrderBuilder,
+  SqlPredicate,
   SqlStoreHandle,
   StoreDecl,
 } from "../elements/store.ts";
@@ -16,6 +17,7 @@ import { schemaTableName, sqlTableRef } from "../manifest/sql-resource.ts";
 import type { CapabilityToken } from "./capability.ts";
 import { DryRunWriteIsolationError, isDryRun } from "./dry-run.ts";
 import type { EffectExternal } from "./effects.ts";
+import { runInSignalTransaction } from "./signal-tx.ts";
 
 /** Capability-gated effect runner from {@link createFx}. */
 type Gated = <T>(
@@ -39,6 +41,13 @@ export interface GatedSqlHandleOptions {
   readonly capability: CapabilityToken;
   /** `fx.ask` — optional search rerank. */
   readonly ask: (model: string, input: unknown) => Promise<unknown>;
+  /**
+   * Open the signal outbox for emits inside {@link SqlStoreHandle.transaction}.
+   * Absent when the app has no signal runtime.
+   */
+  readonly beginSignal?: () => Promise<
+    import("../drivers/signal-types.ts").SignalTransaction | undefined
+  >;
 }
 
 /**
@@ -90,7 +99,7 @@ export function createGatedSqlHandle(options: GatedSqlHandleOptions): SqlStoreHa
     return gated(kind, ref, body, externalOf);
   };
 
-  return {
+  const api = {
     ref,
     get routedRole() {
       return cached?.routedRole ?? "primary";
@@ -102,7 +111,7 @@ export function createGatedSqlHandle(options: GatedSqlHandleOptions): SqlStoreHa
       return {
         from(table: unknown) {
           const run = (plan: {
-            where?: unknown;
+            where?: SqlPredicate<SqlRow> | null;
             orders?: readonly unknown[];
             limit?: number;
             offset?: number;
@@ -110,7 +119,8 @@ export function createGatedSqlHandle(options: GatedSqlHandleOptions): SqlStoreHa
             gatedTable("read", table, async () => {
               const h = await ensure();
               const from = h.select(columns).from(table) as SelectFromBuilder;
-              const filtered = plan.where === undefined ? from : from.where(plan.where);
+              const filtered =
+                plan.where === undefined || plan.where === null ? from : from.where(plan.where);
               const ordered =
                 plan.orders === undefined ? filtered : filtered.orderBy(...plan.orders);
               if (plan.offset !== undefined) return ordered.offset(plan.offset);
@@ -118,7 +128,7 @@ export function createGatedSqlHandle(options: GatedSqlHandleOptions): SqlStoreHa
             });
 
           const tail = (plan: {
-            where?: unknown;
+            where?: SqlPredicate<SqlRow> | null;
             orders?: readonly unknown[];
           }): SelectOrderBuilder => ({
             limit(n) {
@@ -133,7 +143,7 @@ export function createGatedSqlHandle(options: GatedSqlHandleOptions): SqlStoreHa
           });
 
           return {
-            where(where: unknown) {
+            where(where: SqlPredicate<SqlRow>) {
               return {
                 ...tail({ where }),
                 orderBy: (...orders: readonly unknown[]) => tail({ where, orders }),
@@ -185,7 +195,7 @@ export function createGatedSqlHandle(options: GatedSqlHandleOptions): SqlStoreHa
       return {
         set(row) {
           return {
-            where(where) {
+            where(where: SqlPredicate<SqlRow>) {
               return gatedTable("write", table, async () => {
                 refuseDryRunWrite();
                 const h = await ensure();
@@ -211,7 +221,7 @@ export function createGatedSqlHandle(options: GatedSqlHandleOptions): SqlStoreHa
         });
       }
       return {
-        where(where: unknown) {
+        where(where: SqlPredicate<SqlRow>) {
           return gatedTable("write", table, async () => {
             refuseDryRunWrite();
             const h = await ensure();
@@ -240,6 +250,34 @@ export function createGatedSqlHandle(options: GatedSqlHandleOptions): SqlStoreHa
         return h.increment(table, id, column, by);
       });
     },
+    async transaction(fn) {
+      refuseDryRunWrite();
+      const h = await ensure();
+      const signalTx = options.beginSignal ? await options.beginSignal() : undefined;
+      try {
+        const result = await h.transaction(async () => {
+          const body = () => fn(api);
+          if (!signalTx) return body();
+          return runInSignalTransaction(signalTx, body);
+        });
+        if (signalTx) await signalTx.commit();
+        return result;
+      } catch (err) {
+        if (signalTx) await signalTx.rollback();
+        throw err;
+      }
+    },
+    run(builder) {
+      const text = builder.toSQL().sql;
+      const kind = /^(insert|update|delete|create|drop|alter|truncate|replace)\b/i.test(text.trim())
+        ? "write"
+        : "read";
+      return gated(kind, ref, async () => {
+        if (kind === "write") refuseDryRunWrite();
+        const h = await ensure();
+        return h.run(builder);
+      });
+    },
     raw(sql, params) {
       return gated("read", ref, async () => {
         const h = await ensure();
@@ -302,4 +340,5 @@ export function createGatedSqlHandle(options: GatedSqlHandleOptions): SqlStoreHa
       });
     },
   } as SqlStoreHandle;
+  return api;
 }

package/src/kernel/fx.test.ts

@@ -436,9 +436,7 @@ describe("fx — wholesale swap", () => {
       live() {
         throw new Error("live must not be used");
       },
-      async call() {
-        return null;
-      },
+      call: (async () => null) as Fx["call"],
       clock: {
         now: () => 0,
         ago: () => 0,

package/src/kernel/fx.ts

@@ -17,6 +17,7 @@ import {
   type JsonStreamResult,
 } from "./json-result.ts";
 import type { Effects, ResourceRef, SignalResourceRef } from "../manifest/types.ts";
+import type { FlowInput, FlowOutput } from "./flow.ts";
 import { isMcpToolRef } from "../manifest/mcp-ref.ts";
 import type { QueryPageSpec } from "./list-page.ts";
 import type {
@@ -36,6 +37,7 @@ import { rlsIdentityFromAuth } from "../elements/store.ts";
 import type { RlsIdentity } from "../drivers/pg-rls.ts";
 import type { SignalDecl, SignalRuntime } from "../elements/signal.ts";
 import type { DeadLetter, SignalEmitOptions } from "../drivers/signal-types.ts";
+import { currentSignalTransaction } from "./signal-tx.ts";
 import type { VaultActor, VaultAdapter, VaultRuntime } from "../elements/vault.ts";
 import type { ChannelRuntime } from "../elements/channel.ts";
 import type { AgentApprovalResolveResult } from "../elements/ai/approval.ts";
@@ -172,6 +174,12 @@ export type { FxRetryOptions, FxThunk } from "./concurrency.ts";
 /** Named ref: plain string or `{ name }` element handle (optional pin). */
 export type NamedRef = string | { readonly name: string; readonly version?: number };
 
+/** Input of {@link Fx.call}: the flow's input, or `unknown` for a name. */
+type FxCallInput<F> = FlowInput<F>;
+
+/** Result of {@link Fx.call}: the flow's output, or `unknown` for a name. */
+type FxCallResult<F> = Promise<FlowOutput<F>>;
+
 /** Resolve a {@link NamedRef} to its string id (`name@version` when pinned). */
 export function resolveName(ref: NamedRef): string {
   if (typeof ref === "string") return ref;
@@ -768,7 +776,7 @@ export interface Fx {
    * @param flow - Flow name or handle
    * @param input - Input payload
    */
-  call(flow: NamedRef, input?: unknown): Promise<unknown>;
+  call<F extends NamedRef>(flow: F, input?: FxCallInput<F>): FxCallResult<F>;
   /**
    * Query the Runs wide-event store (records `read` on `"runs"`).
    * Requires a bound runs runtime and `effects.reads` including `"runs"`.
@@ -790,10 +798,6 @@ export interface Fx {
   /**
    * Send a provider-managed SMS OTP (records `send` on `sms-otp`).
    *
-   * Vendor extra (Taqnyat Verify API) — requires a bound SMS driver that
-   * supports provider-managed OTP. Dry-run records would-have-fired without
-   * contacting the provider.
-   *
    * @param opts - Recipient + requestId (+ lang / note / from)
    */
   sendOtp(opts: FxSendOtpOptions): Promise<{ ok: true }>;
@@ -806,9 +810,6 @@ export interface Fx {
   /**
    * Deliver an app-owned OTP across declared channels (records `send` on `auth-otp`).
    *
-   * Tier-2 only — uses Channel `deliverOtp` (sently FallbackTransport). Pass
-   * `only` for explicit user resend (single channel, no cross-medium failover).
-   *
    * @param opts - Channels, templates, addresses, OTP data
    */
   deliverOtp(opts: FxDeliverOtpOptions): Promise<{
@@ -1407,6 +1408,11 @@ export function createFxContext(options: CreateFxOptions): FxContext {
           gated,
           capability,
           ask: (model, input) => fx.ask(model, input),
+          beginSignal: async () => {
+            const bus = options.signalRuntime?.bus;
+            if (!bus) return undefined;
+            return bus.begin();
+          },
         });
       }
 
@@ -1783,13 +1789,18 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     emit(signal: NamedRef, payload?: unknown, emitOptions?: SignalEmitOptions) {
       const name = resolveName(signal);
       return gated("emit", name, async () => {
+        const merged: SignalEmitOptions = {
+          ...emitOptions,
+          ...(options.runId !== undefined && emitOptions?.parentRunId === undefined
+            ? { parentRunId: options.runId }
+            : {}),
+        };
+        const pending = currentSignalTransaction();
+        if (pending) {
+          await pending.emit(name, payload, merged);
+          return;
+        }
         if (options.signalRuntime) {
-          const merged: SignalEmitOptions = {
-            ...emitOptions,
-            ...(options.runId !== undefined && emitOptions?.parentRunId === undefined
-              ? { parentRunId: options.runId }
-              : {}),
-          };
           await options.signalRuntime.emit(name, payload, merged);
         }
       });
@@ -1815,7 +1826,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         signalRuntime: options.signalRuntime,
       }) as JsonStreamResult;
     },
-    call(flow, input) {
+    call<F extends NamedRef>(flow: F, input?: FxCallInput<F>): FxCallResult<F> {
       const name = resolveName(flow);
       return gated("call", name, async () => {
         if (isMcpToolRef(name)) {
@@ -1828,7 +1839,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
           return options.callHandler(name, input);
         }
         return undefined;
-      });
+      }) as FxCallResult<F>;
     },
     clock,
     vault: vaultSurface,

package/src/kernel/idempotency.test.ts

@@ -353,7 +353,8 @@ describe("HTTP idempotency", () => {
     expect(step1).toEqual(["step1"]);
     blockers[0]!();
     blockers[1]!();
-    expect((await hung).status).toBe(200);
+    // The forfeited holder kept the old lease token. Its later write is rejected.
+    await expect(hung).rejects.toThrow(/OKE1074/);
     expect((await resumed).status).toBe(200);
     expect(step1).toEqual(["step1"]);
   }, 30_000);

package/src/kernel/journal.test.ts

@@ -5,6 +5,8 @@
 
 import { describe, expect, test } from "bun:test";
 
+import { runDurable } from "../elements/clock/durable.ts";
+import { flow } from "./flow.ts";
 import {
   createJournal,
   createMemoryJournalStore,
@@ -13,6 +15,7 @@ import {
   isJournalSuspend,
   JOURNAL_DEFAULT_LEASE_MS,
 } from "./journal.ts";
+import { OkeError } from "./errors.ts";
 
 describe("journal lease (memory store)", () => {
   test("built-in stores expose the lease surface", () => {
@@ -139,4 +142,115 @@ describe("journal lease (memory store)", () => {
     const again = await journal.resume(session.runId);
     expect(await again.step("s", () => 2)).toBe(1);
   });
+
+  test("a stale lease holder cannot append", async () => {
+    let t = 1_000;
+    const store = createMemoryJournalStore();
+    const a = createJournal({
+      store,
+      now: () => t,
+      lease: { instanceId: "a", leaseMs: 100 },
+      codeVersion: "v1",
+    });
+    const session = await a.start("charge");
+    await session.step("create-intent", () => ({ id: "pi_1" }));
+    t = 1_200;
+    const b = createJournal({
+      store,
+      now: () => t,
+      lease: { instanceId: "b", leaseMs: 100 },
+      codeVersion: "v1",
+    });
+    await b.resume(session.runId);
+    try {
+      await session.step("capture", () => ({ ok: true }));
+      expect.unreachable("stale holder must be rejected");
+    } catch (err) {
+      expect(err).toBeInstanceOf(OkeError);
+      expect((err as OkeError).code).toBe(1074);
+    }
+  });
+
+  test("replay throws when the next call does not match the journal", async () => {
+    const store = createMemoryJournalStore();
+    const journal = createJournal({ store, now: () => 1, codeVersion: "v1" });
+    const session = await journal.start("charge");
+    await session.step("a", () => 1);
+    const resumed = await journal.resume(session.runId);
+    try {
+      await resumed.step("b", () => 2);
+      expect.unreachable("divergent replay must throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(OkeError);
+      expect((err as OkeError).code).toBe(1075);
+    }
+  });
+
+  test("a non-JSON journal value is OKE1077", async () => {
+    const store = createMemoryJournalStore();
+    const session = await createJournal({ store, now: () => 1 }).start("charge");
+    try {
+      await session.effect("call", "charge", () => 1n);
+      expect.unreachable("bigint must not journal");
+    } catch (err) {
+      expect(err).toBeInstanceOf(OkeError);
+      expect((err as OkeError).code).toBe(1077);
+    }
+  });
+
+  test("resume rejects a run stamped with another code version", async () => {
+    const store = createMemoryJournalStore();
+    const started = await createJournal({ store, now: () => 1, codeVersion: "v1" }).start("charge");
+    try {
+      await createJournal({ store, now: () => 2, codeVersion: "v2" }).resume(started.runId);
+      expect.unreachable("version skew must throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(OkeError);
+      expect((err as OkeError).code).toBe(1076);
+    }
+  });
+});
+
+describe("journal fetch snapshot", () => {
+  test("a durable flow replays fx.fetch without calling the network again", async () => {
+    const store = createMemoryJournalStore();
+    let calls = 0;
+    const original = globalThis.fetch;
+    globalThis.fetch = (async () => {
+      calls += 1;
+      return new Response("hello", { status: 201 });
+    }) as unknown as typeof fetch;
+    const load = flow("load", {
+      durable: true,
+      do: async (_input, fx) => {
+        const res = await fx.step("load", () => fx.fetch("https://example.com/data"));
+        return { status: res.status, text: await res.text() };
+      },
+    });
+    try {
+      const first = await runDurable({
+        flow: load,
+        input: {},
+        journalStore: store,
+        now: () => 1,
+      });
+      expect(first).toMatchObject({ status: "completed", output: { status: 201, text: "hello" } });
+      expect(calls).toBe(1);
+      const row = await store.get(first.runId);
+      expect(row?.entries.some((entry) => entry.kind === "step" && entry.name === "load")).toBe(
+        true,
+      );
+      const replay = await createJournal({ store, now: () => 2 }).resume(first.runId);
+      const again = await replay.step("load", () => {
+        calls += 1;
+        return new Response("nope", { status: 500 });
+      });
+      expect(again).toBeInstanceOf(Response);
+      expect(again.status).toBe(201);
+      expect(await again.text()).toBe("hello");
+      expect(calls).toBe(1);
+    } finally {
+      globalThis.fetch = original;
+    }
+  });
 });