okengine 0.18.4 → 0.19.0

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

@@ -4,27 +4,28 @@
 
 import { describe, expect, test } from "bun:test";
 import { mockAiDriver } from "../../drivers/ai-mock.ts";
-import { ollamaAiDriver } from "../../drivers/ai-ollama.ts";
-import { aiDriverFor, aiUrlFor, bindAi, openDefaultsFor, resolveAiDriverId } from "./ai.ts";
+import { openaiCompatibleAiDriver } from "../../drivers/ai-openai-compatible.ts";
+import { aiDriverFor, bindAi, openDefaultsFor, resolveAiDriverId } from "./ai.ts";
 
 describe("ai boot binder", () => {
   test("aiDriverFor maps protocol ids; unknown / reserved throw", () => {
     expect(aiDriverFor("mock").id).toBe("mock");
-    expect(aiDriverFor("ollama")).toBe(ollamaAiDriver);
+    expect(aiDriverFor("openai-compatible")).toBe(openaiCompatibleAiDriver);
+    expect(() => aiDriverFor("ollama")).toThrow(/unknown AI driver/);
     expect(() => aiDriverFor("bedrock")).toThrow(/not implemented/);
     expect(() => aiDriverFor("nope")).toThrow(/unknown AI driver/);
   });
 
   test("resolveAiDriverId defaults to mock; honours config + OKE_AI_DRIVER in docker", () => {
     expect(resolveAiDriverId({}, "test")).toBe("mock");
-    expect(resolveAiDriverId({ config: { drivers: { ai: { test: "ollama" } } } }, "test")).toBe(
-      "ollama",
-    );
+    expect(
+      resolveAiDriverId({ config: { drivers: { ai: { test: "openai-compatible" } } } }, "test"),
+    ).toBe("openai-compatible");
 
     const prev = process.env.OKE_AI_DRIVER;
-    process.env.OKE_AI_DRIVER = "ollama";
+    process.env.OKE_AI_DRIVER = "openai-compatible";
     try {
-      expect(resolveAiDriverId({}, "test", true)).toBe("ollama");
+      expect(resolveAiDriverId({}, "test", true)).toBe("openai-compatible");
     } finally {
       if (prev === undefined) delete process.env.OKE_AI_DRIVER;
       else process.env.OKE_AI_DRIVER = prev;
@@ -51,37 +52,39 @@ describe("ai boot binder", () => {
     }
   });
 
-  test("openDefaultsFor openai-compatible fails loud in docker without OKE_AI_URL", () => {
+  test("openDefaultsFor openai-compatible allows docker without OKE_AI_URL (cloud registry)", () => {
     const prevUrl = process.env.OKE_AI_URL;
     const prevBase = process.env.OPENAI_BASE_URL;
     delete process.env.OKE_AI_URL;
     delete process.env.OPENAI_BASE_URL;
     try {
-      expect(() => openDefaultsFor("openai-compatible", true)).toThrow(/OKE_AI_URL/);
+      expect(openDefaultsFor("openai-compatible", true)).toEqual({});
     } finally {
       if (prevUrl !== undefined) process.env.OKE_AI_URL = prevUrl;
       if (prevBase !== undefined) process.env.OPENAI_BASE_URL = prevBase;
     }
   });
 
-  test("aiUrlFor fails loud in docker without OKE_AI_URL", () => {
+  test("openDefaultsFor openai-compatible keeps compose URL when present", () => {
     const prevUrl = process.env.OKE_AI_URL;
-    const prevHost = process.env.OLLAMA_HOST;
-    delete process.env.OKE_AI_URL;
-    delete process.env.OLLAMA_HOST;
+    const prevBase = process.env.OPENAI_BASE_URL;
+    process.env.OKE_AI_URL = "http://127.0.0.1:8080/v1";
+    delete process.env.OPENAI_BASE_URL;
     try {
-      expect(() => aiUrlFor(true)).toThrow(/OKE_AI_URL/);
-      expect(aiUrlFor(false)).toBe("http://127.0.0.1:11434");
+      expect(openDefaultsFor("openai-compatible", true)).toEqual({
+        baseUrl: "http://127.0.0.1:8080/v1",
+      });
     } finally {
-      if (prevUrl !== undefined) process.env.OKE_AI_URL = prevUrl;
-      if (prevHost !== undefined) process.env.OLLAMA_HOST = prevHost;
+      if (prevUrl === undefined) delete process.env.OKE_AI_URL;
+      else process.env.OKE_AI_URL = prevUrl;
+      if (prevBase !== undefined) process.env.OPENAI_BASE_URL = prevBase;
     }
   });
 
   test("bindAi uses injected defaultDriver over config (tests stay on mock)", () => {
     const runtime = bindAi(
       {
-        config: { drivers: { ai: { test: "ollama" } } },
+        config: { drivers: { ai: { test: "openai-compatible" } } },
         ai: { defaultDriver: mockAiDriver },
       },
       undefined,

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

@@ -9,11 +9,6 @@
 import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
 import { anthropicAiDriver } from "../../drivers/ai-anthropic.ts";
 import { mockAiDriver } from "../../drivers/ai-mock.ts";
-import {
-  normalizeOllamaBaseUrl,
-  ollamaAiDriver,
-  OLLAMA_DEFAULT_BASE_URL,
-} from "../../drivers/ai-ollama.ts";
 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";
@@ -50,7 +45,6 @@ export function bindAi(
       mock: lazyDriver("mock", docker),
       anthropic: lazyDriver("anthropic", docker),
       "openai-compatible": lazyDriver("openai-compatible", docker),
-      ollama: lazyDriver("ollama", docker),
     },
     gates: options.ai?.gates ?? gate,
     now,
@@ -77,7 +71,7 @@ export function resolveAiDriverId(options: BootOptions, env: ConfigEnv, docker =
   if (liveUrl && fromEnv && fromEnv !== "mock") return fromEnv;
   const resolved = resolveDriverId(options.config?.drivers?.ai, env);
   if (liveUrl && (resolved === undefined || resolved === "mock")) {
-    return fromEnv === "ollama" ? "ollama" : "openai-compatible";
+    return fromEnv === "openai-compatible" || !fromEnv ? "openai-compatible" : fromEnv;
   }
   if (resolved) return resolved;
   return "mock";
@@ -97,8 +91,6 @@ export function aiDriverFor(id: string): AiDriver {
       return anthropicAiDriver;
     case "openai-compatible":
       return openaiCompatibleAiDriver;
-    case "ollama":
-      return ollamaAiDriver;
     case "bedrock":
     case "vertex":
       throw new Error(`oke boot: AI driver "${id}" is reserved but not implemented yet`);
@@ -113,13 +105,7 @@ export function aiDriverFor(id: string): AiDriver {
  * @param id - Driver id
  * @param docker - Docker mode
  */
-export function openDefaultsFor(id: string, docker = false): AiOpenOptions {
-  if (id === "ollama") {
-    return {
-      baseUrl: aiUrlFor(docker),
-      ...(process.env.OKE_AI_MODEL?.trim() ? { model: process.env.OKE_AI_MODEL.trim() } : {}),
-    };
-  }
+export function openDefaultsFor(id: string, _docker = false): AiOpenOptions {
   if (id === "anthropic") {
     const apiKey = process.env.ANTHROPIC_API_KEY?.trim();
     return {
@@ -129,12 +115,10 @@ export function openDefaultsFor(id: string, docker = false): AiOpenOptions {
   }
   if (id === "openai-compatible") {
     const apiKey = process.env.OPENAI_API_KEY?.trim();
+    // Prefer explicit proxy / local compose URL. Cloud registry models
+    // (`ai.model({ provider: "openrouter" })`) resolve their own baseUrl —
+    // do not require OKE_AI_URL just because `oke dev` uses Docker for Postgres.
     const baseUrl = process.env.OPENAI_BASE_URL?.trim() || process.env.OKE_AI_URL?.trim();
-    if (docker && !baseUrl) {
-      throw new Error(
-        "oke boot: openai-compatible driver needs OKE_AI_URL (did `oke dev` write .env.local?)",
-      );
-    }
     return {
       ...(apiKey ? { apiKey } : {}),
       ...(baseUrl ? { baseUrl } : {}),
@@ -144,28 +128,6 @@ export function openDefaultsFor(id: string, docker = false): AiOpenOptions {
   return {};
 }
 
-/**
- * Ollama base URL — docker fails loud when compose did not write one.
- *
- * @param docker - Docker mode
- */
-export function aiUrlFor(docker = false): string {
-  const raw = process.env.OKE_AI_URL?.trim() || process.env.OLLAMA_HOST?.trim();
-  if (raw) return normalizeOllamaBaseUrl(raw);
-  if (docker) {
-    throw new Error(
-      "oke boot: ollama driver needs OKE_AI_URL (did `oke dev -d` write .env.local?)",
-    );
-  }
-  return OLLAMA_DEFAULT_BASE_URL;
-}
-
-/**
- * Merge fixed open defaults under per-call options.
- *
- * @param driver - Base driver
- * @param defaults - Env-derived open options
- */
 /**
  * Open a protocol driver with env defaults only when a model actually uses it.
  *

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

@@ -5,6 +5,7 @@
 import { mkdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import {
+  applyClockTimezoneDefaults,
   clock as declareClock,
   createClockRuntime,
   createFileCronStore,
@@ -38,6 +39,15 @@ export function resolveClockDriverId(options: BootOptions, env: ConfigEnv): stri
   return resolveDriverId(options.config?.drivers?.clock, env, CLOCK_DEFAULTS)!;
 }
 
+/**
+ * Effective default timezone: `oke({ clock })` wins over `defineConfig({ clock })`.
+ *
+ * @param options - Boot options
+ */
+function resolveDefaultClockTimezone(options: BootOptions): string | undefined {
+  return options.clock?.timezone ?? options.config?.clock?.timezone;
+}
+
 /**
  * Construct / adopt a Clock runtime, register decls, reconcile.
  *
@@ -102,19 +112,27 @@ export async function bindClock(
     );
   }
 
+  const defaultTimezone = resolveDefaultClockTimezone(options);
   const clockDecls = new Map<string, ClockDecl>();
-  for (const c of options.clocks ?? []) {
+  for (const c of applyClockTimezoneDefaults(options.clocks ?? [], defaultTimezone)) {
     clockDecls.set(c.name, c);
   }
   const coveredEvery = new Set([...clockDecls.values()].flatMap((c) => (c.every ? [c.every] : [])));
   for (const b of options.bindings ?? []) {
+    if (b.trigger.kind === "clock" && b.trigger.clock && !clockDecls.has(b.trigger.name)) {
+      const [resolved] = applyClockTimezoneDefaults([b.trigger.clock], defaultTimezone);
+      if (resolved) clockDecls.set(b.trigger.name, resolved);
+    }
     if (b.trigger.kind !== "every") continue;
     if (clockDecls.has(b.trigger.interval) || coveredEvery.has(b.trigger.interval)) continue;
-    clockDecls.set(
-      b.trigger.interval,
-      declareClock(b.trigger.interval, { every: b.trigger.interval }),
+    const [synthetic] = applyClockTimezoneDefaults(
+      [declareClock(b.trigger.interval, { every: b.trigger.interval })],
+      defaultTimezone,
     );
-    coveredEvery.add(b.trigger.interval);
+    if (synthetic) {
+      clockDecls.set(b.trigger.interval, synthetic);
+      coveredEvery.add(b.trigger.interval);
+    }
   }
   for (const decl of clockDecls.values()) {
     clock.register(decl);

package/src/kernel/boot-bind/honor-config.test.ts

@@ -303,7 +303,7 @@ describe("boot binders honour drivers.* config", () => {
   test("signal: drivers.signal memory binds memory", async () => {
     const result = await bootApplication({
       env: "test",
-      signals: [signal("ping", { delivery: "once" })],
+      signals: [signal.once("ping")],
       config: {
         drivers: {
           signal: { dev: "redis", test: "memory", prod: "redis" },
@@ -321,7 +321,7 @@ describe("boot binders honour drivers.* config", () => {
     const fake = createSignalRedisFake();
     const result = await bootApplication({
       env: "test",
-      signals: [signal("ping", { delivery: "once" })],
+      signals: [signal.once("ping")],
       clients: { signalRedis: fake },
       config: {
         drivers: {
@@ -340,7 +340,7 @@ describe("boot binders honour drivers.* config", () => {
     await expect(
       bootApplication({
         env: "test",
-        signals: [signal("ping", { delivery: "once" })],
+        signals: [signal.once("ping")],
         config: {
           drivers: {
             signal: { test: "postgres" },
@@ -421,7 +421,7 @@ describe("boot binders honour drivers.* config", () => {
     await expect(
       bootApplication({
         env: "test",
-        signals: [signal("ping", { delivery: "once" })],
+        signals: [signal.once("ping")],
         config: {
           drivers: {
             signal: { test: "nats" },

package/src/kernel/boot.test.ts

@@ -16,7 +16,7 @@ import { store } from "../elements/store.ts";
 import { vault, VaultBootError } from "../elements/vault.ts";
 import { bootApplication, resolveElementNeeds } from "./boot.ts";
 import { flow, resetFlowSeq } from "./flow.ts";
-import { every, http } from "./triggers.ts";
+import { http } from "./triggers.ts";
 import { oke } from "./app.ts";
 import { on, resetBindings } from "./on.ts";
 
@@ -79,7 +79,7 @@ describe("boot — lazy element needs", () => {
     expect(needs.signal).toBe(false);
   });
 
-  test("oke() Store-only graph stays under the prior 50 kB baseline", async () => {
+  test("oke() Store-only graph stays under the prior 58 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");
@@ -118,6 +118,8 @@ describe("boot — lazy element needs", () => {
       }
       // Rebased after host API-key persist + allowlist on `oke()` and the
       // realtime bridge (CDC sink, LiveQuery runtime, openLiveStream).
+      // Browser JSON page (`json-code-block`) is lazy on `app.fetch` so this
+      // graph does not pin the traces-language HTML/CSS chunk.
       expect(total).toBeLessThan(58_000);
     } finally {
       await rm(dir, { recursive: true, force: true });
@@ -152,8 +154,9 @@ describe("boot — cron fires without manual dispatch", () => {
     resetFlowSeq();
 
     let ran = 0;
+    const expireStale = clock("expire-stale", { every: "1h" });
     on(
-      every("1h"),
+      expireStale,
       flow("cleanup.expire", {
         do: () => {
           ran += 1;
@@ -163,14 +166,14 @@ describe("boot — cron fires without manual dispatch", () => {
 
     const app = oke({
       name: "cron-boot",
-      clocks: [clock("expire-stale", { every: "1h" })],
+      clocks: [expireStale],
       env: "test",
     });
 
     await app.boot({
       env: "test",
       startScheduler: false,
-      clocks: [clock("expire-stale", { every: "1h" })],
+      clocks: [expireStale],
     });
 
     const rt = app.bootResult!.clock!;
@@ -251,8 +254,9 @@ describe("boot — cron autostart via real timer loop", () => {
     jest.useFakeTimers({ now: 1_000_000 });
 
     let ran = 0;
+    const autostartClock = clock("cleanup.autostart", { every: "10m" });
     on(
-      every("10m"),
+      autostartClock,
       flow("cleanup.autostart", {
         do: () => {
           ran += 1;
@@ -263,6 +267,7 @@ describe("boot — cron autostart via real timer loop", () => {
     // Non-test env → startScheduler defaults ON. No createTestApp / advance.
     const app = oke({
       name: "cron-autostart",
+      clocks: [autostartClock],
       env: "dev",
       schedulerIntervalMs: 1000,
       config: {

package/src/kernel/boot.ts

@@ -42,6 +42,7 @@ import type {
 } from "../elements/vault.ts";
 import type { JournalRuntime } from "./boot-bind/journal.ts";
 import type { InstanceRuntime, InstanceStore } from "./instances.ts";
+import { isBenignSqlDisconnect } from "./instances.ts";
 import { resolveInstanceId } from "./instance-id.ts";
 import {
   resolveRunsConsoleBridge,
@@ -111,6 +112,14 @@ export interface BootOptions {
   readonly signals?: readonly SignalDecl[];
   /** Named clock declarations. */
   readonly clocks?: readonly ClockDecl[];
+  /**
+   * Clock element defaults — `{ timezone }` for declarations that omit
+   * `timezone`. Merged with `defineConfig({ clock: { timezone } })` at bind
+   * (`oke({ clock })` wins over config).
+   */
+  readonly clock?: {
+    readonly timezone?: string;
+  };
   /** Store facet declarations to register. */
   readonly stores?: readonly StoreDecl[];
   /** Channel runtime options. */
@@ -281,7 +290,7 @@ export function resolveElementNeeds(options: BootOptions): ElementNeeds {
     if ((e?.sends?.length ?? 0) > 0) channel = true;
     if ((e?.asks?.length ?? 0) > 0) ai = true;
     for (const t of f.triggers) {
-      if (t.kind === "every") clock = true;
+      if (t.kind === "clock" || t.kind === "every") clock = true;
       if (t.kind === "signal") signal = true;
       if (t.kind === "cdc") store = true;
       if (t.kind === "http" && t.gates.length > 0) gate = true;
@@ -292,7 +301,7 @@ export function resolveElementNeeds(options: BootOptions): ElementNeeds {
   for (const b of options.bindings ?? []) {
     considerFlow(b.flow);
     const t = b.trigger;
-    if (t.kind === "every") clock = true;
+    if (t.kind === "clock" || t.kind === "every") clock = true;
     if (t.kind === "signal") signal = true;
     if (t.kind === "cdc") store = true;
     if (t.kind === "http" && t.gates.length > 0) gate = true;
@@ -529,10 +538,16 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
     const clockRt = clock;
     const durableResume = options.onDurableResume;
     const fleet = instances;
+    /** Swallow pause / disconnect noise so compose-stop does not flood the TTY. */
+    const ignoreBenignSql = (err: unknown): void => {
+      if (isBenignSqlDisconnect(err)) return;
+      // Unexpected scheduler failures stay visible.
+      console.error(err);
+    };
     schedulerTimer = setInterval(() => {
-      if (clockRt) void clockRt.tick();
-      if (journal && durableResume) void durableResume();
-      if (fleet) void fleet.maybeHeartbeat();
+      if (clockRt) void Promise.resolve(clockRt.tick()).catch(ignoreBenignSql);
+      if (journal && durableResume) void Promise.resolve(durableResume()).catch(ignoreBenignSql);
+      if (fleet) void fleet.maybeHeartbeat().catch(ignoreBenignSql);
     }, period);
     schedulerTimer.unref?.();
   }
@@ -635,6 +650,13 @@ export function resetNoEffectsWarnForTests(): void {
   noEffectsWarned = false;
 }
 
+/** Result of a best-effort Manifest extract (never throws). */
+type AutoExtractResult = {
+  readonly manifest?: Manifest;
+  /** Present when extract threw — surfaced before OKE1020 in strict boots. */
+  readonly error?: string;
+};
+
 /**
  * Best-effort AoT extraction from `rootDir` — mirrors the CLI's own lazy,
  * defensive `extractManifest` use (`oke dev`'s `tryLoadProjectManifest`).
@@ -647,13 +669,14 @@ export function resetNoEffectsWarnForTests(): void {
  *
  * @param rootDir - Project root to extract from
  */
-async function tryAutoExtractManifest(rootDir: string): Promise<Manifest | undefined> {
+async function tryAutoExtractManifest(rootDir: string): Promise<AutoExtractResult> {
   try {
     const url = new URL("../compiler/extract.ts", import.meta.url);
     const { extractManifest } = (await import(url.href)) as typeof import("../compiler/extract.ts");
-    return await extractManifest({ rootDir });
-  } catch {
-    return undefined;
+    return { manifest: await extractManifest({ rootDir }) };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { error: message.length > 0 ? message : "unknown extract failure" };
   }
 }
 
@@ -663,9 +686,14 @@ async function tryAutoExtractManifest(rootDir: string): Promise<Manifest | undef
  * an explicit {@link BootOptions.manifest}, or a lazy AoT extract from
  * {@link BootOptions.rootDir} / `OKE_ROOT_DIR`.
  *
- * When neither is available: `test` stays open with a once-per-process
- * `oke boot:` warning; `dev` with compose infra and `prod` fail loud
- * (`OKE1008`) — never a silent open door in a deploy-shaped environment.
+ * When a Manifest is available but a Flow is absent from it (framework /
+ * plugin Flows outside the app tree), stamp an empty least-privilege token
+ * automatically — do not hand-declare `effects: {}` on those Flows.
+ *
+ * When neither Manifest nor declared effects are available: `test` stays
+ * open with a once-per-process `oke boot:` warning; `dev` with compose
+ * infra and `prod` fail loud (`OKE1020`) — never a silent open door in a
+ * deploy-shaped environment.
  *
  * @param flows - Adopted flows
  * @param env - Resolved {@link ConfigEnv}
@@ -683,10 +711,15 @@ export async function mintCapabilities(
   const map = new Map<string, CapabilityToken>();
 
   let manifest = options.manifest;
+  let extractError: string | undefined;
   const needsManifest = manifest === undefined && flows.some((f) => f.effects === undefined);
   if (needsManifest) {
     const rootDir = options.rootDir ?? process.env["OKE_ROOT_DIR"];
-    if (rootDir) manifest = await tryAutoExtractManifest(rootDir);
+    if (rootDir) {
+      const extracted = await tryAutoExtractManifest(rootDir);
+      manifest = extracted.manifest;
+      extractError = extracted.error;
+    }
   }
 
   for (const f of flows) {
@@ -701,17 +734,34 @@ export async function mintCapabilities(
       continue;
     }
 
+    // Manifest extract succeeded (or an explicit Manifest was passed) but this
+    // flow is absent from it — typically a framework / plugin Flow that lives
+    // outside the app tree. Stamp an empty least-privilege token; do not hand
+    // declare `effects: {}` on those Flows. Real fx usage still needs inference
+    // (app source) or an explicit non-empty `effects` block.
+    if (manifest !== undefined) {
+      map.set(f.name, createCapabilityToken(f.name, {}));
+      continue;
+    }
+
     const strict = env === "prod" || (env === "dev" && options.docker === true);
     if (strict) {
+      if (extractError !== undefined) {
+        emitBootWarn(`oke boot: Manifest extract failed — ${extractError}`);
+      }
       throwOke("NO_EFFECTS_DECLARED", { flow: f.name });
     }
     if (!noEffectsWarned) {
       noEffectsWarned = true;
+      const extractHint =
+        extractError !== undefined ? ` Manifest extract failed (${extractError}).` : "";
       emitBootWarn(
         `oke boot: flow "${f.name}" (and possibly others) has no declared effects and no ` +
           "Manifest-derived effects — running with an OPEN capability token (every access " +
-          "allowed, ledgered but not gated). Run `oke build`, or boot with `manifest` / " +
-          "`rootDir`, before deploying — dev+compose/prod refuse to boot this way.",
+          "allowed, ledgered but not gated)." +
+          extractHint +
+          " Run `oke build`, or boot with `manifest` / `rootDir`, before deploying — " +
+          "dev+compose/prod refuse to boot this way.",
       );
     }
     map.set(f.name, createCapabilityToken(f.name, undefined));
@@ -757,7 +807,7 @@ async function tryListFlowsUnits(rootDir: string): Promise<readonly string[] | u
  * Opt-in only via {@link BootOptions.rootDir} / `OKE_ROOT_DIR` (same gate as
  * {@link mintCapabilities}'s Manifest fallback) — never a filesystem read
  * the kernel performs on its own. `test` warns once per process; `prod`
- * (and `dev` with compose) fail loud (`OKE1009`) — same class as
+ * (and `dev` with compose) fail loud (`OKE1030`) — same class as
  * `NO_EFFECTS_DECLARED`, never a silently-incomplete route table in a
  * deploy-shaped environment.
  *

package/src/kernel/boundary-contract.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared invoke-boundary contract — authored on HTTP / call / MCP exposures,
+ * projected onto Manifest `flows.*.{in,out,errors,breaking}`.
+ *
+ * Distinct from Signal/Channel **emit schema** (payload in motion).
+ */
+
+import type { InferSchemaOutput, SchemaInput } from "../validation/standard-schema.ts";
+import type { FlowErrorMap } from "./flow.ts";
+
+/** Invoke contract bag shared by `http.*`, `call`, and `mcp.tool`. */
+export interface BoundaryContract<
+  ISchema = SchemaInput,
+  OSchema = SchemaInput,
+  E extends FlowErrorMap = FlowErrorMap,
+> {
+  /** Request / args schema (Standard Schema). */
+  readonly in?: ISchema;
+  /** Success reply schema (Manifest + typed client; not runtime-validated). */
+  readonly out?: OSchema;
+  /** Typed domain errors (`fx.fail`). */
+  readonly errors?: E;
+  /**
+   * Acknowledge intentional Manifest contract breaks for the bound flow
+   * (`oke doctor --diff` / CI gate).
+   */
+  readonly breaking?: boolean;
+}
+
+/** Infer validated input from a {@link BoundaryContract} bag. */
+export type InferBoundaryIn<Bag> = Bag extends { readonly in: infer S }
+  ? InferSchemaOutput<S>
+  : unknown;
+
+/** Infer success output from a {@link BoundaryContract} bag. */
+export type InferBoundaryOut<Bag> = Bag extends { readonly out: infer S }
+  ? InferSchemaOutput<S>
+  : unknown;
+
+/** Infer error map from a {@link BoundaryContract} bag. */
+export type InferBoundaryErrors<Bag> = Bag extends {
+  readonly errors: infer E extends FlowErrorMap;
+}
+  ? E
+  : {};
+
+/** Runtime fields stamped onto a Flow from an exposure bag. */
+export interface StampedBoundaryContract {
+  readonly in: SchemaInput | undefined;
+  readonly out: SchemaInput | undefined;
+  readonly errors: FlowErrorMap | undefined;
+  readonly breaking: boolean;
+}
+
+/**
+ * Normalize an optional contract bag into stampable fields.
+ *
+ * @param bag - Exposure contract (may be undefined / partial)
+ */
+export function stampBoundaryContract(
+  bag: BoundaryContract | undefined | null,
+): StampedBoundaryContract {
+  if (bag == null) {
+    return { in: undefined, out: undefined, errors: undefined, breaking: false };
+  }
+  return {
+    in: bag.in as SchemaInput | undefined,
+    out: bag.out as SchemaInput | undefined,
+    errors: bag.errors,
+    breaking: bag.breaking ?? false,
+  };
+}
+
+/**
+ * Apply a stamped contract onto a flow carrier (runtime mutation).
+ *
+ * @param flow - Flow definition object
+ * @param stamped - Normalized contract fields
+ */
+export function applyBoundaryContract(
+  flow: {
+    in: SchemaInput | undefined;
+    out: SchemaInput | undefined;
+    errors: FlowErrorMap | undefined;
+    breaking: boolean;
+  },
+  stamped: StampedBoundaryContract,
+): void {
+  flow.in = stamped.in;
+  flow.out = stamped.out;
+  flow.errors = stamped.errors;
+  if (stamped.breaking) flow.breaking = true;
+}

package/src/kernel/budget.test.ts

@@ -1,6 +1,6 @@
 /**
  * Kernel edge profile budget — AGENTS.md / unified-theory §24.
- * Limit: < 16 kB gzipped (minified bundle).
+ * Limit: < 17 kB gzipped (minified bundle).
  */
 
 import { describe, expect, test } from "bun:test";