okengine 0.13.0 → 0.14.1

package/src/elements/index.ts

@@ -176,6 +176,8 @@ export type {
   AiModelDecl,
   AiPromptDecl,
   AiAgentDecl,
+  AiMcpServerDecl,
+  AiMcpServerOptions,
   AiEmbedDecl,
   AiRuntime,
   AgentDenial,

package/src/elements/signal/declare.ts

@@ -34,7 +34,8 @@ export interface SignalOptions {
 }
 
 /**
- * Declared signal handle — usable as `on(signal, flow)` and `fx.emit(signal, …)`.
+ * Declared signal handle — usable as `on(signal, flow)`, `fx.emit(signal, …)`,
+ * and `fx.deadLetters(signal)`.
  */
 export interface SignalDecl<T = unknown> {
   /** Signal name (manifest key). */

package/src/elements/signal/runtime.ts

@@ -3,7 +3,12 @@
  * emit / subscribe / live / drain for `fx` and tests.
  */
 
-import type { SignalBus, SignalDriver, SignalEmitOptions } from "../../drivers/signal-types.ts";
+import type {
+  DeadLetter,
+  SignalBus,
+  SignalDriver,
+  SignalEmitOptions,
+} from "../../drivers/signal-types.ts";
 import type { SignalDecl } from "./declare.ts";
 
 /** Options for {@link createSignalRuntime}. */
@@ -48,6 +53,12 @@ export interface SignalRuntime {
    * @param options - Optional emit options (`key` for per-key once ordering)
    */
   emit(name: string, payload?: unknown, options?: SignalEmitOptions): Promise<void>;
+  /**
+   * Dead-lettered messages for one signal (auto-starts).
+   *
+   * @param name - Signal name
+   */
+  deadLetters(name: string): Promise<readonly DeadLetter[]>;
   /** Close the bus. */
   close(): Promise<void>;
 }
@@ -87,6 +98,10 @@ export function createSignalRuntime(options: CreateSignalRuntimeOptions): Signal
       const b = await this.start();
       await b.emit(name, payload, options);
     },
+    async deadLetters(name) {
+      const b = await this.start();
+      return b.deadLetters(name);
+    },
     async close() {
       if (bus) {
         await bus.close();

package/src/elements/signal.ts

@@ -8,6 +8,7 @@
 
 export { signal } from "./signal/declare.ts";
 export type { SignalDecl, SignalOptions } from "./signal/declare.ts";
+export type { DeadLetter, SignalFailureReason } from "../drivers/signal-types.ts";
 
 export { createSignalRuntime } from "./signal/runtime.ts";
 export type { CreateSignalRuntimeOptions, SignalRuntime } from "./signal/runtime.ts";

package/src/elements/store/cache.test.ts

@@ -92,6 +92,7 @@ describe("autoCacheEligible", () => {
       false,
     );
     expect(autoCacheEligible({ effects: { reads: ["runs"] } })).toBe(false);
+    expect(autoCacheEligible({ effects: { reads: ["signal:notify"] } })).toBe(false);
     expect(autoCacheEligible({ effects: {} })).toBe(false);
   });
 
@@ -112,6 +113,7 @@ describe("autoCacheEligible", () => {
         { kind: "read", resource: "sql:views" },
         { kind: "read", resource: "sql:views" },
         { kind: "read", resource: "runs" },
+        { kind: "read", resource: "signal:notify" },
         { kind: "write", resource: "sql:views" },
         { kind: "ask", resource: "summarize" },
         { kind: "emit", resource: "view-changed" },

package/src/elements/store/cache.ts

@@ -53,7 +53,7 @@ export function tier1KeysForReads(
   effects: Effects,
   dimsByResource?: Readonly<Record<string, readonly string[]>>,
 ): string[] {
-  const reads = (effects.reads ?? []).filter((r): r is ResourceRef => r !== "runs");
+  const reads = (effects.reads ?? []).filter((r): r is ResourceRef => isStoreResourceRef(r));
   return reads.map((resource) => computedCacheKey(resource, dimsByResource?.[resource]));
 }
 
@@ -223,7 +223,7 @@ export function resolveCacheEffects(
   declared: Effects | undefined,
   learnedReads: readonly ResourceRef[] | undefined,
 ): Effects {
-  const declaredReads = (declared?.reads ?? []).filter((r) => r !== "runs");
+  const declaredReads = (declared?.reads ?? []).filter((r) => isStoreResourceRef(r));
   if (declaredReads.length > 0 || (declared?.writes?.length ?? 0) > 0) {
     return declared ?? {};
   }
@@ -275,7 +275,7 @@ export function autoCacheEligible(options: {
   const effects = options.effects ?? {};
   if ((effects.asks?.length ?? 0) > 0) return false;
   if ((effects.writes?.length ?? 0) > 0) return false;
-  const reads = (effects.reads ?? []).filter((r) => r !== "runs");
+  const reads = (effects.reads ?? []).filter((r) => isStoreResourceRef(r));
   return reads.length > 0;
 }
 

package/src/elements/vault/builtin-adapter.ts

@@ -450,6 +450,23 @@ export function createBuiltinVaultAdapter(opts: CreateBuiltinVaultOptions): Buil
    * @param keyRow - That version's live wrapped DEK
    */
   async function decryptRow(row: SecretRow, keyRow: KeyRow): Promise<string> {
+    try {
+      return await decryptRowOnce(row, keyRow);
+    } catch (err) {
+      // Stale key snapshot: rotation committed and dropped `pending` after
+      // this read. Reload the wrap and retry once — never return torn bytes.
+      if (!(err instanceof VaultError) || err.code !== "INVALID_KEY") throw err;
+      return await decryptRowOnce(row, await readKeyRow(row.id));
+    }
+  }
+
+  /**
+   * Unwrap the DEK and decrypt the value ciphertext.
+   *
+   * @param row - Stored secret version
+   * @param keyRow - That version's wrapped DEK
+   */
+  async function decryptRowOnce(row: SecretRow, keyRow: KeyRow): Promise<string> {
     const path = row.path;
     const version = toInt(row.version);
     const algorithm = row.algorithm as VaultAlgorithm;

package/src/full.ts

@@ -88,6 +88,8 @@ export {
   type SignalDecl,
   type SignalOptions,
   type SignalRuntime,
+  type DeadLetter,
+  type SignalFailureReason,
 } from "./elements/signal.ts";
 
 export {

package/src/index.ts

@@ -71,6 +71,8 @@ export {
   type SignalDecl,
   type SignalOptions,
   type SignalRuntime,
+  type DeadLetter,
+  type SignalFailureReason,
 } from "./elements/signal.ts";
 
 export {
@@ -143,6 +145,8 @@ export {
   type AiModelDecl,
   type AiPromptDecl,
   type AiAgentDecl,
+  type AiMcpServerDecl,
+  type AiMcpServerOptions,
   type AiRuntime,
 } from "./elements/ai.ts";
 

package/src/kernel/app.ts

@@ -37,10 +37,12 @@ import { runWithLocale } from "../i18n/locale-context.ts";
 import { runDurable } from "../elements/clock/durable.ts";
 import { isFlow, type AnyFlowDef } from "./flow.ts";
 import { failureFromUnknown, runCompensationPhase } from "./compensate.ts";
+import { withAbortSignal } from "./abort-scope.ts";
 import { fxRetry } from "./concurrency.ts";
 import {
   createFxContext,
   freezePrincipal,
+  isJsonStreamResult,
   resolveName,
   type CreateFxOptions,
   type Fx,
@@ -85,6 +87,7 @@ import { listBindings, resetBindings, type Binding } from "./on.ts";
 import {
   aiAgentRegistry,
   aiEmbedRegistry,
+  aiMcpServerRegistry,
   aiModelRegistry,
   aiPromptRegistry,
   channelTemplateRegistry,
@@ -531,18 +534,21 @@ function mergeAiOptions(
     readonly prompts: NonNullable<BootOptions["ai"]>["prompts"];
     readonly embeds: NonNullable<BootOptions["ai"]>["embeds"];
     readonly agents: NonNullable<BootOptions["ai"]>["agents"];
+    readonly mcpServers: NonNullable<BootOptions["ai"]>["mcpServers"];
   },
 ): BootOptions["ai"] | undefined {
   const models = mergeUnique(explicit?.models, fromRegistry.models ?? []);
   const prompts = mergeUnique(explicit?.prompts, fromRegistry.prompts ?? []);
   const embeds = mergeUnique(explicit?.embeds, fromRegistry.embeds ?? []);
   const agents = mergeUnique(explicit?.agents, fromRegistry.agents ?? []);
+  const mcpServers = mergeUnique(explicit?.mcpServers, fromRegistry.mcpServers ?? []);
   if (
     explicit === undefined &&
     models.length === 0 &&
     prompts.length === 0 &&
     embeds.length === 0 &&
-    agents.length === 0
+    agents.length === 0 &&
+    mcpServers.length === 0
   ) {
     return undefined;
   }
@@ -552,6 +558,7 @@ function mergeAiOptions(
     ...(prompts.length > 0 ? { prompts } : {}),
     ...(embeds.length > 0 ? { embeds } : {}),
     ...(agents.length > 0 ? { agents } : {}),
+    ...(mcpServers.length > 0 ? { mcpServers } : {}),
   };
 }
 
@@ -570,7 +577,7 @@ export function oke(options: OkeOptions): OkeApp {
   if (registry === "consume") resetBindings();
 
   // Same registry mode drains store.sql/store.files, vault.secret, signal(),
-  // channel.<medium>().template(), and ai.model/prompt/embed/agent —
+  // channel.<medium>().template(), and ai.model/prompt/embed/agent/mcpServer —
   // module-evaluation registries that mirror `on`'s trigger drain
   // (`listBindings`/`resetBindings` above). Explicit `options.stores` /
   // `secrets` / `signals` / `channel.templates` / `ai` are additive, never
@@ -588,6 +595,7 @@ export function oke(options: OkeOptions): OkeApp {
           aiPrompts: [],
           aiEmbeds: [],
           aiAgents: [],
+          aiMcpServers: [],
         }
       : {
           stores: storeRegistry.slice(),
@@ -599,6 +607,7 @@ export function oke(options: OkeOptions): OkeApp {
           aiPrompts: aiPromptRegistry.slice(),
           aiEmbeds: aiEmbedRegistry.slice(),
           aiAgents: aiAgentRegistry.slice(),
+          aiMcpServers: aiMcpServerRegistry.slice(),
         };
   if (registry === "consume") {
     storeRegistry.length = 0;
@@ -610,6 +619,7 @@ export function oke(options: OkeOptions): OkeApp {
     aiPromptRegistry.length = 0;
     aiEmbedRegistry.length = 0;
     aiAgentRegistry.length = 0;
+    aiMcpServerRegistry.length = 0;
   }
   const effectiveStores = mergeUnique(options.stores, registrySnapshot.stores);
   const effectiveSecrets = mergeUnique(options.secrets, registrySnapshot.secrets);
@@ -643,6 +653,7 @@ export function oke(options: OkeOptions): OkeApp {
     prompts: registrySnapshot.aiPrompts,
     embeds: registrySnapshot.aiEmbeds,
     agents: registrySnapshot.aiAgents,
+    mcpServers: registrySnapshot.aiMcpServers,
   });
 
   // Resolve Gate bag early so auth HTTP Bindings join `adopted` + the router
@@ -1149,16 +1160,19 @@ export function oke(options: OkeOptions): OkeApp {
       defaultLocale,
     );
 
-    return runWithLocale({ locale: resolvedLocale, defaultLocale }, () =>
-      executeInLocale({
-        flowDef,
-        input,
-        trigger,
-        extras,
-        resolvedLocale,
-        defaultLocale,
-      }),
-    );
+    return runWithLocale({ locale: resolvedLocale, defaultLocale }, () => {
+      const run = () =>
+        executeInLocale({
+          flowDef,
+          input,
+          trigger,
+          extras,
+          resolvedLocale,
+          defaultLocale,
+        });
+      const signal = extras?.request?.signal;
+      return signal ? withAbortSignal(signal, run) : run();
+    });
   }
 
   async function executeInLocale(args: {
@@ -1451,7 +1465,7 @@ export function oke(options: OkeOptions): OkeApp {
                   durable: flowDef.durable,
                   effects: putEffects,
                 });
-              if (storeAfter && output !== undefined) {
+              if (storeAfter && output !== undefined && !isJsonStreamResult(output)) {
                 const ttlMs =
                   typeof flowDef.cache === "string" ? cache.parseTtlMs(flowDef.cache) : undefined;
                 storeRt.putTier1(
@@ -1499,60 +1513,79 @@ export function oke(options: OkeOptions): OkeApp {
 
     const endedAt = now();
     const durationMs = resolveDurationMs(endedAt - startedAt, performance.now() - startedHr);
+    const streamOut = isJsonStreamResult(result.output) ? result.output : undefined;
+
+    const finalizeRun = async (): Promise<void> => {
+      // Stream rows land in Traces only after close. Measure wall time then
+      // so duration / waterfall cover the open stream, not just TTFB.
+      const recordEndedAt = streamOut ? now() : endedAt;
+      const recordDurationMs = streamOut
+        ? resolveDurationMs(recordEndedAt - startedAt, performance.now() - startedHr)
+        : durationMs;
+      if (journalSession) {
+        inflightRuns.delete(journalSession.runId);
+        const sleeping = ctx.state.sleeping as
+          | { readonly wakeAt: number; readonly label: string; readonly runId: string }
+          | undefined;
+        // Lease-capable stores make the shared row the wake schedule; the
+        // in-process map is only for custom stores without the lease surface.
+        if (sleeping && !hasJournalLease(activeJournal().store)) {
+          sleepingRuns.set(sleeping.runId, {
+            flow: flowDef,
+            input: ctx.input,
+            wakeAt: sleeping.wakeAt,
+          });
+        } else if (!sleeping && isTerminalFailure(result)) {
+          const terminalErr = result.failure ?? result.ctx.error;
+          await runCompensationPhase({
+            flow: flowDef,
+            input: ctx.input,
+            session: journalSession,
+            fx,
+            error: terminalErr,
+          });
+        } else if (!sleeping) {
+          await journalSession.commit("completed", {
+            output: streamOut ? { streamed: true } : result.output,
+          });
+        }
+      }
 
-    if (journalSession) {
-      inflightRuns.delete(journalSession.runId);
-      const sleeping = ctx.state.sleeping as
-        | { readonly wakeAt: number; readonly label: string; readonly runId: string }
-        | undefined;
-      // Lease-capable stores make the shared row the wake schedule; the
-      // in-process map is only for custom stores without the lease surface.
-      if (sleeping && !hasJournalLease(activeJournal().store)) {
-        sleepingRuns.set(sleeping.runId, {
-          flow: flowDef,
-          input: ctx.input,
-          wakeAt: sleeping.wakeAt,
-        });
-      } else if (!sleeping && isTerminalFailure(result)) {
-        const terminalErr = result.failure ?? result.ctx.error;
-        await runCompensationPhase({
-          flow: flowDef,
-          input: ctx.input,
-          session: journalSession,
-          fx,
-          error: terminalErr,
-        });
-      } else if (!sleeping) {
-        await journalSession.commit("completed", { output: result.output });
+      const runsRuntime =
+        booted?.runs ?? (isRunsRuntimeLike(options.runs) ? options.runs : undefined);
+      if (runsRuntime) {
+        const archiveCleartext = archiveFromInput(ctx.input, options.archiveInputFields);
+        const replayInput = redactArchivedFields(ctx.input, options.archiveInputFields);
+        const recordFailure =
+          result.failure ??
+          (isTerminalFailure(result) ? failureFromUnknown(result.ctx.error) : undefined);
+        await runsRuntime.record(
+          {
+            flow: flowDef,
+            trigger,
+            fx,
+            ledger,
+            telemetry,
+            startedAt,
+            endedAt: recordEndedAt,
+            durationMs: recordDurationMs,
+            failure: recordFailure,
+            id: runId,
+            input: replayInput,
+            ...(result.output !== undefined && !recordFailure
+              ? { output: streamOut ? { streamed: true } : result.output }
+              : {}),
+            ...(parentId !== undefined ? { parentId } : {}),
+          },
+          archiveCleartext,
+        );
       }
-    }
+    };
 
-    const runsRuntime =
-      booted?.runs ?? (isRunsRuntimeLike(options.runs) ? options.runs : undefined);
-    if (runsRuntime) {
-      const archiveCleartext = archiveFromInput(ctx.input, options.archiveInputFields);
-      const replayInput = redactArchivedFields(ctx.input, options.archiveInputFields);
-      const recordFailure =
-        result.failure ??
-        (isTerminalFailure(result) ? failureFromUnknown(result.ctx.error) : undefined);
-      await runsRuntime.record(
-        {
-          flow: flowDef,
-          trigger,
-          fx,
-          ledger,
-          telemetry,
-          startedAt,
-          endedAt,
-          durationMs,
-          failure: recordFailure,
-          id: runId,
-          input: replayInput,
-          ...(result.output !== undefined && !recordFailure ? { output: result.output } : {}),
-          ...(parentId !== undefined ? { parentId } : {}),
-        },
-        archiveCleartext,
-      );
+    if (streamOut && !isTerminalFailure(result)) {
+      streamOut.finalize = finalizeRun;
+    } else {
+      await finalizeRun();
     }
 
     return {

package/src/kernel/auto-registry.test.ts

@@ -205,6 +205,10 @@ describe("oke() auto-registry — stores/secrets/signals/channel.templates/ai",
     const summarizeNote = smart.prompt("summarize-note", {
       version: 1,
     });
+    ai.mcpServer("github", {
+      url: "https://mcp.example/github",
+      tools: ["create_issue"],
+    });
 
     const ping = flow("ai.ping", {
       effects: { asks: ["summarize-note"] },
@@ -221,6 +225,7 @@ describe("oke() auto-registry — stores/secrets/signals/channel.templates/ai",
 
     expect(app.$options.ai?.models?.some((m) => m.name === "smart")).toBe(true);
     expect(app.$options.ai?.prompts?.some((p) => p.name === "summarize-note")).toBe(true);
+    expect(app.$options.ai?.mcpServers?.some((s) => s.name === "github")).toBe(true);
 
     const runtime = createAiRuntime({
       models: [smart],

package/src/kernel/boot-bind/ai.ts

@@ -18,6 +18,7 @@ import { openaiCompatibleAiDriver } from "../../drivers/ai-openai-compatible.ts"
 import type { AiDriver, AiOpenOptions } from "../../drivers/ai-types.ts";
 import { createAiRuntime, type AiRuntime } from "../../elements/ai.ts";
 import type { GateRuntime } from "../../elements/gate.ts";
+import type { VaultRuntime } from "../../elements/vault.ts";
 import type { BootOptions } from "../boot.ts";
 
 /**
@@ -28,6 +29,7 @@ import type { BootOptions } from "../boot.ts";
  * @param now - Clock
  * @param env - Active environment
  * @param docker - Prefer compose AI URL when active
+ * @param vault - Optional vault for MCP bearer secrets
  */
 export function bindAi(
   options: BootOptions,
@@ -35,13 +37,21 @@ export function bindAi(
   now: () => number,
   env: ConfigEnv = "test",
   docker = false,
+  vault?: VaultRuntime,
 ): AiRuntime {
   const id = resolveAiDriverId(options, env, docker);
   const driver =
     options.ai?.defaultDriver ?? withOpenDefaults(aiDriverFor(id), openDefaultsFor(id, docker));
   return createAiRuntime({
     ...(options.ai ?? {}),
+    ...(vault ? { resolveSecret: (name: string) => vault.read(name) } : undefined),
     defaultDriver: driver,
+    drivers: {
+      mock: lazyDriver("mock", docker),
+      anthropic: lazyDriver("anthropic", docker),
+      "openai-compatible": lazyDriver("openai-compatible", docker),
+      ollama: lazyDriver("ollama", docker),
+    },
     gates: options.ai?.gates ?? gate,
     now,
   });
@@ -156,6 +166,20 @@ export function aiUrlFor(docker = false): string {
  * @param driver - Base driver
  * @param defaults - Env-derived open options
  */
+/**
+ * Open a protocol driver with env defaults only when a model actually uses it.
+ *
+ * @param id - Driver id
+ * @param docker - Docker mode
+ */
+function lazyDriver(id: string, docker: boolean): AiDriver {
+  const base = aiDriverFor(id);
+  return {
+    id: base.id,
+    open: (opts = {}) => base.open({ ...openDefaultsFor(id, docker), ...opts }),
+  };
+}
+
 function withOpenDefaults(driver: AiDriver, defaults: AiOpenOptions): AiDriver {
   if (Object.keys(defaults).length === 0) return driver;
   return {

package/src/kernel/boot-bind/clock.ts

@@ -124,5 +124,7 @@ export async function bindClock(
     }
   }
 
+  clock.startWakes();
+
   return { clock, clockDecls };
 }

package/src/kernel/boot.ts

@@ -550,7 +550,7 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   // 6. AI
   let ai = pre.ai;
   if (needs.ai && !ai) {
-    ai = aiBind!.bindAi(options, gate, now, env, docker);
+    ai = aiBind!.bindAi(options, gate, now, env, docker, vault);
   }
 
   // 7. Runs
@@ -607,12 +607,14 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
         clearInterval(schedulerTimer);
         schedulerTimer = undefined;
       }
+      clock?.stopWakes();
     },
     async close() {
       if (schedulerTimer !== undefined) {
         clearInterval(schedulerTimer);
         schedulerTimer = undefined;
       }
+      clock?.stopWakes();
       await signal?.close();
       await vault?.close();
       await runs?.flush();

package/src/kernel/element-registries.ts

@@ -1,7 +1,7 @@
 /**
  * Module-evaluation registries for `store.sql` / `store.files`, `vault.secret`,
  * `vault.env.required`, `signal()`, `channel.<medium>().template()`, and
- * `ai.model` / `.prompt` / `ai.embed` / `ai.agent` — the plain arrays behind
+ * `ai.model` / `.prompt` / `ai.embed` / `ai.agent` / `ai.mcpServer` — the plain arrays behind
  * each declare module's `listX()` / `resetX()` pair (mirrors `on.ts`'s
  * trigger-drain `bindings` array).
  *
@@ -16,6 +16,7 @@
 import type {
   AiAgentDecl,
   AiEmbedDecl,
+  AiMcpServerDecl,
   AiModelDecl,
   AiPromptDecl,
 } from "../elements/ai/declare.ts";
@@ -42,3 +43,5 @@ export const aiPromptRegistry: AiPromptDecl[] = [];
 export const aiEmbedRegistry: AiEmbedDecl[] = [];
 /** `ai.agent` declarations since the last reset. */
 export const aiAgentRegistry: AiAgentDecl[] = [];
+/** `ai.mcpServer` declarations since the last reset. */
+export const aiMcpServerRegistry: AiMcpServerDecl[] = [];

package/src/kernel/fx-dead-letters.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test";
+import { memorySignalDriver } from "../drivers/index.ts";
+import { createSignalRuntime, signal, type SignalDecl } from "../elements/signal.ts";
+import { OkeError } from "./errors.ts";
+import { createFx, createFxContext, signalReadRef } from "./fx.ts";
+
+describe("fx.deadLetters", () => {
+  test("returns dead-lettered messages for a declared signal read", async () => {
+    const notify = signal("notify", { delivery: "once", retries: 0, deadLetter: true });
+    const runtime = openRuntime(notify);
+    const bus = await runtime.start();
+    await bus.subscribe("notify", "c1", async () => {
+      throw new Error("smtp-down");
+    });
+    await runtime.emit("notify", { orderId: "ord_1" });
+    await bus.drain();
+
+    const { fx, ledger } = createFxContext({
+      flow: "notifications.failed",
+      effects: { reads: [signalReadRef("notify")] },
+      signalRuntime: runtime,
+    });
+
+    const dead = await fx.deadLetters(notify);
+    expect(dead).toHaveLength(1);
+    expect(dead[0]!.payload).toEqual({ orderId: "ord_1" });
+    expect(dead[0]!.status).toBe("dead");
+    expect(dead[0]!.attempts).toBe(1);
+    expect(dead[0]!.failures[0]!.message).toBe("smtp-down");
+    expect(ledger.entries.map((e) => `${e.kind}:${e.resource}`)).toEqual(["read:signal:notify"]);
+
+    await runtime.close();
+  });
+
+  test("undeclared and cross-signal reads throw OKE1001", async () => {
+    const notify = signal("notify", { delivery: "once", retries: 0, deadLetter: true });
+    const other = signal("other", { delivery: "once", retries: 0, deadLetter: true });
+    const runtime = openRuntime(notify);
+    const fx = createFx({
+      flow: "notifications.failed",
+      effects: { reads: [signalReadRef("notify")] },
+      signalRuntime: runtime,
+    });
+
+    let err: unknown;
+    try {
+      await fx.deadLetters(other);
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(OkeError);
+    const oke = err as OkeError;
+    expect(oke.code).toBe(1001);
+    expect(oke.causeText).toBe(
+      'Flow "notifications.failed" reads "signal:other" without declaring it.',
+    );
+    expect(oke.fix).toBe('Add "signal:other" to this flow\'s effects.reads.');
+
+    await runtime.close();
+  });
+
+  test("throws when no signal runtime is bound", async () => {
+    const fx = createFx({
+      flow: "notifications.failed",
+      effects: { reads: [signalReadRef("notify")] },
+    });
+    await expect(fx.deadLetters("notify")).rejects.toThrow(
+      "fx.deadLetters requires a bound signal runtime",
+    );
+  });
+});
+
+function openRuntime(decl: SignalDecl) {
+  const runtime = createSignalRuntime({ driver: memorySignalDriver });
+  runtime.register(decl);
+  return runtime;
+}