okengine 0.11.1 → 0.12.0

package/src/kernel/app.ts

@@ -34,10 +34,9 @@ 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";
-import { getMessageCatalogs, matchConfiguredLocale } from "../i18n/messages.ts";
 import { runDurable } from "../elements/clock/durable.ts";
 import { isFlow, type AnyFlowDef } from "./flow.ts";
-import { failureCodeOf, runCompensationPhase } from "./compensate.ts";
+import { failureFromUnknown, runCompensationPhase } from "./compensate.ts";
 import { fxRetry } from "./concurrency.ts";
 import {
   createFxContext,
@@ -56,7 +55,9 @@ import {
   logDevRequest,
   shouldLogDevRequests,
 } from "../runtime/dev-request-log.ts";
-import { fail, type FlowFailure } from "./errors.ts";
+import { asBrowserJsonCodeBlock, httpNavGroups } from "../runtime/json-code-block.ts";
+import { resolveDurationMs } from "./elapsed.ts";
+import { fail } from "./errors.ts";
 import {
   isFlowFailure,
   mergeHooks,
@@ -78,9 +79,14 @@ import {
   type JournalStore,
 } from "./journal.ts";
 import { releaseInstanceLeases } from "./graceful-shutdown.ts";
+import { mintInstanceId } from "./instance-id.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,
@@ -102,7 +108,13 @@ import {
 } from "./plug.ts";
 import type { PluginCapabilities, PluginDef } from "./plugin.ts";
 import { createPluginRegistry, type PluginRegistry } from "./registry.ts";
-import { createRouter, type Router, type RouterPreset, type SmartRouter } from "./router.ts";
+import {
+  createRouter,
+  formatAllowHeader,
+  type Router,
+  type RouterPreset,
+  type SmartRouter,
+} from "./router.ts";
 import type {
   CdcTrigger,
   EveryTrigger,
@@ -111,8 +123,24 @@ import type {
   SignalAsTrigger,
   Trigger,
 } from "./triggers.ts";
-import { createRunTelemetry } from "./run-telemetry.ts";
+import { recordObservedEffect } from "./effects.ts";
+import { cacheDimensionOf, createRunTelemetry } from "./run-telemetry.ts";
 import type { RunsRuntime } from "../runs/runtime.ts";
+import type { Effects, ResourceRef } from "../manifest/types.ts";
+
+/**
+ * Auto-cache helpers — loaded only when a Store runtime is bound.
+ * A static import would pin cache eligibility/dims on every `oke()` graph,
+ * including Store-declared apps that never execute a cached flow.
+ */
+function loadStoreCache(): typeof import("../elements/store/cache.ts") {
+  return requirePackageModule("elements/store/cache", "store-cache");
+}
+
+/** i18n catalogs — loaded at execute time, not on the `oke()` construction graph. */
+function loadMessages(): typeof import("../i18n/messages.ts") {
+  return requirePackageModule("i18n/messages", "messages");
+}
 
 /** Options for {@link oke}. */
 export interface OkeOptions {
@@ -151,6 +179,11 @@ export interface OkeOptions {
    * After {@link OkeApp.boot}, `bootResult.runs` takes precedence.
    */
   readonly runs?: BootOptions["runs"];
+  /**
+   * Push recorded WideEvents to Console ingest (`oke dev` live Traces bridge).
+   * See {@link BootOptions.runsBridge}.
+   */
+  readonly runsBridge?: BootOptions["runsBridge"];
   /**
    * Personal fields to archive (crypto-shred) from the validated input.
    * Keys are input property names; values become ciphertext under the
@@ -234,6 +267,12 @@ export interface ExecuteResult {
   readonly response: Response | undefined;
   readonly ctx: InvocationContext;
   readonly fx: Fx;
+  /** Wide-event cache dimension from this invocation's telemetry. */
+  readonly cache: "hit" | "miss" | "none";
+  /** Handler duration in milliseconds (high-res; may be fractional). */
+  readonly durationMs: number;
+  /** WideEvent / run id for this invocation. */
+  readonly runId: string;
 }
 
 /**
@@ -377,6 +416,22 @@ export interface OkeApp<D extends Record<string, unknown> = {}, R extends AppRou
       readonly operator?: FxOperator;
       /** Pre-resolved principal (either plane). */
       readonly principal?: ResolvedPrincipal;
+      /**
+       * Console invoke-as / trusted in-process callers only.
+       * When true, `principal` / `auth` injection applies outside `env: "test"`.
+       * Must never be set from public HTTP request handling.
+       */
+      readonly trustedInvoke?: boolean;
+      /**
+       * Console Operator invoke — skip the flow's gate chain.
+       * Takes effect only with {@link trustedInvoke}.
+       */
+      readonly bypassGates?: boolean;
+      /**
+       * Console Call API — open store handles with cleartext PII.
+       * Takes effect only with {@link trustedInvoke}.
+       */
+      readonly revealPii?: boolean;
       /** Parent WideEvent id when this execution was caused by another. */
       readonly parentId?: string;
       /** Explicit run / WideEvent id (defaults to a new UUID). */
@@ -461,6 +516,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}.
  *
@@ -476,20 +570,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;
@@ -497,6 +606,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);
@@ -523,6 +636,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).
@@ -531,8 +652,11 @@ export function oke(options: OkeOptions): OkeApp {
     env: options.env,
   });
 
-  /** 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>();
@@ -662,7 +786,8 @@ export function oke(options: OkeOptions): OkeApp {
   // app replaces this with the bound `drivers.journal` store (postgres etc.).
   // Constructed on first use so non-durable HTTP apps skip the alloc.
   let fallbackJournalStore: JournalStore | undefined;
-  const fallbackJournalInstanceId = `app-${crypto.randomUUID()}`;
+  const processInstanceId = mintInstanceId();
+  const fallbackJournalInstanceId = processInstanceId;
   const sleepingRuns = new Map<
     string,
     { readonly flow: AnyFlowDef; readonly input: unknown; readonly wakeAt: number }
@@ -671,6 +796,8 @@ export function oke(options: OkeOptions): OkeApp {
   // processes, but same-holder renew cannot distinguish two overlapping
   // sessions inside one process (boot orphan scan vs. scheduler tick).
   const inflightRuns = new Set<string>();
+  /** Store reads observed on open (unstamped) flows — next lookup uses these. */
+  const learnedTier1Reads = new Map<string, readonly ResourceRef[]>();
   const EMPTY_CAPABILITIES: ReadonlyMap<string, CapabilityToken> = new Map();
 
   /** Active journal: the boot-bound store once available, else the fallback. */
@@ -828,8 +955,9 @@ 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,
+      runsBridge: overrides?.runsBridge ?? options.runsBridge,
       bindings: adopted,
       flows: [...flowsByName.values()],
     });
@@ -907,10 +1035,14 @@ 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,
+      runsBridge: overrides?.runsBridge ?? options.runsBridge,
       now: overrides?.now ?? options.fx?.now,
-      instanceId: overrides?.instanceId,
+      instanceId: overrides?.instanceId ?? processInstanceId,
+      instanceStore: overrides?.instanceStore,
+      instanceHeartbeatMs: overrides?.instanceHeartbeatMs,
+      instanceLeaseMs: overrides?.instanceLeaseMs,
       startScheduler: overrides?.startScheduler ?? options.startScheduler,
       schedulerIntervalMs: overrides?.schedulerIntervalMs ?? options.schedulerIntervalMs,
       journalLeaseMs: overrides?.journalLeaseMs ?? options.journalLeaseMs,
@@ -989,6 +1121,12 @@ export function oke(options: OkeOptions): OkeApp {
       readonly auth?: ResolvedPrincipal | FxAuth;
       readonly operator?: FxOperator;
       readonly principal?: ResolvedPrincipal;
+      /** Console invoke-as / trusted in-process callers only. */
+      readonly trustedInvoke?: boolean;
+      /** Console Operator invoke — skip gates. Requires {@link trustedInvoke}. */
+      readonly bypassGates?: boolean;
+      /** Console Call API — cleartext store PII. Requires {@link trustedInvoke}. */
+      readonly revealPii?: boolean;
       /** Frozen origin identity for {@link Fx.principal} across `fx.call`. */
       readonly originPrincipal?: FxPrincipal;
       /** Explicit locale override for {@link Fx.t} / channel sends. */
@@ -1005,7 +1143,7 @@ export function oke(options: OkeOptions): OkeApp {
     const configuredLocales = i18nConfig?.locales ?? ["en"];
     const defaultLocale = i18nConfig?.default ?? "en";
     const acceptLanguage = extras?.request?.headers.get("accept-language") ?? undefined;
-    const resolvedLocale = matchConfiguredLocale(
+    const resolvedLocale = loadMessages().matchConfiguredLocale(
       extras?.locale ?? parseAcceptLanguage(acceptLanguage),
       configuredLocales,
       defaultLocale,
@@ -1034,6 +1172,9 @@ export function oke(options: OkeOptions): OkeApp {
       readonly auth?: ResolvedPrincipal | FxAuth;
       readonly operator?: FxOperator;
       readonly principal?: ResolvedPrincipal;
+      readonly trustedInvoke?: boolean;
+      readonly bypassGates?: boolean;
+      readonly revealPii?: boolean;
       readonly originPrincipal?: FxPrincipal;
       readonly locale?: string;
       readonly parentId?: string;
@@ -1071,6 +1212,7 @@ export function oke(options: OkeOptions): OkeApp {
 
     const now = options.fx?.now ?? booted?.clock?.now ?? (() => Date.now());
     const startedAt = now();
+    const startedHr = performance.now();
     const telemetry = createRunTelemetry();
     const inboundId =
       extras?.request?.headers.get("x-request-id")?.trim() ||
@@ -1099,10 +1241,11 @@ export function oke(options: OkeOptions): OkeApp {
         operator: { id: options.fx?.operator?.id ?? null },
       };
 
-      // extras.principal / extras.auth are test-harness only — never from
-      // a real HTTP request in production mode.
+      // Principal injection: test harness (`env: "test"`) OR console-trusted
+      // invoke-as (`extras.trustedInvoke`). Never from public HTTP fetch.
       const testMode = bootEnv === "test";
-      if (testMode) {
+      const allowInjectedPrincipals = testMode || extras?.trustedInvoke === true;
+      if (allowInjectedPrincipals) {
         applyPrincipal(principals, extras?.auth as ResolvedPrincipal | undefined);
         applyPrincipal(principals, extras?.principal);
         if (extras?.operator) principals.operator.id = extras.operator.id;
@@ -1110,15 +1253,20 @@ export function oke(options: OkeOptions): OkeApp {
 
       const binding = authBinding;
       const cookieOpts = gateConfig.auth?.cookies;
-      const verifyBearer = wiredAuth?.verifyBearerToken;
       const cookieToken = wiredAuth?.tokenFromCookieHeader;
+      const apiKeyStore = gateConfig.auth?.apiKeyStore;
       const elementHooks = createElementPipelineHooks({
         gates: booted.gate,
         principals,
         telemetry,
-        allowTestPrincipals: testMode,
+        allowTestPrincipals: allowInjectedPrincipals,
+        ...(extras?.bypassGates === true && extras.trustedInvoke === true
+          ? { bypassGates: true }
+          : {}),
         verifyBearer:
-          binding && verifyBearer ? async (token) => verifyBearer(binding, token) : undefined,
+          binding && wiredAuth
+            ? async (token) => wiredAuth.verifyBearerOrApiKey(binding, token, apiKeyStore)
+            : undefined,
         // Phase 1a: opt-in cookie → Bearer when Authorization is absent.
         resolveToken:
           binding && cookieOpts?.enabled && cookieToken
@@ -1160,21 +1308,23 @@ export function oke(options: OkeOptions): OkeApp {
       }
     }
 
+    const effects = flowDef.effects ?? capability?.declared;
     const { fx, ledger } = createFxContext({
       ...options.fx,
       flow: flowDef.name,
-      effects: flowDef.effects,
+      effects,
       runTelemetry: telemetry,
       runId,
       now,
       i18n: {
         locale: resolvedLocale,
         defaultLocale,
-        catalogs: getMessageCatalogs(),
+        catalogs: loadMessages().getMessageCatalogs(),
         ...options.fx?.i18n,
       },
       ...(principals ? { auth: principals.auth as FxAuth, operator: principals.operator } : {}),
       ...(extras?.originPrincipal ? { principal: extras.originPrincipal } : {}),
+      ...(extras?.trustedInvoke === true && extras.revealPii === true ? { revealPii: true } : {}),
       ...(capability ? { capability } : {}),
       ...(booted
         ? {
@@ -1200,6 +1350,9 @@ export function oke(options: OkeOptions): OkeApp {
             originPrincipal: freezePrincipal(fx.principal),
             locale: resolvedLocale,
             parentId: runId,
+            ...(extras?.trustedInvoke === true && extras.revealPii === true
+              ? { trustedInvoke: true, revealPii: true }
+              : {}),
           },
         );
         if (inner.failure) return inner.failure;
@@ -1216,13 +1369,101 @@ export function oke(options: OkeOptions): OkeApp {
       async () => {
         try {
           const invoke = async (input: unknown) => {
+            const storeRt = booted?.store;
+            const cache = storeRt ? loadStoreCache() : undefined;
+            const declaredForCache: Effects | undefined = capability?.open
+              ? flowDef.effects
+              : (effects ?? {});
+            const cacheEffects = cache
+              ? cache.resolveCacheEffects(declaredForCache, learnedTier1Reads.get(flowDef.name))
+              : undefined;
+            // Revealed PII must not hit a prior masked entry or land in cache.
+            const reveal = extras?.trustedInvoke === true && extras.revealPii === true;
+            const cacheOk =
+              cache !== undefined &&
+              storeRt !== undefined &&
+              cacheEffects !== undefined &&
+              !reveal &&
+              cache.autoCacheEligible({
+                cache: flowDef.cache,
+                durable: flowDef.durable,
+                effects: cacheEffects,
+              });
+            const dims =
+              cacheOk && cache && cacheEffects
+                ? cache.tier1DimsByResource(cacheEffects, flowDef.name, input, fx.auth.userId)
+                : undefined;
+            if (cacheOk && cache && dims && storeRt) {
+              const keys = cache.tier1KeysForReads(cacheEffects, dims);
+              const probes: { key: string; timestamp: number; duration: number }[] = [];
+              const cached = cache.tier1Lookup((key) => {
+                const timestamp = now();
+                const t0 = performance.now();
+                const value = storeRt.cache.get(key);
+                probes.push({
+                  key,
+                  timestamp,
+                  duration: resolveDurationMs(now() - timestamp, performance.now() - t0),
+                });
+                return value;
+              }, keys);
+              if (cached !== undefined) {
+                for (const probe of probes) {
+                  recordObservedEffect(ledger, "read", probe.key, probe.timestamp, probe.duration);
+                }
+                telemetry.cacheHits += 1;
+                return cached;
+              }
+              telemetry.cacheMisses += 1;
+            }
             const run = () => {
               // Flow-level retry re-enters `do` on the same journal session —
               // rewind so completed steps/effects replay instead of re-executing.
               journalSession?.rewind();
               return flowDef.do(input as never, fx);
             };
-            return flowDef.retry ? fxRetry(run, flowDef.retry) : run();
+            const output = await (flowDef.retry ? fxRetry(run, flowDef.retry) : run());
+            if (!isFlowFailure(output) && cache && storeRt && cacheEffects) {
+              const ledgerFx = cache.effectsFromLedger(ledger.entries);
+              const writeEffects: Effects = {
+                writes: [
+                  ...new Set([...(cacheEffects.writes ?? []), ...(ledgerFx.writes ?? [])]),
+                ].filter(cache.isStoreResourceRef),
+              };
+              if ((writeEffects.writes?.length ?? 0) > 0) {
+                storeRt.onWriteEffects(writeEffects);
+              }
+              const mergedReads = [
+                ...new Set([...(cacheEffects.reads ?? []), ...(ledgerFx.reads ?? [])]),
+              ].filter(cache.isStoreResourceRef);
+              if (mergedReads.length > 0) {
+                learnedTier1Reads.set(flowDef.name, mergedReads);
+              }
+              const putEffects: Effects = {
+                reads: mergedReads,
+                ...(ledgerFx.writes ? { writes: ledgerFx.writes } : {}),
+                ...(ledgerFx.asks ? { asks: ledgerFx.asks } : {}),
+              };
+              const storeAfter =
+                !reveal &&
+                cache.autoCacheEligible({
+                  cache: flowDef.cache,
+                  durable: flowDef.durable,
+                  effects: putEffects,
+                });
+              if (storeAfter && output !== undefined) {
+                const ttlMs =
+                  typeof flowDef.cache === "string" ? cache.parseTtlMs(flowDef.cache) : undefined;
+                storeRt.putTier1(
+                  putEffects,
+                  output,
+                  cache.tier1DimsByResource(putEffects, flowDef.name, input, fx.auth.userId),
+                  ttlMs,
+                );
+                if (!cacheOk) telemetry.cacheMisses += 1;
+              }
+            }
+            return output;
           };
           if (!alreadyValidated) {
             const parsed = await validate(flowDef.in, ctx.input);
@@ -1257,6 +1498,7 @@ export function oke(options: OkeOptions): OkeApp {
     });
 
     const endedAt = now();
+    const durationMs = resolveDurationMs(endedAt - startedAt, performance.now() - startedHr);
 
     if (journalSession) {
       inflightRuns.delete(journalSession.runId);
@@ -1302,9 +1544,11 @@ export function oke(options: OkeOptions): OkeApp {
           telemetry,
           startedAt,
           endedAt,
+          durationMs,
           failure: recordFailure,
           id: runId,
           input: replayInput,
+          ...(result.output !== undefined && !recordFailure ? { output: result.output } : {}),
           ...(parentId !== undefined ? { parentId } : {}),
         },
         archiveCleartext,
@@ -1317,6 +1561,9 @@ export function oke(options: OkeOptions): OkeApp {
       response: result.response,
       ctx: result.ctx,
       fx,
+      cache: cacheDimensionOf(telemetry),
+      durationMs,
+      runId,
     };
   }
 
@@ -1349,6 +1596,7 @@ export function oke(options: OkeOptions): OkeApp {
         ai: bootResult.ai,
         runs: bootResult.runs,
         ...(bootResult.journal ? { journal: bootResult.journal } : {}),
+        ...(bootResult.instances ? { instances: bootResult.instances } : {}),
       };
     },
     get capabilities() {
@@ -1370,6 +1618,7 @@ export function oke(options: OkeOptions): OkeApp {
         bootResult: {
           clock: bootResult.clock,
           journal: bootResult.journal,
+          instances: bootResult.instances,
         },
         stop: async () => {},
       });
@@ -1476,22 +1725,35 @@ export function oke(options: OkeOptions): OkeApp {
     async fetch(request) {
       const started = performance.now();
       let flowLabel: string | undefined;
+      let runLabel: string | undefined;
+      let cacheLabel: "hit" | "miss" | "none" | undefined;
       const url = new URL(request.url);
       const method = request.method.toUpperCase();
 
       const respond = async (response: Response): Promise<Response> => {
+        if (method === "QUERY" || response.headers.get("allow")?.includes("QUERY")) {
+          response.headers.set("accept-query", '"application/json"');
+        }
         if (shouldLogDevRequests()) {
           logDevRequest({
             surface: currentDevSurface(),
             method,
             path: url.pathname,
             flow: flowLabel,
+            runId: runLabel,
             status: response.status,
             ms: Math.round(performance.now() - started),
             detail: await failureDetailFromResponse(response),
           });
         }
-        return response;
+        return asBrowserJsonCodeBlock(
+          request,
+          response,
+          options.name,
+          httpNavGroups(adopted, request),
+          performance.now() - started,
+          cacheLabel ?? "none",
+        );
       };
 
       // Kernel readiness — distinct from app-authored GET /health (liveness).
@@ -1514,7 +1776,7 @@ export function oke(options: OkeOptions): OkeApp {
 
       if (method === "GET" && url.pathname === "/_oke/client.json") {
         return respond(
-          new Response(JSON.stringify(routes), {
+          new Response(JSON.stringify({ routes }), {
             headers: { "content-type": "application/json" },
           }),
         );
@@ -1543,6 +1805,8 @@ export function oke(options: OkeOptions): OkeApp {
             { kind: "internal" } satisfies InternalTrigger,
             { request },
           );
+          runLabel = internalResult.runId;
+          cacheLabel = internalResult.cache;
           return respond(encodeExecuteResult(internalResult));
         }
       }
@@ -1555,11 +1819,44 @@ export function oke(options: OkeOptions): OkeApp {
           const edgeResponse = await handle(request, { method, path: url.pathname });
           if (edgeResponse !== undefined) return respond(edgeResponse);
         }
+        const allowed = router.allowedMethods(url.pathname);
+        if (allowed.length > 0) {
+          return respond(
+            new Response("Method Not Allowed", {
+              status: 405,
+              headers: { allow: formatAllowHeader(allowed) },
+            }),
+          );
+        }
         return respond(new Response("Not Found", { status: 404 }));
       }
       const { value: binding, params } = matched;
       flowLabel = binding.flow.name;
 
+      if (method === "QUERY") {
+        const ct = request.headers.get("content-type");
+        if (!ct) {
+          return respond(encodeFailure(fail("InvalidQuery", { reason: "missing_content_type" })));
+        }
+        if ((ct.split(";")[0] ?? "").trim().toLowerCase() !== "application/json") {
+          return respond(
+            Response.json(
+              { data: null, error: fail("UnsupportedMediaType", { contentType: ct }).error },
+              { status: 415 },
+            ),
+          );
+        }
+        let text: string;
+        try {
+          text = await request.text();
+          if (text.length === 0) throw 0;
+          JSON.parse(text);
+        } catch {
+          return respond(encodeFailure(fail("InvalidQuery", { reason: "inconsistent_content" })));
+        }
+        request = new Request(request, { method: "QUERY", body: text });
+      }
+
       let route = compiled.get(binding);
       if (!route && binding.trigger.kind === "http") {
         route = compileHttpBinding(binding, aot);
@@ -1586,6 +1883,8 @@ export function oke(options: OkeOptions): OkeApp {
         params,
         validated,
       });
+      runLabel = result.runId;
+      cacheLabel = result.cache;
 
       return respond(encodeExecuteResult(result));
     },
@@ -1674,12 +1973,6 @@ function isTerminalFailure(result: PipelineResult): boolean {
   return result.ctx.error !== undefined && !isJournalSuspend(result.ctx.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.
  *