okengine 0.13.0 → 0.15.2

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

@@ -1,17 +1,21 @@
 /**
- * `oke({...})` auto-populates `stores` / `secrets` / `signals` /
- * `channel.templates` from the same kind of module-evaluation registry
- * already proven for `on()`'s trigger drain (`registry-isolation.test.ts`).
+ * `oke({...})` auto-populates `stores` / `secrets` / `signals` / `clocks` /
+ * `gate.policies` / `channel.templates` from the same kind of
+ * module-evaluation registry already proven for `on()`'s trigger drain
+ * (`registry-isolation.test.ts`).
  *
- * `store.sql` / `store.files`, `vault.secret`, `signal()`, and medium-binder
- * `.template()` push into a shared registry (`src/kernel/element-registries.ts`)
- * at call time — zero change to how developers call them. `oke()` drains it
- * at construction under the same `registry: "consume" | "keep" | "ignore"`
- * switch that already governs bindings.
+ * `store.*`, `vault.secret`, `signal()`, `clock()`, `gate.policy` / `.scope`
+ * / `.rate`, and medium-binder `.template()` push into a shared registry
+ * (`src/kernel/element-registries.ts`) at call time — zero change to how
+ * developers call them. `oke()` drains it at construction under the same
+ * `registry: "consume" | "keep" | "ignore"` switch that already governs
+ * bindings.
  */
 
 import { describe, expect, test } from "bun:test";
 import { channel } from "../elements/channel/declare.ts";
+import { clock } from "../elements/clock/declare.ts";
+import { gate } from "../elements/gate/declare.ts";
 import { signal } from "../elements/signal/declare.ts";
 import { store } from "../elements/store/declare.ts";
 import { vault } from "../elements/vault/declare.ts";
@@ -20,7 +24,7 @@ import { flow } from "./flow.ts";
 import { on, resetBindings } from "./on.ts";
 import { http } from "./triggers.ts";
 
-describe("oke() auto-registry — stores/secrets/signals/channel.templates/ai", () => {
+describe("oke() auto-registry — stores/secrets/signals/clocks/gates/channel.templates/ai", () => {
   test("before/after: zero explicit arrays boots identically to the explicit-array form", async () => {
     resetBindings();
 
@@ -161,6 +165,42 @@ describe("oke() auto-registry — stores/secrets/signals/channel.templates/ai",
     expect(app.bootResult?.vault?.contracts.has("IGNORED_SECRET")).toBeFalsy();
   });
 
+  test("store.kv / store.index / clock() / gate.policy auto-drain — no explicit oke() arrays", async () => {
+    resetBindings();
+    store.kv("drafts", { description: "Compose drafts" });
+    store.index("tasks", { description: "Task search" });
+    clock("daily-digest", { cron: "0 8 * * *", every: "1d", timezone: "UTC" });
+    const member = gate.policy("member", ({ auth }) => !!auth.verified);
+    gate.scope("task:write");
+    gate.rate({ max: 60, per: "1m", keyBy: "user" });
+
+    const ping = flow("auto.ping", {
+      do: () => ({ ok: true as const }),
+    });
+    on(http.get("/auto-ping").gate(member), ping);
+
+    const app = oke({
+      name: "auto-kv-clock-gate",
+      autoBoot: false,
+      startScheduler: false,
+    });
+
+    expect(app.$options.stores?.some((s) => s.ref === "kv:drafts")).toBe(true);
+    expect(app.$options.stores?.some((s) => s.ref === "index:tasks")).toBe(true);
+    expect(app.$options.clocks?.some((c) => c.name === "daily-digest")).toBe(true);
+    expect(app.$options.gate?.policies?.some((g) => "name" in g && g.name === "member")).toBe(true);
+    expect(app.$options.gate?.policies?.some((g) => "name" in g && g.name === "task:write")).toBe(
+      true,
+    );
+
+    await app.boot({ env: "test" });
+    expect(app.bootResult?.store?.declarations.has("kv:drafts")).toBe(true);
+    expect(app.bootResult?.store?.declarations.has("index:tasks")).toBe(true);
+    expect(app.bootResult?.clock?.declarations.has("daily-digest")).toBe(true);
+    expect(app.bootResult?.gate?.gates.has("member")).toBe(true);
+    expect(app.bootResult?.gate?.gates.has("task:write")).toBe(true);
+  });
+
   test('registry: "consume" (default) drains stores/secrets/signals/channel.templates — a later app does not inherit them', async () => {
     store.sql("leak-app", { schema: {} });
     vault.secret("LEAK_SECRET", { dev: "dev-leak" });
@@ -205,6 +245,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 +265,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.test.ts

@@ -116,9 +116,9 @@ describe("boot — lazy element needs", () => {
         if (raw.byteLength === 0) continue;
         total += Bun.gzipSync(new Uint8Array(raw)).byteLength;
       }
-      // Rebased after 0.12.0 store/http graph growth
-      // (~47.6 kB gzip with export externals).
-      expect(total).toBeLessThan(48_000);
+      // Rebased after clock / gate / kv / index auto-drain on `oke()`.
+      // (~48.3 kB gzip with export externals).
+      expect(total).toBeLessThan(49_000);
     } finally {
       await rm(dir, { recursive: true, force: true });
     }
@@ -227,7 +227,7 @@ describe("boot — HTTP gate wiring on the default path", () => {
     resetBindings();
     resetFlowSeq();
     on(
-      http.get("/ping").gate.public,
+      http.get("/ping").public(),
       flow("ping-public", {
         do: () => ({ ok: true }),
       }),

package/src/kernel/boot.ts

@@ -101,10 +101,10 @@ export interface BootOptions {
   readonly gates?: readonly GateDecl[];
   /**
    * HTTP auth-posture enforcement at boot.
-   * - `"deny"` (default) — every HTTP trigger must carry a gate or `.gate.public`
+   * - `"deny"` (default) — every HTTP trigger must carry a gate or `.public()`
    * - `"allow"` — skips the audit **only** when {@link env} is `"test"`;
    *   ignored in local/prod/docker (never a production-wide bypass).
-   *   Migrate real apps with per-trigger `.gate.public`.
+   *   Migrate real apps with per-trigger `.public()`.
    */
   readonly unguardedHttp?: "deny" | "allow";
   /** Signal declarations. */
@@ -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/effects-stamping.test.ts

@@ -47,7 +47,7 @@ const CreateOut = z.object({ ok: z.boolean() });
 
 function buildUnannotatedCreateFlow(db: ReturnType<typeof store.sql>) {
   return on(
-    http.post("/notes").gate.public,
+    http.post("/notes").public(),
     flow("notes.create", {
       in: CreateIn,
       out: CreateOut,
@@ -140,7 +140,7 @@ describe("boot-level: table-ref resolution stays backward compatible", () => {
     resetFlowSeq();
     const db = store.sql("app", { schema: { notes } });
     const create = on(
-      http.post("/notes").gate.public,
+      http.post("/notes").public(),
       flow("notes.create", {
         in: CreateIn,
         out: CreateOut,
@@ -193,7 +193,7 @@ import { on, flow, http, gate } from "okengine";
 const db = {} as any;
 const notes = {} as any;
 export const create = on(
-  http.post("/notes").gate.public,
+  http.post("/notes").public(),
   flow("notes.create", {
     do: async (input, fx) => {
       await fx.store(db).insert(notes).values({ id: input.id, title: input.title, createdAt: 1 });

package/src/kernel/element-registries.ts

@@ -1,8 +1,9 @@
 /**
- * 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
- * each declare module's `listX()` / `resetX()` pair (mirrors `on.ts`'s
+ * Module-evaluation registries for `store.*`, `vault.secret`,
+ * `vault.env.required`, `signal()`, `clock()`, `gate.policy` / `.scope` /
+ * `.rate`, `channel.<medium>().template()`, and `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).
  *
  * Lives here, not in the declare modules themselves, so {@link oke} can read
@@ -16,6 +17,7 @@
 import type {
   AiAgentDecl,
   AiEmbedDecl,
+  AiMcpServerDecl,
   AiModelDecl,
   AiPromptDecl,
 } from "../elements/ai/declare.ts";
@@ -23,8 +25,10 @@ import type { StoreDecl } from "../elements/store/declare.ts";
 import type { VaultSecretDecl } from "../elements/vault/declare.ts";
 import type { SignalDecl } from "../elements/signal/declare.ts";
 import type { ChannelTemplateDecl } from "../elements/channel/declare.ts";
+import type { ClockDecl } from "../elements/clock/declare.ts";
+import type { GateDecl } from "../elements/gate/declare.ts";
 
-/** `store.sql` / `store.files` declarations since the last reset. */
+/** `store.sql` / `store.kv` / `store.files` / `store.index` declarations since the last reset. */
 export const storeRegistry: StoreDecl[] = [];
 /** `vault.secret` declarations since the last reset. */
 export const secretRegistry: VaultSecretDecl[] = [];
@@ -32,6 +36,10 @@ export const secretRegistry: VaultSecretDecl[] = [];
 export const requiredEnvRegistry: string[] = [];
 /** `signal()` declarations since the last reset. */
 export const signalRegistry: SignalDecl[] = [];
+/** `clock()` declarations since the last reset. */
+export const clockRegistry: ClockDecl[] = [];
+/** `gate.policy` / `gate.scope` / `gate.rate` declarations since the last reset. */
+export const gateRegistry: GateDecl[] = [];
 /** Medium-binder `.template()` declarations since the last reset. */
 export const channelTemplateRegistry: ChannelTemplateDecl[] = [];
 /** `ai.model` declarations since the last reset. */
@@ -42,3 +50,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/errors.ts

@@ -183,6 +183,30 @@ export const OKE_ERRORS = {
     cause: "src/flows/{unit} exists on disk but adopted no flows — the .adopt() barrel is stale.",
     fix: "Run `oke dev` or `oke build` to regenerate `src/flows/generated.ts`.",
   },
+  /**
+   * `http.get()` was never stamped from the file tree — refuse a silent `/`.
+   */
+  HTTP_PATH_UNRESOLVED: {
+    code: 1010,
+    cause: 'Flow "{flow}" bound {method} with no path — the file-tree stamp never ran.',
+    fix: 'Put the file under `src/flows/<unit>/` and import `@/flows/generated`, or pass an explicit path to `http.{method}("/…")`.',
+  },
+  /**
+   * Two HTTP bindings share method + path — last-add-wins is the opposite of this DX.
+   */
+  HTTP_ROUTE_DUPLICATE: {
+    code: 1011,
+    cause: '{method} {path} is bound twice (flow "{flow}").',
+    fix: "Give each HTTP flow a unique method + path.",
+  },
+  /**
+   * Adopted HTTP flow still has no name (`flow({ do })` outside a unit).
+   */
+  HTTP_FLOW_UNNAMED: {
+    code: 1012,
+    cause: "An HTTP flow on {method} {path} has no name.",
+    fix: 'Use `flow("unit.export", {…})` or export it from a `src/flows/<unit>/` file so the tree can stamp `unit.export`.',
+  },
   /**
    * Emit target has no subscriber (unified-theory §21).
    * Thrown at emit when `optional` is false and nobody is subscribed.

package/src/kernel/flow-units.ts

@@ -0,0 +1,64 @@
+/**
+ * Module-evaluation registry for `src/flows/generated.ts`.
+ *
+ * Same consume/ignore posture as `on()` / `listBindings()`: generated.ts
+ * calls {@link registerFlowUnits}; {@link oke} drains the bag into `$routes`
+ * unless `registry: "ignore"`.
+ */
+
+import type { AnyFlowDef } from "./flow.ts";
+import { isFlow } from "./flow.ts";
+
+/** Unit name → export name → Flow. */
+export type FlowUnitBag = {
+  readonly [exportName: string]: unknown;
+};
+
+const pending: Record<string, FlowUnitBag> = {};
+
+/**
+ * Record generated flow units for the next {@link oke} construction.
+ *
+ * @param units - `{ notes, main, … }` from `generated.ts`
+ */
+export function registerFlowUnits(units: Record<string, FlowUnitBag>): void {
+  Object.assign(pending, units);
+}
+
+/**
+ * Drain registered units (consume). Clears the registry.
+ */
+export function consumeRegisteredFlowUnits(): Record<string, FlowUnitBag> {
+  const snap: Record<string, FlowUnitBag> = { ...pending };
+  resetRegisteredFlowUnits();
+  return snap;
+}
+
+/**
+ * Snapshot without clearing (keep / tests).
+ */
+export function peekRegisteredFlowUnits(): Record<string, FlowUnitBag> {
+  return { ...pending };
+}
+
+/**
+ * Clear the unit registry (tests / `registry: "consume"` after drain).
+ */
+export function resetRegisteredFlowUnits(): void {
+  for (const key of Object.keys(pending)) {
+    delete pending[key];
+  }
+}
+
+/**
+ * Collect FlowDefs from a unit bag (skip non-flow exports).
+ *
+ * @param bag - Namespace object
+ */
+export function flowsInUnitBag(bag: FlowUnitBag): AnyFlowDef[] {
+  const found: AnyFlowDef[] = [];
+  for (const value of Object.values(bag)) {
+    if (isFlow(value)) found.push(value);
+  }
+  return found;
+}

package/src/kernel/flow.ts

@@ -239,13 +239,34 @@ export const flowBrand: unique symbol = Symbol("oke.flow");
  * Input / output types are inferred from Standard Schema `in` / `out` when
  * present; otherwise from the `do` handler signature.
  *
+ * A nameless `flow({ do })` is stamped `unit.export` by the file-tree
+ * generator, {@link unit}, or `.adopt()`. Explicit `flow("notes.get", {…})`
+ * still wins.
+ *
+ * @param options - Contract and handler (name stamped later)
+ */
+export function flow<Opts extends FlowOptions<any, any, any>>(
+  options: Opts,
+): FlowDef<InferFlowIn<Opts>, InferFlowOut<Opts>, InferFlowErrors<Opts>>;
+/**
  * @param name - Stable name (used by `fx.call` and the Manifest)
  * @param options - Contract and handler
  */
 export function flow<Opts extends FlowOptions<any, any, any>>(
   name: string,
   options: Opts & { readonly name?: never },
-): FlowDef<InferFlowIn<Opts>, InferFlowOut<Opts>, InferFlowErrors<Opts>> {
+): FlowDef<InferFlowIn<Opts>, InferFlowOut<Opts>, InferFlowErrors<Opts>>;
+export function flow(
+  nameOrOptions: string | FlowOptions<any, any, any>,
+  maybeOptions?: FlowOptions<any, any, any> & { readonly name?: never },
+): FlowDef {
+  const named = typeof nameOrOptions === "string";
+  const name = named ? nameOrOptions : "";
+  const options = (named ? maybeOptions : nameOrOptions) as FlowOptions<any, any, any> | undefined;
+  if (!options || typeof options.do !== "function") {
+    throw new TypeError("flow() expected an options bag with a do handler");
+  }
+
   const triggers: Trigger[] = [];
   const hooks: Partial<Record<HookStage, HookFn[]>> = {};
   const pendingPlugins: PluginDef[] = [];
@@ -253,13 +274,13 @@ export function flow<Opts extends FlowOptions<any, any, any>>(
   const dot = name.indexOf(".");
   const unit = dot > 0 ? name.slice(0, dot) : undefined;
 
-  const def: FlowDef<InferFlowIn<Opts>, InferFlowOut<Opts>, InferFlowErrors<Opts>> = {
+  const def: FlowDef = {
     [flowBrand]: true,
     name,
     unit,
     in: options.in,
     out: options.out,
-    errors: (options.errors ?? undefined) as InferFlowErrors<Opts> | undefined,
+    errors: (options.errors ?? undefined) as FlowErrorMap | undefined,
     effects: options.effects,
     durable: options.durable ?? false,
     retry: options.retry,
@@ -268,17 +289,8 @@ 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>>,
+    compensate: options.compensate as FlowDef["compensate"],
+    do: options.do as FlowHandler,
     triggers,
     $trigger: undefined,
     hooks,
@@ -320,9 +332,9 @@ export function isFlow(value: unknown): value is AnyFlowDef {
 }
 
 /**
- * No-op. `name` is a required positional argument now, so there is no
- * auto-name sequence left to reset — kept so existing test `beforeEach`
- * blocks don't need touching.
+ * No-op. Nameless flows start as `""` and are stamped by unit / adopt /
+ * the file-tree generator — kept so existing test `beforeEach` blocks
+ * don't need touching.
  *
  * @internal
  */

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

package/src/kernel/fx.test.ts

@@ -361,11 +361,17 @@ describe("fx — wholesale swap", () => {
       async emit(signal) {
         calls.push(`emit:${typeof signal === "string" ? signal : signal.name}`);
       },
+      async deadLetters() {
+        return [];
+      },
       async call() {
         return null;
       },
       clock: {
         now: () => 0,
+        ago: () => 0,
+        fromNow: () => 0,
+        duration: () => 0,
         sleep: async () => undefined,
       },
       vault: {
@@ -451,6 +457,9 @@ describe("fx — wholesale swap", () => {
         withQuery(rows) {
           return { [jsonResultBrand]: true, status: 200, value: [...rows], meta: {} };
         },
+        stream(chunks) {
+          return { [jsonResultBrand]: true, kind: "stream" as const, status: 200 as const, chunks };
+        },
       },
       async step(_name, fn) {
         return fn();
@@ -514,6 +523,19 @@ describe("fx.t — catalogs", () => {
   });
 });
 
+describe("fx.clock — relative instants", () => {
+  test("ago / fromNow / duration use the injected now and duration strings", () => {
+    const fx = createFx({ flow: "sessions.sweepExpired", effects: {}, now: () => 1_000_000 });
+    expect(fx.clock.now()).toBe(1_000_000);
+    expect(fx.clock.duration("30d")).toBe(30 * 86_400_000);
+    expect(fx.clock.ago("30d")).toBe(1_000_000 - 30 * 86_400_000);
+    expect(fx.clock.fromNow("14d")).toBe(1_000_000 + 14 * 86_400_000);
+    expect(fx.clock.duration("nope")).toBe(0);
+    expect(fx.clock.ago("nope")).toBe(1_000_000);
+    expect(fx.clock.fromNow("200ms")).toBe(1_000_200);
+  });
+});
+
 describe("fx.json", () => {
   test("with accepts a page or (data, meta)", () => {
     const fx = createFx({ flow: "x", effects: {} });