okengine 0.9.0 → 0.10.0

package/src/elements/channel/whatsapp-compliance.test.ts

@@ -0,0 +1,124 @@
+/**
+ * WhatsApp Business characterization (Known gap freeze):
+ * - drivers pick template vs free-text by presence of message.template only
+ * - Channel runtime has no 24h session-window API
+ *
+ * Meta requires free-form session messages inside a customer-initiated 24h
+ * window and pre-approved templates outside it. OKE does not enforce that
+ * window today — this file freezes the current payload-shape behavior so the
+ * gap cannot silently look fixed without a real design.
+ */
+
+import { describe, expect, test } from "bun:test";
+import type {
+  ChannelDriver,
+  ChannelMessage,
+  ChannelSendResult,
+} from "../../drivers/channel-types.ts";
+import { channel, createChannelRuntime } from "../channel.ts";
+
+type Captured =
+  | { kind: "template"; name: string; language: string; to: string }
+  | { kind: "text"; text: string; to: string };
+
+function fakeWhatsAppDriver(captures: Captured[]): ChannelDriver {
+  const channelTransport = {
+    provider: "wa-cloud",
+    mediums: ["whatsapp" as const],
+    async send(message: ChannelMessage): Promise<ChannelSendResult> {
+      const templateName =
+        message.template ??
+        (typeof message.data?.template === "string" ? message.data.template : undefined);
+      const language =
+        message.locale ??
+        (typeof message.data?.language === "string" ? message.data.language : "en_US");
+
+      if (templateName) {
+        captures.push({
+          kind: "template",
+          name: templateName,
+          language,
+          to: message.to,
+        });
+      } else {
+        captures.push({
+          kind: "text",
+          text: message.text ?? "",
+          to: message.to,
+        });
+      }
+
+      return {
+        ok: true,
+        messageId: "wa-1",
+        driverId: "wa-cloud",
+        attempts: [{ driverId: "wa-cloud", ok: true, at: Date.now(), messageId: "wa-1" }],
+      };
+    },
+  };
+
+  return {
+    id: "wa-cloud",
+    channel: channelTransport,
+    whatsappTransport: {
+      provider: "wa-cloud",
+      async send() {
+        return { messageId: "x", to: "", status: "sent", response: "" };
+      },
+    },
+  };
+}
+
+describe("WhatsApp session vs template (characterization)", () => {
+  test("template name on the send path selects template payload shape", async () => {
+    const captures: Captured[] = [];
+    const runtime = createChannelRuntime({
+      templates: [channel.template("order-update", { medium: "whatsapp" })],
+      drivers: [fakeWhatsAppDriver(captures)],
+      catalog: {
+        "order-update": { en: { text: "Your order shipped" } },
+      },
+    });
+
+    await runtime.send("order-update", {
+      to: "+966500000000",
+      locale: "en_US",
+    });
+
+    expect(captures).toEqual([
+      {
+        kind: "template",
+        name: "order-update",
+        language: "en_US",
+        to: "+966500000000",
+      },
+    ]);
+  });
+
+  test("missing template name sends free-text (no session-window gate)", async () => {
+    const captures: Captured[] = [];
+    // Medium-agnostic path that still hits channel transport without a template
+    // name on ChannelMessage — simulate driver-level choice when template unset.
+    const driver = fakeWhatsAppDriver(captures);
+    const result = await driver.channel!.send({
+      medium: "whatsapp",
+      to: "+966500000000",
+      text: "Hello from session",
+      // no template field — free-form
+    });
+
+    expect(result.ok).toBe(true);
+    expect(captures).toEqual([{ kind: "text", text: "Hello from session", to: "+966500000000" }]);
+  });
+
+  test("ChannelRuntime has no session-window surface", () => {
+    const runtime = createChannelRuntime({});
+    const keys = Object.keys(runtime);
+    expect(keys).not.toContain("sessionWindow");
+    expect(keys).not.toContain("whatsappSession");
+    expect(keys).not.toContain("withinSessionWindow");
+    expect(typeof (runtime as { withinSessionWindow?: unknown }).withinSessionWindow).toBe(
+      "undefined",
+    );
+  });
+});

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 ?? [];
+  const reads = (effects.reads ?? []).filter((r): r is ResourceRef => r !== "runs");
   return reads.map((resource) => computedCacheKey(resource, dimsByResource?.[resource]));
 }
 

package/src/elements/store/emit-drizzle.ts

@@ -5,8 +5,9 @@
  * watch) when abstract decls exist — not a third schema CLI.
  */
 
+import { existsSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join } from "node:path";
 import type { TableContribution } from "../../kernel/plugin.ts";
 import {
   isFieldBuilder,
@@ -30,10 +31,16 @@ export type SqlDialect = "sqlite" | "postgres";
 export const GENERATED_SCHEMA_HEADER = "// generated by oke — do not edit";
 
 /** Default output path (relative to project root). */
-export const DEFAULT_GENERATED_SCHEMA_REL = "src/schema.generated.ts";
+export const DEFAULT_GENERATED_SCHEMA_REL = "src/db/schema.generated.ts";
 
 /** Default declaration module path (relative to project root). */
-export const DEFAULT_DECLARE_SCHEMA_REL = "src/schema.decl.ts";
+export const DEFAULT_DECLARE_SCHEMA_REL = "src/db/schema.decl.ts";
+
+/** Legacy paths kept so pre-layout projects keep resolving. */
+export const LEGACY_GENERATED_SCHEMA_REL = "src/schema.generated.ts";
+
+/** @see LEGACY_GENERATED_SCHEMA_REL */
+export const LEGACY_DECLARE_SCHEMA_REL = "src/schema.decl.ts";
 
 /**
  * Map a store.sql driver id to an emit dialect.
@@ -306,8 +313,16 @@ export async function maybeEmitDomainSchema(
   options: EmitDomainSchemaOptions,
 ): Promise<{ readonly emitted: boolean; readonly path?: string; readonly tableCount?: number }> {
   const cwd = options.cwd;
-  const declareRel = options.declarePath ?? DEFAULT_DECLARE_SCHEMA_REL;
-  const declareAbs = resolve(cwd, declareRel);
+  const resolved = resolveEmitPaths(cwd, {
+    ...(options.declarePath !== undefined ? { declare: options.declarePath } : {}),
+    ...(options.outPath !== undefined ? { generated: options.outPath } : {}),
+  });
+  const declareAbs = resolved.declarePath;
+  const outAbs = resolved.outPath;
+  const declareRel = declareAbs.startsWith(`${cwd}/`)
+    ? declareAbs.slice(cwd.length + 1)
+    : declareAbs;
+  const outRel = outAbs.startsWith(`${cwd}/`) ? outAbs.slice(cwd.length + 1) : outAbs;
   const declareFile = Bun.file(declareAbs);
 
   let appTables: SchemaTableDecl[] = [];
@@ -332,8 +347,6 @@ export async function maybeEmitDomainSchema(
   }
 
   const tables = mergeSchemaTables(appTables, fromPlugins);
-  const outRel = options.outPath ?? DEFAULT_GENERATED_SCHEMA_REL;
-  const outAbs = resolve(cwd, outRel);
   const source = emitDrizzleSource(tables, options.dialect, { relations: appRelations });
   await mkdir(dirname(outAbs), { recursive: true });
   await writeFile(outAbs, source, "utf8");
@@ -345,6 +358,7 @@ export async function maybeEmitDomainSchema(
 
 /**
  * Resolve declare/out paths from an optional db config slice.
+ * Prefers explicit config, then new `src/db/*` defaults, then legacy `src/*`.
  *
  * @param cwd - Project root
  * @param db - Config `db` block
@@ -353,9 +367,29 @@ export function resolveEmitPaths(
   cwd: string,
   db?: { readonly declare?: string; readonly generated?: string },
 ): { readonly declarePath: string; readonly outPath: string } {
+  let declareRel = db?.declare;
+  if (!declareRel) {
+    if (existsSync(join(cwd, DEFAULT_DECLARE_SCHEMA_REL))) {
+      declareRel = DEFAULT_DECLARE_SCHEMA_REL;
+    } else if (existsSync(join(cwd, LEGACY_DECLARE_SCHEMA_REL))) {
+      declareRel = LEGACY_DECLARE_SCHEMA_REL;
+    } else {
+      declareRel = DEFAULT_DECLARE_SCHEMA_REL;
+    }
+  }
+
+  let outRel = db?.generated;
+  if (!outRel) {
+    const preferLegacy =
+      declareRel === LEGACY_DECLARE_SCHEMA_REL ||
+      (!existsSync(join(cwd, DEFAULT_DECLARE_SCHEMA_REL)) &&
+        existsSync(join(cwd, LEGACY_GENERATED_SCHEMA_REL)));
+    outRel = preferLegacy ? LEGACY_GENERATED_SCHEMA_REL : DEFAULT_GENERATED_SCHEMA_REL;
+  }
+
   return {
-    declarePath: join(cwd, db?.declare ?? DEFAULT_DECLARE_SCHEMA_REL),
-    outPath: join(cwd, db?.generated ?? DEFAULT_GENERATED_SCHEMA_REL),
+    declarePath: join(cwd, declareRel),
+    outPath: join(cwd, outRel),
   };
 }
 

package/src/elements/store/runtime.ts

@@ -473,7 +473,7 @@ export function createStoreRuntime(options: CreateStoreRuntimeOptions): StoreRun
     },
     putTier1(effects, value, dimsByResource) {
       const keys = tier1KeysForReads(effects, dimsByResource);
-      const resources = effects.reads ?? [];
+      const resources = (effects.reads ?? []).filter((r): r is ResourceRef => r !== "runs");
       for (const key of keys) {
         cache.set({
           tier: 1,

package/src/elements/store/schema-decl.test.ts

@@ -39,6 +39,8 @@ describe("store.schema.table + field.*", () => {
     expect(notes.columns.createdAt.sqlType).toBe("integer");
     expect(notes.columns.id.defaultFnKind).toBe("id");
     expect(notes.columns.createdAt.defaultFnKind).toBe("now");
+    expect(typeof notes.id.getSQL).toBe("function");
+    expect(() => notes.id.getSQL()).toThrow(/type bridge/);
   });
 
   test("PII masks via declaration path without Drizzle metadata", async () => {

package/src/elements/store/schema-decl.ts

@@ -34,6 +34,10 @@ export interface ColumnReference {
 /**
  * Finalized column declaration — also satisfies {@link ColumnDef} so
  * {@link classificationsFromTable} / runtime masking work without Drizzle.
+ *
+ * `getSQL` is a structural bridge so drizzle-orm operators (`eq`, `isNull`, …)
+ * accept abstract columns in TypeScript. OKE’s SQL compiler never calls it —
+ * it reads {@link SchemaColumnDecl.sqlName} / metadata directly.
  */
 export interface SchemaColumnDecl extends ColumnDef {
   /** JS object key (e.g. `createdAt`). */
@@ -57,6 +61,12 @@ export interface SchemaColumnDecl extends ColumnDef {
   readonly references?: ColumnReference;
   /** Optional human description for Console / docs (falls back to the JS key). */
   readonly description?: string;
+  /**
+   * Drizzle `SQLWrapper` structural match — never invoked at runtime.
+   *
+   * @returns never (throws if called)
+   */
+  getSQL(): never;
 }
 
 /** Table from {@link store.schema.table} — extends {@link TableHandle}. */
@@ -171,6 +181,11 @@ function createBuilder(state: FieldState): FieldBuilder {
         ...(state.classification ? { classification: state.classification } : {}),
         ...(state.description !== undefined ? { description: state.description } : {}),
         ...(state.references ? { references: state.references } : {}),
+        getSQL(): never {
+          throw new Error(
+            `SchemaColumnDecl.getSQL("${sqlName}") is a type bridge — OKE compiles columns directly`,
+          );
+        },
       };
     },
   };

package/src/elements/store/seed.ts

@@ -30,7 +30,7 @@ export interface SeedDef {
 export type SeedCategory = "dev" | "prod";
 
 /**
- * Freeze a seed declaration for `src/seed/index.ts` default export.
+ * Freeze a seed declaration for `src/db/seed/index.ts` default export.
  *
  * @param def - Essential / dev / prod function bags
  */

package/src/index.ts

@@ -141,6 +141,7 @@ export {
   channel,
   createChannelRuntime,
   createConsentStore,
+  createSuppressionStore,
   createReceiptLedger,
   type ChannelTemplateDecl,
   type ChannelRuntime,

package/src/kernel/app.ts

@@ -59,7 +59,9 @@ import {
   logDevRequest,
   shouldLogDevRequests,
 } from "../runtime/dev-request-log.ts";
+import { fail, type FlowFailure } from "./errors.ts";
 import {
+  isFlowFailure,
   mergeHooks,
   runPipeline,
   type HookFn,
@@ -359,6 +361,10 @@ export interface OkeApp<D extends Record<string, unknown> = {}, R extends AppRou
       readonly operator?: FxOperator;
       /** Pre-resolved principal (either plane). */
       readonly principal?: ResolvedPrincipal;
+      /** Parent WideEvent id when this execution was caused by another. */
+      readonly parentId?: string;
+      /** Explicit run / WideEvent id (defaults to a new UUID). */
+      readonly runId?: string;
     },
   ): Promise<ExecuteResult>;
   /**
@@ -381,8 +387,13 @@ export interface OkeApp<D extends Record<string, unknown> = {}, R extends AppRou
    *
    * @param signal - Signal name or handle
    * @param payload - Payload
+   * @param meta - Optional envelope from the bus (producer run id)
    */
-  dispatchSignal(signal: NamedRef, payload?: unknown): Promise<ExecuteResult[]>;
+  dispatchSignal(
+    signal: NamedRef,
+    payload?: unknown,
+    meta?: { readonly parentRunId?: string; readonly messageId?: string },
+  ): Promise<ExecuteResult[]>;
   /**
    * Invoke all flows bound to an `every` interval.
    *
@@ -637,8 +648,12 @@ export function oke(options: OkeOptions): OkeApp {
     }
   }
 
-  async function handleSignalFire(name: string, payload: unknown): Promise<void> {
-    await app.dispatchSignal(name, payload);
+  async function handleSignalFire(
+    name: string,
+    payload: unknown,
+    meta?: { readonly parentRunId?: string; readonly messageId?: string },
+  ): Promise<void> {
+    await app.dispatchSignal(name, payload, meta);
   }
 
   async function handleDurableResume(): Promise<void> {
@@ -844,7 +859,7 @@ export function oke(options: OkeOptions): OkeApp {
     };
     const result = await bootApplication(merged);
     bootResult = result;
-    // otp() Tier 1 / Tier 2 capability — fail loud at boot, never silent downgrade.
+    // otp() provider / app mode capability — fail loud at boot, never silent downgrade.
     if (result.channel) {
       const { assertOtpPluginCapability } = await import("../auth/otp-capability.ts");
       for (const entry of pluginRegistry.installed) {
@@ -918,6 +933,10 @@ export function oke(options: OkeOptions): OkeApp {
       readonly originPrincipal?: FxPrincipal;
       /** Explicit locale override for {@link Fx.t} / channel sends. */
       readonly locale?: string;
+      /** Parent WideEvent id when this execution was caused by another. */
+      readonly parentId?: string;
+      /** Explicit run / WideEvent id (defaults to a new UUID). */
+      readonly runId?: string;
     },
   ): Promise<ExecuteResult> {
     registerFlow(flowDef);
@@ -957,6 +976,8 @@ export function oke(options: OkeOptions): OkeApp {
       readonly principal?: ResolvedPrincipal;
       readonly originPrincipal?: FxPrincipal;
       readonly locale?: string;
+      readonly parentId?: string;
+      readonly runId?: string;
     };
     readonly resolvedLocale: string;
     readonly defaultLocale: string;
@@ -991,6 +1012,15 @@ export function oke(options: OkeOptions): OkeApp {
     const now = options.fx?.now ?? booted?.clock?.now ?? (() => Date.now());
     const startedAt = now();
     const telemetry = createRunTelemetry();
+    const inboundId =
+      extras?.request?.headers.get("x-request-id")?.trim() ||
+      extras?.request?.headers.get("x-correlation-id")?.trim() ||
+      undefined;
+    const runId =
+      extras?.runId ??
+      (inboundId && inboundId.length > 0 ? inboundId : undefined) ??
+      crypto.randomUUID();
+    const parentId = extras?.parentId;
 
     // Element pipeline wiring only kicks in once booted — `autoBoot: false`
     // keeps intentional pre-boot unit tests ungated (no elements either).
@@ -1057,6 +1087,7 @@ export function oke(options: OkeOptions): OkeApp {
         const journal = createJournal({
           store,
           now,
+          id: () => runId,
           // Hold the run lease for the request's lifetime — a crash mid-run
           // leaves an expired lease another instance can reclaim and resume.
           ...(hasJournalLease(store) ? { lease: { instanceId, leaseMs } } : {}),
@@ -1071,6 +1102,7 @@ export function oke(options: OkeOptions): OkeApp {
       flow: flowDef.name,
       effects: flowDef.effects,
       runTelemetry: telemetry,
+      runId,
       now,
       i18n: {
         locale: resolvedLocale,
@@ -1090,6 +1122,7 @@ export function oke(options: OkeOptions): OkeApp {
             aiRuntime: booted.ai,
           }
         : {}),
+      runsRuntime: booted?.runs ?? (isRunsRuntimeLike(options.runs) ? options.runs : undefined),
       ...(journalSession ? { journal: journalSession, durable: true } : {}),
       callHandler: async (name, callInput) => {
         const target = flowsByName.get(name);
@@ -1103,6 +1136,7 @@ export function oke(options: OkeOptions): OkeApp {
           {
             originPrincipal: freezePrincipal(fx.principal),
             locale: resolvedLocale,
+            parentId: runId,
           },
         );
         if (inner.failure) return inner.failure;
@@ -1174,10 +1208,32 @@ export function oke(options: OkeOptions): OkeApp {
           input: ctx.input,
           wakeAt: sleeping.wakeAt,
         });
-      } else if (!sleeping && result.failure) {
-        await journalSession.commit("failed", {
-          error: result.failure.error.code,
-        });
+      } else if (!sleeping && isTerminalFailure(result)) {
+        const terminalErr = result.failure ?? result.ctx.error;
+        if (flowDef.compensate) {
+          try {
+            const completedSteps = journalSession.run.entries
+              .filter((e) => e.kind === "step")
+              .map((e) => e.name);
+            await flowDef.compensate(
+              {
+                input: ctx.input as never,
+                error: terminalErr,
+                completedSteps,
+              },
+              fx,
+            );
+          } catch (compErr) {
+            await journalSession.commit("failed", {
+              error: `compensate:${failureCodeOf(compErr)}`,
+            });
+          }
+        }
+        if (journalSession.run.status === "running") {
+          await journalSession.commit("failed", {
+            error: failureCodeOf(terminalErr),
+          });
+        }
       } else if (!sleeping) {
         await journalSession.commit("completed", { output: result.output });
       }
@@ -1187,6 +1243,10 @@ export function oke(options: OkeOptions): OkeApp {
       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,
@@ -1196,7 +1256,10 @@ export function oke(options: OkeOptions): OkeApp {
           telemetry,
           startedAt,
           endedAt,
-          failure: result.failure,
+          failure: recordFailure,
+          id: runId,
+          input: replayInput,
+          ...(parentId !== undefined ? { parentId } : {}),
         },
         archiveCleartext,
       );
@@ -1480,12 +1543,16 @@ export function oke(options: OkeOptions): OkeApp {
 
       return respond(encodeExecuteResult(result));
     },
-    async dispatchSignal(signal, payload) {
+    async dispatchSignal(signal, payload, meta) {
       const name = resolveName(signal);
       const results: ExecuteResult[] = [];
       for (const b of adopted) {
         if (b.trigger.kind === "signal" && b.trigger.name === name) {
-          results.push(await execute(b.flow, payload, b.trigger as SignalAsTrigger));
+          results.push(
+            await execute(b.flow, payload, b.trigger as SignalAsTrigger, {
+              ...(meta?.parentRunId !== undefined ? { parentId: meta.parentRunId } : {}),
+            }),
+          );
         }
       }
       return results;
@@ -1555,6 +1622,26 @@ function compileHttpBinding(binding: Binding, aot: boolean): CompiledRoute {
   );
 }
 
+/** True when the pipeline ended in a terminal failure (not sleep park). */
+function isTerminalFailure(result: PipelineResult): boolean {
+  if (result.failure) return true;
+  return result.ctx.error !== undefined && !isJournalSuspend(result.ctx.error);
+}
+
+/** Machine-readable code for journal / Runs failure fields. */
+function failureCodeOf(err: unknown): string {
+  if (isFlowFailure(err)) return err.error.code;
+  if (err instanceof Error && err.name && err.name !== "Error") return err.name;
+  if (err instanceof Error && err.message) return err.message.slice(0, 120);
+  return "Error";
+}
+
+/** Coerce a thrown value into a FlowFailure for Runs wide events. */
+function failureFromUnknown(err: unknown): FlowFailure {
+  if (isFlowFailure(err)) return err;
+  return fail(failureCodeOf(err), {});
+}
+
 /**
  * Pull personal fields from validated input for crypto-shred archival.
  *
@@ -1576,6 +1663,26 @@ function archiveFromInput(
   return Object.keys(out).length > 0 ? out : undefined;
 }
 
+/**
+ * Clone input with archived personal fields replaced by shred markers so the
+ * replay snapshot never retains cleartext for those keys.
+ *
+ * @param input - Validated flow input
+ * @param fields - Property names that go to {@link archiveFromInput}
+ */
+function redactArchivedFields(input: unknown, fields: readonly string[] | undefined): unknown {
+  if (input === undefined) return undefined;
+  if (!fields || fields.length === 0) return input;
+  if (!input || typeof input !== "object" || Array.isArray(input)) return input;
+  const obj = { ...(input as Record<string, unknown>) };
+  for (const name of fields) {
+    if (typeof obj[name] === "string" && (obj[name] as string).length > 0) {
+      obj[name] = "[archived]";
+    }
+  }
+  return obj;
+}
+
 /**
  * Deep-merge channel template catalogs (later parts win per locale).
  *

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

@@ -7,6 +7,7 @@ import { memorySignalDriver } from "../../drivers/signal-memory.ts";
 import { createBunSignalRedisClient, redisSignalDriver } from "../../drivers/signal-redis.ts";
 import type { SignalRedisClientLike } from "../../drivers/signal-types.ts";
 import { createSignalRuntime, type SignalRuntime } from "../../elements/signal.ts";
+import { emitBootWarn } from "../../runtime/boot-warn.ts";
 import type { BootOptions } from "../boot.ts";
 
 /**
@@ -35,7 +36,7 @@ let signalRedisWarned = false;
 function warnSignalRedisProcessLocal(): void {
   if (signalRedisWarned) return;
   signalRedisWarned = true;
-  console.warn(
+  emitBootWarn(
     "oke boot: drivers.signal redis — emit relays to Redis, but consume/live/drain use a " +
       "process-local outbox (not multi-instance competing consumers). Prefer a shared durable " +
       "outbox path for multi-process tests, or a single consumer instance, until Redis Streams " +
@@ -129,7 +130,10 @@ export async function bindSignal(
       if (seen.has(name)) continue;
       seen.add(name);
       await bus.subscribe(name, `oke:${name}`, async (msg) => {
-        await handler(name, msg.payload);
+        await handler(name, msg.payload, {
+          ...(msg.parentRunId !== undefined ? { parentRunId: msg.parentRunId } : {}),
+          messageId: msg.id,
+        });
       });
     }
   }

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

@@ -16,6 +16,7 @@ import { sqliteDriver } from "../../drivers/sqlite.ts";
 import type { FilesDriver, IndexDriver, KvDriver, SqlDriver } from "../../drivers/types.ts";
 import { createStoreRuntime, type StoreRuntime } from "../../elements/store.ts";
 import type { StoreDecl } from "../../elements/store/declare.ts";
+import { emitBootWarn } from "../../runtime/boot-warn.ts";
 import type { BootOptions } from "../boot.ts"; // type-only — no cycle at runtime
 
 /**
@@ -43,7 +44,7 @@ export function resetFilesFsWarnForTests(): void {
 function warnFilesFsMultiInstance(): void {
   if (filesFsWarned) return;
   filesFsWarned = true;
-  console.warn(
+  emitBootWarn(
     'oke boot: drivers.store.files "fs" is single-host — each instance sees its own ' +
       "filesystem (temp root when unbound). For horizontal scale use drivers.store.files s3 " +
       "(or an explicitly shared volume root, still single-host semantics).",

package/src/kernel/boot.test.ts

@@ -79,7 +79,7 @@ describe("boot — lazy element needs", () => {
     expect(needs.signal).toBe(false);
   });
 
-  test("oke() Store-only graph stays under the prior 53 kB baseline", async () => {
+  test("oke() Store-only graph stays under the prior 54 kB baseline", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-store-only-"));
     const entry = join(dir, "entry.ts");
     const appPath = join(import.meta.dir, "app.ts");
@@ -117,10 +117,11 @@ describe("boot — lazy element needs", () => {
         total += Bun.gzipSync(new Uint8Array(raw)).byteLength;
       }
       // Rebased after fx.sendOtp/verifyOtp on the shared fx surface (~50.1 kB
-      // gzip), durable-journal lease surface (~51.2 kB), then fx.deliverOtp +
-      // unified otp() plugin wiring on the shared surface (~50.9 kB → 53 kB
-      // cap). Clock/channel/journal drivers stay lazy-bound; far below eager bind.
-      expect(total).toBeLessThan(53_000);
+      // gzip), durable-journal lease surface (~51.2 kB), fx.deliverOtp +
+      // unified otp() (~50.9 kB → 53 kB), then fx.runs / SLO window on the
+      // shared surface (~53.3 kB → 54 kB cap). Clock/channel/journal drivers
+      // stay lazy-bound; far below eager bind.
+      expect(total).toBeLessThan(54_000);
     } finally {
       await rm(dir, { recursive: true, force: true });
     }

package/src/kernel/boot.ts

@@ -115,8 +115,13 @@ export interface BootOptions {
    *
    * @param signal - Signal name
    * @param payload - Payload
+   * @param meta - Optional envelope (producer run id for trace chains)
    */
-  readonly onSignal?: (signal: string, payload: unknown) => void | Promise<void>;
+  readonly onSignal?: (
+    signal: string,
+    payload: unknown,
+    meta?: { readonly parentRunId?: string; readonly messageId?: string },
+  ) => void | Promise<void>;
   /**
    * Resume due durable runs — called on every scheduler tick when any flow
    * declares `durable: true` (claimDueSleep on the shared journal store).
@@ -257,8 +262,8 @@ async function loadBind<T>(name: string): Promise<T> {
 export async function bootApplication(input: BootOptions = {}): Promise<BootResult> {
   const docker =
     input.docker === true || (input.docker !== false && process.env.OKE_DOCKER === "1");
-  // `-d` always selects the `docker` driver profile — not a mix of test/local +
-  // prod store overrides (templates often pin `env: "test"` for harnesses).
+  // `-d` always selects the `docker` driver profile — not a mix of local/test +
+  // prod store overrides when `$options.env` is unset.
   const env: ConfigEnv = docker ? "docker" : (input.env ?? "local");
   let config = input.config;
   if (config === undefined) {