okengine 0.13.0 → 0.15.2

package/src/elements/clock/runtime.ts

@@ -11,6 +11,7 @@ import type { ClockDecl } from "./declare.ts";
 import { detectDstAmbiguity } from "./dst.ts";
 import { parseDurationMs } from "./duration.ts";
 import { tryAcquireLease } from "./leader.ts";
+import { nextCronFireAt } from "./schedule.ts";
 import {
   createMemoryCronStore,
   effectiveSchedule,
@@ -98,6 +99,13 @@ export interface ClockRuntime {
    * @param name - Cron name
    */
   dstAmbiguity(name: string): Promise<ReturnType<typeof detectDstAmbiguity>>;
+  /**
+   * Register in-process {@link Bun.cron} wakes for declared cron expressions.
+   * No-op on a frozen / time-travel runtime (tests drive {@link tick}).
+   */
+  startWakes(): void;
+  /** Stop every in-process {@link Bun.cron} wake registered by {@link startWakes}. */
+  stopWakes(): void;
 }
 
 /**
@@ -115,6 +123,8 @@ export function createClockRuntime(options: CreateClockRuntimeOptions = {}): Clo
   const handlers = new Map<string, CronHandler>();
   /** The 1s boot scheduler must not stack ticks while a handler is still running. */
   let ticking = false;
+  /** In-process {@link Bun.cron} jobs — precise wake; {@link tick} still owns the lease. */
+  const wakes: Array<{ stop(): void }> = [];
   const driverId: ClockRuntime["driverId"] = timeTravel
     ? "frozen"
     : store.kind === "file"
@@ -154,11 +164,18 @@ export function createClockRuntime(options: CreateClockRuntimeOptions = {}): Clo
 
     // Claim the slot before the handler so a stacked 1s tick cannot re-enter.
     const ranAt = now();
-    const interval = fresh.effectiveEvery ? parseDurationMs(fresh.effectiveEvery) : 0;
+    const sched = effectiveSchedule(fresh);
+    let nextRunAt = fresh.nextRunAt;
+    if (sched.every) {
+      const interval = parseDurationMs(sched.every);
+      if (interval > 0) nextRunAt = ranAt + interval;
+    } else if (sched.cron) {
+      nextRunAt = nextCronFireAt(sched.cron, ranAt, fresh.timezone) ?? fresh.nextRunAt;
+    }
     await store.put({
       ...fresh,
       lastRunAt: ranAt,
-      nextRunAt: interval > 0 ? ranAt + interval : fresh.nextRunAt,
+      nextRunAt,
     });
 
     const handler = handlers.get(name);
@@ -250,6 +267,42 @@ export function createClockRuntime(options: CreateClockRuntimeOptions = {}): Clo
       if (!row?.effectiveCron) return null;
       return detectDstAmbiguity(row.effectiveCron, row.timezone, now());
     },
+    startWakes() {
+      runtime.stopWakes();
+      if (timeTravel) return;
+      for (const decl of declarations.values()) {
+        if (!decl.cron) continue;
+        try {
+          const job = (
+            Bun.cron as (
+              schedule: string,
+              handler: () => unknown,
+              options?: { readonly tz?: string },
+            ) => { stop(): void; unref(): void }
+          )(
+            decl.cron,
+            () => {
+              void runtime.tick();
+            },
+            { tz: decl.timezone },
+          );
+          job.unref();
+          wakes.push(job);
+        } catch {
+          /* invalid expression — 1s tick remains the fallback */
+        }
+      }
+    },
+    stopWakes() {
+      for (const job of wakes) {
+        try {
+          job.stop();
+        } catch {
+          /* already stopped */
+        }
+      }
+      wakes.length = 0;
+    },
   };
 
   return runtime;

package/src/elements/clock/schedule.ts

@@ -1,13 +1,58 @@
 /**
  * Next-occurrence helpers for cron / every schedules (console §9.6 timeline).
  *
- * Supports `every` intervals and simple daily cron (`M H * * *` / `M H * * DOW`).
- * Complex cron expressions fall back to a single `nextRunAt` when present.
+ * Cron math uses {@link Bun.cron.parse} (5-field + nicknames + `{ tz }`).
+ * Interval (`every`) stays on {@link parseDurationMs}.
  */
 
 import { parseDurationMs } from "./duration.ts";
 import { effectiveSchedule, type CronRow } from "./reconcile.ts";
 
+/**
+ * Bun 1.4 `{ tz }` parse — `@types/bun` 1.3.14 only declares two arguments.
+ *
+ * @param expression - 5-field expression or nickname
+ * @param relativeMs - Exclusive start
+ * @param timezone - IANA zone
+ */
+function parseCronNext(expression: string, relativeMs: number, timezone: string): Date | null {
+  return (
+    Bun.cron.parse as (
+      expression: string,
+      relativeDate?: Date | number,
+      options?: { readonly tz?: string },
+    ) => Date | null
+  )(expression, relativeMs, { tz: timezone });
+}
+
+/** Cap walk loops so a `* * * * *` range cannot hang the Console timeline. */
+const MAX_CRON_FIRES = 10_000;
+/** How far back {@link previousOccurrence} searches for a prior cron fire. */
+const PREVIOUS_LOOKBACK_MS = 400 * 86_400_000;
+
+/**
+ * Next matching UTC epoch-ms after `relativeMs`, or `undefined` when the
+ * expression is invalid or has no match within eight years.
+ *
+ * {@link Bun.cron.parse} is exclusive of `relativeMs`.
+ *
+ * @param cron - 5-field expression or nickname (`@hourly`)
+ * @param relativeMs - Search starts after this instant
+ * @param timezone - IANA zone passed as `{ tz }`
+ */
+export function nextCronFireAt(
+  cron: string,
+  relativeMs: number,
+  timezone: string,
+): number | undefined {
+  try {
+    const next = parseCronNext(cron, relativeMs, timezone);
+    return next === null ? undefined : next.getTime();
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Compute fire times in `[from, until)` for a reconciled cron row.
  *
@@ -24,7 +69,7 @@ export function nextOccurrences(row: CronRow, from: number, until: number): read
     return nextEveryOccurrences(row, sched.every, from, until);
   }
   if (sched.cron) {
-    return nextCronOccurrences(row, sched.cron, sched.timezone, from, until);
+    return nextCronOccurrences(sched.cron, row.timezone, from, until);
   }
   return [];
 }
@@ -41,25 +86,12 @@ export function previousOccurrence(row: CronRow, at: number): number | null {
     const interval = parseDurationMs(sched.every);
     if (interval <= 0) return null;
     if (row.lastRunAt === undefined) return null;
-    // Floor to the slot boundary at or before `at`.
     const origin = row.lastRunAt % interval;
     const slot = at - ((at - origin) % interval);
     return slot > 0 ? slot : null;
   }
   if (sched.cron) {
-    const parsed = parseSimpleDaily(sched.cron);
-    if (!parsed) return null;
-    // Walk back up to 400 days for a prior civil fire.
-    for (let day = 1; day <= 400; day++) {
-      const probe = at - day * 86_400_000;
-      const local = zonedParts(probe, sched.timezone);
-      if (local.hour === parsed.hour && local.minute === parsed.minute) {
-        // Align to that local wall time's UTC instant near `probe`.
-        const fires = civilFiresOnDay(local.date, parsed, sched.timezone);
-        const prior = fires.filter((t) => t <= at).pop();
-        if (prior !== undefined) return prior;
-      }
-    }
+    return previousCronFire(sched.cron, row.timezone, at);
   }
   return null;
 }
@@ -77,11 +109,10 @@ export function countMissedOccurrences(row: CronRow, from: number, until: number
   if (sched.every) {
     const interval = parseDurationMs(sched.every);
     if (interval <= 0) return 0;
-    return Math.max(0, Math.floor((until - from) / interval) - 0);
+    return Math.max(0, Math.floor((until - from) / interval));
   }
   if (sched.cron) {
-    // Count fires in (from, until].
-    const fires = nextCronOccurrences(row, sched.cron, sched.timezone, from + 1, until + 1);
+    const fires = nextCronOccurrences(sched.cron, row.timezone, from + 1, until + 1);
     return fires.filter((t) => t > from && t <= until).length;
   }
   return 0;
@@ -102,145 +133,43 @@ function nextEveryOccurrences(
       : row.lastRunAt !== undefined
         ? row.lastRunAt + interval
         : from;
-  // If still in the past relative to `from`, advance to first >= from.
   while (t < from) t += interval;
   while (t < until) {
     out.push(t);
     t += interval;
-    if (out.length > 10_000) break;
+    if (out.length > MAX_CRON_FIRES) break;
   }
   return out;
 }
 
 function nextCronOccurrences(
-  row: CronRow,
   cron: string,
   timezone: string,
   from: number,
   until: number,
 ): readonly number[] {
-  const parsed = parseSimpleDaily(cron);
-  if (!parsed) {
-    if (row.nextRunAt !== undefined && row.nextRunAt >= from && row.nextRunAt < until) {
-      return [row.nextRunAt];
-    }
-    return [];
-  }
-
   const out: number[] = [];
-  const start = new Date(from);
-  for (let day = 0; day < 400; day++) {
-    const probe = Date.UTC(
-      start.getUTCFullYear(),
-      start.getUTCMonth(),
-      start.getUTCDate() + day,
-      12,
-      0,
-      0,
-    );
-    if (probe > until + 86_400_000) break;
-    const local = zonedParts(probe, timezone);
-    const fires = civilFiresOnDay(local.date, parsed, timezone);
-    for (const t of fires) {
-      if (t >= from && t < until) out.push(t);
-    }
-    if (out.length > 10_000) break;
+  // parse is exclusive of the cursor — step back 1ms so `from` itself can match.
+  let cursor = from - 1;
+  while (out.length < MAX_CRON_FIRES) {
+    const t = nextCronFireAt(cron, cursor, timezone);
+    if (t === undefined || t >= until) break;
+    if (t >= from) out.push(t);
+    cursor = t;
   }
-  return out.sort((a, b) => a - b);
-}
-
-/** Parsed simple daily cron. */
-interface SimpleDaily {
-  readonly minute: number;
-  readonly hour: number;
-  readonly dow?: number;
+  return out;
 }
 
-function parseSimpleDaily(cron: string): SimpleDaily | null {
-  const parts = cron.trim().split(/\s+/);
-  if (parts.length < 5) return null;
-  const minute = parts[0]!;
-  const hour = parts[1]!;
-  const dom = parts[2]!;
-  const mon = parts[3]!;
-  const dow = parts[4]!;
-  if (!/^\d+$/.test(minute) || !/^\d+$/.test(hour)) return null;
-  if (dom !== "*" || mon !== "*") return null;
-  const m = Number(minute);
-  const h = Number(hour);
-  if (m < 0 || m > 59 || h < 0 || h > 23) return null;
-  if (dow === "*") return { minute: m, hour: h };
-  if (/^\d+$/.test(dow)) {
-    const d = Number(dow);
-    if (d < 0 || d > 6) return null;
-    return { minute: m, hour: h, dow: d };
+function previousCronFire(cron: string, timezone: string, at: number): number | null {
+  let cursor = at - PREVIOUS_LOOKBACK_MS;
+  let prev: number | null = null;
+  let steps = 0;
+  while (steps < MAX_CRON_FIRES) {
+    const t = nextCronFireAt(cron, cursor, timezone);
+    if (t === undefined || t >= at) break;
+    prev = t;
+    cursor = t;
+    steps++;
   }
-  return null;
-}
-
-function civilFiresOnDay(
-  dateStr: string,
-  parsed: SimpleDaily,
-  timezone: string,
-): readonly number[] {
-  const matches: number[] = [];
-  const base = Date.parse(`${dateStr}T00:00:00.000Z`);
-  if (Number.isNaN(base)) return [];
-
-  for (let offsetMin = -14 * 60; offsetMin <= 14 * 60; offsetMin += 15) {
-    const utc = base + parsed.hour * 3_600_000 + parsed.minute * 60_000 - offsetMin * 60_000;
-    const local = zonedParts(utc, timezone);
-    if (local.date === dateStr && local.hour === parsed.hour && local.minute === parsed.minute) {
-      if (parsed.dow !== undefined) {
-        const localDow = zonedDow(utc, timezone);
-        if (localDow !== parsed.dow) continue;
-      }
-      if (!matches.includes(utc)) matches.push(utc);
-    }
-  }
-  return matches;
-}
-
-interface ZonedParts {
-  readonly date: string;
-  readonly hour: number;
-  readonly minute: number;
-}
-
-function zonedParts(utcMs: number, timezone: string): ZonedParts {
-  const fmt = new Intl.DateTimeFormat("en-US", {
-    timeZone: timezone,
-    year: "numeric",
-    month: "2-digit",
-    day: "2-digit",
-    hour: "2-digit",
-    minute: "2-digit",
-    hourCycle: "h23",
-  });
-  const parts = fmt.formatToParts(new Date(utcMs));
-  const get = (type: Intl.DateTimeFormatPartTypes): string =>
-    parts.find((p) => p.type === type)?.value ?? "0";
-  return {
-    date: `${get("year")}-${get("month")}-${get("day")}`,
-    hour: Number(get("hour")),
-    minute: Number(get("minute")),
-  };
-}
-
-function zonedDow(utcMs: number, timezone: string): number {
-  const fmt = new Intl.DateTimeFormat("en-US", {
-    timeZone: timezone,
-    weekday: "short",
-  });
-  const w = fmt.format(new Date(utcMs));
-  const map: Record<string, number> = {
-    Sun: 0,
-    Mon: 1,
-    Tue: 2,
-    Wed: 3,
-    Thu: 4,
-    Fri: 5,
-    Sat: 6,
-  };
-  return map[w] ?? 0;
+  return prev;
 }

package/src/elements/clock.test.ts

@@ -466,8 +466,9 @@ describe("DST ambiguity", () => {
     expect(doctorSrc).not.toMatch(/detectDstAmbiguity/);
   });
 
-  test("overlap day: two civil instants; lease does not span the gap; stub isDue avoids walk", async () => {
-    // US fall-back 2026-11-01: 01:30 local occurs twice (~1h apart in UTC).
+  test("overlap day: crontab fires once; next slot is the following day", async () => {
+    // US fall-back 2026-11-01: 01:30 local occurs twice. Bun.cron.parse
+    // matches crontab — a fixed wall time fires at the first occurrence only.
     const from = Date.UTC(2026, 10, 1, 0, 0, 0);
     const until = Date.UTC(2026, 10, 2, 0, 0, 0);
     const fires = nextOccurrences(
@@ -481,13 +482,11 @@ describe("DST ambiguity", () => {
       from,
       until,
     );
-    expect(fires.length).toBe(2);
-    expect(fires[1]! - fires[0]!).toBe(3_600_000);
+    expect(fires).toHaveLength(1);
+    expect(fires[0]).toBe(Date.UTC(2026, 10, 1, 5, 30, 0));
 
-    // Stub isDue (nextRunAt unset after first fire): does not walk civil fires →
-    // advancing across the overlap gap does not double-fire.
     const store = createMemoryCronStore();
-    const rt = createTestClockRuntime(0, {
+    const rt = createTestClockRuntime(fires[0]! - 1, {
       store,
       instanceId: "dst-fire",
       leaseMs: 1_000,
@@ -503,43 +502,13 @@ describe("DST ambiguity", () => {
     rt.onCron("ambig", () => {
       ran.push(rt.now());
     });
+    rt.advance(2);
     expect((await rt.tick()).ran).toEqual(["ambig"]);
     rt.advance(3_600_000);
     expect((await rt.tick()).ran).toEqual([]);
     expect(ran).toHaveLength(1);
-
-    // Lease TTL << 1h overlap gap: if nextRunAt is driven to the second civil
-    // instant, a second fire CAN occur. Leader lease is not a DST policy.
-    const store2 = createMemoryCronStore();
-    const rt2 = createTestClockRuntime(fires[0]! - 1, {
-      store: store2,
-      instanceId: "dst-risk",
-      leaseMs: 1_000,
-    });
-    rt2.register(
-      clock("ambig2", {
-        cron: "30 1 * * *",
-        timezone: "America/New_York",
-      }),
-    );
-    await rt2.reconcile();
-    await store2.put({
-      ...(await store2.get("ambig2"))!,
-      nextRunAt: fires[0],
-    });
-    const ran2: number[] = [];
-    rt2.onCron("ambig2", () => {
-      ran2.push(rt2.now());
-    });
-    rt2.advance(2);
-    expect((await rt2.tick()).ran).toEqual(["ambig2"]);
-    rt2.advance(fires[1]! - rt2.now());
-    await store2.put({
-      ...(await store2.get("ambig2"))!,
-      nextRunAt: fires[1],
-    });
-    expect((await rt2.tick()).ran).toEqual(["ambig2"]);
-    expect(ran2).toHaveLength(2);
+    const after = await store.get("ambig");
+    expect(after?.nextRunAt).toBeGreaterThan(fires[0]! + 3_600_000);
   });
 });
 

package/src/elements/clock.ts

@@ -50,7 +50,12 @@ export { runDurable, type DurableResult, type RunDurableOptions } from "./clock/
 
 export { cronHealth, type CatchUpPolicy, type CronHealth } from "./clock/health.ts";
 
-export { nextOccurrences, previousOccurrence, countMissedOccurrences } from "./clock/schedule.ts";
+export {
+  nextOccurrences,
+  previousOccurrence,
+  countMissedOccurrences,
+  nextCronFireAt,
+} from "./clock/schedule.ts";
 
 export {
   pauseCron,

package/src/elements/gate/boot.ts

@@ -1,9 +1,9 @@
 /**
  * Gate boot audit — every HTTP trigger must declare auth posture.
  *
- * Fail loud: missing gate and missing {@link gate.public} → {@link GateBootError}.
+ * Fail loud: missing gate and missing `.public()` → {@link GateBootError}.
  * `unguardedHttp: "allow"` is honoured **only** when `env === "test"` — never a
- * production-wide bypass. Migrate real apps with per-trigger `gate.public`.
+ * production-wide bypass. Migrate real apps with per-trigger `.public()`.
  */
 
 import { GATE_PUBLIC_NAME } from "./declare.ts";
@@ -19,7 +19,7 @@ export interface GatePostureGap {
 }
 
 /**
- * Thrown when HTTP triggers omit both a gate chain and {@link gate.public}.
+ * Thrown when HTTP triggers omit both a gate chain and `.public()`.
  * Lists every gap (Vault-style — fail once with the full set).
  */
 export class GateBootError extends Error {
@@ -28,7 +28,7 @@ export class GateBootError extends Error {
   constructor(gaps: readonly GatePostureGap[]) {
     const lines = gaps.map((g) => `  - ${g.flowId} ${g.method} ${g.path}`);
     super(
-      `gate boot failed — ${gaps.length} HTTP trigger(s) missing auth posture (attach a gate or gate.public):\n${lines.join("\n")}`,
+      `gate boot failed — ${gaps.length} HTTP trigger(s) missing auth posture (attach a gate or .public()):\n${lines.join("\n")}`,
     );
     this.name = "GateBootError";
     this.gaps = gaps;
@@ -84,7 +84,7 @@ export function hasHttpGatePosture(
 }
 
 /**
- * Collect HTTP triggers with neither a gate nor {@link gate.public}.
+ * Collect HTTP triggers with neither a gate nor `.public()`.
  *
  * @param bindings - Adopted / registered bindings
  */

package/src/elements/gate/declare.ts

@@ -5,6 +5,7 @@
  */
 
 import type { RateStrategy } from "../../manifest/types.ts";
+import { gateRegistry } from "../../kernel/element-registries.ts";
 import { DEFAULT_RATE_STRATEGY } from "./constants.ts";
 import { GATE_PUBLIC_NAME, type GateAllDecl, type GateMember } from "./flatten.ts";
 
@@ -89,6 +90,29 @@ export interface RateGateDecl {
 /** Declared gate handle. */
 export type GateDecl = PolicyGateDecl | RateGateDecl;
 
+/**
+ * `gate.policy` / `gate.scope` / `gate.rate` push into the shared
+ * {@link gateRegistry} (`src/kernel/element-registries.ts`) so {@link oke}
+ * can auto-populate `gate.policies` with zero explicit array — mirrors the
+ * {@link on} trigger-drain registry (`src/kernel/on.ts`). `gate.public` is
+ * built into the runtime; `gate.all` is a composition of already-registered
+ * members.
+ *
+ * Snapshot of every policy / rate declared since the last reset.
+ */
+export function listGates(): readonly GateDecl[] {
+  return gateRegistry.slice();
+}
+
+/**
+ * Clear the gate registry (tests / fresh app adopt).
+ *
+ * @internal
+ */
+export function resetGates(): void {
+  gateRegistry.length = 0;
+}
+
 /**
  * Shape of the {@link gate} element namespace.
  */
@@ -151,9 +175,11 @@ export const gate: GateNamespace = {
       );
     }
     if (typeof checkOrOptions === "function") {
-      return { kind: "policy", name, check: checkOrOptions };
+      const decl: PolicyGateDecl = { kind: "policy", name, check: checkOrOptions };
+      gateRegistry.push(decl);
+      return decl;
     }
-    return {
+    const decl: PolicyGateDecl = {
       kind: "policy",
       name,
       check: checkOrOptions.check,
@@ -161,6 +187,8 @@ export const gate: GateNamespace = {
         ? { description: checkOrOptions.description }
         : {}),
     };
+    gateRegistry.push(decl);
+    return decl;
   },
 
   /**
@@ -172,12 +200,14 @@ export const gate: GateNamespace = {
     if (name === GATE_PUBLIC_NAME) {
       throw new TypeError('gate.scope: name "public" is reserved — use gate.public');
     }
-    return {
+    const decl: PolicyGateDecl = {
       kind: "policy",
       name,
       check: ({ auth }) => auth.scopes.has(name),
       scopes: [name],
     };
+    gateRegistry.push(decl);
+    return decl;
   },
 
   public: {
@@ -201,7 +231,7 @@ export const gate: GateNamespace = {
     }
     const strategy = options.strategy ?? DEFAULT_RATE_STRATEGY;
     const name = `rate:${strategy}:${options.max}/${options.per}`;
-    return {
+    const decl: RateGateDecl = {
       kind: "rate",
       name,
       strategy,
@@ -211,6 +241,8 @@ export const gate: GateNamespace = {
       overridable: options.overridable ?? false,
       ...(options.description !== undefined ? { description: options.description } : {}),
     };
+    gateRegistry.push(decl);
+    return decl;
   },
 
   /**

package/src/elements/gate/flatten.ts

@@ -7,7 +7,7 @@
 
 import type { GateDecl } from "./declare.ts";
 
-/** Reserved policy name for `gate.public` / `.gate.public`. */
+/** Reserved policy name for `gate.public` / `.public()`. */
 export const GATE_PUBLIC_NAME = "public";
 
 /** Member of `gate.all` — a policy/rate or a nested `all` handle. */

package/src/elements/gate/runtime.ts

@@ -70,7 +70,7 @@ export interface GateRuntime {
  */
 export function createGateRuntime(options: CreateGateRuntimeOptions = {}): GateRuntime {
   const map = new Map<string, GateDecl>();
-  // Built-in sentinel — `.gate.public` works without listing it in `oke({ gates })`.
+  // Built-in sentinel — `.public()` works without listing it in `oke({ gates })`.
   map.set(gate.public.name, gate.public);
   for (const g of options.gates ?? []) {
     if (isGateAllDecl(g)) {

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";