okengine 0.18.4 → 0.19.0

package/src/kernel/call.ts

@@ -0,0 +1,89 @@
+/**
+ * `call(name, opts)` — call-only Flow sugar with invoke contract on the bag.
+ *
+ * Same species as `flow` + internal trigger; contracts live here (not on `flow()`).
+ */
+
+import {
+  stampBoundaryContract,
+  type BoundaryContract,
+  type InferBoundaryErrors,
+  type InferBoundaryIn,
+  type InferBoundaryOut,
+} from "./boundary-contract.ts";
+import {
+  flow,
+  type FlowDef,
+  type FlowErrorMap,
+  type FlowHandler,
+  type FlowOptions,
+} from "./flow.ts";
+import { internal } from "./triggers.ts";
+
+/** Options for {@link call} — boundary contract + flow runtime + `do`. */
+export type CallOptions<
+  I = unknown,
+  O = unknown,
+  E extends FlowErrorMap = FlowErrorMap,
+> = BoundaryContract<unknown, unknown, E> &
+  Omit<FlowOptions<I, O>, "do"> & {
+    readonly do: FlowHandler<I, O>;
+  };
+
+type InferCallIn<Opts> = Opts extends { readonly in: unknown }
+  ? InferBoundaryIn<Opts>
+  : Opts extends { readonly do: FlowHandler<infer I, infer _O> }
+    ? I
+    : unknown;
+
+type InferCallOut<Opts> = Opts extends { readonly out: unknown }
+  ? InferBoundaryOut<Opts>
+  : Opts extends { readonly do: FlowHandler<infer _I, infer O> }
+    ? O
+    : unknown;
+
+/**
+ * Define a call-only Flow with its invoke contract on the same bag.
+ *
+ * @param name - Stable Manifest / `fx.call` name
+ * @param options - Contract + runtime + `do`
+ */
+export function call<Opts extends CallOptions<any, any, any>>(
+  name: string,
+  options: Opts & { readonly name?: never },
+): FlowDef<InferCallIn<Opts>, InferCallOut<Opts>, InferBoundaryErrors<Opts>> {
+  if (typeof name !== "string" || name.trim().length === 0) {
+    throw new TypeError("call(name, opts): name is required");
+  }
+  const {
+    in: inSchema,
+    out: outSchema,
+    errors,
+    breaking,
+    do: handler,
+    ...runtime
+  } = options as CallOptions<any, any, any>;
+
+  const def = flow(name, {
+    ...runtime,
+    do: handler as FlowHandler,
+  }) as FlowDef<InferCallIn<Opts>, InferCallOut<Opts>, InferBoundaryErrors<Opts>>;
+
+  const stamped = stampBoundaryContract({
+    in: inSchema,
+    out: outSchema,
+    errors,
+    breaking,
+  });
+  def.in = stamped.in;
+  def.out = stamped.out;
+  def.errors = stamped.errors as InferBoundaryErrors<Opts> | undefined;
+  def.breaking = stamped.breaking;
+
+  // Mark as internal / call-only exposure (addressable trigger kind).
+  const triggers = def.triggers as import("./triggers.ts").Trigger[];
+  triggers.push(internal);
+  (def as { $trigger: typeof internal }).$trigger = internal;
+
+  return def;
+}

package/src/kernel/capability.ts

@@ -17,8 +17,10 @@ const UNDECLARED_KEY: Readonly<Record<EffectKind, keyof typeof OKE_ERRORS>> = {
   emit: "UNDECLARED_EMIT",
   send: "UNDECLARED_SEND",
   ask: "UNDECLARED_ASK",
+  embed: "UNDECLARED_EMBED",
   secret: "UNDECLARED_SECRET",
   call: "UNDECLARED_CALL",
+  fetch: "UNDECLARED_FETCH",
 };
 
 /** Maps effect kind → the corresponding `Effects` field. */
@@ -28,8 +30,10 @@ const EFFECTS_FIELD: Readonly<Record<EffectKind, keyof Effects>> = {
   emit: "emits",
   send: "sends",
   ask: "asks",
+  embed: "embeds",
   secret: "secrets",
   call: "calls",
+  fetch: "fetches",
 };
 
 /**
@@ -83,8 +87,10 @@ export function createCapabilityToken(flow: string, declared?: Effects): Capabil
     emit: new Set(effects.emits ?? []),
     send: new Set(effects.sends ?? []),
     ask: new Set(effects.asks ?? []),
+    embed: new Set(effects.embeds ?? []),
     secret: new Set(effects.secrets ?? []),
     call: new Set(effects.calls ?? []),
+    fetch: new Set(effects.fetches ?? []),
   };
 
   return {

package/src/kernel/client-descriptor.ts

@@ -0,0 +1,123 @@
+/**
+ * Build {@link ClientDescriptor} for `GET /_oke/client.json` / `oke client add`.
+ *
+ * @module
+ */
+
+import type { ClientDescriptor } from "../client/types.ts";
+import type { AnyFlowDef } from "./flow.ts";
+import type { RuntimeRouteMap } from "./adopt-routes.ts";
+import { z } from "zod";
+
+/**
+ * Build a client descriptor from runtime routes + flow defs (type strings + stamps).
+ *
+ * @param routes - Runtime `$routes` map
+ * @param flowsByName - Flow name → definition (for schemas)
+ */
+export function buildClientDescriptor(
+  routes: RuntimeRouteMap,
+  flowsByName: ReadonlyMap<string, AnyFlowDef> | Readonly<Record<string, AnyFlowDef>>,
+): ClientDescriptor {
+  const lookup =
+    flowsByName instanceof Map
+      ? flowsByName
+      : new Map(Object.entries(flowsByName as Record<string, AnyFlowDef>));
+
+  type RouteEntry = ClientDescriptor["routes"][string][string];
+  const out: Record<string, Record<string, RouteEntry>> = {};
+  for (const [unit, flows] of Object.entries(routes)) {
+    const unitOut: Record<string, RouteEntry> = {};
+    for (const [flowName, stamp] of Object.entries(flows)) {
+      const full = `${unit}.${flowName}`;
+      const def = lookup.get(full) ?? lookup.get(flowName);
+      const errors: Record<string, string> = {};
+      if (def?.errors) {
+        for (const [code, schema] of Object.entries(def.errors)) {
+          errors[code] = schemaToTsString(schema);
+        }
+      }
+      unitOut[flowName] = {
+        in: schemaToTsString(def?.in),
+        out: schemaToTsString(def?.out),
+        ...(Object.keys(errors).length > 0 ? { errors } : { errors: {} }),
+        ...(stamp.method !== undefined ? { method: stamp.method } : {}),
+        ...(stamp.path !== undefined ? { path: stamp.path } : {}),
+        ...(stamp.live !== undefined ? { live: stamp.live } : {}),
+        ...(stamp.stream === true ? { stream: true as const } : {}),
+        ...(stamp.matchKey !== undefined ? { matchKey: stamp.matchKey } : {}),
+        ...(stamp.gates !== undefined && stamp.gates.length > 0 ? { gates: stamp.gates } : {}),
+      };
+    }
+    out[unit] = unitOut;
+  }
+  return { routes: out };
+}
+
+/**
+ * Print a compact TypeScript type string from a schema (Zod / JSON Schema).
+ * Falls back to `unknown` when unprintable.
+ *
+ * @param schema - Flow in/out/error schema
+ */
+export function schemaToTsString(schema: unknown): string {
+  if (schema === undefined || schema === null) return "unknown";
+  try {
+    if (hasToJSONSchema(schema)) {
+      return jsonSchemaToTs(schema.toJSONSchema());
+    }
+    // Zod 4 schemas expose `~standard` — convert via z.toJSONSchema when possible.
+    const json = z.toJSONSchema(schema as never);
+    return jsonSchemaToTs(json);
+  } catch {
+    if (isObjectSchema(schema)) return jsonSchemaToTs(schema);
+    return "unknown";
+  }
+}
+
+function hasToJSONSchema(value: unknown): value is { toJSONSchema: () => unknown } {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    "toJSONSchema" in value &&
+    typeof (value as { toJSONSchema?: unknown }).toJSONSchema === "function"
+  );
+}
+
+function isObjectSchema(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && "type" in value;
+}
+
+function jsonSchemaToTs(schema: unknown): string {
+  if (schema === null || typeof schema !== "object") return "unknown";
+  const s = schema as Record<string, unknown>;
+  if (Array.isArray(s.anyOf) || Array.isArray(s.oneOf)) {
+    const parts = ((s.anyOf ?? s.oneOf) as unknown[]).map(jsonSchemaToTs);
+    return parts.join(" | ") || "unknown";
+  }
+  if (s.const !== undefined) return JSON.stringify(s.const);
+  if (Array.isArray(s.enum)) {
+    return s.enum.map((v) => JSON.stringify(v)).join(" | ") || "unknown";
+  }
+  const typ = s.type;
+  if (typ === "string") return "string";
+  if (typ === "number" || typ === "integer") return "number";
+  if (typ === "boolean") return "boolean";
+  if (typ === "null") return "null";
+  if (typ === "array") {
+    const items = s.items !== undefined ? jsonSchemaToTs(s.items) : "unknown";
+    return `readonly ${items}[]`;
+  }
+  if (typ === "object" || s.properties) {
+    const props = (s.properties ?? {}) as Record<string, unknown>;
+    const required = new Set(
+      Array.isArray(s.required) ? s.required.filter((k): k is string => typeof k === "string") : [],
+    );
+    const lines = Object.entries(props).map(([k, v]) => {
+      const opt = required.has(k) ? "" : "?";
+      return `${JSON.stringify(k)}${opt}: ${jsonSchemaToTs(v)}`;
+    });
+    return `{ ${lines.join("; ")} }`;
+  }
+  return "unknown";
+}

package/src/kernel/clock-timezone.test.ts

@@ -0,0 +1,80 @@
+/**
+ * App-wide Clock timezone — `oke({ clock })` / `defineConfig({ clock })`.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { clock, resetClocks } from "../elements/clock/declare.ts";
+import { defineConfig } from "../config/index.ts";
+import { bootApplication } from "./boot.ts";
+import { oke } from "./app.ts";
+import { resetBindings } from "./on.ts";
+
+describe("oke({ clock: { timezone } })", () => {
+  test("applies to clocks that omit timezone; explicit wins", async () => {
+    resetBindings();
+    resetClocks();
+
+    clock.daily("local", { at: "06:00" });
+    clock.daily("ny", { at: "09:00", timezone: "America/New_York" });
+
+    const app = oke({
+      name: "tz-oke",
+      autoBoot: false,
+      startScheduler: false,
+      clock: { timezone: "Asia/Riyadh" },
+    });
+
+    expect(app.$options.clocks?.find((c) => c.name === "local")?.timezone).toBe("Asia/Riyadh");
+    expect(app.$options.clocks?.find((c) => c.name === "ny")?.timezone).toBe("America/New_York");
+
+    await app.boot({ env: "test" });
+    expect(app.bootResult?.clock?.declarations.get("local")?.timezone).toBe("Asia/Riyadh");
+    expect(app.bootResult?.clock?.declarations.get("ny")?.timezone).toBe("America/New_York");
+    await app.bootResult?.close();
+  });
+
+  test("defineConfig({ clock: { timezone } }) applies at bind when oke omits it", async () => {
+    resetBindings();
+    resetClocks();
+
+    const digest = clock.daily("digest", { at: "08:00" });
+    expect(digest.timezoneDefaulted).toBe(true);
+
+    const result = await bootApplication({
+      env: "test",
+      clocks: [digest],
+      config: defineConfig({
+        clock: { timezone: "Asia/Riyadh" },
+        drivers: { clock: { test: "frozen" } },
+      }),
+    });
+    try {
+      expect(result.clock?.declarations.get("digest")?.timezone).toBe("Asia/Riyadh");
+    } finally {
+      await result.close();
+    }
+  });
+
+  test("oke({ clock }) wins over defineConfig", async () => {
+    resetBindings();
+    resetClocks();
+
+    clock.daily("digest", { at: "08:00" });
+
+    const app = oke({
+      name: "tz-precedence",
+      autoBoot: false,
+      startScheduler: false,
+      clock: { timezone: "Europe/Berlin" },
+      config: defineConfig({
+        clock: { timezone: "Asia/Riyadh" },
+      }),
+    });
+
+    expect(app.$options.clocks?.[0]?.timezone).toBe("Europe/Berlin");
+    await app.boot({ env: "test" });
+    expect(app.bootResult?.clock?.declarations.get("digest")?.timezone).toBe("Europe/Berlin");
+    await app.bootResult?.close();
+  });
+});

package/src/kernel/correlation.test.ts

@@ -13,7 +13,7 @@ import { http } from "./triggers.ts";
 describe("correlation — parentId across Flow → Signal → Flow", () => {
   test("consumer WideEvent.parentId equals producer run id", async () => {
     resetBindings();
-    const orderPlaced = signal("corr-order-placed", { delivery: "once" });
+    const orderPlaced = signal.once("corr-order-placed");
     const runs = createRunsRuntime({ driver: "memory" });
     await runs.open();
 

package/src/kernel/dry-run.ts

@@ -1,8 +1,8 @@
 /**
  * Dry-run effect stubbing + write isolation (console §9.1 · §9.3 · §9.4).
  *
- * - Irreversible effects (`send` / `ask`) are intercepted and recorded as
- *   "would have fired" — never contact a real channel or model.
+ * - Irreversible effects (`send` / `ask` / `embed` / `fetch`) are intercepted and
+ *   recorded as "would have fired" — never contact a real channel, model, or URL.
  * - Store writes run against real data for an honest pass/fail verdict, then
  *   are always rolled back (snapshot / restore) when the dry-run scope exits.
  * - Drivers that cannot isolate writes throw {@link DryRunWriteIsolationError};
@@ -14,8 +14,8 @@ import { AsyncLocalStorage } from "node:async_hooks";
 /** One intercepted irreversible effect during a dry run. */
 export interface DryRunWouldHaveFired {
   /** Irreversible kind. */
-  readonly kind: "send" | "ask";
-  /** Template / prompt name. */
+  readonly kind: "send" | "ask" | "embed" | "fetch";
+  /** Template / prompt / model / host name. */
   readonly resource: string;
   /** Optional correlating message id (signal dry-run). */
   readonly messageId?: string;
@@ -23,7 +23,7 @@ export interface DryRunWouldHaveFired {
 
 /** Active dry-run bag. */
 export interface DryRunContext {
-  /** Intercepted send/ask calls in order. */
+  /** Intercepted send/ask/embed calls in order. */
   readonly wouldHaveFired: DryRunWouldHaveFired[];
   /** Optional message id stamped onto subsequent intercepts. */
   messageId?: string;
@@ -89,12 +89,15 @@ export function setDryRunMessageId(messageId: string): void {
 }
 
 /**
- * Record that a send/ask would have fired. No-op outside dry-run.
+ * Record that a send/ask/embed/fetch would have fired. No-op outside dry-run.
  *
  * @param kind - Irreversible kind
- * @param resource - Template / prompt name
+ * @param resource - Template / prompt / embed-model / host name
  */
-export function recordWouldHaveFired(kind: "send" | "ask", resource: string): void {
+export function recordWouldHaveFired(
+  kind: "send" | "ask" | "embed" | "fetch",
+  resource: string,
+): void {
   const ctx = storage.getStore();
   if (!ctx) return;
   ctx.wouldHaveFired.push({

package/src/kernel/effects-stamping.test.ts

@@ -23,6 +23,7 @@ import { join } from "node:path";
 import { z } from "zod";
 import { gate } from "../elements/gate.ts";
 import { field, id, now, store } from "../elements/store.ts";
+import { passkey } from "../plugins/passkey.ts";
 import { oke } from "./app.ts";
 import { resetNoEffectsWarnForTests } from "./boot.ts";
 import { flow, resetFlowSeq } from "./flow.ts";
@@ -47,10 +48,8 @@ const CreateOut = z.object({ ok: z.boolean() });
 
 function buildUnannotatedCreateFlow(db: ReturnType<typeof store.sql>) {
   return on(
-    http.post("/notes").public(),
+    http.post("/notes", { in: CreateIn, out: CreateOut }).public(),
     flow("notes.create", {
-      in: CreateIn,
-      out: CreateOut,
       // Deliberately no `effects` — the "let the compiler infer it" case.
       do: async (input, fx) => {
         await fx.store(db).insert(notes).values({ id: input.id, title: input.title, createdAt: 1 });
@@ -84,7 +83,7 @@ describe("boot-level: undeclared-effects flow, no manifest / rootDir", () => {
     expect(res.status).toBe(200);
   });
 
-  test("docker: hard fail at boot — OKE1008, never an open token in a deploy-shaped env", async () => {
+  test("docker: hard fail at boot — OKE1020, never an open token in a deploy-shaped env", async () => {
     resetBindings();
     resetFlowSeq();
     const db = store.sql("app", { schema: { notes } });
@@ -107,7 +106,7 @@ describe("boot-level: undeclared-effects flow, no manifest / rootDir", () => {
         startScheduler: false,
         config: { drivers: memoryDrivers },
       }),
-    ).rejects.toThrow(/OKE1008/);
+    ).rejects.toThrow(/OKE1020/);
   });
 
   test("prod: hard fail at boot — same posture as docker", async () => {
@@ -130,7 +129,7 @@ describe("boot-level: undeclared-effects flow, no manifest / rootDir", () => {
           },
         },
       }),
-    ).rejects.toThrow(/OKE1008/);
+    ).rejects.toThrow(/OKE1020/);
   });
 });
 
@@ -140,10 +139,8 @@ describe("boot-level: table-ref resolution stays backward compatible", () => {
     resetFlowSeq();
     const db = store.sql("app", { schema: { notes } });
     const create = on(
-      http.post("/notes").public(),
+      http.post("/notes", { in: CreateIn, out: CreateOut }).public(),
       flow("notes.create", {
-        in: CreateIn,
-        out: CreateOut,
         // The convention every template/test predates Direction B with —
         // store-level, not table-level. Must keep working unchanged.
         effects: { writes: ["sql:app"] },
@@ -227,3 +224,39 @@ export const create = on(
     }
   });
 });
+
+describe("boot-level: built-in auth flows under docker", () => {
+  test("emailAndPassword + passkey boot with docker:true — empty stamp from Manifest, no hand-declared effects", async () => {
+    resetBindings();
+    resetFlowSeq();
+    const memoryDrivers = {
+      store: {
+        sql: { dev: "memory", prod: "memory" },
+        kv: { dev: "memory", prod: "memory" },
+      },
+      channel: { email: { dev: "console", prod: "console" } },
+    } as const;
+    const app = oke({
+      name: "auth-stamp-docker",
+      registry: "ignore",
+      gate: {
+        auth: {
+          secret: "test-secret-at-least-16",
+          emailAndPassword: { enabled: true },
+        },
+      },
+    }).plug(passkey({ origins: ["http://localhost"] }));
+
+    // Explicit Manifest (as `oke dev` extract would supply for app Flows).
+    // Framework auth Flows are absent → mintCapabilities stamps `{}`.
+    await app.boot({
+      env: "dev",
+      docker: true,
+      unguardedHttp: "allow",
+      startScheduler: false,
+      manifest: { oke: "1.0", app: "auth-stamp-docker", flows: {} },
+      config: { drivers: memoryDrivers },
+    });
+    await app.stop();
+  });
+});

package/src/kernel/effects.test.ts

@@ -10,18 +10,20 @@ import {
 } from "./effects.ts";
 
 describe("effects — reversibility tiers", () => {
-  test("all seven effect kinds have the correct reversibility tier", () => {
+  test("all effect kinds have the correct reversibility tier", () => {
     const expected: Record<EffectKind, ReversibilityTier> = {
       read: "none",
       write: "reversible",
       emit: "deferred",
       send: "irreversible",
       ask: "irreversible",
+      embed: "irreversible",
       secret: "capability",
       call: "portal",
+      fetch: "irreversible",
     };
 
-    expect(EFFECT_KIND_TIERS).toHaveLength(7);
+    expect(EFFECT_KIND_TIERS).toHaveLength(9);
     for (const { kind, reversibility } of EFFECT_KIND_TIERS) {
       expect(reversibility).toBe(expected[kind]);
       expect(reversibilityOf(kind)).toBe(expected[kind]);

package/src/kernel/effects.ts

@@ -7,16 +7,25 @@
 
 import { resolveDurationMs } from "./elapsed.ts";
 
-/** The seven load-bearing effect kinds (manifest `effects` keys, singular). */
-export type EffectKind = "read" | "write" | "emit" | "send" | "ask" | "secret" | "call";
+/** Load-bearing effect kinds (manifest `effects` keys, singular). */
+export type EffectKind =
+  | "read"
+  | "write"
+  | "emit"
+  | "send"
+  | "ask"
+  | "embed"
+  | "secret"
+  | "call"
+  | "fetch";
 
 /**
- * Reversibility tier — console §9.1 ranking, applied to all seven kinds.
+ * Reversibility tier — console §9.1 ranking, applied to all effect kinds.
  *
  * - `none` — reads; no world change
  * - `reversible` — writes; undoable in-transaction
  * - `deferred` — emits; commit with the txn, then fan-out
- * - `irreversible` — sends / asks; cannot be undone by the runtime
+ * - `irreversible` — sends / asks / embeds / fetches; cannot be undone by the runtime
  * - `capability` — secrets; authority held, not an effect caused
  * - `portal` — calls; expands to the callee's transitive effects
  */
@@ -28,11 +37,22 @@ export type ReversibilityTier =
   | "capability"
   | "portal";
 
+/**
+ * Optional egress identity for an effect that left the process.
+ *
+ * Driver-reported — never inferred from hostname patterns. Only `host` is
+ * required when present; `provider` and `kind` are additive precision.
+ *
+ * Re-exported from drivers so kernel and driver contracts share one shape.
+ */
+export type { DriverExternal as EffectExternal } from "../drivers/external.ts";
+import type { DriverExternal as EffectExternal } from "../drivers/external.ts";
+
 /** One recorded effect call. */
 export interface EffectEntry {
-  /** Which of the seven kinds. */
+  /** Which effect kind. */
   readonly kind: EffectKind;
-  /** Resource / signal / template / prompt / secret / flow ref. */
+  /** Resource / signal / template / prompt / embed-model / secret / flow / host ref. */
   readonly resource: string;
   /** Epoch-ms when the call started. */
   readonly timestamp: number;
@@ -40,6 +60,11 @@ export interface EffectEntry {
   readonly duration: number;
   /** Reversibility tier for {@link kind}. */
   readonly reversibility: ReversibilityTier;
+  /**
+   * When set, this effect left the process and reached an external peer.
+   * Omitted for in-process work (PGlite, mock AI, local channel console).
+   */
+  readonly external?: EffectExternal;
 }
 
 /** Append-only ledger of effect entries for one flow invocation. */
@@ -63,14 +88,16 @@ const TIER_BY_KIND: Readonly<Record<EffectKind, ReversibilityTier>> = {
   emit: "deferred",
   send: "irreversible",
   ask: "irreversible",
+  embed: "irreversible",
   secret: "capability",
   call: "portal",
+  fetch: "irreversible",
 };
 
 /**
  * Reversibility tier for an effect kind.
  *
- * @param kind - One of the seven effect kinds
+ * @param kind - One of the effect kinds
  */
 export function reversibilityOf(kind: EffectKind): ReversibilityTier {
   return TIER_BY_KIND[kind];
@@ -105,6 +132,7 @@ export function createEffectLedger(): EffectLedger {
  * @param resource - Resource ref
  * @param now - Clock (injectable for tests)
  * @param body - Work to time
+ * @param externalOf - Optional egress metadata (static or derived from result / error)
  */
 export async function recordEffect<T>(
   ledger: EffectLedger,
@@ -112,18 +140,29 @@ export async function recordEffect<T>(
   resource: string,
   now: () => number,
   body: () => T | Promise<T>,
+  externalOf?:
+    | EffectExternal
+    | ((result: T | undefined, error: unknown) => EffectExternal | undefined),
 ): Promise<T> {
   const timestamp = now();
   const t0 = performance.now();
+  let result: T | undefined;
+  let error: unknown;
   try {
-    return await body();
+    result = await body();
+    return result;
+  } catch (e) {
+    error = e;
+    throw e;
   } finally {
+    const external = typeof externalOf === "function" ? externalOf(result, error) : externalOf;
     recordObservedEffect(
       ledger,
       kind,
       resource,
       timestamp,
       resolveDurationMs(now() - timestamp, performance.now() - t0),
+      external,
     );
   }
 }
@@ -139,6 +178,7 @@ export async function recordEffect<T>(
  * @param resource - Resource ref (or kernel cache key)
  * @param timestamp - Epoch-ms when the call started
  * @param duration - Measured duration in milliseconds
+ * @param external - Optional egress identity
  */
 export function recordObservedEffect(
   ledger: EffectLedger,
@@ -146,6 +186,7 @@ export function recordObservedEffect(
   resource: string,
   timestamp: number,
   duration: number,
+  external?: EffectExternal,
 ): void {
   ledger.record({
     kind,
@@ -153,11 +194,12 @@ export function recordObservedEffect(
     timestamp,
     duration,
     reversibility: reversibilityOf(kind),
+    ...(external !== undefined ? { external } : {}),
   });
 }
 
 /**
- * All seven kinds with their tiers — useful for exhaustive tests.
+ * All effect kinds with their tiers — useful for exhaustive tests.
  */
 export const EFFECT_KIND_TIERS: ReadonlyArray<{
   kind: EffectKind;

package/src/kernel/errors-channel.ts

@@ -0,0 +1,17 @@
+/**
+ * OKE1605 — kept off the kernel edge profile.
+ *
+ * Channel `fx.send` throws this when template `data` fails the template schema.
+ * Loaded via computed `import.meta.require` from {@link lookupOkeError}; the
+ * Channel runtime imports it directly (that graph is not in `budget-entry`).
+ */
+
+import type { OkeErrorDefinition } from "./errors.ts";
+
+/** Send payload failed the channel template's declared Standard Schema. */
+export const CHANNEL_SCHEMA: OkeErrorDefinition = {
+  code: 1605,
+  domain: "channel",
+  cause: '"{resource}": {detail}',
+  fix: "Fix template data payload or the template schema.",
+};