okengine 0.11.0 → 0.11.2

package/src/kernel/app-auth.ts

@@ -0,0 +1,98 @@
+/**
+ * Sync auth wiring for `oke({ gate: { auth } })`.
+ *
+ * Loaded only when auth is configured so HTTP-only cold graphs never import
+ * bindings / sessions / identity (`requirePackageModule` in `app.ts`).
+ */
+
+import type { ResolvedGateAuth } from "../auth/config.ts";
+import { auth as authPlugin } from "../auth/plugin.ts";
+import { createAuthHttpBindings, type AuthHttpMaterialization } from "../auth/bindings.ts";
+import { tokenFromCookieHeader } from "../auth/cookies.ts";
+import { setActiveGateAuthContext } from "../auth/method-context.ts";
+import type { ResolvedGateConfig } from "../elements/gate/config.ts";
+import { createAppAuthBinding, verifyBearerToken, type AppAuthBinding } from "./auth-resolve.ts";
+import type { PluginDef } from "./plugin.ts";
+
+/** Result of wiring Gate auth at construction. */
+export interface WiredGateAuth {
+  readonly materialization: AuthHttpMaterialization | undefined;
+  readonly authPlugin: PluginDef | undefined;
+  readonly authBinding: AppAuthBinding;
+  readonly verifyBearerToken: typeof verifyBearerToken;
+  readonly tokenFromCookieHeader: typeof tokenFromCookieHeader;
+  /** Rebuild binding when boot supplies a clock. */
+  rebind(now: () => number): AppAuthBinding;
+}
+
+/** Options for {@link wireGateAuth}. */
+export interface WireGateAuthOptions {
+  readonly gateConfig: ResolvedGateConfig & { readonly auth: ResolvedGateAuth };
+  /** Clock fallback when `gate.auth.now` is omitted (`oke({ fx: { now } })`). */
+  readonly now?: () => number;
+}
+
+/**
+ * Materialize auth HTTP bindings, absorb the builtin auth plugin, and publish
+ * the active Gate auth context for `.plug(username())` etc.
+ *
+ * @param options - Resolved Gate bag + optional clock
+ */
+export function wireGateAuth(options: WireGateAuthOptions): WiredGateAuth {
+  const { gateConfig } = options;
+  const auth = gateConfig.auth;
+  let materialization: AuthHttpMaterialization | undefined;
+  if (auth.http) {
+    materialization = createAuthHttpBindings(auth, {
+      rateLimitEnabled: gateConfig.rateLimitEnabled,
+      sessions: auth.sessions,
+    });
+  }
+
+  const pluginDef = authPlugin({
+    secret: auth.secret,
+    accessTtlMs: auth.session.accessTtlMs,
+    refreshTtlMs: auth.session.refreshTtlMs,
+    session: {
+      accessTtlMs: auth.session.accessTtlMs,
+      refreshTtlMs: auth.session.refreshTtlMs,
+      idleTtlMs: auth.session.idleTtlMs,
+      absoluteTtlMs: auth.session.absoluteTtlMs,
+      singleSessionPerUser: auth.session.singleSessionPerUser,
+    },
+    password: auth.password,
+    passwordPolicy: auth.passwordPolicy,
+    breachCheck: auth.breachCheck,
+  });
+
+  let authBinding = createAppAuthBinding({
+    secret: auth.secret,
+    sessions: materialization?.ctx.sessions ?? auth.sessions,
+    now: auth.now ?? options.now,
+  });
+
+  setActiveGateAuthContext({
+    secret: authBinding.secret,
+    sessions: authBinding.sessions,
+    now: authBinding.now,
+    passwordPolicy: auth.passwordPolicy,
+    password: auth.password,
+    breachCheck: auth.breachCheck,
+  });
+
+  return {
+    materialization,
+    authPlugin: pluginDef,
+    authBinding,
+    verifyBearerToken,
+    tokenFromCookieHeader,
+    rebind(now) {
+      authBinding = createAppAuthBinding({
+        secret: authBinding.secret,
+        sessions: authBinding.sessions,
+        now,
+      });
+      return authBinding;
+    },
+  };
+}

package/src/kernel/app.ts

@@ -6,12 +6,9 @@
  * pipeline, and wires `fx.call` to untriggered (and triggered) flows.
  */
 
-import {
-  compileRoute,
-  encodeExecuteResult,
-  encodeFailure,
-  type CompiledRoute,
-} from "../compiler/index.ts";
+import { compileRoute } from "../compiler/dynamic.ts";
+import type { CompiledRoute } from "../compiler/aot.ts";
+import { encodeExecuteResult, encodeFailure } from "../compiler/response.ts";
 import { validate } from "../validation/standard-schema.ts";
 import {
   accumulateAdoptArgs,
@@ -25,16 +22,15 @@ import {
 // when an app actually boots (AGENTS.md / unified-theory budget: cold start < 75 ms).
 import type { BootOptions, BootResult, ElementRuntimes } from "./boot.ts";
 import type { CapabilityToken } from "./capability.ts";
-import { createAppAuthBinding, verifyBearerToken, type AppAuthBinding } from "./auth-resolve.ts";
-import { createAuthHttpBindings, type AuthHttpMaterialization } from "../auth/bindings.ts";
-import { auth as authPlugin } from "../auth/plugin.ts";
-import { tokenFromCookieHeader } from "../auth/cookies.ts";
-import { setActiveGateAuthContext } from "../auth/method-context.ts";
+import type { AppAuthBinding } from "./auth-resolve.ts";
+import type { AuthHttpMaterialization } from "../auth/bindings.ts";
+import type { WiredGateAuth } from "./app-auth.ts";
 import {
   resolveGateConfig,
   type GateOptions,
   type ResolvedGateConfig,
 } from "../elements/gate/config.ts";
+import { requirePackageModule } from "../shared/lazy-src.ts";
 import type { TemplateCatalog } from "../elements/channel/runtime.ts";
 import { parseAcceptLanguage } from "../elements/channel/locale.ts";
 import { runWithLocale } from "../i18n/locale-context.ts";
@@ -85,6 +81,10 @@ import { releaseInstanceLeases } from "./graceful-shutdown.ts";
 import type { JournalRuntime } from "./boot-bind/journal.ts";
 import { listBindings, resetBindings, type Binding } from "./on.ts";
 import {
+  aiAgentRegistry,
+  aiEmbedRegistry,
+  aiModelRegistry,
+  aiPromptRegistry,
   channelTemplateRegistry,
   requiredEnvRegistry,
   secretRegistry,
@@ -465,6 +465,45 @@ function mergeUnique<T>(explicit: readonly T[] | undefined, fromRegistry: readon
   return out;
 }
 
+/**
+ * Merge explicit `oke({ ai })` with auto-drained AI decls. Returns
+ * `undefined` when neither side contributes — a defined empty object would
+ * flip {@link resolveElementNeeds}'s `ai` flag for every app.
+ *
+ * @param explicit - Hand-passed AI boot options
+ * @param fromRegistry - Models / prompts / embeds / agents from declare registries
+ */
+function mergeAiOptions(
+  explicit: BootOptions["ai"] | undefined,
+  fromRegistry: {
+    readonly models: NonNullable<BootOptions["ai"]>["models"];
+    readonly prompts: NonNullable<BootOptions["ai"]>["prompts"];
+    readonly embeds: NonNullable<BootOptions["ai"]>["embeds"];
+    readonly agents: NonNullable<BootOptions["ai"]>["agents"];
+  },
+): BootOptions["ai"] | undefined {
+  const models = mergeUnique(explicit?.models, fromRegistry.models ?? []);
+  const prompts = mergeUnique(explicit?.prompts, fromRegistry.prompts ?? []);
+  const embeds = mergeUnique(explicit?.embeds, fromRegistry.embeds ?? []);
+  const agents = mergeUnique(explicit?.agents, fromRegistry.agents ?? []);
+  if (
+    explicit === undefined &&
+    models.length === 0 &&
+    prompts.length === 0 &&
+    embeds.length === 0 &&
+    agents.length === 0
+  ) {
+    return undefined;
+  }
+  return {
+    ...(explicit ?? {}),
+    ...(models.length > 0 ? { models } : {}),
+    ...(prompts.length > 0 ? { prompts } : {}),
+    ...(embeds.length > 0 ? { embeds } : {}),
+    ...(agents.length > 0 ? { agents } : {}),
+  };
+}
+
 /**
  * Create an application. Adopts bindings registered via {@link on}.
  *
@@ -480,20 +519,35 @@ export function oke(options: OkeOptions): OkeApp {
   if (registry === "consume") resetBindings();
 
   // Same registry mode drains store.sql/store.files, vault.secret, signal(),
-  // and channel.<medium>().template() — module-evaluation registries that
-  // mirror `on`'s trigger drain (`listBindings`/`resetBindings` above).
-  // Explicit `options.stores` / `secrets` / `signals` / `channel.templates`
-  // are additive, never silently ignored — deduped by reference so an
-  // explicitly-passed decl that is also in the registry is not doubled.
+  // channel.<medium>().template(), and ai.model/prompt/embed/agent —
+  // module-evaluation registries that mirror `on`'s trigger drain
+  // (`listBindings`/`resetBindings` above). Explicit `options.stores` /
+  // `secrets` / `signals` / `channel.templates` / `ai` are additive, never
+  // silently ignored — deduped by reference so an explicitly-passed decl
+  // that is also in the registry is not doubled.
   const registrySnapshot =
     registry === "ignore"
-      ? { stores: [], secrets: [], requiredEnv: [], signals: [], channelTemplates: [] }
+      ? {
+          stores: [],
+          secrets: [],
+          requiredEnv: [],
+          signals: [],
+          channelTemplates: [],
+          aiModels: [],
+          aiPrompts: [],
+          aiEmbeds: [],
+          aiAgents: [],
+        }
       : {
           stores: storeRegistry.slice(),
           secrets: secretRegistry.slice(),
           requiredEnv: requiredEnvRegistry.slice(),
           signals: signalRegistry.slice(),
           channelTemplates: channelTemplateRegistry.slice(),
+          aiModels: aiModelRegistry.slice(),
+          aiPrompts: aiPromptRegistry.slice(),
+          aiEmbeds: aiEmbedRegistry.slice(),
+          aiAgents: aiAgentRegistry.slice(),
         };
   if (registry === "consume") {
     storeRegistry.length = 0;
@@ -501,6 +555,10 @@ export function oke(options: OkeOptions): OkeApp {
     requiredEnvRegistry.length = 0;
     signalRegistry.length = 0;
     channelTemplateRegistry.length = 0;
+    aiModelRegistry.length = 0;
+    aiPromptRegistry.length = 0;
+    aiEmbedRegistry.length = 0;
+    aiAgentRegistry.length = 0;
   }
   const effectiveStores = mergeUnique(options.stores, registrySnapshot.stores);
   const effectiveSecrets = mergeUnique(options.secrets, registrySnapshot.secrets);
@@ -527,6 +585,14 @@ export function oke(options: OkeOptions): OkeApp {
           ...(options.channel ?? {}),
           templates: mergeUnique(options.channel?.templates, registrySnapshot.channelTemplates),
         };
+  // Same undefined-when-empty rule for AI — a bare `{}` would force the AI
+  // runtime open even when the app never declared models / prompts.
+  const effectiveAi = mergeAiOptions(options.ai, {
+    models: registrySnapshot.aiModels,
+    prompts: registrySnapshot.aiPrompts,
+    embeds: registrySnapshot.aiEmbeds,
+    agents: registrySnapshot.aiAgents,
+  });
 
   // Resolve Gate bag early so auth HTTP Bindings join `adopted` + the router
   // before posture audit (same ensureBoot → doBoot path — never a side channel).
@@ -534,17 +600,12 @@ export function oke(options: OkeOptions): OkeApp {
     gate: options.gate,
     env: options.env,
   });
-  let authMaterialization: AuthHttpMaterialization | undefined;
-  if (gateConfig.auth?.http) {
-    authMaterialization = createAuthHttpBindings(gateConfig.auth, {
-      rateLimitEnabled: gateConfig.rateLimitEnabled,
-      sessions: gateConfig.auth.sessions,
-    });
-    adopted.push(...authMaterialization.bindings);
-  }
 
-  /** Retained for test harness / boot merges. */
-  const $options = options;
+  /** Retained for test harness / boot merges (includes auto-drained AI decls). */
+  const $options: OkeOptions =
+    effectiveAi === undefined || options.ai === effectiveAi
+      ? options
+      : { ...options, ai: effectiveAi };
 
   const appHooks: HookMap = {};
   const unitHooks = new Map<string, HookMap>();
@@ -555,27 +616,26 @@ export function oke(options: OkeOptions): OkeApp {
   /** Runtime route table — types accumulate on the returned {@link OkeApp}. */
   const routes: RuntimeRouteMap = {};
 
-  // Absorb auth() tables into gate.auth — `.needs("auth")` sees plugin name.
+  let authMaterialization: AuthHttpMaterialization | undefined;
+  let wiredAuth: WiredGateAuth | undefined;
+  let authBinding: AppAuthBinding | undefined;
   if (gateConfig.auth) {
-    applyPlugin(
-      pluginRegistry,
-      authPlugin({
-        secret: gateConfig.auth.secret,
-        accessTtlMs: gateConfig.auth.session.accessTtlMs,
-        refreshTtlMs: gateConfig.auth.session.refreshTtlMs,
-        session: {
-          accessTtlMs: gateConfig.auth.session.accessTtlMs,
-          refreshTtlMs: gateConfig.auth.session.refreshTtlMs,
-          idleTtlMs: gateConfig.auth.session.idleTtlMs,
-          absoluteTtlMs: gateConfig.auth.session.absoluteTtlMs,
-          singleSessionPerUser: gateConfig.auth.session.singleSessionPerUser,
-        },
-        password: gateConfig.auth.password,
-        passwordPolicy: gateConfig.auth.passwordPolicy,
-        breachCheck: gateConfig.auth.breachCheck,
-      }),
-      appPluginScope,
+    const { wireGateAuth } = requirePackageModule<typeof import("./app-auth.ts")>(
+      "kernel/app-auth",
+      "app-auth",
     );
+    wiredAuth = wireGateAuth({
+      gateConfig: { ...gateConfig, auth: gateConfig.auth },
+      now: options.fx?.now,
+    });
+    authMaterialization = wiredAuth.materialization;
+    authBinding = wiredAuth.authBinding;
+    if (authMaterialization) {
+      adopted.push(...authMaterialization.bindings);
+    }
+    if (wiredAuth.authPlugin) {
+      applyPlugin(pluginRegistry, wiredAuth.authPlugin, appPluginScope);
+    }
   }
 
   const smart = createRouter<Binding>(options.router ?? "default");
@@ -671,29 +731,10 @@ export function oke(options: OkeOptions): OkeApp {
   let bootPromise: Promise<BootResult> | undefined;
   let readyState: ReadyState = "booting";
   let bootEnv: BootOptions["env"] = options.env;
-  let authBinding: AppAuthBinding | undefined =
-    gateConfig.auth !== undefined
-      ? createAppAuthBinding({
-          secret: gateConfig.auth.secret,
-          sessions: authMaterialization?.ctx.sessions ?? gateConfig.auth.sessions,
-          now: gateConfig.auth.now ?? options.fx?.now,
-        })
-      : undefined;
-  if (authBinding) {
-    setActiveGateAuthContext({
-      secret: authBinding.secret,
-      sessions: authBinding.sessions,
-      now: authBinding.now,
-      passwordPolicy: gateConfig.auth?.passwordPolicy,
-      password: gateConfig.auth?.password,
-      breachCheck: gateConfig.auth?.breachCheck,
-    });
-  } else {
-    setActiveGateAuthContext(undefined);
-  }
   // Fallback journal for pre-boot / `autoBoot: false` unit tests. A booted
   // app replaces this with the bound `drivers.journal` store (postgres etc.).
-  const fallbackJournalStore = createMemoryJournalStore();
+  // Constructed on first use so non-durable HTTP apps skip the alloc.
+  let fallbackJournalStore: JournalStore | undefined;
   const fallbackJournalInstanceId = `app-${crypto.randomUUID()}`;
   const sleepingRuns = new Map<
     string,
@@ -715,6 +756,7 @@ export function oke(options: OkeOptions): OkeApp {
     if (bound) {
       return { store: bound.store, instanceId: bound.instanceId, leaseMs: bound.leaseMs };
     }
+    fallbackJournalStore ??= createMemoryJournalStore();
     return {
       store: fallbackJournalStore,
       instanceId: fallbackJournalInstanceId,
@@ -859,7 +901,7 @@ export function oke(options: OkeOptions): OkeApp {
       clocks: overrides?.clocks ?? options.clocks,
       stores: overrides?.stores ?? effectiveStores,
       channel: overrides?.channel ?? effectiveChannel,
-      ai: overrides?.ai ?? options.ai,
+      ai: overrides?.ai ?? effectiveAi,
       runs: overrides?.runs ?? options.runs,
       bindings: adopted,
       flows: [...flowsByName.values()],
@@ -938,7 +980,7 @@ export function oke(options: OkeOptions): OkeApp {
           (overrides?.config ?? options.config)?.i18n?.default ??
           "en",
       },
-      ai: overrides?.ai ?? options.ai,
+      ai: overrides?.ai ?? effectiveAi,
       runs: overrides?.runs ?? options.runs,
       now: overrides?.now ?? options.fx?.now,
       instanceId: overrides?.instanceId,
@@ -978,12 +1020,9 @@ export function oke(options: OkeOptions): OkeApp {
       readyState = "ready";
     }
     // Prefer the booted clock for access-token expiry checks.
-    if (authBinding) {
-      authBinding = createAppAuthBinding({
-        secret: authBinding.secret,
-        sessions: authBinding.sessions,
-        now: result.clock?.now.bind(result.clock) ?? authBinding.now,
-      });
+    if (wiredAuth && authBinding) {
+      const now = result.clock?.now.bind(result.clock) ?? authBinding.now;
+      authBinding = wiredAuth.rebind(now);
     }
     return result;
   }
@@ -1144,21 +1183,24 @@ export function oke(options: OkeOptions): OkeApp {
 
       const binding = authBinding;
       const cookieOpts = gateConfig.auth?.cookies;
+      const verifyBearer = wiredAuth?.verifyBearerToken;
+      const cookieToken = wiredAuth?.tokenFromCookieHeader;
       const elementHooks = createElementPipelineHooks({
         gates: booted.gate,
         principals,
         telemetry,
         allowTestPrincipals: testMode,
-        verifyBearer: binding ? async (token) => verifyBearerToken(binding, token) : undefined,
+        verifyBearer:
+          binding && verifyBearer ? async (token) => verifyBearer(binding, token) : undefined,
         // Phase 1a: opt-in cookie → Bearer when Authorization is absent.
         resolveToken:
-          binding && cookieOpts?.enabled
+          binding && cookieOpts?.enabled && cookieToken
             ? (request) => {
                 const header = request.headers.get("authorization");
                 if (header?.startsWith("Bearer ")) {
                   return header.slice("Bearer ".length).trim() || undefined;
                 }
-                return tokenFromCookieHeader(request.headers.get("cookie"), cookieOpts);
+                return cookieToken(request.headers.get("cookie"), cookieOpts);
               }
             : undefined,
       });

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

@@ -20,7 +20,7 @@ import { flow } from "./flow.ts";
 import { on, resetBindings } from "./on.ts";
 import { http } from "./triggers.ts";
 
-describe("oke() auto-registry — stores/secrets/signals/channel.templates", () => {
+describe("oke() auto-registry — stores/secrets/signals/channel.templates/ai", () => {
   test("before/after: zero explicit arrays boots identically to the explicit-array form", async () => {
     resetBindings();
 
@@ -195,4 +195,55 @@ describe("oke() auto-registry — stores/secrets/signals/channel.templates", ()
     expect(appB.bootResult?.signal).toBeUndefined();
     expect(appB.bootResult?.channel?.templates.has("leak-template") ?? false).toBe(false);
   });
+
+  test("ai.model / .prompt auto-drain into oke options (no explicit oke({ ai }))", async () => {
+    const { ai } = await import("../elements/ai/declare.ts");
+    const { mockAiDriver } = await import("../drivers/ai-mock.ts");
+    const { createAiRuntime } = await import("../elements/ai/runtime.ts");
+
+    const smart = ai.model("smart", { provider: "mock" });
+    const summarizeNote = smart.prompt("summarize-note", {
+      version: 1,
+    });
+
+    const ping = flow("ai.ping", {
+      effects: { asks: ["summarize-note"] },
+      do: async (_input, fx) => fx.ask("summarize-note", { title: "t", body: "b" }),
+    });
+    on(http.post("/ai-ping"), ping);
+
+    const app = oke({
+      name: "ai-auto-registry",
+      autoBoot: false,
+      startScheduler: false,
+      gate: { unguardedHttp: "allow" },
+    });
+
+    expect(app.$options.ai?.models?.some((m) => m.name === "smart")).toBe(true);
+    expect(app.$options.ai?.prompts?.some((p) => p.name === "summarize-note")).toBe(true);
+
+    const runtime = createAiRuntime({
+      models: [smart],
+      prompts: [summarizeNote],
+      defaultDriver: {
+        id: "mock",
+        open: () =>
+          mockAiDriver.open({
+            mockResponses: { "*": { summary: "one-line summary" } },
+          }),
+      },
+    });
+    await app.boot({
+      env: "test",
+      unguardedHttp: "allow",
+      elements: { ai: runtime },
+    });
+
+    const res = await app.fetch(
+      new Request("http://127.0.0.1/ai-ping", { method: "POST", body: "{}" }),
+    );
+    expect(res.status).toBe(200);
+    const json = (await res.json()) as { data: { summary: string } };
+    expect(json.data.summary).toBe("one-line summary");
+  });
 });

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 54.3 kB baseline", async () => {
+  test("oke() Store-only graph stays under the prior 39 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");
@@ -116,23 +116,9 @@ describe("boot — lazy element needs", () => {
         if (raw.byteLength === 0) continue;
         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), 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. Rebased again for the
-      // store/vault/signal/channel auto-registry drain (`element-registries.ts`
-      // + the `oke()` merge/dedup logic) — every app now carries this
-      // regardless of which elements it uses, since the drain must run
-      // synchronously at construction (same isolation guarantee as the
-      // `on()` binding registry) and can't be deferred behind a lazy import
-      // (~54.0 kB → 54.3 kB cap). Rebased again for `assertAdoptBarrelFresh`
-      // + `tryListFlowsUnits` in `boot.ts` (`.adopt()` barrel staleness
-      // check, OKE1009) — part of the already-lazily-loaded boot graph, not
-      // the `oke()` construction path, but `Bun.build` still traces and
-      // sums the dynamic-import chunk (~54.3 kB → 54.7 kB → 55.0 kB after
-      // ConfigEnv local/docker → dev/test/prod + sqlite removal).
-      expect(total).toBeLessThan(55_000);
+      // Rebased after lazy `gate.auth` / auth-config chunks + `gate.public`
+      // decoupling from kv-lua strategies (~38.9 kB gzip with export externals).
+      expect(total).toBeLessThan(40_000);
     } finally {
       await rm(dir, { recursive: true, force: true });
     }

package/src/kernel/element-registries.ts

@@ -1,17 +1,24 @@
 /**
  * Module-evaluation registries for `store.sql` / `store.files`, `vault.secret`,
- * `vault.env.required`, `signal()`, and `channel.<medium>().template()` — the
- * plain arrays behind each declare module's `listX()` / `resetX()` pair
- * (mirrors `on.ts`'s trigger-drain `bindings` array).
+ * `vault.env.required`, `signal()`, `channel.<medium>().template()`, and
+ * `ai.model` / `.prompt` / `ai.embed` / `ai.agent` — the plain arrays behind
+ * each declare module's `listX()` / `resetX()` pair (mirrors `on.ts`'s
+ * trigger-drain `bindings` array).
  *
  * Lives here, not in the declare modules themselves, so {@link oke} can read
  * every registry with one lightweight import instead of statically pulling
- * in all four element `declare.ts` modules (and every unrelated export they
+ * in all element `declare.ts` modules (and every unrelated export they
  * carry) into every app's bundle — see the `oke()` Store-only bundle-size
  * budget in `boot.test.ts`. Only type imports cross back to the declare
  * modules, so this file has zero runtime dependencies of its own.
  */
 
+import type {
+  AiAgentDecl,
+  AiEmbedDecl,
+  AiModelDecl,
+  AiPromptDecl,
+} from "../elements/ai/declare.ts";
 import type { StoreDecl } from "../elements/store/declare.ts";
 import type { VaultSecretDecl } from "../elements/vault/declare.ts";
 import type { SignalDecl } from "../elements/signal/declare.ts";
@@ -27,3 +34,11 @@ export const requiredEnvRegistry: string[] = [];
 export const signalRegistry: SignalDecl[] = [];
 /** Medium-binder `.template()` declarations since the last reset. */
 export const channelTemplateRegistry: ChannelTemplateDecl[] = [];
+/** `ai.model` declarations since the last reset. */
+export const aiModelRegistry: AiModelDecl[] = [];
+/** `model.prompt` declarations since the last reset. */
+export const aiPromptRegistry: AiPromptDecl[] = [];
+/** `ai.embed` declarations since the last reset. */
+export const aiEmbedRegistry: AiEmbedDecl[] = [];
+/** `ai.agent` declarations since the last reset. */
+export const aiAgentRegistry: AiAgentDecl[] = [];

package/src/kernel/errors.ts

@@ -144,19 +144,19 @@ export const OKE_ERRORS = {
   },
   /**
    * Flow has no declared `effects` and no Manifest-derived effects were
-   * available to stamp at boot (docker / prod — never a silent open token).
+   * available to stamp at boot (dev+compose / prod — never a silent open token).
    */
   NO_EFFECTS_DECLARED: {
     code: 1008,
     cause: 'Flow "{flow}" has no declared effects and no Manifest to derive them from.',
     fix:
       "Add explicit `effects` to this flow, or boot with a Manifest (`oke build`) / " +
-      "`rootDir` so effects can be derived. docker/prod refuse an open capability token.",
+      "`rootDir` so effects can be derived. dev+compose/prod refuse an open capability token.",
   },
   /**
    * A `src/flows/<unit>` folder exists on disk but no adopted flow carries
    * that unit — the generated `.adopt()` barrel (`src/flows/generated.ts`)
-   * is stale or was hand-edited. docker/prod — never a silently-incomplete
+   * is stale or was hand-edited. dev+compose / prod — never a silently-incomplete
    * route table in a deploy-shaped environment.
    */
   ADOPT_BARREL_STALE: {

package/src/kernel/fx.test.ts

@@ -93,6 +93,31 @@ describe("fx — effect ledger", () => {
       },
       ledger,
       secrets: { STRIPE_KEY: "sk_test" },
+      aiRuntime: {
+        prompts: new Map(),
+        agents: new Map(),
+        embeds: new Map(),
+        autoCacheDisabled: true,
+        journalingForced: false,
+        denials: [],
+        agentRuns: [],
+        journal: [],
+        async ask() {
+          return { ok: true };
+        },
+        async runAgent() {
+          return { ok: true, steps: 0, denials: [], output: {} };
+        },
+        async *stream() {
+          /* no tokens */
+        },
+        async search() {
+          return [];
+        },
+        async embed() {
+          return { vectors: [] };
+        },
+      } as never,
     });
 
     await stub(fx, "sql:bookings").get("x");

package/src/kernel/fx.ts

@@ -297,6 +297,8 @@ export interface FxDeliverOtpOptions {
 /** Options for {@link Fx.ask}. */
 export interface FxAskOptions {
   readonly via?: readonly NamedRef[];
+  /** Per-call deadline — overrides prompt `timeout` (`"30s"` or ms). */
+  readonly timeout?: string | number;
   /** Flow refs offered as tools — each model call goes through `fx.call`. */
   readonly tools?: readonly NamedRef[];
   /** Bound on tool invocations (default 6). */
@@ -1587,13 +1589,14 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         if (options.aiRuntime) {
           return options.aiRuntime.ask(name, input, {
             via: opts?.via?.map(resolveName),
+            ...(opts?.timeout !== undefined ? { timeout: opts.timeout } : {}),
             tools: opts?.tools?.map(resolveName),
             maxSteps: opts?.maxSteps,
             // Host fx.call — same capability / ledger / Runs path as any call.
             callTool: (tool, toolInput) => fx.call(tool, toolInput),
           });
         }
-        return {};
+        throw new Error(`fx.ask: AI runtime is not configured for prompt "${name}"`);
       });
     },
     search(embed, query, opts) {

package/src/manifest/types.ts

@@ -300,6 +300,10 @@ export interface AiPrompt {
   version?: number;
   evals?: string;
   budget?: AiBudget;
+  /** Ordered recovery chain of logical model names. */
+  via?: string[];
+  /** Per-command deadline (`"30s"` or milliseconds). */
+  timeout?: string | number;
   model?: string;
   in?: JsonSchema;
   out?: JsonSchema;

package/src/release/build-lib.ts

@@ -22,6 +22,9 @@ const ENTRIES: readonly { readonly src: string; readonly out: string }[] = [
   { src: "src/i18n-entry.ts", out: "dist/i18n-entry.js" },
   { src: "src/compiler-entry.ts", out: "dist/compiler-entry.js" },
   { src: "src/journal-entry.ts", out: "dist/journal-entry.js" },
+  // Lazy sync chunks — loaded via requirePackageModule when gate.auth is set.
+  { src: "src/kernel/app-auth.ts", out: "dist/app-auth.js" },
+  { src: "src/auth/config.ts", out: "dist/auth-config.js" },
 ];
 
 /**