okengine 0.23.0 → 0.23.2

package/src/kernel/boot.ts

@@ -182,6 +182,13 @@ export interface BootOptions {
   readonly onDurableResume?: () => void | Promise<void>;
   /** Durable-run lease duration ms (default 30_000 — matches Signal claims). */
   readonly journalLeaseMs?: number;
+  /** Opt-in durable code version. Unset skips the stamp and the check. */
+  readonly codeVersion?: string;
+  /** Tier-1 cache bounds. Defaults: 10_000 entries, 60s TTL. */
+  readonly cache?: {
+    readonly maxEntries?: number;
+    readonly defaultTtlMs?: number;
+  };
   /** Injectable clock for test / frozen harnesses. */
   readonly now?: () => number;
   /**
@@ -191,6 +198,8 @@ export interface BootOptions {
   readonly clients?: {
     readonly kv?: import("../drivers/types.ts").KvClientLike;
     readonly signalRedis?: import("../drivers/signal-types.ts").SignalRedisClientLike;
+    /** Injected postgres signal client (tests). Production opens Bun.SQL. */
+    readonly signalSql?: import("../drivers/signal-postgres.ts").PostgresSignalSql;
   };
   /**
    * Process instance id for Clock / Journal / fleet registry.
@@ -537,8 +546,21 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
 
   // 4d. Scheduler — one timer drives clock ticks, durable-run resume, heartbeat.
   let schedulerTimer: ReturnType<typeof setInterval> | undefined;
+  const inflight = new Map<string, Promise<void>>();
+  let stopping = false;
   const startScheduler = options.startScheduler ?? env !== "test";
-  if (startScheduler && (clock !== undefined || journal !== undefined || instances !== undefined)) {
+  const signalBus = signal?.bus ?? undefined;
+  let refreshChannel: (() => Promise<void>) | undefined;
+  const pollCache = store?.cacheInvalidation === "postgres";
+  if (
+    startScheduler &&
+    (clock !== undefined ||
+      journal !== undefined ||
+      instances !== undefined ||
+      signalBus !== undefined ||
+      needs.channel ||
+      pollCache)
+  ) {
     const period = options.schedulerIntervalMs ?? 1000;
     const clockRt = clock;
     const durableResume = options.onDurableResume;
@@ -549,16 +571,30 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
       // Unexpected scheduler failures stay visible.
       console.error(err);
     };
+    const spawn = (name: string, task: () => Promise<unknown>): void => {
+      if (stopping || inflight.has(name)) return;
+      const run = Promise.resolve()
+        .then(task)
+        .then(() => undefined)
+        .catch(ignoreBenignSql)
+        .finally(() => {
+          inflight.delete(name);
+        });
+      inflight.set(name, run);
+    };
     schedulerTimer = setInterval(() => {
-      if (clockRt) void Promise.resolve(clockRt.tick()).catch(ignoreBenignSql);
-      if (journal && durableResume) void Promise.resolve(durableResume()).catch(ignoreBenignSql);
-      if (fleet) void fleet.maybeHeartbeat().catch(ignoreBenignSql);
+      if (signalBus) spawn("signal", () => signalBus.drain());
+      if (refreshChannel) spawn("channel", () => refreshChannel!());
+      if (clockRt) spawn("clock", () => Promise.resolve(clockRt.tick()));
+      if (journal && durableResume) spawn("durable", () => Promise.resolve(durableResume()));
+      if (fleet) spawn("fleet", () => fleet.maybeHeartbeat());
+      if (pollCache && store) spawn("cache", () => store.pollCacheInvalidations());
       const stem = ["run", "events"].join("-");
-      void import(`../elements/ai/${stem}.ts`)
-        .then((mod: typeof import("../elements/ai/run-events.ts")) =>
-          mod.sweepInstalledAgentEvents(),
-        )
-        .catch(ignoreBenignSql);
+      spawn("agents", () =>
+        import(`../elements/ai/${stem}.ts`).then(
+          (mod: typeof import("../elements/ai/run-events.ts")) => mod.sweepInstalledAgentEvents(),
+        ),
+      );
     }, period);
     schedulerTimer.unref?.();
   }
@@ -572,7 +608,8 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   // 5. Channel
   let channel = pre.channel;
   if (needs.channel && !channel) {
-    channel = channelBind!.bindChannel(options, env, now, docker);
+    channel = await channelBind!.bindChannel(options, env, now, docker);
+    refreshChannel = channel.refresh?.bind(channel);
   }
 
   // 6. AI
@@ -639,7 +676,12 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
     instanceId,
     instances,
     capabilities,
+    /**
+     * Stop the scheduler interval and wake timers.
+     * Does not wait for a tick that has already started — {@link BootResult.close} does.
+     */
     stopScheduler() {
+      stopping = true;
       if (schedulerTimer !== undefined) {
         clearInterval(schedulerTimer);
         schedulerTimer = undefined;
@@ -647,11 +689,13 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
       clock?.stopWakes();
     },
     async close() {
+      stopping = true;
       if (schedulerTimer !== undefined) {
         clearInterval(schedulerTimer);
         schedulerTimer = undefined;
       }
       clock?.stopWakes();
+      await Promise.all([...inflight.values()]);
       await signal?.close();
       await vault?.close();
       await runs?.flush();

package/src/kernel/boundary-contract.ts

@@ -30,6 +30,13 @@ export interface BoundaryContract<
    * (`oke doctor --diff` / CI gate).
    */
   readonly breaking?: boolean;
+  /** Per-route body cap in bytes. Falls back to the app `maxRequestBodySize`. */
+  readonly maxBodySize?: number;
+  /**
+   * `required` (default) rejects a JSON-shaped body that is not
+   * `application/json` or `+json`. `any` keeps the previous parse-or-string behavior.
+   */
+  readonly jsonContentType?: "required" | "any";
 }
 
 /** Infer validated input from a {@link BoundaryContract} bag. */

package/src/kernel/builtin-errors.ts

@@ -15,6 +15,7 @@ export const BUILTIN_ERROR_STATUS = {
   Conflict: 409,
   ForeignKey: 409,
   UnsupportedMediaType: 415,
+  PayloadTooLarge: 413,
   RateLimited: 429,
   AuthRateLimited: 429,
   InvalidQuery: 400,
@@ -78,6 +79,7 @@ export type BuiltinErrorMap = {
   readonly Conflict: BuiltinErrorBag;
   readonly ForeignKey: BuiltinErrorBag;
   readonly UnsupportedMediaType: BuiltinErrorBag;
+  readonly PayloadTooLarge: BuiltinErrorBag;
   readonly RateLimited: { readonly retryAfterMs?: number };
   readonly AuthRateLimited: BuiltinErrorBag;
   readonly InvalidQuery: BuiltinErrorBag;

package/src/kernel/call.test.ts

@@ -112,6 +112,7 @@ describe("fx.call — untriggered flows", () => {
     const a = await app.fetch(
       new Request("http://localhost/work", {
         method: "POST",
+        headers: { "content-type": "application/json" },
         body: JSON.stringify({ v: 10 }),
       }),
     );

package/src/kernel/errors-compiler.ts

@@ -12,6 +12,17 @@ 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.
  */
+/**
+ * A durable Flow calls `fx.fetch` or `fx.send` outside `fx.step`.
+ * Those effects are irreversible and must be an explicit step so replay skips them.
+ */
+export const DURABLE_BARE_EFFECT: OkeErrorDefinition = {
+  code: 1901,
+  domain: "compiler",
+  cause: 'Durable flow "{flow}" calls fx.{effect} outside fx.step.',
+  fix: "Wrap fx.fetch and fx.send in fx.step so replay returns the journaled value instead of repeating the call.",
+};
+
 export const FX_INFERENCE_OPAQUE: OkeErrorDefinition = {
   code: 1900,
   domain: "compiler",

package/src/kernel/errors-text.ts

@@ -84,6 +84,22 @@ export const OKE_ERROR_TEXT: Readonly<Record<string, OkeErrorText>> = {
       'Live signal "{signal}" is exposed twice with the same gates ({gates}) and match ({match}).',
     fix: "Use a different gate or path-param filter, or drop the extra route.",
   },
+  JOURNAL_STALE_LEASE: {
+    cause: 'Journal run "{runId}" rejected a write from an expired lease holder.',
+    fix: "Resume the run so the current holder acquires a new lease token. Do not write with a token from a previous holder.",
+  },
+  JOURNAL_REPLAY_DIVERGENCE: {
+    cause: 'Journal run "{runId}" expected {expected} but the code called {actual}.',
+    fix: "Keep step names, sleep labels, and effect order stable for in-flight runs. A code change that reorders journal calls cannot resume the old run.",
+  },
+  JOURNAL_CODE_VERSION: {
+    cause: 'Journal run "{runId}" was started on code {expected} and this process is {actual}.',
+    fix: "Finish or abandon in-flight runs before deploying a different code version. Do not replay them on the new build.",
+  },
+  JOURNAL_VALUE_NOT_JSON: {
+    cause: "A durable journal entry held a value that is not JSON ({detail}).",
+    fix: "Return plain JSON from fx.step. fx.fetch and fx.send must run inside fx.step so the journal can store a JSON snapshot.",
+  },
   MCP_TOOL_DUPLICATE: {
     cause: 'MCP tool "{tool}" is bound twice (flow "{flow}").',
     fix: "Give each MCP tool exposure a unique tool name.",

package/src/kernel/errors.ts

@@ -294,6 +294,14 @@ const OKE_ERROR_ROWS = {
   LIVE_EXPOSURE_DUPLICATE: { code: 1050, domain: "kernel" },
   /** Two MCP tool bindings share the same exposed tool name. */
   MCP_TOOL_DUPLICATE: { code: 1060, domain: "kernel" },
+  /** A journal write arrived from a holder whose lease token no longer matches. */
+  JOURNAL_STALE_LEASE: { code: 1074, domain: "kernel" },
+  /** Replay called a different step or effect than the next journal entry. */
+  JOURNAL_REPLAY_DIVERGENCE: { code: 1075, domain: "kernel" },
+  /** Resume of a run stamped with a different code version. */
+  JOURNAL_CODE_VERSION: { code: 1076, domain: "kernel" },
+  /** A journaled value could not be stored as JSON. */
+  JOURNAL_VALUE_NOT_JSON: { code: 1077, domain: "kernel" },
   /**
    * Emit target has no subscriber (unified-theory §21).
    * Thrown at emit when `optional` is false and nobody is subscribed.

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 { currentSignalTransaction, 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,40 @@ export function createGatedSqlHandle(options: GatedSqlHandleOptions): SqlStoreHa
         return h.increment(table, id, column, by);
       });
     },
+    async transaction(fn) {
+      refuseDryRunWrite();
+      const h = await ensure();
+      // Already inside a signal transaction: do not begin or commit another
+      // one. sql-session opens a child staging scope and merges it; only the
+      // outermost commit publishes.
+      if (currentSignalTransaction()) {
+        return h.transaction(() => fn(api));
+      }
+      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 +346,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,