okengine 0.23.0 → 0.23.2

package/src/kernel/app.ts

@@ -8,6 +8,7 @@
 
 import { bindAgentApprovalFlows } from "../elements/ai/approval-http.ts";
 import { compileRoute } from "../compiler/dynamic.ts";
+import { HttpBodyRejected, parseBody, type ParseBodyOptions } from "../compiler/http-parse.ts";
 import type { CompiledRoute } from "../compiler/aot.ts";
 import { encodeExecuteResult, encodeFailure } from "../compiler/response.ts";
 import { validate } from "../validation/standard-schema.ts";
@@ -87,9 +88,12 @@ import {
   createJournal,
   createJournalSlot,
   createMemoryJournalStore,
+  clearJournalHeartbeats,
   hasJournalLease,
   isJournalLeaseBusy,
   isJournalSuspend,
+  isLostJournalLease,
+  JournalLeaseBusy,
   JOURNAL_DEFAULT_LEASE_MS,
   type JournalSession,
   type JournalStore,
@@ -368,6 +372,19 @@ export interface OkeOptions {
       };
     };
   };
+  /**
+   * Tier-1 read cache. Omitted caches pure store-read flows. `{ auto: false }`
+   * turns that off. A flow can still opt in with `cache: true` or a duration,
+   * and `cache: false` always disables. The key includes tenant, locale,
+   * scopes, and membership roles.
+   */
+  readonly cache?: {
+    readonly auto?: boolean;
+    /** Auto-cache entry cap. Default 10_000. */
+    readonly maxEntries?: number;
+    /** Auto-cache TTL when a flow sets none. Default 60_000. */
+    readonly defaultTtlMs?: number;
+  };
   /** Channel runtime options. */
   readonly channel?: BootOptions["channel"];
   /** AI runtime options. */
@@ -389,6 +406,15 @@ export interface OkeOptions {
   readonly schedulerIntervalMs?: number;
   /** Durable-run lease duration ms (default 30_000). Forwarded to boot. */
   readonly journalLeaseMs?: number;
+  /** Request body cap in bytes. Default 1 MiB. A route `maxBodySize` overrides it. */
+  readonly maxRequestBodySize?: number;
+  /**
+   * Opt-in durable code version. Unset stamps nothing and checks nothing.
+   * When set, new runs are stamped `app:<version>`. A stored stamp without
+   * the `app:` prefix (0.23.1 and earlier) is treated as compatible and
+   * restamped. An `app:` stamp that differs fails the run with OKE1076.
+   */
+  readonly codeVersion?: string;
 }
 
 /** Readiness probe state — see `GET /_/ready`. */
@@ -598,6 +624,8 @@ export interface OkeApp<D extends Record<string, unknown> = {}, R extends AppRou
       readonly runId?: string;
       /** Tenant identity for cron / `fx.call` (propagated, unlike auth). */
       readonly tenant?: { readonly id: string | null };
+      /** Explicit locale override for {@link Fx.t} / channel sends. */
+      readonly locale?: string;
     },
   ): Promise<ExecuteResult>;
   /**
@@ -792,6 +820,7 @@ function registerHttpRoute(
   smart: { add(method: string, path: string, value: Binding): void },
   compiled: WeakMap<Binding, CompiledRoute>,
   aot: boolean,
+  maxRequestBodySize?: number,
 ): void {
   const trigger = binding.trigger;
   if (trigger.kind !== "http") return;
@@ -823,7 +852,7 @@ function registerHttpRoute(
     seenLiveExposures.set(exposure, binding.flow.name);
   }
   smart.add(trigger.method, trigger.path, binding);
-  compiled.set(binding, compileHttpBinding(binding, aot));
+  compiled.set(binding, compileHttpBinding(binding, aot, maxRequestBodySize));
 }
 
 /**
@@ -1114,7 +1143,15 @@ export function oke(options: OkeOptions): OkeApp {
   for (const b of adopted) {
     if (b.trigger.kind === "http") {
       assertHttpBindingReady(b);
-      registerHttpRoute(b, seenHttpRoutes, seenLiveExposures, smart, compiled, aot);
+      registerHttpRoute(
+        b,
+        seenHttpRoutes,
+        seenLiveExposures,
+        smart,
+        compiled,
+        aot,
+        options.maxRequestBodySize,
+      );
     }
     if (b.trigger.kind === "mcp") {
       registerMcpTool(b, seenMcpTools, mcpToolsByName);
@@ -1137,7 +1174,15 @@ export function oke(options: OkeOptions): OkeApp {
     registerFlow(b.flow);
     if (b.trigger.kind === "http") {
       assertHttpBindingReady(b);
-      registerHttpRoute(b, seenHttpRoutes, seenLiveExposures, smart, compiled, aot);
+      registerHttpRoute(
+        b,
+        seenHttpRoutes,
+        seenLiveExposures,
+        smart,
+        compiled,
+        aot,
+        options.maxRequestBodySize,
+      );
     }
     if (b.trigger.kind === "mcp") {
       registerMcpTool(b, seenMcpTools, mcpToolsByName);
@@ -1389,6 +1434,7 @@ export function oke(options: OkeOptions): OkeApp {
           journalStore: store,
           runId,
           ...(hasJournalLease(store) ? { lease: { instanceId, leaseMs } } : {}),
+          ...(options.codeVersion ? { codeVersion: options.codeVersion } : {}),
           now,
           fx: {
             ...durableResumeFx(),
@@ -1411,7 +1457,13 @@ export function oke(options: OkeOptions): OkeApp {
         });
       } catch (err) {
         if (isJournalLeaseBusy(err)) return;
-        throw err;
+        console.warn(
+          JSON.stringify({
+            event: "journal.resume.failed",
+            runId,
+            message: err instanceof Error ? err.message : String(err),
+          }),
+        );
       }
     } finally {
       inflightRuns.delete(runId);
@@ -1587,6 +1639,19 @@ export function oke(options: OkeOptions): OkeApp {
       startScheduler: overrides?.startScheduler ?? options.startScheduler,
       schedulerIntervalMs: overrides?.schedulerIntervalMs ?? options.schedulerIntervalMs,
       journalLeaseMs: overrides?.journalLeaseMs ?? options.journalLeaseMs,
+      codeVersion: overrides?.codeVersion ?? options.codeVersion,
+      ...(options.cache
+        ? {
+            cache: {
+              ...(options.cache.maxEntries !== undefined
+                ? { maxEntries: options.cache.maxEntries }
+                : {}),
+              ...(options.cache.defaultTtlMs !== undefined
+                ? { defaultTtlMs: options.cache.defaultTtlMs }
+                : {}),
+            },
+          }
+        : {}),
       bindings: adopted,
       flows: [...flowsByName.values()],
       onCronFire: overrides?.onCronFire ?? handleCronFire,
@@ -1970,6 +2035,7 @@ export function oke(options: OkeOptions): OkeApp {
         // Hold the run lease for the request's lifetime — a crash mid-run
         // leaves an expired lease another instance can reclaim and resume.
         ...(hasJournalLease(store) ? { lease: { instanceId, leaseMs } } : {}),
+        ...(options.codeVersion ? { codeVersion: options.codeVersion } : {}),
       });
     };
 
@@ -2085,6 +2151,16 @@ export function oke(options: OkeOptions): OkeApp {
               : undefined;
             // Revealed PII must not hit a prior masked entry or land in cache.
             const reveal = extras?.trustedInvoke === true && extras.revealPii === true;
+            const cacheAuto = options.cache?.auto !== false;
+            const cacheCaller = {
+              userId: fx.auth.userId,
+              tenantId: fx.tenant.id,
+              locale: fx.locale,
+              scopes: fx.auth.scopes,
+              roles: principals?.cacheRoles ?? [],
+              verified: fx.auth.verified === true,
+              operatorId: fx.operator.id,
+            };
             const cacheOk =
               cache !== undefined &&
               storeRt !== undefined &&
@@ -2092,12 +2168,13 @@ export function oke(options: OkeOptions): OkeApp {
               !reveal &&
               cache.autoCacheEligible({
                 cache: flowDef.cache,
+                auto: cacheAuto,
                 durable: flowDef.durable,
                 effects: cacheEffects,
               });
             const dims =
               cacheOk && cache && cacheEffects
-                ? cache.tier1DimsByResource(cacheEffects, flowDef.name, input, fx.auth.userId)
+                ? cache.tier1DimsByResource(cacheEffects, flowDef.name, input, cacheCaller)
                 : undefined;
             if (cacheOk && cache && dims && storeRt) {
               const keys = cache.tier1KeysForReads(cacheEffects, dims);
@@ -2128,43 +2205,79 @@ export function oke(options: OkeOptions): OkeApp {
               journalSession?.rewind();
               return flowDef.do(input as never, fx);
             };
-            const raw = await (flowDef.retry ? fxRetry(run, flowDef.retry) : run());
+            const flightKey =
+              cacheOk && cache && dims && cacheEffects
+                ? cache.tier1KeysForReads(cacheEffects, dims)[0]
+                : undefined;
+            const flightResources = (cacheEffects?.reads ?? []).filter(
+              cache?.isStoreResourceRef ?? (() => false),
+            );
+            const generation =
+              storeRt && flightKey
+                ? Object.fromEntries(
+                    flightResources.map((resource) => [
+                      resource,
+                      storeRt.cache.generationOf(resource),
+                    ]),
+                  )
+                : undefined;
+            let raw: unknown;
+            let cacheable = true;
+            try {
+              const load = () => (flowDef.retry ? fxRetry(run, flowDef.retry) : run());
+              if (flightKey && storeRt) {
+                const flight = await storeRt.cache.coalesce(flightKey, flightResources, load);
+                raw = flight.value;
+                cacheable =
+                  flight.cacheable &&
+                  (generation === undefined || storeRt.cache.sameGeneration(generation));
+              } else {
+                raw = await load();
+              }
+            } finally {
+              if (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 output = isFlowFailure(raw) ? raw : await projectFlowOut(flowDef.out, raw);
             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 observed = cache.mergeEffects(cacheEffects, ledgerFx);
+              const storeReads = (observed.reads ?? []).filter(cache.isStoreResourceRef);
+              if (cache.autoCachePure(observed) && storeReads.length > 0) {
+                learnedTier1Reads.set(flowDef.name, storeReads);
+              } else {
+                learnedTier1Reads.delete(flowDef.name);
               }
-              const putEffects: Effects = {
-                reads: mergedReads,
-                ...(ledgerFx.writes ? { writes: ledgerFx.writes } : {}),
-                ...(ledgerFx.asks ? { asks: ledgerFx.asks } : {}),
-              };
               const storeAfter =
                 !reveal &&
                 cache.autoCacheEligible({
                   cache: flowDef.cache,
+                  auto: cacheAuto,
                   durable: flowDef.durable,
-                  effects: putEffects,
+                  effects: observed,
                 });
-              if (storeAfter && output !== undefined && !loadFx().isJsonStreamResult(output)) {
+              if (
+                cacheable &&
+                storeAfter &&
+                output !== undefined &&
+                !loadFx().isJsonStreamResult(output)
+              ) {
                 const ttlMs =
                   typeof flowDef.cache === "string" ? cache.parseTtlMs(flowDef.cache) : undefined;
+                const putEffects: Effects = { reads: storeReads };
                 storeRt.putTier1(
                   putEffects,
                   output,
-                  cache.tier1DimsByResource(putEffects, flowDef.name, input, fx.auth.userId),
+                  cache.tier1DimsByResource(putEffects, flowDef.name, input, cacheCaller),
                   ttlMs,
                 );
                 if (!cacheOk) telemetry.cacheMisses += 1;
@@ -2215,6 +2328,9 @@ export function oke(options: OkeOptions): OkeApp {
               const journal = openJournal();
               const resumeId = claimed.kind === "reclaimed" ? claimed.row.runId : undefined;
               try {
+                if (resumeId && inflightRuns.has(resumeId)) {
+                  throw new JournalLeaseBusy(resumeId);
+                }
                 const session = resumeId
                   ? await journal.resume(resumeId)
                   : await journal.start(flowDef.name, validated);
@@ -2319,6 +2435,9 @@ export function oke(options: OkeOptions): OkeApp {
             };
             return undefined;
           }
+          if (flowDef.durable && journalSession && isLostJournalLease(err)) {
+            return fail("JournalLeaseBusy", {});
+          }
           throw err;
         }
       },
@@ -2367,13 +2486,22 @@ export function oke(options: OkeOptions): OkeApp {
           });
         } else if (!sleeping && isTerminalFailure(result)) {
           const terminalErr = result.failure ?? result.ctx.error;
-          await runCompensationPhase({
-            flow: flowDef,
-            input: ctx.input,
-            session: journalSession,
-            fx,
-            error: terminalErr,
-          });
+          const lost =
+            isLostJournalLease(terminalErr) ||
+            isJournalLeaseBusy(terminalErr) ||
+            (terminalErr != null &&
+              typeof terminalErr === "object" &&
+              "error" in terminalErr &&
+              (terminalErr as { error?: { code?: string } }).error?.code === "JournalLeaseBusy");
+          if (!lost) {
+            await runCompensationPhase({
+              flow: flowDef,
+              input: ctx.input,
+              session: journalSession,
+              fx,
+              error: terminalErr,
+            });
+          }
         } else if (parked && sleeping) {
           await journalSession.commit("sleeping", { wakeAt: sleeping.wakeAt });
         } else if (!sleeping) {
@@ -2487,6 +2615,7 @@ export function oke(options: OkeOptions): OkeApp {
     },
     async stop() {
       if (!bootResult) return;
+      clearJournalHeartbeats();
       bootResult.stopScheduler();
       // Realtime bridge down before connections close.
       {
@@ -2514,7 +2643,11 @@ export function oke(options: OkeOptions): OkeApp {
     /** Shared identity store when `gate.auth` is enabled. */
     identities: gateConfig.auth?.identities,
     async resumeDurable(now) {
-      const t = now ?? bootResult?.clock?.now() ?? options.fx?.now?.() ?? Date.now();
+      // Due selection uses one sample. The run itself must not: a frozen
+      // closure wrote leases that were already expired by the time persist ran.
+      const sample = (): number => bootResult?.clock?.now() ?? options.fx?.now?.() ?? Date.now();
+      const t = now ?? sample();
+      const live = typeof now === "number" ? (): number => now : sample;
       const { store, instanceId, leaseMs } = activeJournal();
       if (hasJournalLease(store)) {
         // Shared store is the wake schedule — claim due sleeps across all
@@ -2523,14 +2656,14 @@ export function oke(options: OkeOptions): OkeApp {
           const due = await store.claimDueSleep(instanceId, t, leaseMs);
           if (!due) break;
           sleepingRuns.delete(due.id);
-          await resumeDurableRun(due.id, due.flow, due.input, () => t);
+          await resumeDurableRun(due.id, due.flow, due.input, live);
         }
         // Crash sweep: the boot orphan scan is once-only, so each tick also
         // reclaims `running` runs whose holder's lease has expired (same
         // takeover physics as Clock: lease expiry + next tick).
         for (const orphan of await store.listOrphans(t)) {
           if (orphan.status !== "running") continue;
-          await resumeDurableRun(orphan.id, orphan.flow, orphan.input, () => t);
+          await resumeDurableRun(orphan.id, orphan.flow, orphan.input, live);
         }
         return;
       }
@@ -2543,7 +2676,7 @@ export function oke(options: OkeOptions): OkeApp {
           input: sleeper.input,
           journalStore: store,
           runId,
-          now: () => t,
+          now: live,
           fx: durableResumeFx(),
         });
         if (result.status === "sleeping") {
@@ -2684,9 +2817,15 @@ export function oke(options: OkeOptions): OkeApp {
           flowLabel = target.name;
           let internalInput: unknown;
           try {
-            internalInput = await request.json();
-          } catch {
-            internalInput = undefined;
+            internalInput = await parseBody(request, {
+              maxBytes: options.maxRequestBodySize,
+              jsonContentType: "required",
+            });
+          } catch (err) {
+            if (err instanceof HttpBodyRejected) {
+              return respond(encodeFailure(bodyFailure(err, request)));
+            }
+            throw err;
           }
           const internalResult = await execute(
             target,
@@ -2753,7 +2892,7 @@ export function oke(options: OkeOptions): OkeApp {
 
       let route = compiled.get(binding);
       if (!route && binding.trigger.kind === "http") {
-        route = compileHttpBinding(binding, aot);
+        route = compileHttpBinding(binding, aot, options.maxRequestBodySize);
         compiled.set(binding, route);
       }
 
@@ -2859,7 +2998,31 @@ export function oke(options: OkeOptions): OkeApp {
   return app;
 }
 
-function compileHttpBinding(binding: Binding, aot: boolean): CompiledRoute {
+function httpBodyOptions(trigger: HttpTrigger, maxRequestBodySize?: number): ParseBodyOptions {
+  const contract = trigger.contract as
+    | { readonly maxBodySize?: number; readonly jsonContentType?: "required" | "any" }
+    | undefined;
+  return {
+    maxBytes: contract?.maxBodySize ?? maxRequestBodySize,
+    ...(contract?.jsonContentType ? { jsonContentType: contract.jsonContentType } : {}),
+  };
+}
+
+function bodyFailure(err: HttpBodyRejected, request: Request): ReturnType<typeof fail> {
+  if (err.code === "InvalidQuery") {
+    return fail("InvalidQuery", { reason: err.reason ?? "malformed_body" });
+  }
+  if (err.code === "UnsupportedMediaType") {
+    return fail("UnsupportedMediaType", { contentType: request.headers.get("content-type") ?? "" });
+  }
+  return fail("PayloadTooLarge", {});
+}
+
+function compileHttpBinding(
+  binding: Binding,
+  aot: boolean,
+  maxRequestBodySize?: number,
+): CompiledRoute {
   const trigger = binding.trigger as HttpTrigger;
   const hookFns: Array<(...args: never[]) => unknown> = [];
   for (const list of Object.values(binding.flow.hooks)) {
@@ -2875,6 +3038,7 @@ function compileHttpBinding(binding: Binding, aot: boolean): CompiledRoute {
       handler: binding.flow.do as (...args: never[]) => unknown,
       hooks: hookFns,
       schema: binding.flow.in,
+      body: httpBodyOptions(trigger, maxRequestBodySize),
     },
     aot,
   );